phase 0.2.0 → 0.3.1

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
 
@@ -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.
 
@@ -1236,15 +1236,15 @@ 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`    |             869 B |
+| `createSight`             |           1.05 kB |
+| `createLifecycle`         |           1.55 kB |
+| `createLoop`              |           2.68 kB |
+| `createScrollProgress`    |             895 B |
 | `createRenderState`       |             490 B |
 | `createDevicePixelRatio`  |             544 B |
-| `createMutation`          |           1.17 kB |
-| `createPointer`           |           1.26 kB |
-| `createScroll`            |           1.56 kB |
+| `createMutation`          |           1.21 kB |
+| `createPointer`           |           1.29 kB |
+| `createScroll`            |           1.61 kB |
 | `createThrottle`          |             660 B |
 | `createDebounce`          |             558 B |
 | `whenIdle`                |             409 B |
@@ -1252,32 +1252,32 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | **Ease**                  |                   |
 | `ease (all)`              |             210 B |
 | **React**                 |                   |
-| `useLoop`                 |           2.85 kB |
-| `useLifecycle`            |           1.68 kB |
-| `useSight`                |           1.18 kB |
-| `useCanvas`               |           3.47 kB |
-| `useMutation`             |           1.36 kB |
-| `usePointer`              |           1.47 kB |
-| `useScroll`               |            1.9 kB |
-| `useThrottledCallback`    |             797 B |
-| `useDebouncedCallback`    |             690 B |
+| `useLoop`                 |              3 kB |
+| `useLifecycle`            |           1.83 kB |
+| `useSight`                |           1.36 kB |
+| `useCanvas`               |           3.58 kB |
+| `useMutation`             |           1.39 kB |
+| `usePointer`              |           1.51 kB |
+| `useScroll`               |           1.96 kB |
+| `useThrottledCallback`    |             804 B |
+| `useDebouncedCallback`    |             696 B |
 | `useTween`                |             680 B |
 | `usePresence`             |             591 B |
-| `useScrollProgress`       |              1 kB |
-| `useSize`                 |             378 B |
-| `useContainerQuery`       |             384 B |
+| `useScrollProgress`       |           1.03 kB |
+| `useSize`                 |             418 B |
+| `useContainerQuery`       |             389 B |
 | `useMediaQuery`           |             246 B |
 | `usePrefersReducedMotion` |             272 B |
 | `useDevicePixelRatio`     |             231 B |
 | `useSyncedRef`            |              22 B |
 | `useStableCallback`       |              39 B |
 | `Presence`                |             741 B |
-| `WhenVisible`             |           1.43 kB |
-| `WhenIdle`                |             592 B |
+| `WhenVisible`             |           1.61 kB |
+| `WhenIdle`                |             596 B |
 | `Defer`                   |              86 B |
-| `useIdle`                 |             435 B |
-| `useWhenIdle`             |             443 B |
-| `useRenderState`          |             521 B |
+| `useIdle`                 |             414 B |
+| `useWhenIdle`             |             445 B |
+| `useRenderState`          |             515 B |
 | `Swap`                    |           1.12 kB |
 
 <!-- SIZE-TABLE:END -->

package/dist/{debounce-V_5xqZSY.js → debounce-ALTBuZYx.js}

@@ -60,7 +60,7 @@ function conflictingTargetError(fn) {
 	throw new PhaseError(`${fn}() received both ref and target.`, {
 		code: "conflicting_target",
 		reason: "A tracker has one anchor.",
-		fix: "Pass ref for an element, or target: 'page' for the page."
+		fix: "Pass one: ref for an element, target: 'page' for the page."
 	});
 }
 function invalidDurationError(fn, value) {
@@ -213,13 +213,34 @@ 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();
 /**
 * Observe an element via a shared IntersectionObserver pool.
-* Elements with identical options share one IO instance.
+* Elements with identical options share one IO instance. An element may have
+* any number of subscribers; each receives every entry delivered after it
+* subscribes, and the element stays observed until the last one cleans up.
 *
-* @returns Cleanup function that unobserves the element and removes the IO if empty.
+* A subscriber joining an already-observed element does not get the initial
+* entry: `observe()` is a no-op for a target the observer already holds, so
+* nothing arrives until the next intersection change. Callers that need
+* current state on subscribe have to read it themselves.
+*
+* @returns Cleanup function that removes this subscriber, unobserving the
+* element once none remain and dropping the IO once it observes nothing.
 */
 function observeIntersection(options) {
 	const { element, onIntersect, root, rootMargin, threshold } = options;
@@ -230,7 +251,12 @@ function observeIntersection(options) {
 	};
 	const key = getPoolKey(ioInit);
 	const entry = getOrCreatePoolEntry(key, ioInit);
-	entry.callbacks.set(element, onIntersect);
+	let subscribers = entry.callbacks.get(element);
+	if (!subscribers) {
+		subscribers = /* @__PURE__ */ new Set();
+		entry.callbacks.set(element, subscribers);
+	}
+	subscribers.add(onIntersect);
 	entry.observer.observe(element);
 	let disposed = false;
 	return () => {
@@ -238,9 +264,13 @@ function observeIntersection(options) {
 		disposed = true;
 		const poolEntry = pool$1.get(key);
 		if (!poolEntry) return;
-		if (poolEntry.callbacks.get(element) === onIntersect) {
-			poolEntry.observer.unobserve(element);
-			poolEntry.callbacks.delete(element);
+		const current = poolEntry.callbacks.get(element);
+		if (current) {
+			current.delete(onIntersect);
+			if (current.size === 0) {
+				poolEntry.observer.unobserve(element);
+				poolEntry.callbacks.delete(element);
+			}
 		}
 		if (poolEntry.callbacks.size === 0) {
 			poolEntry.observer.disconnect();
@@ -269,8 +299,9 @@ const createPoolEntry$1 = (options) => {
 	return {
 		observer: new IntersectionObserver((entries) => {
 			for (const ioEntry of entries) {
-				const cb = callbacks.get(ioEntry.target);
-				if (cb) cb(ioEntry);
+				const subscribers = callbacks.get(ioEntry.target);
+				if (!subscribers) continue;
+				for (const cb of subscribers) cb(ioEntry);
 			}
 		}, options),
 		callbacks
@@ -285,6 +316,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,
@@ -303,8 +337,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;
@@ -329,7 +364,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
@@ -341,7 +384,7 @@ function createSight(options) {
 		unlinkAbort?.();
 		document.removeEventListener("visibilitychange", onVisibilityChange);
 		window.removeEventListener("pageshow", onPageShow);
-		unobserveIO();
+		unobserveIO?.();
 		_phase = "hidden";
 		_reason = "initial";
 	}
@@ -1219,30 +1262,46 @@ let observer = null;
 const callbacks = /* @__PURE__ */ new Map();
 /**
 * Observe an element via a singleton ResizeObserver.
-* One RO instance for the entire page. Per-element `box` options are
-* forwarded to `ResizeObserver.observe()`.
+* One RO instance for the entire page. An element may have any number of
+* subscribers; each receives every entry delivered after it subscribes, and
+* the element stays observed until the last one cleans up.
 *
-* @returns Cleanup function that unobserves the element.
+* Per-element `box` options are forwarded to `ResizeObserver.observe()`. A
+* single RO holds one observation per target, so when subscribers disagree on
+* `box` the most recent call wins. Every entry carries all box sizes, so a
+* subscriber can still read the box it cares about; only which box change
+* triggers a notification is affected.
+*
+* @returns Cleanup function that removes this subscriber, unobserving the
+* element once none remain.
 */
 function observeResize(element, callback, box) {
-	callbacks.set(element, callback);
+	let subscribers = callbacks.get(element);
+	if (!subscribers) {
+		subscribers = /* @__PURE__ */ new Set();
+		callbacks.set(element, subscribers);
+	}
+	subscribers.add(callback);
 	getObserver().observe(element, box ? { box } : void 0);
 	let disposed = false;
 	return () => {
 		if (disposed) return;
 		disposed = true;
-		if (callbacks.get(element) === callback) {
-			callbacks.delete(element);
-			observer?.unobserve(element);
-		}
+		const current = callbacks.get(element);
+		if (!current) return;
+		current.delete(callback);
+		if (current.size > 0) return;
+		callbacks.delete(element);
+		observer?.unobserve(element);
 	};
 }
 /** Lazy-created singleton. RO takes zero constructor options, so one instance can observe everything. */
 function getObserver() {
 	if (!observer) observer = new ResizeObserver((entries) => {
 		for (const entry of entries) {
-			const cb = callbacks.get(entry.target);
-			if (cb) cb(entry);
+			const subscribers = callbacks.get(entry.target);
+			if (!subscribers) continue;
+			for (const cb of subscribers) cb(entry);
 		}
 	});
 	return observer;
@@ -1289,7 +1348,7 @@ function createScroll(options) {
 	};
 	let rafId = 0;
 	let dirty = false;
-	let needsMeasure = false;
+	let geometryDirty = false;
 	let listenersAttached = false;
 	let unobserveRO;
 	function setPhase(phase, reason) {
@@ -1307,8 +1366,7 @@ function createScroll(options) {
 		_state.progressX = maxX > 0 ? _state.x / maxX : 0;
 		_state.progressY = maxY > 0 ? _state.y / maxY : 0;
 	}
-	function measure() {
-		if (stopped || !listenersAttached) return;
+	function readGeometry() {
 		const scrollWidth = scroller.scrollWidth;
 		const clientWidth = scroller.clientWidth;
 		const scrollHeight = scroller.scrollHeight;
@@ -1319,19 +1377,21 @@ function createScroll(options) {
 		_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 (stopped) return;
-		if (needsMeasure) {
-			needsMeasure = false;
-			dirty = false;
-			measure();
-			return;
+		if (stopped || !dirty && !geometryDirty) return;
+		if (geometryDirty) {
+			geometryDirty = false;
+			readGeometry();
 		}
-		if (!dirty) return;
 		dirty = false;
 		computePosition();
 		onScroll(_state);
@@ -1346,7 +1406,7 @@ function createScroll(options) {
 			rafId = 0;
 		}
 		dirty = false;
-		needsMeasure = false;
+		geometryDirty = false;
 	}
 	function onScrollEvent() {
 		if (stopped) return;
@@ -1354,13 +1414,9 @@ function createScroll(options) {
 		scheduleFlush();
 	}
 	function onROResize() {
-		if (stopped) return;
-		if (pageDoc) {
-			needsMeasure = true;
-			scheduleFlush();
-			return;
-		}
-		measure();
+		if (stopped || !listenersAttached) return;
+		geometryDirty = true;
+		scheduleFlush();
 	}
 	function attachListeners() {
 		if (listenersAttached) return;
@@ -1418,7 +1474,13 @@ function createScroll(options) {
 			window.removeEventListener("pageshow", onPageShow);
 			unobserveIO?.();
 		};
-		recompute();
+		try {
+			recompute();
+		} catch (error) {
+			cleanupVisibility();
+			detachListeners();
+			throw error;
+		}
 	} else {
 		setPhase("tracking", "started");
 		attachListeners();
@@ -1448,10 +1510,6 @@ function createScroll(options) {
 		stop
 	};
 }
-const DOCUMENT_NODE = 9;
-function isDocument(target) {
-	return target.nodeType === DOCUMENT_NODE;
-}
 //#endregion
 //#region src/core/throttle/index.ts
 /**
@@ -1657,4 +1715,4 @@ function createDebounce(options) {
 //#endregion
 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-V_5xqZSY.js.map
+//# sourceMappingURL=debounce-ALTBuZYx.js.map