phase 0.1.0 → 0.3.0

package/README.md

@@ -238,15 +238,15 @@ createLoop({
 
 #### Loop options
 
-| Option          | Type                                | Default      | Description                               |
-| --------------- | ----------------------------------- | ------------ | ----------------------------------------- |
-| `target`        | `Element`                           | required     | Element to observe for visibility         |
-| `onTick`        | `(frame: FrameState) => void`       | required     | Called each frame while running           |
-| `fps`           | `number`                            | —            | Cap frames per second                     |
-| `reducedMotion` | `'pause' \| 'complete' \| 'ignore'` | `'pause'`    | Behavior when user prefers reduced motion |
-| `degraded`      | `'throttle' \| 'pause' \| 'ignore'` | `'throttle'` | Behavior when quality degrades            |
-| `degradedFps`   | `number`                            | `30`         | FPS cap in degraded throttle mode         |
-| `onPhaseChange` | `(phase, reason) => void`           | —            | Called on every phase transition          |
+| Option          | Type                                | Default      | Description                                                   |
+| --------------- | ----------------------------------- | ------------ | ------------------------------------------------------------- |
+| `target`        | `Element \| Document`               | required     | Element to observe for visibility, or `document` for the page |
+| `onTick`        | `(frame: FrameState) => void`       | required     | Called each frame while running                               |
+| `fps`           | `number`                            | —            | Cap frames per second                                         |
+| `reducedMotion` | `'pause' \| 'complete' \| 'ignore'` | `'pause'`    | Behavior when user prefers reduced motion                     |
+| `degraded`      | `'throttle' \| 'pause' \| 'ignore'` | `'throttle'` | Behavior when quality degrades                                |
+| `degradedFps`   | `number`                            | `30`         | FPS cap in degraded throttle mode                             |
+| `onPhaseChange` | `(phase, reason) => void`           | —            | Called on every phase transition                              |
 
 ### createTicker
 
@@ -337,7 +337,7 @@ Pause priority is `reduced-motion` > `sight` > `manual`.
 
 Reports what fraction of an element is currently visible in the viewport (0–1), via the shared IntersectionObserver pool. Zero forced reflows, zero extra observers. Ideal for reveal/opacity effects.
 
-> **Visibility ratio, not scroll offset.** This reports `intersectionRatio` (how much of an element is visible in the viewport), which plateaus for tall elements once they fill it. For a scroll container's _own_ offset (scrollbars, carousels) use [`createScroll`](#createscroll); for CSS-declarative scroll-linked animation use the native `ScrollTimeline` API; for spring/gesture scroll use `motion`.
+> **Visibility ratio, not scroll offset.** This reports `intersectionRatio` (how much of an element is visible in the viewport), which plateaus for tall elements once they fill it. For a scroll container's _own_ offset (scrollbars, carousels, or the page via `target: 'page'` on the hook) use [`createScroll`](#createscroll); for CSS-declarative scroll-linked animation use the native `ScrollTimeline` API; for spring/gesture scroll use `motion`.
 
 ```ts
 import { createScrollProgress } from 'phase';
@@ -359,17 +359,17 @@ The `steps` option controls threshold granularity. Default `20` generates 21 eve
 
 #### ScrollProgress options
 
-| Option       | Type                          | Default  | Description                        |
-| ------------ | ----------------------------- | -------- | ---------------------------------- |
-| `target`     | `Element`                     | required | Element to observe                 |
-| `onProgress` | `(ratio: number) => void`     | required | Called at each threshold crossing  |
-| `steps`      | `number`                      | `20`     | Number of evenly-spaced thresholds |
-| `root`       | `Element \| Document \| null` | —        | IO root element                    |
-| `rootMargin` | `string`                      | —        | IO root margin                     |
+| Option       | Type                          | Default  | Description                                    |
+| ------------ | ----------------------------- | -------- | ---------------------------------------------- |
+| `target`     | `Element \| Document`         | required | Element to observe, or `document` for the page |
+| `onProgress` | `(ratio: number) => void`     | required | Called at each threshold crossing              |
+| `steps`      | `number`                      | `20`     | Number of evenly-spaced thresholds             |
+| `root`       | `Element \| Document \| null` | —        | IO root element                                |
+| `rootMargin` | `string`                      | —        | IO root margin                                 |
 
 ### createScroll
 
-Tracks a scroll container's offset and progress. Reads `scrollLeft`/`scrollTop` once per rAF frame and reads the reflow-heavy geometry (`scrollWidth`/`clientWidth`) only on resize or explicit `measure()`, never on the scroll path. Auto-pauses off-screen via the shared IntersectionObserver pool. This is to `scroll` + `scrollWidth` what `createPointer` is to `pointermove` + `getBoundingClientRect`.
+Tracks a scroll container's offset and progress. Reads `scrollLeft`/`scrollTop` once per rAF frame and reads the reflow-heavy geometry (`scrollWidth`/`clientWidth`) only on a coalesced resize or an explicit `measure()`, never on the scroll path. Auto-pauses off-screen via the shared IntersectionObserver pool. This is to `scroll` + `scrollWidth` what `createPointer` is to `pointermove` + `getBoundingClientRect`.
 
 > **Scroll offset, not visibility ratio.** This reports the element's own scroll position (for scrollbars, carousels, position indicators). For _how much of an element is in the viewport_, use [`createScrollProgress`](#createscrollprogress); for CSS-declarative scroll-linked animation, use the native `ScrollTimeline` API.
 
@@ -401,7 +401,7 @@ scroll.stop();
 
 | Option                | Type                           | Default   | Description                                        |
 | --------------------- | ------------------------------ | --------- | -------------------------------------------------- |
-| `target`              | `Element`                      | required  | Scroll container to track                          |
+| `target`              | `Element \| Document`          | required  | Scroll container, or `document` for the page       |
 | `onScroll`            | `(state: ScrollState) => void` | required  | Called once per rAF frame with position + progress |
 | `onPhaseChange`       | `(phase, reason) => void`      | —         | Called on phase transitions                        |
 | `visibility`          | `'pause' \| 'ignore'`          | `'pause'` | Pause tracking when off-screen, or ignore          |
@@ -410,6 +410,8 @@ scroll.stop();
 
 The options type is `CreateScrollOptions` (`ScrollOptions` is a `lib.dom` global and must not be shadowed).
 
+Pass `document` to track the page scroller. Offsets and geometry then come from `document.scrollingElement`, and since the page is never off-screen, `visibility: 'pause'` reacts to tab visibility alone and creates no `IntersectionObserver`. Use it for scroll progress bars, condensing headers, and scroll-to-top affordances instead of a bare `window` scroll listener.
+
 ### createThrottle
 
 Frame-aligned, visibility-aware throttle for event-driven work below frame rate (socket emits, worker messaging, expensive recompute). Leading calls fire synchronously; a pending trailing call fires with the latest value on the first animation frame at or past `interval`. Nothing is scheduled while the trigger is idle or the document is hidden.
@@ -1209,13 +1211,14 @@ Every error includes a machine-readable `code` and an actionable message.
 import { PhaseError, isPhaseError } from 'phase';
 ```
 
-| Code               | Trigger                                             |
-| ------------------ | --------------------------------------------------- |
-| `server_context`   | Calling a browser-only primitive during SSR         |
-| `no_target`        | Passing a null or undefined `target` to a primitive |
-| `invalid_duration` | `useTween` duration is zero, negative, or NaN       |
-| `ticker_stopped`   | Calling `start`/`resume` on a stopped ticker        |
-| `missing_context`  | `<Swap.State>` used outside `<Swap>`                |
+| Code                 | Trigger                                             |
+| -------------------- | --------------------------------------------------- |
+| `server_context`     | Calling a browser-only primitive during SSR         |
+| `no_target`          | Passing a null or undefined `target` to a primitive |
+| `conflicting_target` | Passing both `ref` and `target` to a hook           |
+| `invalid_duration`   | `useTween` duration is zero, negative, or NaN       |
+| `ticker_stopped`     | Calling `start`/`resume` on a stopped ticker        |
+| `missing_context`    | `<Swap.State>` used outside `<Swap>`                |
 
 ## Relationship to View Transitions
 
@@ -1233,34 +1236,34 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | ------------------------- | ----------------: |
 | **Core**                  |                   |
 | `createTicker`            |             847 B |
-| `createSight`             |             970 B |
-| `createLifecycle`         |           1.48 kB |
-| `createLoop`              |            2.6 kB |
-| `createScrollProgress`    |             865 B |
+| `createSight`             |           1.01 kB |
+| `createLifecycle`         |           1.52 kB |
+| `createLoop`              |           2.65 kB |
+| `createScrollProgress`    |             869 B |
 | `createRenderState`       |             490 B |
 | `createDevicePixelRatio`  |             544 B |
 | `createMutation`          |           1.17 kB |
 | `createPointer`           |           1.26 kB |
-| `createScroll`            |           1.46 kB |
-| `createThrottle`          |             659 B |
-| `createDebounce`          |             557 B |
+| `createScroll`            |           1.56 kB |
+| `createThrottle`          |             660 B |
+| `createDebounce`          |             558 B |
 | `whenIdle`                |             409 B |
 | `prefersReducedMotion`    |             101 B |
 | **Ease**                  |                   |
 | `ease (all)`              |             210 B |
 | **React**                 |                   |
-| `useLoop`                 |           2.85 kB |
-| `useLifecycle`            |           1.68 kB |
-| `useSight`                |           1.18 kB |
-| `useCanvas`               |           3.47 kB |
-| `useMutation`             |           1.37 kB |
-| `usePointer`              |           1.48 kB |
-| `useScroll`               |           1.72 kB |
-| `useThrottledCallback`    |             797 B |
-| `useDebouncedCallback`    |             687 B |
-| `useTween`                |             655 B |
+| `useLoop`                 |           2.98 kB |
+| `useLifecycle`            |           1.81 kB |
+| `useSight`                |           1.33 kB |
+| `useCanvas`               |           3.51 kB |
+| `useMutation`             |           1.36 kB |
+| `usePointer`              |           1.47 kB |
+| `useScroll`               |            1.9 kB |
+| `useThrottledCallback`    |             804 B |
+| `useDebouncedCallback`    |             696 B |
+| `useTween`                |             680 B |
 | `usePresence`             |             591 B |
-| `useScrollProgress`       |             999 B |
+| `useScrollProgress`       |             991 B |
 | `useSize`                 |             378 B |
 | `useContainerQuery`       |             384 B |
 | `useMediaQuery`           |             246 B |
@@ -1269,12 +1272,12 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | `useSyncedRef`            |              22 B |
 | `useStableCallback`       |              39 B |
 | `Presence`                |             741 B |
-| `WhenVisible`             |           1.43 kB |
-| `WhenIdle`                |             593 B |
+| `WhenVisible`             |           1.57 kB |
+| `WhenIdle`                |             596 B |
 | `Defer`                   |              86 B |
-| `useIdle`                 |             435 B |
-| `useWhenIdle`             |             446 B |
-| `useRenderState`          |             521 B |
+| `useIdle`                 |             414 B |
+| `useWhenIdle`             |             445 B |
+| `useRenderState`          |             515 B |
 | `Swap`                    |           1.12 kB |
 
 <!-- SIZE-TABLE:END -->

package/dist/{debounce-BX3NrBak.js → debounce-BA-WszUy.js}

@@ -56,6 +56,13 @@ function noTargetError(fn) {
 		fix: "Pass a mounted Element, or use the React hook which manages the ref."
 	});
 }
+function conflictingTargetError(fn) {
+	throw new PhaseError(`${fn}() received both ref and target.`, {
+		code: "conflicting_target",
+		reason: "A tracker has one anchor.",
+		fix: "Pass one: ref for an element, target: 'page' for the page."
+	});
+}
 function invalidDurationError(fn, value) {
 	throw new PhaseError(`${fn}() received an invalid duration: ${value}`, {
 		code: "invalid_duration",
@@ -206,6 +213,19 @@ function createTicker(options) {
 	};
 }
 //#endregion
+//#region src/core/_internal/dom/index.ts
+const DOCUMENT_NODE = 9;
+/**
+* Discriminates a page target from an element target.
+*
+* Uses `nodeType` rather than a property check: `document.scrollingElement` is
+* absent in some test DOMs, so feature detection would silently classify a
+* Document as an Element.
+*/
+function isDocument(target) {
+	return target.nodeType === DOCUMENT_NODE;
+}
+//#endregion
 //#region src/core/_internal/pool/io-pool.ts
 const pool$1 = /* @__PURE__ */ new Map();
 /**
@@ -278,6 +298,9 @@ const createPoolEntry$1 = (options) => {
 * and the element is within the viewport. Uses a shared IntersectionObserver
 * pool. Multiple `createSight` calls with the same options share one observer.
 *
+* Pass `document` to anchor to the page instead. There is no viewport test to
+* make, so no observer is created and `phase` follows document visibility.
+*
 * @example
 * const sight = createSight({
 *   target: el,
@@ -296,8 +319,9 @@ function createSight(options) {
 	let _phase = "unknown";
 	let _reason = "initial";
 	let stopped = false;
+	const isPage = isDocument(target);
 	let documentVisible = !document.hidden;
-	let elementInView = false;
+	let elementInView = isPage;
 	function recompute(trigger) {
 		if (stopped) return;
 		const prev = _phase;
@@ -322,7 +346,15 @@ function createSight(options) {
 	}
 	document.addEventListener("visibilitychange", onVisibilityChange);
 	window.addEventListener("pageshow", onPageShow);
-	const unobserveIO = observeIntersection({
+	let unobserveIO;
+	if (isPage) try {
+		recompute("initial");
+	} catch (error) {
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		window.removeEventListener("pageshow", onPageShow);
+		throw error;
+	}
+	else unobserveIO = observeIntersection({
 		element: target,
 		onIntersect: onIntersection,
 		...intersectionOptions
@@ -334,7 +366,7 @@ function createSight(options) {
 		unlinkAbort?.();
 		document.removeEventListener("visibilitychange", onVisibilityChange);
 		window.removeEventListener("pageshow", onPageShow);
-		unobserveIO();
+		unobserveIO?.();
 		_phase = "hidden";
 		_reason = "initial";
 	}
@@ -1251,11 +1283,22 @@ function getObserver() {
 * This is to `scroll` + `scrollWidth` what `createPointer` is to `pointermove`
 * + `getBoundingClientRect`: the layout read is batched off the hot path so the
 * per-scroll work is a single cheap position read plus math on cached geometry.
+*
+* Pass `document` to track the page. Offsets and geometry then come from
+* `document.scrollingElement`, and because the page is always in view,
+* `visibility: 'pause'` reacts to tab visibility alone rather than an
+* `IntersectionObserver`.
 */
 function createScroll(options) {
 	if (typeof document === "undefined") serverContextError("createScroll");
 	const { target, onScroll, onPhaseChange, visibility = "pause", intersectionOptions, signal } = options;
 	if (!target) noTargetError("createScroll");
+	let pageDoc;
+	let scroller;
+	if (isDocument(target)) {
+		pageDoc = target;
+		scroller = target.scrollingElement ?? target.documentElement;
+	} else scroller = target;
 	let _phase = "paused";
 	let _reason = "initial";
 	let stopped = false;
@@ -1271,6 +1314,7 @@ function createScroll(options) {
 	};
 	let rafId = 0;
 	let dirty = false;
+	let geometryDirty = false;
 	let listenersAttached = false;
 	let unobserveRO;
 	function setPhase(phase, reason) {
@@ -1281,31 +1325,39 @@ function createScroll(options) {
 	}
 	function computePosition() {
 		const { maxX, maxY } = _state;
-		const x = target.scrollLeft;
-		const y = target.scrollTop;
+		const x = scroller.scrollLeft;
+		const y = scroller.scrollTop;
 		_state.x = x < 0 ? 0 : x > maxX ? maxX : x;
 		_state.y = y < 0 ? 0 : y > maxY ? maxY : y;
 		_state.progressX = maxX > 0 ? _state.x / maxX : 0;
 		_state.progressY = maxY > 0 ? _state.y / maxY : 0;
 	}
-	function measure() {
-		if (stopped || !listenersAttached) return;
-		const scrollWidth = target.scrollWidth;
-		const clientWidth = target.clientWidth;
-		const scrollHeight = target.scrollHeight;
-		const clientHeight = target.clientHeight;
+	function readGeometry() {
+		const scrollWidth = scroller.scrollWidth;
+		const clientWidth = scroller.clientWidth;
+		const scrollHeight = scroller.scrollHeight;
+		const clientHeight = scroller.clientHeight;
 		const maxX = scrollWidth - clientWidth;
 		const maxY = scrollHeight - clientHeight;
 		_state.maxX = maxX > 0 ? maxX : 0;
 		_state.maxY = maxY > 0 ? maxY : 0;
 		_state.visibleX = maxX > 0 ? clientWidth / scrollWidth : 1;
 		_state.visibleY = maxY > 0 ? clientHeight / scrollHeight : 1;
+	}
+	function measure() {
+		if (stopped || !listenersAttached) return;
+		geometryDirty = false;
+		readGeometry();
 		computePosition();
 		onScroll(_state);
 	}
 	function flush() {
 		rafId = 0;
-		if (!dirty || stopped) return;
+		if (stopped || !dirty && !geometryDirty) return;
+		if (geometryDirty) {
+			geometryDirty = false;
+			readGeometry();
+		}
 		dirty = false;
 		computePosition();
 		onScroll(_state);
@@ -1320,6 +1372,7 @@ function createScroll(options) {
 			rafId = 0;
 		}
 		dirty = false;
+		geometryDirty = false;
 	}
 	function onScrollEvent() {
 		if (stopped) return;
@@ -1327,14 +1380,16 @@ function createScroll(options) {
 		scheduleFlush();
 	}
 	function onROResize() {
-		if (stopped) return;
-		measure();
+		if (stopped || !listenersAttached) return;
+		geometryDirty = true;
+		scheduleFlush();
 	}
 	function attachListeners() {
 		if (listenersAttached) return;
 		listenersAttached = true;
 		target.addEventListener("scroll", onScrollEvent, { passive: true });
-		unobserveRO = observeResize(target, onROResize);
+		unobserveRO = observeResize(scroller, onROResize);
+		if (pageDoc) window.addEventListener("resize", onROResize);
 		measure();
 	}
 	function detachListeners() {
@@ -1343,11 +1398,12 @@ function createScroll(options) {
 		target.removeEventListener("scroll", onScrollEvent);
 		unobserveRO?.();
 		unobserveRO = void 0;
+		if (pageDoc) window.removeEventListener("resize", onROResize);
 		cancelFlush();
 	}
 	let cleanupVisibility;
 	if (visibility === "pause") {
-		let elementInView = false;
+		let elementInView = pageDoc !== void 0;
 		let documentVisible = !document.hidden;
 		function recompute() {
 			if (stopped) return;
@@ -1371,8 +1427,8 @@ function createScroll(options) {
 		}
 		document.addEventListener("visibilitychange", onVisChange);
 		window.addEventListener("pageshow", onPageShow);
-		const unobserveIO = observeIntersection({
-			element: target,
+		const unobserveIO = pageDoc ? void 0 : observeIntersection({
+			element: scroller,
 			onIntersect: (entry) => {
 				elementInView = entry.isIntersecting;
 				recompute();
@@ -1382,8 +1438,15 @@ function createScroll(options) {
 		cleanupVisibility = () => {
 			document.removeEventListener("visibilitychange", onVisChange);
 			window.removeEventListener("pageshow", onPageShow);
-			unobserveIO();
+			unobserveIO?.();
 		};
+		try {
+			recompute();
+		} catch (error) {
+			cleanupVisibility();
+			detachListeners();
+			throw error;
+		}
 	} else {
 		setPhase("tracking", "started");
 		attachListeners();
@@ -1616,6 +1679,6 @@ function createDebounce(options) {
 	};
 }
 //#endregion
-export { missingContextError as C, isPhaseError as S, linkAbortSignal as T, subscribeMediaQuery as _, createPointer as a, PhaseError as b, prefersReducedMotion as c, subscribeDpr as d, createRenderState as f, readMediaQuery as g, createLifecycle as h, observeResize as i, whenIdle as l, createLoop as m, createThrottle as n, createMutation as o, createScrollProgress as p, createScroll as r, REDUCED_MOTION_QUERY as s, createDebounce as t, readDpr as u, createSight as v, serverContextError as w, invalidDurationError as x, createTicker as y };
+export { isPhaseError as C, linkAbortSignal as E, invalidDurationError as S, serverContextError as T, subscribeMediaQuery as _, createPointer as a, PhaseError as b, prefersReducedMotion as c, subscribeDpr as d, createRenderState as f, readMediaQuery as g, createLifecycle as h, observeResize as i, whenIdle as l, createLoop as m, createThrottle as n, createMutation as o, createScrollProgress as p, createScroll as r, REDUCED_MOTION_QUERY as s, createDebounce as t, readDpr as u, createSight as v, missingContextError as w, conflictingTargetError as x, createTicker as y };
 
-//# sourceMappingURL=debounce-BX3NrBak.js.map
+//# sourceMappingURL=debounce-BA-WszUy.js.map