phase 0.4.2 → 0.5.1

package/README.md

@@ -36,9 +36,10 @@ function Orbit({ radius }) {
 
 - **Pauses when unseen.** Off-screen or in a background tab, work stops and CPU drops to zero.
 - **Respects reduced motion by default.** Accessibility is built in, not an opt-in.
-- **Never forces a reflow.** No `getBoundingClientRect`, no layout thrash, anywhere in the package.
+- **Batches layout reads.** Element-relative pointer tracking reads one rect per dirty frame; scroll geometry is read on attachment or explicit measurement and coalesced after resize signals; other dimensions and visibility come from observers.
 - **Zero re-renders from the frame loop.** Per-frame work writes to refs and the DOM, never React state.
-- **Frame-locked shared clock.** Every animation on the page reads one clock, so nothing drifts out of sync.
+- **Frame-locked shared clock.** Tickers using the same clock protocol read one timestamp, so they do not drift out of sync.
+- **Input before frame loops.** Within one clock protocol, pointer, scroll, mutation, and throttle work queued before a frame flushes before its animation callbacks.
 - **Renders only what matters.** Skip painting off-screen content, mount non-critical UI when idle.
 
 Read the [full documentation](https://github.com/vercel-labs/phase#readme), install the [phase agent skill](https://github.com/vercel-labs/phase/tree/main/skills/phase), review the [changelog](https://github.com/vercel-labs/phase/blob/main/CHANGELOG.md), or see the [MIT license](https://github.com/vercel-labs/phase/blob/main/packages/phase/LICENSE).

package/dist/{debounce-BkVwTxwI.js → debounce-CJYqsSXm.js}

@@ -22,6 +22,93 @@ function linkAbortSignal(signal, stop) {
 /** Shared empty unlink for the no-signal and already-aborted paths. */
 function unlinkNoop() {}
 //#endregion
+//#region src/core/_internal/clock/index.ts
+const EXECUTING = -1;
+const RESCHEDULED = -2;
+let sharedClock;
+let inputError;
+let inputFailed = false;
+function getSharedClock() {
+	const registry = globalThis;
+	return registry[Symbol.for("phase.clock@2")] ??= {
+		rafId: null,
+		frame: 0,
+		time: 0,
+		ticks: /* @__PURE__ */ new Map(),
+		input: /* @__PURE__ */ new Map()
+	};
+}
+function stopIfEmpty() {
+	if (sharedClock.ticks.size === 0 && sharedClock.input.size === 0 && sharedClock.rafId !== null) {
+		cancelAnimationFrame(sharedClock.rafId);
+		sharedClock.rafId = null;
+	}
+}
+function dispatchInput(joinedFrame, callback) {
+	if (joinedFrame < sharedClock.frame) {
+		sharedClock.input.set(callback, EXECUTING);
+		let keep = false;
+		try {
+			keep = callback(sharedClock.time) === true;
+		} catch (error) {
+			if (!inputFailed) inputError = error;
+			inputFailed = true;
+		}
+		const state = sharedClock.input.get(callback);
+		if (state !== void 0 && (keep || state !== EXECUTING)) {
+			sharedClock.input.set(callback, sharedClock.frame);
+			scheduleFrame();
+		} else sharedClock.input.delete(callback);
+	}
+}
+function dispatchTick(joinedFrame, callback) {
+	if (joinedFrame < sharedClock.frame) callback(sharedClock.time);
+}
+function tick(time) {
+	sharedClock.time = time;
+	sharedClock.frame++;
+	inputFailed = false;
+	sharedClock.rafId = sharedClock.ticks.size === 0 ? null : requestAnimationFrame(tick);
+	sharedClock.input.forEach(dispatchInput);
+	const failed = inputFailed;
+	const error = inputError;
+	inputFailed = false;
+	inputError = void 0;
+	sharedClock.ticks.forEach(dispatchTick);
+	stopIfEmpty();
+	if (failed) throw error;
+}
+function scheduleFrame() {
+	if (sharedClock.rafId === null) sharedClock.rafId = requestAnimationFrame(tick);
+}
+function joinTick(callback) {
+	sharedClock ??= getSharedClock();
+	sharedClock.ticks.set(callback, sharedClock.frame);
+	scheduleFrame();
+}
+function leaveTick(callback) {
+	if (!sharedClock) return;
+	sharedClock.ticks.delete(callback);
+	stopIfEmpty();
+}
+function scheduleInput(callback) {
+	sharedClock ??= getSharedClock();
+	const state = sharedClock.input.get(callback);
+	if (state === EXECUTING) {
+		sharedClock.input.set(callback, RESCHEDULED);
+		scheduleFrame();
+		return;
+	}
+	if (state !== void 0) return;
+	sharedClock.input.set(callback, sharedClock.frame);
+	scheduleFrame();
+}
+function cancelInput(callback) {
+	if (!sharedClock) return;
+	sharedClock.input.delete(callback);
+	stopIfEmpty();
+}
+//#endregion
 //#region src/core/_internal/errors/index.ts
 /** Lightweight structured error for phase. */
 var PhaseError = class extends Error {
@@ -93,42 +180,10 @@ function missingContextError(child, parent) {
 }
 //#endregion
 //#region src/core/tick/index.ts
-/** Prevents teleportation on resume. Matches motion's maxElapsed. */
+/** Maximum amount delta may exceed the active FPS interval. */
 const MAX_DELTA_MS = 40;
 /** Default first-frame delta when no previous tick exists. */
 const DEFAULT_FIRST_DELTA_MS = 16.67;
-let sharedClock;
-function getSharedClock() {
-	const registry = globalThis;
-	return registry[Symbol.for("phase.clock@1")] ??= {
-		rafId: null,
-		frame: 0,
-		time: 0,
-		subscribers: /* @__PURE__ */ new Set()
-	};
-}
-function dispatchSharedSubscription(subscription) {
-	if (subscription.joinedFrame < sharedClock.frame) subscription.callback(sharedClock.time);
-}
-function sharedTick(time) {
-	sharedClock.time = time;
-	sharedClock.frame++;
-	sharedClock.rafId = requestAnimationFrame(sharedTick);
-	sharedClock.subscribers.forEach(dispatchSharedSubscription);
-}
-function joinSharedClock(subscription) {
-	const wasEmpty = sharedClock.subscribers.size === 0;
-	subscription.joinedFrame = sharedClock.frame;
-	sharedClock.subscribers.add(subscription);
-	if (wasEmpty) sharedClock.rafId = requestAnimationFrame(sharedTick);
-}
-function leaveSharedClock(subscription) {
-	sharedClock.subscribers.delete(subscription);
-	if (sharedClock.subscribers.size === 0 && sharedClock.rafId !== null) {
-		cancelAnimationFrame(sharedClock.rafId);
-		sharedClock.rafId = null;
-	}
-}
 function resetFrameState(state) {
 	state.time = 0;
 	state.delta = 0;
@@ -153,23 +208,27 @@ function advanceDeadline(deadline, now, interval) {
 	return next + Math.floor(behind / interval) * interval;
 }
 /**
-* Core rAF loop primitive with FPS cap, delta clamping, and strong pause.
+* Low-level requestAnimationFrame loop with an optional FPS limit and pause controls.
 *
 * @remarks
+* Event-derived callbacks sharing this clock protocol run before `onTick` when
+* queued before frame dispatch. A callback first queued during dispatch runs
+* in the next frame; additional work can coalesce into an eligible callback
+* that has not run yet.
+*
 * `FrameState` is reused across frames. Do not store a reference to it.
 * Read values immediately in your `onTick` callback.
 */
 function createTicker(options) {
 	if (typeof requestAnimationFrame === "undefined") serverContextError("createTicker");
-	sharedClock ??= getSharedClock();
 	const { onTick, signal } = options;
 	let minFrameTime = resolveMinFrameTime("createTicker", options.fps);
+	let maxDeltaTime = minFrameTime + MAX_DELTA_MS;
 	let _phase = "idle";
 	let _reason = "initial";
-	let lastTickTime = 0;
-	let pauseStartTime = 0;
-	let totalPausedTime = 0;
-	let startTime = 0;
+	let lastTickTime = -1;
+	let elapsedTime = 0;
+	let frameCount = 0;
 	let nextDueTime = 0;
 	const frame = {
 		time: 0,
@@ -179,20 +238,18 @@ function createTicker(options) {
 	};
 	function tick(now) {
 		if (now < nextDueTime) return;
-		const isFirstDelivery = lastTickTime === 0;
-		const rawDelta = isFirstDelivery ? DEFAULT_FIRST_DELTA_MS : now - lastTickTime;
+		const isFirstDelivery = lastTickTime < 0;
+		const rawDelta = isFirstDelivery ? minFrameTime || DEFAULT_FIRST_DELTA_MS : now - lastTickTime;
 		lastTickTime = now;
 		if (minFrameTime > 0) nextDueTime = isFirstDelivery ? now + minFrameTime : advanceDeadline(nextDueTime, now, minFrameTime);
 		frame.time = now;
-		frame.delta = rawDelta > MAX_DELTA_MS ? MAX_DELTA_MS : rawDelta;
-		frame.elapsed = now - startTime - totalPausedTime;
-		frame.frame++;
+		frame.delta = rawDelta > maxDeltaTime ? maxDeltaTime : rawDelta;
+		elapsedTime += frame.delta;
+		frame.elapsed = elapsedTime;
+		frameCount++;
+		frame.frame = frameCount;
 		onTick(frame);
 	}
-	const subscription = {
-		callback: tick,
-		joinedFrame: 0
-	};
 	function start() {
 		if (_phase === "running") return;
 		if (_phase === "stopped") tickerStoppedError();
@@ -202,41 +259,41 @@ function createTicker(options) {
 		}
 		_phase = "running";
 		_reason = "started";
-		startTime = performance.now();
-		lastTickTime = 0;
+		lastTickTime = -1;
 		nextDueTime = 0;
-		totalPausedTime = 0;
+		elapsedTime = 0;
+		frameCount = 0;
 		resetFrameState(frame);
-		joinSharedClock(subscription);
+		joinTick(tick);
 	}
 	function pause() {
 		if (_phase !== "running") return;
 		_phase = "paused";
 		_reason = "manual";
-		pauseStartTime = performance.now();
-		leaveSharedClock(subscription);
+		leaveTick(tick);
 	}
 	function resume() {
 		if (_phase === "stopped") tickerStoppedError();
 		if (_phase !== "paused") return;
-		totalPausedTime += performance.now() - pauseStartTime;
-		lastTickTime = 0;
+		lastTickTime = -1;
 		nextDueTime = 0;
 		_phase = "running";
 		_reason = "resumed";
-		joinSharedClock(subscription);
+		joinTick(tick);
 	}
 	function setFps(fps) {
 		if (_phase === "stopped") tickerStoppedError();
-		minFrameTime = resolveMinFrameTime("setFps", fps);
-		nextDueTime = lastTickTime === 0 ? 0 : lastTickTime + minFrameTime;
+		const nextMinFrameTime = resolveMinFrameTime("setFps", fps);
+		minFrameTime = nextMinFrameTime;
+		maxDeltaTime = nextMinFrameTime + MAX_DELTA_MS;
+		nextDueTime = lastTickTime < 0 ? 0 : lastTickTime + minFrameTime;
 	}
 	function stop() {
 		if (_phase === "stopped") return;
 		_phase = "stopped";
 		_reason = _reason === "initial" ? "disposed" : "manual";
 		unlinkAbort?.();
-		leaveSharedClock(subscription);
+		leaveTick(tick);
 	}
 	let unlinkAbort;
 	unlinkAbort = linkAbortSignal(signal, stop);
@@ -1057,7 +1114,6 @@ function createMutation(options) {
 	let _reason = "initial";
 	let stopped = false;
 	let pendingRecords = [];
-	let rafId = 0;
 	function setPhase(phase, reason) {
 		const prev = _phase;
 		_phase = phase;
@@ -1065,20 +1121,15 @@ function createMutation(options) {
 		if (prev !== phase) onPhaseChange?.(phase, reason);
 	}
 	function flushRecords() {
-		rafId = 0;
 		if (stopped || pendingRecords.length === 0) return;
 		const batch = pendingRecords;
 		pendingRecords = [];
 		onMutations(batch);
 	}
-	function scheduleFlush() {
-		if (rafId !== 0) return;
-		rafId = requestAnimationFrame(flushRecords);
-	}
 	const mo = new MutationObserver((records) => {
 		if (stopped || _phase !== "observing") return;
 		for (let i = 0, len = records.length; i < len; i++) pendingRecords[pendingRecords.length] = records[i];
-		scheduleFlush();
+		scheduleInput(flushRecords);
 	});
 	function startObserving() {
 		if (stopped || _phase === "observing") return;
@@ -1089,10 +1140,7 @@ function createMutation(options) {
 		if (stopped || _phase === "paused") return;
 		setPhase("paused", reason);
 		mo.disconnect();
-		if (rafId !== 0) {
-			cancelAnimationFrame(rafId);
-			rafId = 0;
-		}
+		cancelInput(flushRecords);
 		pendingRecords = [];
 	}
 	let cleanupVisibility;
@@ -1136,10 +1184,7 @@ function createMutation(options) {
 		unlinkAbort?.();
 		cleanupVisibility?.();
 		mo.disconnect();
-		if (rafId !== 0) {
-			cancelAnimationFrame(rafId);
-			rafId = 0;
-		}
+		cancelInput(flushRecords);
 		pendingRecords = [];
 		setPhase("stopped", "disposed");
 	}
@@ -1178,7 +1223,6 @@ function createPointer(options) {
 		y: 0,
 		active: false
 	};
-	let rafId = 0;
 	let lastClientX = 0;
 	let lastClientY = 0;
 	let dirty = false;
@@ -1189,7 +1233,6 @@ function createPointer(options) {
 		if (prev !== phase) onPhaseChange?.(phase, reason);
 	}
 	function flush() {
-		rafId = 0;
 		if (!dirty || stopped) return;
 		dirty = false;
 		const rect = element.getBoundingClientRect();
@@ -1197,15 +1240,8 @@ function createPointer(options) {
 		_state.y = lastClientY - rect.top;
 		onPointer(_state);
 	}
-	function scheduleFlush() {
-		if (rafId !== 0) return;
-		rafId = requestAnimationFrame(flush);
-	}
 	function cancelFlush() {
-		if (rafId !== 0) {
-			cancelAnimationFrame(rafId);
-			rafId = 0;
-		}
+		cancelInput(flush);
 		dirty = false;
 	}
 	function onPointerMove(e) {
@@ -1214,7 +1250,7 @@ function createPointer(options) {
 		lastClientX = pe.clientX;
 		lastClientY = pe.clientY;
 		dirty = true;
-		scheduleFlush();
+		scheduleInput(flush);
 	}
 	function onPointerEnter() {
 		if (stopped) return;
@@ -1399,7 +1435,6 @@ function createScroll(options) {
 		visibleX: 1,
 		visibleY: 1
 	};
-	let rafId = 0;
 	let dirty = false;
 	let geometryDirty = false;
 	let listenersAttached = false;
@@ -1439,7 +1474,6 @@ function createScroll(options) {
 		onScroll(_state);
 	}
 	function flush() {
-		rafId = 0;
 		if (stopped || !dirty && !geometryDirty) return;
 		if (geometryDirty) {
 			geometryDirty = false;
@@ -1449,27 +1483,20 @@ function createScroll(options) {
 		computePosition();
 		onScroll(_state);
 	}
-	function scheduleFlush() {
-		if (rafId !== 0) return;
-		rafId = requestAnimationFrame(flush);
-	}
 	function cancelFlush() {
-		if (rafId !== 0) {
-			cancelAnimationFrame(rafId);
-			rafId = 0;
-		}
+		cancelInput(flush);
 		dirty = false;
 		geometryDirty = false;
 	}
 	function onScrollEvent() {
 		if (stopped) return;
 		dirty = true;
-		scheduleFlush();
+		scheduleInput(flush);
 	}
 	function onROResize() {
 		if (stopped || !listenersAttached) return;
 		geometryDirty = true;
-		scheduleFlush();
+		scheduleInput(flush);
 	}
 	function attachListeners() {
 		if (listenersAttached) return;
@@ -1584,7 +1611,6 @@ function createThrottle(options) {
 	let stopped = false;
 	let pending = false;
 	let lastFire = 0;
-	let rafId = 0;
 	let documentVisible = !document.hidden;
 	let latest = void 0;
 	function fire(now) {
@@ -1592,21 +1618,11 @@ function createThrottle(options) {
 		pending = false;
 		callback(latest);
 	}
-	function cancelRaf() {
-		if (rafId !== 0) {
-			cancelAnimationFrame(rafId);
-			rafId = 0;
-		}
-	}
-	function tick() {
-		rafId = 0;
+	function flushWhenDue() {
 		if (stopped || !pending) return;
 		const now = performance.now();
 		if (now - lastFire >= interval) fire(now);
-		else rafId = requestAnimationFrame(tick);
-	}
-	function scheduleRaf() {
-		if (rafId === 0) rafId = requestAnimationFrame(tick);
+		else return true;
 	}
 	function call(value) {
 		if (stopped) return;
@@ -1625,17 +1641,17 @@ function createThrottle(options) {
 		}
 		if (trailing) {
 			pending = true;
-			scheduleRaf();
+			scheduleInput(flushWhenDue);
 		}
 	}
 	function flush() {
 		if (stopped || !pending) return;
-		cancelRaf();
+		cancelInput(flushWhenDue);
 		fire(performance.now());
 	}
 	function cancel() {
 		if (stopped) return;
-		cancelRaf();
+		cancelInput(flushWhenDue);
 		pending = false;
 		lastFire = 0;
 	}
@@ -1643,15 +1659,15 @@ function createThrottle(options) {
 		documentVisible = !document.hidden;
 		if (stopped) return;
 		if (!documentVisible) {
-			cancelRaf();
+			cancelInput(flushWhenDue);
 			if (pending) if (hidden === "flush") fire(performance.now());
 			else pending = false;
-		} else if (pending) scheduleRaf();
+		} else if (pending) scheduleInput(flushWhenDue);
 	}
 	function onPageShow(event) {
 		if (!event.persisted) return;
 		documentVisible = true;
-		if (!stopped && pending) scheduleRaf();
+		if (!stopped && pending) scheduleInput(flushWhenDue);
 	}
 	document.addEventListener("visibilitychange", onVisibilityChange);
 	window.addEventListener("pageshow", onPageShow);
@@ -1662,7 +1678,7 @@ function createThrottle(options) {
 		unlinkAbort?.();
 		document.removeEventListener("visibilitychange", onVisibilityChange);
 		window.removeEventListener("pageshow", onPageShow);
-		cancelRaf();
+		cancelInput(flushWhenDue);
 		pending = false;
 	}
 	unlinkAbort = linkAbortSignal(signal, stop);
@@ -1768,4 +1784,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-BkVwTxwI.js.map
+//# sourceMappingURL=debounce-CJYqsSXm.js.map