@delacour/react-native-ui 0.3.0-alpha.20261017084646 → 0.3.0-alpha.20261017122152

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.3.0-alpha.20261017084646",
+	"version": "0.3.0-alpha.20261017122152",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -93,6 +93,8 @@
 		"./hooks/use-controllable-state": "./src/hooks/use-controllable-state.ts",
 		"./hooks/use-keyboard-state-sync": "./src/hooks/use-keyboard-state-sync.tsx",
 		"./hooks/use-navigation-theme": "./src/hooks/use-navigation-theme.ts",
+		"./hooks/use-scroll-sections": "./src/hooks/use-scroll-sections.ts",
+		"./hooks/use-scroll-source": "./src/hooks/use-scroll-source.tsx",
 		"./hooks/use-theme-color": "./src/hooks/use-theme-color.ts",
 		"./lib/calm-motion": "./src/lib/calm-motion.ts",
 		"./lib/cn": "./src/lib/cn.ts",
@@ -102,6 +104,9 @@
 		"./lib/merge-props": "./src/lib/merge-props.ts",
 		"./lib/navigation-theme": "./src/lib/navigation-theme.ts",
 		"./lib/paging": "./src/lib/paging.ts",
+		"./lib/scroll-edges": "./src/lib/scroll-edges.ts",
+		"./lib/scroll-maths": "./src/lib/scroll-maths.ts",
+		"./lib/scroll-sections": "./src/lib/scroll-sections.ts",
 		"./lib/slot": "./src/lib/slot.tsx",
 		"./lib/tv": "./src/lib/tv.ts",
 		"./icons/central": "./src/icons/central.ts"

package/src/components/screen/AGENTS.md

@@ -14,6 +14,7 @@ whole-screen states.
 | `index.ts` | → `@registry/ui/screen` |
 | `screen.tsx` | The `Object.assign` compound surface |
 | `screen-root.tsx` | The root box and its provider — see below for why it is split out |
+| `screen-scroll-source.tsx` | The bridge publishing the screen's scroll values as a `ScrollSource` — internal |
 | `screen-navbar.tsx` | `Screen.Navbar`, plus its own nested surface |
 | `screen-navbar-title.tsx` | `Screen.Navbar.Title` |
 | `screen-navbar-subtitle.tsx` | `Screen.Navbar.Subtitle` |
@@ -265,6 +266,16 @@ the first row is still leaving.
 - **A nested `<Screen>` passes the outer context through** rather than shadowing
   it, so `Screen.Loading` returned from inside a screen does not start a second,
   unread set of measurements.
+- **A screen publishes a `ScrollSource`.** `ScreenRoot` mounts
+  `ScreenScrollSourceBridge` inside its provider, which hands the same
+  `scrollY` / `contentHeight` / `layoutHeight` to a `ScrollSourceProvider`
+  (`hooks/use-scroll-source.tsx`) as `offset` / `contentSize` / `layoutSize`,
+  vertical, with no ref. That is what lets the scroll family — `ScrollFade`,
+  `ScrollBlur`, `ScrollCanvas`, `ScrollHeader`; see [The scroll family's shared
+  code](../../../AGENTS.md#the-scroll-familys-shared-code) — work inside a
+  `<Screen>` with no wiring. It adds no handler and no new shared value — the
+  scrollables write exactly what they did — and the import points one way,
+  screen to hook, so installing the hook never pulls `Screen` in after it.
 
 ## Dependencies
 

package/src/components/screen/screen-root.tsx

@@ -2,6 +2,7 @@ import type { ReactElement } from "react";
 import { View, type ViewProps } from "react-native";
 import { ScreenProvider, useScreenContext } from "./screen.context";
 import { screenVariants } from "./screen.variants";
+import { ScreenScrollSourceBridge } from "./screen-scroll-source";
 
 export type ScreenRootProps = ViewProps & {
 	/**
@@ -28,11 +29,15 @@ export function ScreenRoot({ debug = false, className, children, ...props }: Scr
 	// second, unread set of measurements.
 	const parentContext = useScreenContext();
 
+	// The bridge republishes the scroll values as a `ScrollSource`, which is what
+	// lets the scroll family work inside a screen with no wiring.
 	return (
 		<ScreenProvider debug={debug} parentContext={parentContext}>
-			<View className={screenVariants().root({ className })} {...props}>
-				{children}
-			</View>
+			<ScreenScrollSourceBridge>
+				<View className={screenVariants().root({ className })} {...props}>
+					{children}
+				</View>
+			</ScreenScrollSourceBridge>
 		</ScreenProvider>
 	);
 }

package/src/components/screen/screen-scroll-source.tsx

@@ -0,0 +1,38 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { type ScrollSource, ScrollSourceProvider } from "../../hooks/use-scroll-source";
+import { useScreen } from "./screen.context";
+
+export type ScreenScrollSourceBridgeProps = { children: ReactNode };
+
+/**
+ * Publishes the screen's scroll values as a `ScrollSource`, so every
+ * scroll-linked effect — `ScrollFade` and the rest of its family — works inside
+ * a `<Screen>` with no wiring.
+ *
+ * Built from the shared values the screen already holds rather than new ones:
+ * `scrollY` is the offset, `contentHeight` and `layoutHeight` the sizes. Every
+ * Screen scrollable writes those from its own scroll handler, so nothing here
+ * intercepts a scroll event, and `Screen.ScrollShadow` keeps reading the same
+ * values it always did. A Screen body only scrolls vertically, and its
+ * scrollable is whichever one is mounted, so there is no ref to hand on.
+ *
+ * The import runs one way — screen to hook — so installing `useScrollSource`
+ * never drags `Screen` and its peers in after it.
+ */
+export function ScreenScrollSourceBridge({ children }: ScreenScrollSourceBridgeProps): ReactElement {
+	const { scrollY, contentHeight, layoutHeight } = useScreen();
+
+	const source = useMemo<ScrollSource>(
+		() => ({
+			offset: scrollY,
+			contentSize: contentHeight,
+			layoutSize: layoutHeight,
+			orientation: "vertical",
+			ref: null,
+		}),
+		[scrollY, contentHeight, layoutHeight]
+	);
+
+	return <ScrollSourceProvider source={source}>{children}</ScrollSourceProvider>;
+}
+ScreenScrollSourceBridge.displayName = "DelacourUI.Screen.ScrollSourceBridge";

package/src/hooks/use-scroll-sections.ts

@@ -0,0 +1,137 @@
+import { useCallback, useRef, useState } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import type Animated from "react-native-reanimated";
+import {
+	type AnimatedRef,
+	type SharedValue,
+	scrollTo as scrollToWorklet,
+	useAnimatedRef,
+	useAnimatedScrollHandler,
+	useSharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import {
+	resolveActiveSection,
+	resolveScrollProgress,
+	resolveSectionScrollTarget,
+	type SectionOffset,
+} from "../lib/scroll-sections";
+
+export type UseScrollSectionsOptions = {
+	/** Points below the viewport's top where a section counts as entered. Default 0. */
+	readingLine?: number;
+	/** Whether `scrollTo` animates. Default true. */
+	isAnimated?: boolean;
+	/** Fires when the reader crosses into a different section. */
+	onActiveChange?: (id: string) => void;
+};
+
+export type UseScrollSectionsResult = {
+	/** Attach to the `Animated.ScrollView` whose sections are tracked. */
+	scrollRef: AnimatedRef<Animated.ScrollView>;
+	/** Pass as that scroll view's `onScroll`, with `scrollEventThrottle={16}`. */
+	scrollHandler: ReturnType<typeof useAnimatedScrollHandler>;
+	/** `onLayout` for a section's box — a direct child of the scroll content. Stable per id. */
+	register: (id: string) => (event: LayoutChangeEvent) => void;
+	/** The section being read. React state: changes only when the section does. */
+	activeId: string | undefined;
+	/** 0–1, how far down the content the reader is. Updated on the UI thread. */
+	progress: SharedValue<number>;
+	/** The raw scroll offset. */
+	scrollY: SharedValue<number>;
+	/** Scrolls a section's top onto the reading line and makes it active at once. */
+	scrollTo: (id: string) => void;
+};
+
+/**
+ * Tracks which section of a scroll view the reader is in, and how far down they are, on the
+ * UI thread. `SectionProgress` and `SectionRail` read it; any custom table of contents can too.
+ *
+ * The scroll handler resolves the active section every frame but crosses to React only when it
+ * changes, so a scroll costs no renders. A `scrollTo` pins the target as active until the scroll
+ * arrives there (or the reader drags), so a jump from the first section to the last does not
+ * flick the label through every section in between.
+ *
+ * Offsets come from each section's `onLayout`, which reports `y` relative to the parent — so a
+ * registered section must be a direct child of the scroll content.
+ */
+export function useScrollSections({
+	readingLine = 0,
+	isAnimated = true,
+	onActiveChange,
+}: UseScrollSectionsOptions = {}): UseScrollSectionsResult {
+	const scrollRef = useAnimatedRef<Animated.ScrollView>();
+	const sections = useSharedValue<SectionOffset[]>([]);
+	const scrollY = useSharedValue(0);
+	const progress = useSharedValue(0);
+	const lastActive = useSharedValue<string | undefined>(undefined);
+	const pinned = useSharedValue<string | undefined>(undefined);
+	const [activeId, setActiveId] = useState<string | undefined>(undefined);
+
+	const report = useCallback(
+		(id: string) => {
+			setActiveId(id);
+			onActiveChange?.(id);
+		},
+		[onActiveChange]
+	);
+
+	const scrollHandler = useAnimatedScrollHandler({
+		onBeginDrag: () => {
+			pinned.value = undefined;
+		},
+		onScroll: (event) => {
+			const y = event.contentOffset.y;
+			scrollY.value = y;
+			progress.value = resolveScrollProgress(y, event.contentSize.height, event.layoutMeasurement.height);
+			const next = resolveActiveSection(sections.value, y, readingLine);
+			if (pinned.value !== undefined) {
+				if (next !== pinned.value) return;
+				pinned.value = undefined;
+			}
+			if (next !== undefined && next !== lastActive.value) {
+				lastActive.value = next;
+				scheduleOnRN(report, next);
+			}
+		},
+	});
+
+	const handlers = useRef(new Map<string, (event: LayoutChangeEvent) => void>());
+	const register = useCallback(
+		(id: string) => {
+			const cached = handlers.current.get(id);
+			if (cached) return cached;
+			const handler = (event: LayoutChangeEvent) => {
+				const y = event.nativeEvent.layout.y;
+				sections.modify((list) => {
+					"worklet";
+					const index = list.findIndex((section) => section.id === id);
+					if (index === -1) list.push({ id, y });
+					else list[index] = { id, y };
+					return list;
+				});
+			};
+			handlers.current.set(id, handler);
+			return handler;
+		},
+		[sections]
+	);
+
+	const scrollTo = useCallback(
+		(id: string) => {
+			const section = sections.value.find((candidate) => candidate.id === id);
+			if (section === undefined) return;
+			const target = resolveSectionScrollTarget(section.y, readingLine);
+			pinned.value = id;
+			lastActive.value = id;
+			report(id);
+			scheduleOnUI(() => {
+				"worklet";
+				scrollToWorklet(scrollRef, 0, target, isAnimated);
+			});
+		},
+		[isAnimated, lastActive, pinned, readingLine, report, scrollRef, sections]
+	);
+
+	return { scrollRef, scrollHandler, register, activeId, progress, scrollY, scrollTo };
+}

package/src/hooks/use-scroll-source.tsx

@@ -0,0 +1,173 @@
+import { createContext, type ReactElement, type ReactNode, use, useCallback, useMemo } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import {
+	type AnimatedRef,
+	type SharedValue,
+	useAnimatedRef,
+	useAnimatedScrollHandler,
+	useSharedValue,
+} from "react-native-reanimated";
+import { readScrollEvent, type ScrollEventFields, type ScrollOrientation } from "../lib/scroll-maths";
+
+export type { ScrollEventFields, ScrollOrientation } from "../lib/scroll-maths";
+
+/** Everything a scroll-linked effect reads, all of it on the UI thread. */
+export type ScrollSource = {
+	/** Scroll offset along `orientation`; negative while rubber-banding at the start. */
+	offset: SharedValue<number>;
+	/** Content extent along `orientation`; 0 until measured. */
+	contentSize: SharedValue<number>;
+	/** Viewport extent along `orientation`; 0 until measured. */
+	layoutSize: SharedValue<number>;
+	orientation: ScrollOrientation;
+	/**
+	 * Present when the source came from `useScrollSource`; null from a Screen.
+	 * Lets an effect `measureLayout` against the scroller.
+	 */
+	ref: AnimatedRef | null;
+};
+
+export type UseScrollSourceOptions = {
+	/** @default "vertical" */
+	orientation?: ScrollOrientation;
+	/** Worklets composed after the source has written its values. */
+	onBeginDrag?: (event: ScrollEventFields) => void;
+	onEndDrag?: (event: ScrollEventFields) => void;
+	onMomentumBegin?: (event: ScrollEventFields) => void;
+	onMomentumEnd?: (event: ScrollEventFields) => void;
+};
+
+/** Props to spread onto an `Animated.ScrollView` / `Animated.FlatList` / `Animated.SectionList`. */
+export type ScrollSourceProps = {
+	ref: AnimatedRef;
+	onScroll: ReturnType<typeof useAnimatedScrollHandler>;
+	onLayout: (event: LayoutChangeEvent) => void;
+	onContentSizeChange: (width: number, height: number) => void;
+	scrollEventThrottle: 16;
+};
+
+export type UseScrollSourceResult = { source: ScrollSource; scrollProps: ScrollSourceProps };
+
+/**
+ * A scroll source for a scrollable that is not a `Screen` body — a horizontal
+ * card row, a list inside a card, a sheet body — and the props that feed it.
+ *
+ * **Spread `scrollProps` onto the scrollable; nothing clones it for you.** A
+ * wrapper that cloned its child to attach `onScroll` would collide with
+ * Reanimated's handler composition and with every handler a scrollable already
+ * owns. Spread them last, or compose your own `onLayout` with them by hand.
+ *
+ * **Sizes are measured on layout, not only on scroll.** `onLayout` and
+ * `onContentSizeChange` write `layoutSize` and `contentSize` as soon as the
+ * scrollable lays out, so an effect over a list too short to scroll is right
+ * before anyone touches it — a `Screen`'s source cannot do that, and an edge
+ * fade over a short Screen body waits for the first scroll event.
+ *
+ * `orientation` is fixed here, by whoever creates the source, so no effect can
+ * disagree with the scroller about which axis it moves on.
+ *
+ * @example
+ * const { source, scrollProps } = useScrollSource({ orientation: "horizontal" });
+ *
+ * <ScrollFade scrollSource={source}>
+ *   <Animated.ScrollView horizontal {...scrollProps}>{cards}</Animated.ScrollView>
+ * </ScrollFade>
+ */
+export function useScrollSource(options: UseScrollSourceOptions = {}): UseScrollSourceResult {
+	const { orientation = "vertical", onBeginDrag, onEndDrag, onMomentumBegin, onMomentumEnd } = options;
+	const ref = useAnimatedRef();
+	const offset = useSharedValue(0);
+	const contentSize = useSharedValue(0);
+	const layoutSize = useSharedValue(0);
+
+	const onScroll = useAnimatedScrollHandler(
+		{
+			onScroll: (event) => {
+				const reading = readScrollEvent(event, orientation);
+				offset.value = reading.offset;
+				if (reading.contentSize !== contentSize.value) contentSize.value = reading.contentSize;
+				if (reading.layoutSize !== layoutSize.value) layoutSize.value = reading.layoutSize;
+			},
+			onBeginDrag: (event) => {
+				offset.value = readScrollEvent(event, orientation).offset;
+				onBeginDrag?.(event);
+			},
+			onEndDrag: (event) => {
+				offset.value = readScrollEvent(event, orientation).offset;
+				onEndDrag?.(event);
+			},
+			onMomentumBegin: (event) => {
+				offset.value = readScrollEvent(event, orientation).offset;
+				onMomentumBegin?.(event);
+			},
+			onMomentumEnd: (event) => {
+				offset.value = readScrollEvent(event, orientation).offset;
+				onMomentumEnd?.(event);
+			},
+		},
+		[orientation, onBeginDrag, onEndDrag, onMomentumBegin, onMomentumEnd]
+	);
+
+	const onLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const { width, height } = event.nativeEvent.layout;
+			layoutSize.value = orientation === "horizontal" ? width : height;
+		},
+		[orientation, layoutSize]
+	);
+
+	const onContentSizeChange = useCallback(
+		(width: number, height: number) => {
+			contentSize.value = orientation === "horizontal" ? width : height;
+		},
+		[orientation, contentSize]
+	);
+
+	return useMemo(
+		() => ({
+			source: { offset, contentSize, layoutSize, orientation, ref },
+			scrollProps: { ref, onScroll, onLayout, onContentSizeChange, scrollEventThrottle: 16 },
+		}),
+		[offset, contentSize, layoutSize, orientation, ref, onScroll, onLayout, onContentSizeChange]
+	);
+}
+
+const ScrollSourceContext = createContext<ScrollSource | null>(null);
+
+export type ScrollSourceProviderProps = {
+	source: ScrollSource;
+	children: ReactNode;
+};
+
+/**
+ * Publishes a scroll source to every scroll-linked effect beneath it, so none
+ * of them needs a `scrollSource` prop. A `Screen` mounts one around its body
+ * already; mount one by hand to share a single scrollable's source with several
+ * effects, or with an effect a few components away from the list.
+ */
+export function ScrollSourceProvider({ source, children }: ScrollSourceProviderProps): ReactElement {
+	return <ScrollSourceContext value={source}>{children}</ScrollSourceContext>;
+}
+ScrollSourceProvider.displayName = "DelacourUI.ScrollSourceProvider";
+
+/** The nearest provider's source, or null. For an effect that can work without one. */
+export function useScrollSourceContext(): ScrollSource | null {
+	return use(ScrollSourceContext);
+}
+
+/**
+ * The source a scroll-linked effect follows: the one it was given, else the
+ * nearest `ScrollSourceProvider` (a `Screen` counts), else a thrown error
+ * naming the component — an effect with nothing to follow would silently draw
+ * its resting state forever.
+ */
+export function useResolvedScrollSource(component: string, explicit?: ScrollSource): ScrollSource {
+	const ambient = useScrollSourceContext();
+	const source = explicit ?? ambient;
+	if (!source) {
+		throw new Error(
+			`\`${component}\` must be given a \`scrollSource\` or rendered inside a Screen / ScrollSourceProvider.`
+		);
+	}
+	return source;
+}

package/src/lib/scroll-edges.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { resolveFadeBand, resolveFadeEdges, resolveFadeGradient, SCROLL_EDGES, type ScrollEdges } from "./scroll-edges";
+
+describe("resolveFadeEdges", () => {
+	const EXPECTED: Record<ScrollEdges, { start: boolean; end: boolean }> = {
+		both: { start: true, end: true },
+		start: { start: true, end: false },
+		end: { start: false, end: true },
+		none: { start: false, end: false },
+	};
+
+	for (const edges of SCROLL_EDGES) {
+		test(`${edges} draws ${JSON.stringify(EXPECTED[edges])}`, () => {
+			expect(resolveFadeEdges(edges)).toEqual(EXPECTED[edges]);
+		});
+	}
+});
+
+describe("resolveFadeBand", () => {
+	test("a vertical start band holds its inset from the top", () => {
+		expect(resolveFadeBand({ orientation: "vertical", edge: "start", size: 48, inset: 10 })).toStrictEqual({
+			top: 10,
+			height: 48,
+		});
+	});
+
+	test("a vertical end band sits on the bottom", () => {
+		expect(resolveFadeBand({ orientation: "vertical", edge: "end", size: 48, inset: 0 })).toStrictEqual({
+			bottom: 0,
+			height: 48,
+		});
+	});
+
+	test("a horizontal start band sits on the left", () => {
+		expect(resolveFadeBand({ orientation: "horizontal", edge: "start", size: 48, inset: 0 })).toStrictEqual({
+			left: 0,
+			width: 48,
+		});
+	});
+
+	test("a horizontal end band holds its inset from the right", () => {
+		expect(resolveFadeBand({ orientation: "horizontal", edge: "end", size: 48, inset: 6 })).toStrictEqual({
+			right: 6,
+			width: 48,
+		});
+	});
+});
+
+describe("resolveFadeGradient", () => {
+	test("vertical start runs top to bottom", () => {
+		expect(resolveFadeGradient({ orientation: "vertical", edge: "start" })).toEqual({
+			start: { x: 0, y: 0 },
+			end: { x: 0, y: 1 },
+		});
+	});
+
+	test("vertical end runs bottom to top", () => {
+		expect(resolveFadeGradient({ orientation: "vertical", edge: "end" })).toEqual({
+			start: { x: 0, y: 1 },
+			end: { x: 0, y: 0 },
+		});
+	});
+
+	test("horizontal start runs left to right", () => {
+		expect(resolveFadeGradient({ orientation: "horizontal", edge: "start" })).toEqual({
+			start: { x: 0, y: 0 },
+			end: { x: 1, y: 0 },
+		});
+	});
+
+	test("horizontal end runs right to left", () => {
+		expect(resolveFadeGradient({ orientation: "horizontal", edge: "end" })).toEqual({
+			start: { x: 1, y: 0 },
+			end: { x: 0, y: 0 },
+		});
+	});
+});

package/src/lib/scroll-edges.ts

@@ -0,0 +1,81 @@
+/**
+ * The pure geometry of an affordance drawn at a scrollable's edges — where each
+ * band sits and which way its gradient runs. `ScrollFade` paints a gradient in
+ * these bands and `ScrollBlur` a blur, so the geometry lives here rather than in
+ * either component's folder, and neither has to import the other.
+ *
+ * Every function is a self-contained worklet, for the reason `scroll-maths.ts`
+ * gives: a helper called from inside a worklet can be missing from its closure
+ * on the UI thread. Free of React Native imports, so `bun test` reaches it all.
+ */
+
+import type { ScrollEdge, ScrollOrientation } from "./scroll-maths";
+
+/** Which edges of a scrollable draw an affordance. */
+export const SCROLL_EDGES = ["both", "start", "end", "none"] as const;
+export type ScrollEdges = (typeof SCROLL_EDGES)[number];
+
+/** Whether each edge draws a band at all. */
+export function resolveFadeEdges(edges: ScrollEdges): { start: boolean; end: boolean } {
+	"worklet";
+	return {
+		start: edges === "both" || edges === "start",
+		end: edges === "both" || edges === "end",
+	};
+}
+
+/** The placement of one band, as absolute-position style props. Only the keys that apply are present. */
+export type FadeBandStyle =
+	| { top: number; height: number }
+	| { bottom: number; height: number }
+	| { left: number; width: number }
+	| { right: number; width: number };
+
+export type FadeBandInput = {
+	orientation: ScrollOrientation;
+	edge: ScrollEdge;
+	/** Depth in points along the scroll axis. */
+	size: number;
+	/** Points to hold the band in from its edge. */
+	inset: number;
+};
+
+/**
+ * Where one band sits: pinned `inset` points in from its edge, `size` deep
+ * along the scroll axis. The band spans the other axis through its class
+ * (`inset-x-0` / `inset-y-0`), not through this style.
+ *
+ * `start` and `end` follow the scroll axis in layout space — top and bottom,
+ * left and right — so they do not flip under right-to-left on their own.
+ */
+export function resolveFadeBand({ orientation, edge, size, inset }: FadeBandInput): FadeBandStyle {
+	"worklet";
+	if (orientation === "vertical") {
+		return edge === "start" ? { top: inset, height: size } : { bottom: inset, height: size };
+	}
+
+	return edge === "start" ? { left: inset, width: size } : { right: inset, width: size };
+}
+
+/** A gradient's direction, in the unit square `expo-linear-gradient` takes. */
+export type FadeGradientVector = { start: { x: number; y: number }; end: { x: number; y: number } };
+
+/**
+ * The direction of one band's gradient: from its own edge, where the colour is
+ * solid, inward to where it has faded out. A blur mask runs the same way.
+ */
+export function resolveFadeGradient({
+	orientation,
+	edge,
+}: {
+	orientation: ScrollOrientation;
+	edge: ScrollEdge;
+}): FadeGradientVector {
+	"worklet";
+	const near = edge === "start" ? 0 : 1;
+	const far = 1 - near;
+
+	if (orientation === "vertical") return { start: { x: 0, y: near }, end: { x: 0, y: far } };
+
+	return { start: { x: near, y: 0 }, end: { x: far, y: 0 } };
+}

package/src/lib/scroll-maths.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import { readScrollEvent, type ScrollEdge, scrollEdgeOpacity, scrollProgress } from "./scroll-maths";
+
+type EdgeCase = {
+	edge: ScrollEdge;
+	offset: number;
+	contentSize: number;
+	layoutSize: number;
+	fadeInDistance: number;
+	expected: number;
+	why: string;
+};
+
+const EDGE_CASES: readonly EdgeCase[] = [
+	{ edge: "start", offset: 0, contentSize: 1000, layoutSize: 600, fadeInDistance: 24, expected: 0, why: "at rest" },
+	{
+		edge: "start",
+		offset: 12,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 24,
+		expected: 0.5,
+		why: "halfway in",
+	},
+	{ edge: "start", offset: 100, contentSize: 1000, layoutSize: 600, fadeInDistance: 24, expected: 1, why: "fully in" },
+	{
+		edge: "start",
+		offset: -30,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 24,
+		expected: 0,
+		why: "rubber-banding past the start",
+	},
+	{ edge: "end", offset: 0, contentSize: 1000, layoutSize: 600, fadeInDistance: 24, expected: 1, why: "at rest" },
+	{
+		edge: "end",
+		offset: 388,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 24,
+		expected: 0.5,
+		why: "halfway out",
+	},
+	{ edge: "end", offset: 400, contentSize: 1000, layoutSize: 600, fadeInDistance: 24, expected: 0, why: "at the end" },
+	{
+		edge: "end",
+		offset: 430,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 24,
+		expected: 0,
+		why: "bouncing past the end",
+	},
+	{
+		edge: "start",
+		offset: 50,
+		contentSize: 300,
+		layoutSize: 600,
+		fadeInDistance: 24,
+		expected: 0,
+		why: "short content",
+	},
+	{ edge: "end", offset: 50, contentSize: 300, layoutSize: 600, fadeInDistance: 24, expected: 0, why: "short content" },
+	{ edge: "start", offset: 0, contentSize: 0, layoutSize: 0, fadeInDistance: 24, expected: 0, why: "unmeasured" },
+	{ edge: "end", offset: 0, contentSize: 0, layoutSize: 0, fadeInDistance: 24, expected: 1, why: "unmeasured" },
+	{
+		edge: "start",
+		offset: 0.5,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 0,
+		expected: 1,
+		why: "a step, moved",
+	},
+	{
+		edge: "start",
+		offset: 0,
+		contentSize: 1000,
+		layoutSize: 600,
+		fadeInDistance: 0,
+		expected: 0,
+		why: "a step, at rest",
+	},
+];
+
+describe("scrollEdgeOpacity", () => {
+	for (const { expected, why, ...state } of EDGE_CASES) {
+		test(`${state.edge} at ${state.offset} (${why}) is ${expected}`, () => {
+			expect(scrollEdgeOpacity(state)).toBeCloseTo(expected, 6);
+		});
+	}
+
+	// A Screen's source only learns its sizes from a scroll event, so a tall
+	// list must show its end fade at rest — while the start still follows the
+	// finger, since the offset is real even before the sizes are.
+	test("an unmeasured start still follows the offset", () => {
+		expect(scrollEdgeOpacity({ edge: "start", offset: 12, contentSize: 0, layoutSize: 0, fadeInDistance: 24 })).toBe(
+			0.5
+		);
+		expect(scrollEdgeOpacity({ edge: "end", offset: 12, contentSize: 800, layoutSize: 0, fadeInDistance: 24 })).toBe(1);
+	});
+
+	test("a step at the end is in until the last point", () => {
+		const base = { edge: "end", contentSize: 1000, layoutSize: 600, fadeInDistance: 0 } as const;
+		expect(scrollEdgeOpacity({ ...base, offset: 399.5 })).toBe(1);
+		expect(scrollEdgeOpacity({ ...base, offset: 400 })).toBe(0);
+	});
+
+	test("content exactly the viewport's size fades neither edge", () => {
+		const base = { offset: 0, contentSize: 600, layoutSize: 600, fadeInDistance: 24 } as const;
+		expect(scrollEdgeOpacity({ ...base, edge: "start" })).toBe(0);
+		expect(scrollEdgeOpacity({ ...base, edge: "end" })).toBe(0);
+	});
+});
+
+describe("scrollProgress", () => {
+	test.each([
+		[5, 0, 10, 0.5],
+		[-5, 0, 10, 0],
+		[15, 0, 10, 1],
+		[3, 10, 0, 0.7],
+		[5, 5, 5, 1],
+		[4, 5, 5, 0],
+	])("(%p, %p, %p) is %p", (value, from, to, expected) => {
+		expect(scrollProgress(value, from, to)).toBeCloseTo(expected, 6);
+	});
+});
+
+describe("readScrollEvent", () => {
+	const event = {
+		contentOffset: { x: 30, y: -12 },
+		contentSize: { width: 900, height: 1400 },
+		layoutMeasurement: { width: 390, height: 700 },
+	};
+
+	test("reads y and heights on a vertical scroller", () => {
+		expect(readScrollEvent(event, "vertical")).toEqual({ offset: -12, contentSize: 1400, layoutSize: 700 });
+	});
+
+	test("reads x and widths on a horizontal scroller", () => {
+		expect(readScrollEvent(event, "horizontal")).toEqual({ offset: 30, contentSize: 900, layoutSize: 390 });
+	});
+
+	test("passes a negative offset through", () => {
+		const bounce = { ...event, contentOffset: { x: -40, y: 0 } };
+		expect(readScrollEvent(bounce, "horizontal").offset).toBe(-40);
+	});
+});

package/src/lib/scroll-maths.ts

@@ -0,0 +1,114 @@
+/**
+ * The pure maths behind the scroll-linked components — `ScrollFade` and the
+ * effects that build on `useScrollSource`.
+ *
+ * **Every function here is a self-contained worklet.** A module-scope helper
+ * called from inside a worklet can be missing from that worklet's closure on
+ * the UI thread, which surfaces as `undefined is not a function` mid-scroll and
+ * is invisible to `bun test`. So each function writes its own clamp inline and
+ * none of them calls another — do not "tidy" the repetition into a helper.
+ *
+ * Free of React Native imports, so the whole table is reachable from `bun test`.
+ */
+
+/** The axis a scrollable moves along. */
+export type ScrollOrientation = "vertical" | "horizontal";
+
+/** One end of a scrollable, along its own axis — top or left is `start`. */
+export type ScrollEdge = "start" | "end";
+
+/** The scroll-event fields a handler worklet receives, narrowed to what the scroll family reads. */
+export type ScrollEventFields = {
+	contentOffset: { x: number; y: number };
+	contentSize: { width: number; height: number };
+	layoutMeasurement: { width: number; height: number };
+	velocity?: { x: number; y: number };
+};
+
+/** One scroll event, read along one axis. */
+export type ScrollReading = { offset: number; contentSize: number; layoutSize: number };
+
+/**
+ * The offset and sizes of a scroll event along `orientation` — `y` and heights
+ * vertically, `x` and widths horizontally.
+ *
+ * A negative offset passes through untouched: it is the rubber band at the
+ * start, and an effect that wants to stretch with it needs to see it.
+ */
+export function readScrollEvent(event: ScrollEventFields, orientation: ScrollOrientation): ScrollReading {
+	"worklet";
+	if (orientation === "horizontal") {
+		return {
+			offset: event.contentOffset.x,
+			contentSize: event.contentSize.width,
+			layoutSize: event.layoutMeasurement.width,
+		};
+	}
+
+	return {
+		offset: event.contentOffset.y,
+		contentSize: event.contentSize.height,
+		layoutSize: event.layoutMeasurement.height,
+	};
+}
+
+export type ScrollEdgeState = {
+	edge: ScrollEdge;
+	offset: number;
+	contentSize: number;
+	layoutSize: number;
+	/** Points of travel from fully clear to fully in. 0 makes it a step. */
+	fadeInDistance: number;
+};
+
+/**
+ * The 0..1 opacity of an affordance at one edge of a scrollable — a fade, a
+ * blur, a hairline — which is in exactly while there is content past that edge.
+ *
+ * - **start** is clear at rest and arrives over the first `fadeInDistance`
+ *   points of travel. Rubber-banding past the start keeps it clear.
+ * - **end** is in at rest and leaves over the last `fadeInDistance` points.
+ *   Bouncing past the end keeps it clear.
+ * - **Short content** — no further to scroll — clears both: an edge that
+ *   promises content which does not exist is worse than a hard edge.
+ * - **Unmeasured** — either size still 0 — lets the start follow the offset
+ *   and draws the end. A `Screen`'s source learns its sizes only from the first
+ *   scroll event, and a tall list must show its end fade at rest.
+ */
+export function scrollEdgeOpacity(state: ScrollEdgeState): number {
+	"worklet";
+	const { edge, offset, contentSize, layoutSize, fadeInDistance } = state;
+	const isMeasured = contentSize > 0 && layoutSize > 0;
+	const maxScroll = contentSize - layoutSize;
+
+	if (isMeasured && maxScroll <= 0) return 0;
+
+	// Points of content past this edge.
+	let past: number;
+	if (edge === "start") {
+		past = offset;
+	} else {
+		if (!isMeasured) return 1;
+		past = maxScroll - offset;
+	}
+
+	if (fadeInDistance <= 0) return past > 0 ? 1 : 0;
+
+	const ratio = past / fadeInDistance;
+	return ratio < 0 ? 0 : ratio > 1 ? 1 : ratio;
+}
+
+/**
+ * Where `value` sits between `from` and `to`, as a clamped 0..1.
+ *
+ * `from` may exceed `to` — the ramp then runs downward, which is how an effect
+ * that leaves as the scroll arrives is written. With `from === to` it is a
+ * step: 1 at or past the point, 0 before it.
+ */
+export function scrollProgress(value: number, from: number, to: number): number {
+	"worklet";
+	if (from === to) return value >= to ? 1 : 0;
+
+	const ratio = (value - from) / (to - from);
+	return ratio < 0 ? 0 : ratio > 1 ? 1 : ratio;
+}

package/src/lib/scroll-sections.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { resolveActiveSection, resolveScrollProgress, resolveSectionScrollTarget } from "./scroll-sections";
+
+const sections = [
+	{ id: "intro", y: 0 },
+	{ id: "setup", y: 400 },
+	{ id: "usage", y: 1000 },
+];
+
+describe("resolveActiveSection", () => {
+	test("returns undefined with no sections", () => {
+		expect(resolveActiveSection([], 100, 0)).toBeUndefined();
+	});
+
+	test("picks the last section whose top has crossed the reading line", () => {
+		expect(resolveActiveSection(sections, 0, 0)).toBe("intro");
+		expect(resolveActiveSection(sections, 399, 0)).toBe("intro");
+		expect(resolveActiveSection(sections, 400, 0)).toBe("setup");
+		expect(resolveActiveSection(sections, 2000, 0)).toBe("usage");
+	});
+
+	test("the reading line moves the switch earlier", () => {
+		expect(resolveActiveSection(sections, 304, 96)).toBe("setup");
+		expect(resolveActiveSection(sections, 303, 96)).toBe("intro");
+	});
+
+	test("above the first section reads as the first section", () => {
+		expect(resolveActiveSection([{ id: "a", y: 200 }], 0, 0)).toBe("a");
+		expect(resolveActiveSection(sections, -80, 0)).toBe("intro");
+	});
+
+	test("reads sections in offset order, not registration order", () => {
+		const shuffled = [sections[2], sections[0], sections[1]].filter((s) => s !== undefined);
+		expect(resolveActiveSection(shuffled, 500, 0)).toBe("setup");
+	});
+});
+
+describe("resolveScrollProgress", () => {
+	test("is 0 at the top and 1 at the end", () => {
+		expect(resolveScrollProgress(0, 2000, 800)).toBe(0);
+		expect(resolveScrollProgress(1200, 2000, 800)).toBe(1);
+		expect(resolveScrollProgress(600, 2000, 800)).toBe(0.5);
+	});
+
+	test("clamps overscroll at both ends", () => {
+		expect(resolveScrollProgress(-50, 2000, 800)).toBe(0);
+		expect(resolveScrollProgress(1500, 2000, 800)).toBe(1);
+	});
+
+	test("is 1 when nothing scrolls", () => {
+		expect(resolveScrollProgress(0, 500, 800)).toBe(1);
+		expect(resolveScrollProgress(0, 800, 800)).toBe(1);
+	});
+});
+
+describe("resolveSectionScrollTarget", () => {
+	test("puts the section's top on the reading line", () => {
+		expect(resolveSectionScrollTarget(400, 96)).toBe(304);
+	});
+
+	test("never scrolls above the top", () => {
+		expect(resolveSectionScrollTarget(40, 96)).toBe(0);
+	});
+});

package/src/lib/scroll-sections.ts

@@ -0,0 +1,44 @@
+/** A section of a scrolled screen: its id and the top of its box in content coordinates. */
+export type SectionOffset = { id: string; y: number };
+
+/**
+ * The section the reader is in: the last one whose top has crossed the reading line, a fixed
+ * distance below the top of the viewport. Above the first section's top the first section is
+ * still the answer — a screen with a header before its first section is reading that section.
+ *
+ * Sections are read in offset order, not registration order: `onLayout` reports in whatever
+ * order the native views measure, and a section mounted late would otherwise win the tie.
+ */
+export function resolveActiveSection(
+	sections: readonly SectionOffset[],
+	scrollY: number,
+	readingLine: number
+): string | undefined {
+	"worklet";
+	if (sections.length === 0) return undefined;
+	const line = scrollY + readingLine;
+	let first: SectionOffset | undefined;
+	let active: SectionOffset | undefined;
+	for (const section of sections) {
+		if (first === undefined || section.y < first.y) first = section;
+		if (section.y <= line && (active === undefined || section.y >= active.y)) active = section;
+	}
+	return (active ?? first)?.id;
+}
+
+/**
+ * How far down the content the reader is, 0 to 1. Overscroll clamps at both ends, and a screen
+ * whose content fits reads as finished — there is nothing left to read.
+ */
+export function resolveScrollProgress(scrollY: number, contentHeight: number, viewportHeight: number): number {
+	"worklet";
+	const range = contentHeight - viewportHeight;
+	if (range <= 0) return 1;
+	return Math.min(1, Math.max(0, scrollY / range));
+}
+
+/** The scroll offset that puts a section's top on the reading line, never above the top. */
+export function resolveSectionScrollTarget(y: number, readingLine: number): number {
+	"worklet";
+	return Math.max(0, y - readingLine);
+}