@oxy.so/bloom 7.3.0 → 7.5.0

package/src/content-panel/ContentPanel.tsx

@@ -38,7 +38,7 @@ import { StyleSheet, useWindowDimensions } from 'react-native';
 import { useOptionalPanelChrome, usePanelShape } from '../styles/panel-chrome';
 import { surfaceStyle as resolveShapeStyle } from '../shapes/surface-style';
 import { StyledView } from '../styles/styled-primitives';
-import { SurfaceLevelProvider, surfaceFillVars, useOptionalSurfaceFill } from '../styles/surface-levels';
+import { SurfaceLevelProvider, surfaceFillVars, useOptionalSurfaceFill, useSurfaceLevelValue } from '../styles/surface-levels';
 import {
   ContentPanelNestingContext,
   useContentPanelNestingGuard,
@@ -80,6 +80,7 @@ const RESPONSIVE_CONTENT: Record<ContentPanelFramedBreakpoint, string> = {
 const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   errorBoundary = false,
+  appearance = 'solid',
   framed,
   framedFrom = 768,
   fill = false,
@@ -100,8 +101,10 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   const defaultFill = rawFill;
   const { width } = useWindowDimensions();
   const parentFill = useOptionalSurfaceFill();
-  const paintsSurface = Boolean(defaultFill) && parentFill !== undefined && (framed ?? width >= framedFrom) && chrome !== 'none';
-  const publishedFill = rawFill && paintsSurface ? resolveSurfaceMaterial({ fill: rawFill, parentFill: parentFill! }).publishedFill : rawFill;
+  const parentLevel = useSurfaceLevelValue();
+  const isPlain = appearance === 'plain';
+  const paintsSurface = !isPlain && Boolean(defaultFill) && parentFill !== undefined && (framed ?? width >= framedFrom) && chrome !== 'none';
+  const publishedFill = isPlain ? parentFill : rawFill && paintsSurface ? resolveSurfaceMaterial({ fill: rawFill, parentFill: parentFill! }).publishedFill : rawFill;
   const radius = StyleSheet.flatten(surfaceStyle)?.borderRadius ?? panelShape.radius;
   const isFramed = framed ?? width >= framedFrom;
   const geometry = { ...resolveShapeStyle({ curve: panelShape.curve }), borderRadius: isFramed ? radius : 0 };
@@ -113,18 +116,18 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   // (the breakpoint bundle lives whole in `RESPONSIVE_SURFACE`; `framed ===
   // true`/`false` ignore `framedFrom` for fixed always/never framing).
   const surfaceBase =
-    chrome === 'none'
+    isPlain || chrome === 'none'
       ? 'flex-1'
       : framed === undefined
         ? `flex-1 ${RESPONSIVE_SURFACE[framedFrom]}`
         : framed
           ? 'flex-1 border border-border'
           : 'flex-1';
-  const surfaceClass = [surfaceBase, fill ? 'min-h-0' : '', surfaceClassName ?? (paintsSurface ? 'bg-transparent' : 'bg-card')].filter(Boolean).join(' ');
+  const surfaceClass = [surfaceBase, fill ? 'min-h-0' : '', surfaceClassName ?? (isPlain || paintsSurface ? 'bg-transparent' : 'bg-card')].filter(Boolean).join(' ');
   // Native has no overlays: the surface itself carries the edge. `none` drops
   // both, `border` keeps the class-drawn hairline, `elevated` adds the lift.
   const chromeStyle =
-    !isFramed || chrome === 'none' || chrome === 'border'
+    !isFramed || isPlain || chrome === 'none' || chrome === 'border'
       ? null
       : shadow || panelChrome
         ? { boxShadow: shadow ?? panelChrome?.shadow }
@@ -149,14 +152,14 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
           geometry,
           chromeStyle,
           surfaceStyle,
-          paintsSurface ? { backgroundColor: 'transparent' } : null,
+          isPlain || paintsSurface ? { backgroundColor: 'transparent' } : null,
         ]}
       >
         {paintsSurface ? <SurfacePaint fill={defaultFill!} radius={radius} shape={{ curve: panelShape.curve }} /> : null}
         <StyledView testID="content-panel-content" className={contentClass} style={[geometry, contentStyle]}>
-          {/* The panel is a surface: everything inside is sitting on rung 1,
-              painted in the colour this panel actually paints. */}
-          <SurfaceLevelProvider level={1} fill={publishedFill}>
+          {/* Solid panels publish their painted surface. Plain panels preserve
+              the enclosing surface so descendant scrims follow its real fill. */}
+          <SurfaceLevelProvider level={isPlain ? parentLevel : 1} fill={publishedFill}>
             {errorBoundary === false ? children : <PanelErrorBoundary {...(errorBoundary === true ? {} : errorBoundary)}>{children}</PanelErrorBoundary>}
           </SurfaceLevelProvider>
         </StyledView>

package/src/content-panel/ContentPanel.web.tsx

@@ -97,7 +97,7 @@ import { surfaceStyle as resolveShapeStyle } from '../shapes/surface-style';
 import { StyledView } from '../styles/styled-primitives';
 
 import { useOptionalPanelChrome, usePanelShape } from '../styles/panel-chrome';
-import { SurfaceLevelProvider, surfaceFillVars, useOptionalSurfaceFill } from '../styles/surface-levels';
+import { SurfaceLevelProvider, surfaceFillVars, useOptionalSurfaceFill, useSurfaceLevelValue } from '../styles/surface-levels';
 import { useTheme } from '../theme/use-theme';
 import {
   ContentPanelNestingContext,
@@ -173,6 +173,7 @@ const PANEL_INSET_CSS = `
 const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   errorBoundary = false,
+  appearance = 'solid',
   framed,
   framedFrom = 768,
   fill = false,
@@ -211,8 +212,10 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   const defaultFill = rawFill;
   const { width } = useWindowDimensions();
   const parentFill = useOptionalSurfaceFill();
-  const paintsSurface = Boolean(defaultFill) && parentFill !== undefined && (framed ?? width >= framedFrom) && chrome !== 'none';
-  const publishedFill = rawFill && paintsSurface ? resolveSurfaceMaterial({ fill: rawFill, parentFill: parentFill! }).publishedFill : rawFill;
+  const parentLevel = useSurfaceLevelValue();
+  const isPlain = appearance === 'plain';
+  const paintsSurface = !isPlain && Boolean(defaultFill) && parentFill !== undefined && (framed ?? width >= framedFrom) && chrome !== 'none';
+  const publishedFill = isPlain ? parentFill : rawFill && paintsSurface ? resolveSurfaceMaterial({ fill: rawFill, parentFill: parentFill! }).publishedFill : rawFill;
   const materialStyle = useSurfaceMaterial('[data-bloom-panel-material]', 'bloom-content-panel-material', defaultFill ?? 'transparent');
 
   // Tri-state: `undefined` → responsive (md:-gated), `true` → always framed,
@@ -257,7 +260,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   const gridStackClass = boundToPanel
     ? 'web:grid web:[grid-template-columns:minmax(0,1fr)] web:[grid-template-rows:minmax(0,1fr)]'
     : '';
-  const surfaceClass = [surfaceBase, fillSurface, gridStackClass, surfaceClassName ?? (paintsSurface ? 'bg-transparent' : 'bg-card')].filter(Boolean).join(' ');
+  const surfaceClass = [surfaceBase, fillSurface, gridStackClass, surfaceClassName ?? (isPlain || paintsSurface ? 'bg-transparent' : 'bg-card')].filter(Boolean).join(' ');
   const contentClass = [contentBase, fillContent, boundToPanel ? 'web:[grid-area:1/1]' : '', contentClassName]
     .filter(Boolean)
     .join(' ');
@@ -313,6 +316,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
           framed === true ? { borderRadius: radius } : framed === false ? { borderRadius: 0 } : null,
           surfaceStyle,
           paintsSurface ? materialStyle : null,
+          isPlain ? { backgroundColor: 'transparent' } : null,
         ]}
       >
         {/* (1) Bleed-mask overlay — gutter box-shadow ring, below chrome. Not
@@ -331,12 +335,12 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
                   ? `web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-[var(--bloom-panel-radius)] ${bp.overlayHidden} web:[margin-bottom:calc(-100dvh+16px)]`
                   : 'web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-[var(--bloom-panel-radius)] web:[margin-bottom:calc(-100dvh+16px)]'
             }
-            style={{ ...panelStyle, ...insetStyle, boxShadow: `0 0 0 ${maskSpread}px ${maskColor ?? colors.background}` }}
+            style={{ ...panelStyle, ...insetStyle, boxShadow: `0 0 0 ${maskSpread}px ${maskColor ?? (isPlain ? parentFill : undefined) ?? colors.background}` }}
           />
         )}
         {/* (2) Border-frame overlay — one continuous rounded border, above all.
             Same visibility gating as the bleed-mask. */}
-        {showOverlays && showStickyFrame !== false && chrome !== 'none' && (
+        {showOverlays && showStickyFrame !== false && !isPlain && chrome !== 'none' && (
           <StyledView
             key="border-frame"
             testID="content-panel-border-frame"
@@ -361,9 +365,9 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
             scroll/virtualizer + refetch on a breakpoint cross). Clipped to the
             rounded panel shape on web when framed. */}
         <StyledView key="content" testID="content-panel-content" className={contentClass} style={[curveStyle, framed === true ? { borderRadius: radius } : framed === false ? { borderRadius: 0 } : null, contentStyle]}>
-          {/* The panel is a surface: everything inside is sitting on rung 1,
-              painted in the colour this panel actually paints. */}
-          <SurfaceLevelProvider level={1} fill={publishedFill}>
+          {/* Solid panels publish their painted surface. Plain panels preserve
+              the enclosing surface so descendant scrims follow its real fill. */}
+          <SurfaceLevelProvider level={isPlain ? parentLevel : 1} fill={publishedFill}>
             {errorBoundary === false ? children : <PanelErrorBoundary {...(errorBoundary === true ? {} : errorBoundary)}>{children}</PanelErrorBoundary>}
           </SurfaceLevelProvider>
         </StyledView>

package/src/content-panel/types.ts

@@ -18,6 +18,13 @@ export type ContentPanelChrome = 'elevated' | 'border' | 'none';
 
 export interface ContentPanelProps {
   children: React.ReactNode;
+  /**
+   * `solid` (default) paints a panel surface. `plain` keeps layout, framing and
+   * clipping while leaving the enclosing surface visible, without material,
+   * border or shadow. Descendants inherit the parent's surface level and fill.
+   * In plain mode surface background overrides and surfaceColor are ignored.
+   */
+  appearance?: 'solid' | 'plain';
   /** Opt in to local themed error recovery. Split panes already provide their own boundaries. */
   errorBoundary?: boolean | PanelErrorBoundaryOptions;
   /**

package/src/index.ts

@@ -169,13 +169,16 @@ export {
   useClaimTopEdge,
   useTopEdgeInset,
   ScrollOffsetProvider,
+  ScrollMetricsProvider,
+  useScrollMetricsBinding,
+  ScrollArea,
   useScrollOffset,
   ScreenScope,
   HeaderDockProvider,
   useHeaderDockInset,
   StickySection,
 } from './layout';
-export type { StickySectionProps } from './layout';
+export type { StickySectionProps, ScrollMetricsBindingOptions, ScrollAreaProps } from './layout';
 export { Fab } from './fab';
 export type { FabProps, FabSize } from './fab';
 export { FrostedIconButton } from './frosted-icon-button';

package/src/index.web.ts

@@ -174,13 +174,16 @@ export {
   useClaimTopEdge,
   useTopEdgeInset,
   ScrollOffsetProvider,
+  ScrollMetricsProvider,
+  useScrollMetricsBinding,
+  ScrollArea,
   useScrollOffset,
   ScreenScope,
   HeaderDockProvider,
   useHeaderDockInset,
   StickySection,
 } from './layout';
-export type { StickySectionProps } from './layout';
+export type { StickySectionProps, ScrollMetricsBindingOptions, ScrollAreaProps } from './layout';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabSize } from './fab/index.web';
 export { FrostedIconButton } from './frosted-icon-button/index.web';

package/src/layout/ScrollArea.tsx

@@ -0,0 +1,25 @@
+import React, { forwardRef, type ComponentType, type Ref } from 'react';
+import { ScrollView, type ScrollViewProps } from 'react-native';
+import { styled } from 'react-native-css';
+import { useScrollMetricsBinding } from './use-scroll-metrics-binding';
+
+export interface ScrollAreaProps extends ScrollViewProps {
+  /** Utilities for the scrolling viewport, resolved by Bloom's own interop. */
+  className?: string;
+  /** Utilities for the inner content container. */
+  contentContainerClassName?: string;
+}
+
+// Narrow only the styled mapping input to avoid ScrollViewProps' recursive
+// dot-path union. The public component retains the complete ScrollView contract.
+const ScrollAreaBase: ComponentType<Pick<ScrollViewProps, 'style' | 'contentContainerStyle'>> = ScrollView;
+const StyledScrollView: ComponentType<ScrollAreaProps & { ref?: Ref<ScrollView> }> = styled(ScrollAreaBase, {
+  className: 'style',
+  contentContainerClassName: 'contentContainerStyle',
+});
+
+/** A ScrollView that publishes its measurements to surrounding page chrome. */
+export const ScrollArea = forwardRef<ScrollView, ScrollAreaProps>(function ScrollArea({ onScroll, onLayout, onContentSizeChange, scrollEventThrottle, ...props }, ref) {
+  const binding = useScrollMetricsBinding({ onScroll, onLayout, onContentSizeChange });
+  return <StyledScrollView {...props} {...binding} scrollEventThrottle={scrollEventThrottle ?? binding.scrollEventThrottle} ref={ref} />;
+});

package/src/layout/index.ts

@@ -18,3 +18,9 @@ export { ScreenScope } from './screen-scope';
 export { HeaderDockProvider, useHeaderDockInset } from './header-dock';
 export { StickySection } from './StickySection';
 export type { StickySectionProps } from './StickySection';
+
+export { ScrollMetricsProvider } from './scroll-metrics';
+export { useScrollMetricsBinding } from './use-scroll-metrics-binding';
+export type { ScrollMetricsBindingOptions } from './use-scroll-metrics-binding';
+export { ScrollArea } from './ScrollArea';
+export type { ScrollAreaProps } from './ScrollArea';

package/src/layout/screen-scope.tsx

@@ -39,6 +39,7 @@ import { ScreenContext, ScreenNavigationContext } from '../screen/context';
 import type { PropsWithChildren } from 'react';
 
 import { BottomEdgeProvider } from './bottom-edge';
+import { ScrollMetricsContext } from './scroll-metrics';
 import { ScrollOffsetProvider } from './scroll-offset';
 import { TopEdgeProvider } from './top-edge';
 
@@ -49,7 +50,7 @@ export function ScreenScope({ children }: PropsWithChildren) {
         <TopEdgeProvider>
           <BottomEdgeProvider>
             {/* null means no scroller has claimed this scope yet. */}
-            <ScrollOffsetProvider value={null}>{children}</ScrollOffsetProvider>
+            <ScrollMetricsContext.Provider value={null}><ScrollOffsetProvider value={null}>{children}</ScrollOffsetProvider></ScrollMetricsContext.Provider>
           </BottomEdgeProvider>
         </TopEdgeProvider>
       </ScreenNavigationContext.Provider>

package/src/layout/scroll-metrics.tsx

@@ -0,0 +1,35 @@
+import React, { createContext, useContext, useMemo, type PropsWithChildren } from 'react';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+import { ScrollOffsetProvider } from './scroll-offset';
+
+export interface ScrollMetrics {
+  scrollY: SharedValue<number>;
+  contentHeight: SharedValue<number>;
+  viewportHeight: SharedValue<number>;
+}
+
+/** Internal scope boundary; overlay screens must not follow the page beneath them. */
+export const ScrollMetricsContext = createContext<ScrollMetrics | null>(null);
+
+/** Pair one scroller with its surrounding header/footer without adding a layout box. */
+export function ScrollMetricsProvider({ children }: PropsWithChildren) {
+  const scrollY = useSharedValue(0);
+  const contentHeight = useSharedValue(-1);
+  const viewportHeight = useSharedValue(0);
+  const value = useMemo(() => ({ scrollY, contentHeight, viewportHeight }), [scrollY, contentHeight, viewportHeight]);
+  return <ScrollMetricsContext.Provider value={value}>
+    <ScrollOffsetProvider value={scrollY}>{children}</ScrollOffsetProvider>
+  </ScrollMetricsContext.Provider>;
+}
+
+export function useScrollMetricsValue(): ScrollMetrics | null {
+  return useContext(ScrollMetricsContext);
+}
+
+/** Unmeasured and non-scrollable content has no hidden bottom edge. */
+export function remainingScrollDistance(metrics: ScrollMetrics | null): number {
+  'worklet';
+  if (!metrics || metrics.viewportHeight.value <= 0 || metrics.contentHeight.value < 0) return 0;
+  const max = Math.max(0, metrics.contentHeight.value - metrics.viewportHeight.value);
+  return Math.max(0, max - Math.max(0, metrics.scrollY.value));
+}

package/src/layout/scroll-offset.ts

@@ -8,7 +8,11 @@
  * one scroll container has moved. The container is the screen's, and the chrome
  * is usually not inside it, so the number has to travel.
  *
- * Until now it travelled as a prop, and the default when the prop was omitted
+ * Prefer ScrollMetricsProvider with ScrollArea when the footer also needs to
+ * know the remaining content. This lower-level offset-only provider remains
+ * useful for an existing animated scroll owner.
+ *
+ * Originally it travelled as a prop, and the default when the prop was omitted
  * was `window.scrollY` on web and "nothing moves" on native. That default is
  * right for exactly one layout — a web page whose document IS the scroller —
  * and silently wrong for the two that a Bloom app usually has: a desktop panel

package/src/layout/use-scroll-metrics-binding.ts

@@ -0,0 +1,37 @@
+import { useCallback } from 'react';
+import type { ScrollViewProps } from 'react-native';
+import { useScrollMetricsValue } from './scroll-metrics';
+
+/** Events accepted by ordinary RN ScrollView, FlatList and SectionList. */
+export type ScrollMetricsBindingOptions = Pick<ScrollViewProps, 'onScroll' | 'onLayout' | 'onContentSizeChange'>;
+
+/** Bind one scrolling owner to the nearest ScrollMetricsProvider. No React updates per frame. */
+export function useScrollMetricsBinding({ onScroll, onLayout, onContentSizeChange }: ScrollMetricsBindingOptions = {}) {
+  const metrics = useScrollMetricsValue();
+  const handleScroll = useCallback<NonNullable<ScrollViewProps['onScroll']>>(event => {
+    if (metrics) {
+      const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+      if (Number.isFinite(contentSize.height)) metrics.contentHeight.value = Math.max(0, contentSize.height);
+      if (Number.isFinite(layoutMeasurement.height)) metrics.viewportHeight.value = Math.max(0, layoutMeasurement.height);
+      const max = Math.max(0, metrics.contentHeight.value - metrics.viewportHeight.value);
+      if (Number.isFinite(contentOffset.y)) metrics.scrollY.value = Math.min(max, Math.max(0, contentOffset.y));
+    }
+    onScroll?.(event);
+  }, [metrics, onScroll]);
+  const handleLayout = useCallback<NonNullable<ScrollViewProps['onLayout']>>(event => {
+    const height = event.nativeEvent.layout.height;
+    if (metrics && Number.isFinite(height)) {
+      metrics.viewportHeight.value = Math.max(0, height);
+      if (metrics.contentHeight.value >= 0) metrics.scrollY.value = Math.min(metrics.scrollY.value, Math.max(0, metrics.contentHeight.value - height));
+    }
+    onLayout?.(event);
+  }, [metrics, onLayout]);
+  const handleContentSizeChange = useCallback<NonNullable<ScrollViewProps['onContentSizeChange']>>((width, height) => {
+    if (metrics && Number.isFinite(height)) {
+      metrics.contentHeight.value = Math.max(0, height);
+      metrics.scrollY.value = Math.min(metrics.scrollY.value, Math.max(0, height - metrics.viewportHeight.value));
+    }
+    onContentSizeChange?.(width, height);
+  }, [metrics, onContentSizeChange]);
+  return { onScroll: handleScroll, onLayout: handleLayout, onContentSizeChange: handleContentSizeChange, scrollEventThrottle: 16 };
+}

package/src/mail-thread/MailMessage.tsx

@@ -143,7 +143,7 @@ export function MailMessage({
       appearance="solid"
       border="none"
       elevation="s"
-      radius="radius-16"
+      radius="panel"
       testID={testID}
       style={[open ? { paddingBottom: geo.paddingVertical } : null, style]}
     >

package/src/mail-thread/MailThread.tsx

@@ -2,7 +2,6 @@ import React, { useEffect, useMemo, useState } from 'react';
 import { View } from 'react-native';
 
 import { Button } from '../button';
-import { Divider } from '../divider';
 import { useControllableState } from '../hooks/use-controllable-state';
 import { MailLabelChips, MailStar } from '../mail-list/parts';
 import { mailStrings, resolveMailPaint, visibleLabels } from '../mail-list/shared';
@@ -145,7 +144,6 @@ export function MailThread({
           />
         </View>
       ) : null}
-      <Divider />
       <View testID={testID ? `${testID}-messages` : undefined} style={{ paddingTop: space.xs, paddingBottom: space.xs, gap: messageGap }}>
         {entries.map((entry) =>
           entry.kind === 'message' ? (

package/src/mail-thread/shared.ts

@@ -1,5 +1,5 @@
 import { Platform } from 'react-native';
-import { RADIUS } from '../design-tokens/scales';
+import { SURFACE_SHAPES } from '../design-tokens/shapes';
 
 import { MAIL_THREAD_MESSAGES } from './messages';
 import type { MailThreadMessage, MailAddress, MailThreadStrings } from './types';
@@ -44,8 +44,8 @@ export const MAIL_THREAD_GEOMETRY = {
   glyph: 16,
   /** The star and the overflow trigger. A touch target, so 44. */
   action: 44,
-  /** Radius of a message's own surface. */
-  radius: RADIUS['radius-16'],
+  /** Default radius; rendered messages inherit BloomScope.panelRadius via Card. */
+  radius: SURFACE_SHAPES.sidebar.radius,
 } as const;
 
 /**

package/src/note-card/shared.ts

@@ -40,7 +40,7 @@ export interface NoteCardGeometry {
   padding: number;
   gap: number;
   /** A rung of the `RADIUS` scale — `Card` takes the rung, the focus ring takes its px. */
-  radius: CardRadius;
+  radius: Exclude<CardRadius, 'panel'>;
   excerptLines: number;
   titleLines: number;
   maxTags: number;

package/src/page-footer/PageFooter.tsx

@@ -1,6 +1,8 @@
 import React, { memo, useContext, useEffect, useId, useState } from 'react';
 import { Platform, StyleSheet, View, useWindowDimensions, type LayoutChangeEvent } from 'react-native';
 import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+import { remainingScrollDistance, useScrollMetricsValue } from '../layout/scroll-metrics';
 import { BloomScope } from '../appearance';
 import { useBottomEdgeInset } from '../layout/bottom-edge';
 import { EdgeScrim, SCRIM_TAIL_RATIO } from '../page-header/EdgeScrim';
@@ -15,9 +17,14 @@ const BAR_HEIGHT = 56;
 
 /** Page-local controls floating over a bounded scroller, above app navigation. */
 function PageFooterComponent({
-  children, actions, bottomInset, safeArea, scrim = 'always', scrimColor, style, testID,
+  children, actions, bottomInset, safeArea, scrim = 'always', scrimColor, scrollThreshold = 20, style, testID,
 }: PageFooterProps) {
   const theme = useTheme();
+  const metrics = useScrollMetricsValue();
+  const threshold = Math.max(1, Number.isFinite(scrollThreshold) ? scrollThreshold : 20);
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity: scrim === 'auto' ? Math.min(1, remainingScrollDistance(metrics) / threshold) : 1,
+  }), [metrics, scrim, threshold]);
   const fill = useSurfaceFill() ?? theme.colors.background;
   const occupied = useBottomEdgeInset();
   const rawBottom = bottomInset ?? occupied;
@@ -51,13 +58,13 @@ function PageFooterComponent({
       style={[styles.container, { bottom, paddingBottom: padBottom }, style]}
     >
       {scrim !== 'none' ? (
-        <View
+        <Animated.View
           pointerEvents="none"
-          style={[styles.scrim, { height: height * (1 + SCRIM_TAIL_RATIO) }]}
+          style={[styles.scrim, { height: height * (1 + SCRIM_TAIL_RATIO) }, scrimStyle]}
           testID={testID ? `${testID}-scrim` : undefined}
         >
           <EdgeScrim edge="bottom" color={scrimColor ?? fill} testID={testID ? `${testID}-scrim-gradient` : undefined} />
-        </View>
+        </Animated.View>
       ) : null}
       <View
         onLayout={onLayout}

package/src/page-footer/types.ts

@@ -17,8 +17,14 @@ export interface PageFooterProps {
    * true on native, false on web. Disable when the containing shell owns it.
    */
   safeArea?: boolean;
-  /** The PageHeader gradient, mirrored upward. Default always. */
-  scrim?: 'always' | 'none';
+  /**
+   * Mirrored PageHeader gradient. Default always preserves existing behavior.
+   * auto follows ScrollMetricsProvider: hidden at the bottom or for short /
+   * unmeasured content, fading in over scrollThreshold of remaining content.
+   */
+  scrim?: 'auto' | 'always' | 'none';
+  /** Distance from the bottom over which the automatic scrim fades. Default 20. */
+  scrollThreshold?: number;
   /** Opaque gradient color; defaults to the containing surface's fill. */
   scrimColor?: string;
   style?: StyleProp<ViewStyle>;

package/src/page-header/PageHeader.tsx

@@ -24,6 +24,7 @@ import { BUTTON_SHADOW } from '../button/shared';
 import { BloomScope } from "../appearance";
 import { GlassIsland } from '../glass';
 import { RiArrowLeftLine } from '../icons/remix/RiArrowLeftLine';
+import { useScrollMetricsValue } from '../layout/scroll-metrics';
 import { useClaimTopEdge, useScrollOffset } from '../layout';
 import { BREAKPOINTS } from '../styles/breakpoints';
 import { WEB_POSITION_STICKY, WEB_SURFACE_STICKY_TOP, type WebCssStyle } from '../styles/web-view-style';
@@ -186,14 +187,15 @@ function PageHeaderComponent({
 
   // ── The scroll owner ──────────────────────────────────────────────────────
   //
-  // Prop, then Screen, then the nearest ScrollOffsetProvider, then the document on web.
+  // Explicit offset, dock, local metrics, Screen, legacy offset, then the web document.
   // The context step is the one that matters for a Bloom composition: without
   // it a header inside a scrolling panel followed `window.scrollY`, which on a
   // desktop shell never moves, so the header looked deliberately inert.
   const screen = useScreenContext();
   const contextScrollY = useScrollOffset();
+  const metrics = useScrollMetricsValue();
   const internalScrollY = useSharedValue(0);
-  const scrollY = externalScrollY ?? dock?.scrollY ?? screen?.scrollY ?? contextScrollY ?? internalScrollY;
+  const scrollY = externalScrollY ?? dock?.scrollY ?? metrics?.scrollY ?? screen?.scrollY ?? contextScrollY ?? internalScrollY;
   const followsWindow = !externalScrollY && !dock && !screen && !contextScrollY;
 
   useEffect(() => {

package/src/page-header/types.ts

@@ -142,10 +142,9 @@ export interface PageHeaderProps {
   /**
    * The scroll offset driving the scrim, the separator and the shadow.
    *
-   * Resolution order: this prop, then the enclosing `Screen` offset, then the nearest `ScrollOffsetProvider`
-   * (`@oxy.so/bloom/layout`) — which is how a header inside a Bloom scroll
-   * composition gets it with no wiring — then, on web only, `window.scrollY`.
-   * On native with none of the three, the header stays at rest.
+   * Resolution order: this prop, HeaderDockProvider, ScrollMetricsProvider,
+   * the enclosing Screen, then ScrollOffsetProvider. On web with no local
+   * owner it follows window.scrollY; on native it stays at rest.
    */
   scrollY?: SharedValue<number>;
   /** The offset (px) over which the scrim, separator and shadow fade in. Default 20. */