phase 0.0.7 → 0.0.8

package/README.md

@@ -35,6 +35,8 @@ Each guarantee is a [tested invariant](#guarantees), not an aspiration. Every ex
   - [createLifecycle](#createlifecycle)
   - [createScrollProgress](#createscrollprogress)
   - [createScroll](#createscroll)
+  - [createThrottle](#createthrottle)
+  - [createDebounce](#createdebounce)
   - [prefersReducedMotion](#prefersreducedmotion)
 - [Easing and math](#easing-and-math)
 - [Choosing a primitive](#choosing-a-primitive)
@@ -46,6 +48,8 @@ Each guarantee is a [tested invariant](#guarantees), not an aspiration. Every ex
   - [usePresence](#usepresence)
   - [useScrollProgress](#usescrollprogress)
   - [useScroll](#usescroll)
+  - [useThrottledCallback](#usethrottledcallback)
+  - [useDebouncedCallback](#usedebouncedcallback)
   - [Utility hooks](#utility-hooks)
 - [React components](#react-components)
   - [How animations work](#how-animations-work)
@@ -398,6 +402,69 @@ scroll.stop();
 
 The options type is `CreateScrollOptions` (`ScrollOptions` is a `lib.dom` global and must not be shadowed).
 
+### 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.
+
+> **Event-driven, not a loop.** This fires on the trigger and idles otherwise. To cap a continuous render loop, use `fps` on [`createLoop`](#createloop). To think in rates, `interval: 1000 / 20` reads as "at most 20 per second".
+
+```ts
+import { createThrottle } from 'phase';
+
+const throttle = createThrottle({
+  callback: (state) => socket.emit('cursor', state.x, state.y),
+  interval: 50,
+});
+
+const pointer = createPointer({ element, onPointer: throttle.call });
+
+// throttle.flush()  fires a pending trailing call now
+// throttle.cancel() discards it and resets the window
+// cleanup:
+throttle.stop();
+```
+
+When the document hides, a pending call is flushed with the latest value (default) or dropped per `hidden`. Calls made while hidden are recorded but fire nothing until the document is visible again.
+
+#### Throttle options
+
+| Option     | Type                                | Default   | Description                                   |
+| ---------- | ----------------------------------- | --------- | --------------------------------------------- |
+| `callback` | `(value: T) => void`                | required  | Called with the latest value passed to `call` |
+| `interval` | `number`                            | required  | Minimum ms between invocations                |
+| `edge`     | `'leading' \| 'trailing' \| 'both'` | `'both'`  | Which edges fire                              |
+| `hidden`   | `'flush' \| 'drop'`                 | `'flush'` | Pending-call policy when the document hides   |
+| `signal`   | `AbortSignal`                       | —         | Stops the throttle when aborted               |
+
+### createDebounce
+
+Visibility-aware trailing debounce: fires the callback with the latest value once `wait` ms pass without a new call. No timer runs while the document is hidden; the quiet period restarts on return. Use it for work that should wait out a burst, like reallocating canvas buffers after a resize stream settles.
+
+```ts
+import { createDebounce } from 'phase';
+
+const debounce = createDebounce({
+  callback: (size) => reallocateBuffers(size),
+  wait: 250,
+});
+
+debounce.call({ width, height });
+
+// cleanup:
+debounce.stop();
+```
+
+Same surface as `createThrottle`: `flush()`, `cancel()`, a synchronous `pending` read, and terminal `stop()`.
+
+#### Debounce options
+
+| Option     | Type                 | Default   | Description                                   |
+| ---------- | -------------------- | --------- | --------------------------------------------- |
+| `callback` | `(value: T) => void` | required  | Called with the latest value passed to `call` |
+| `wait`     | `number`             | required  | Quiet period in ms; each call restarts it     |
+| `hidden`   | `'flush' \| 'drop'`  | `'flush'` | Pending-call policy when the document hides   |
+| `signal`   | `AbortSignal`        | —         | Stops the debounce when aborted               |
+
 ### prefersReducedMotion
 
 Returns `true` when reduced motion is enabled at the OS level. Use it to gate expensive setup or dynamic imports.
@@ -468,6 +535,8 @@ Easing, interpolation, and your value range are three separate concerns. `phase`
 | Pause non-`phase` work inside a `Defer` subtree          | `useRenderState`                                                                            |
 | Subscribe to scroll, size, or media values reactively    | `useScrollProgress` / `useSize` / `useContainerQuery` / `useMediaQuery`                     |
 | Scroll/size/visibility without re-renders?               | Same hooks with a callback (`onProgress` / `onResize` / `onVisibilityChange`), read via ref |
+| Rate-limit event-driven work (sockets, workers)          | `useThrottledCallback`                                                                      |
+| Run once after a burst settles (resize, typing)          | `useDebouncedCallback`                                                                      |
 
 **`useSight` vs `useLifecycle`:** `useSight` reports pure visibility (for lazy-mounting, analytics, `WhenVisible`). `useLifecycle` folds in reduced motion and a manual pause, so you can't accidentally animate for users who asked not to. If you're gating an animation, use `useLifecycle`. If you're gating content, use `useSight`.
 
@@ -668,6 +737,42 @@ function Carousel({ children }) {
 
 Scrolling writes to the DOM directly with zero re-renders. Read the latest position on demand from `stateRef.current` (e.g. inside a `useLoop` tick), and call `measure()` after changing scrollable content.
 
+### useThrottledCallback
+
+Wraps `createThrottle` with React lifecycle management. Returns a stable-identity throttled function (with `flush()` and `cancel()` attached) that drops directly into any callback slot and always invokes the latest `callback`.
+
+```tsx
+import { usePointer, useThrottledCallback } from 'phase/react';
+
+function LiveCursor() {
+  const emit = useThrottledCallback(
+    (s: PointerState) => socket.emit('cursor', { x: s.x, y: s.y }),
+    { interval: 50 },
+  );
+  const { ref } = usePointer({ onPointer: emit });
+  return <div ref={ref} />;
+}
+```
+
+Unmount and option changes discard a pending trailing call. When the final value must land, flush in your own cleanup: `useEffect(() => () => emit.flush(), [emit])`.
+
+### useDebouncedCallback
+
+Wraps `createDebounce` with React lifecycle management. Same shape as `useThrottledCallback`, but fires once `wait` ms pass without a new call.
+
+```tsx
+import { useSize, useDebouncedCallback } from 'phase/react';
+
+function SimulationCanvas() {
+  const realloc = useDebouncedCallback(
+    (size: Size) => reallocateBuffers(size),
+    { wait: 250 },
+  );
+  const { ref } = useSize({ onResize: realloc });
+  return <canvas ref={ref} />;
+}
+```
+
 ### Utility hooks
 
 | Hook                | Purpose                                                                               |
@@ -983,36 +1088,40 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | `createMutation`          |           1.17 kB |
 | `createPointer`           |           1.26 kB |
 | `createScroll`            |           1.45 kB |
+| `createThrottle`          |             657 B |
+| `createDebounce`          |             559 B |
 | `whenIdle`                |             409 B |
 | `prefersReducedMotion`    |             101 B |
 | **Ease**                  |                   |
 | `ease (all)`              |             210 B |
 | **React**                 |                   |
-| `useLoop`                 |           2.81 kB |
-| `useLifecycle`            |           1.69 kB |
-| `useSight`                |           1.18 kB |
+| `useLoop`                 |           2.82 kB |
+| `useLifecycle`            |           1.68 kB |
+| `useSight`                |           1.19 kB |
 | `useCanvas`               |           3.44 kB |
 | `useMutation`             |           1.36 kB |
 | `usePointer`              |           1.48 kB |
-| `useScroll`               |           1.71 kB |
-| `useTween`                |             617 B |
-| `usePresence`             |             593 B |
+| `useScroll`               |           1.72 kB |
+| `useThrottledCallback`    |             797 B |
+| `useDebouncedCallback`    |             688 B |
+| `useTween`                |             619 B |
+| `usePresence`             |             591 B |
 | `useScrollProgress`       |             993 B |
-| `useSize`                 |             384 B |
-| `useContainerQuery`       |             357 B |
-| `useMediaQuery`           |             245 B |
+| `useSize`                 |             378 B |
+| `useContainerQuery`       |             384 B |
+| `useMediaQuery`           |             246 B |
 | `usePrefersReducedMotion` |             272 B |
 | `useDevicePixelRatio`     |             231 B |
 | `useSyncedRef`            |              22 B |
 | `useStableCallback`       |              39 B |
-| `Presence`                |             739 B |
+| `Presence`                |             741 B |
 | `WhenVisible`             |           1.44 kB |
-| `WhenIdle`                |             592 B |
+| `WhenIdle`                |             593 B |
 | `Defer`                   |              86 B |
 | `useIdle`                 |             435 B |
-| `useWhenIdle`             |             449 B |
+| `useWhenIdle`             |             445 B |
 | `useRenderState`          |             527 B |
-| `Swap`                    |           1.12 kB |
+| `Swap`                    |           1.13 kB |
 
 <!-- SIZE-TABLE:END -->
 

package/dist/{scroll-DZvWyPQE.js → debounce-D5ugkrXN.js}

@@ -1414,6 +1414,208 @@ function createScroll(options) {
 	};
 }
 //#endregion
-export { linkAbortSignal as C, serverContextError as S, createTicker as _, REDUCED_MOTION_QUERY as a, isPhaseError as b, readDpr as c, createScrollProgress as d, createLoop as f, createSight as g, subscribeMediaQuery as h, createMutation as i, subscribeDpr as l, readMediaQuery as m, observeResize as n, prefersReducedMotion as o, createLifecycle as p, createPointer as r, whenIdle as s, createScroll as t, createRenderState as u, PhaseError as v, missingContextError as x, invalidDurationError as y };
+//#region src/core/throttle/index.ts
+/**
+* Frame-aligned, visibility-aware throttle. Leading calls fire synchronously;
+* a pending trailing call rides a one-shot rAF chain and fires with the latest
+* value on the first frame at or past `interval`. While the document is hidden
+* nothing is scheduled: a pending call is flushed or dropped per `hidden`, and
+* new calls are recorded but deferred until the document is visible again.
+*
+* @remarks
+* `call` takes exactly one value and stores it by reference, so the hot path
+* never allocates. Trailing calls read the value at fire time.
+*/
+function createThrottle(options) {
+	if (typeof document === "undefined") serverContextError("createThrottle");
+	const { callback, interval, edge = "both", hidden = "flush", signal } = options;
+	const leading = edge !== "trailing";
+	const trailing = edge !== "leading";
+	let stopped = false;
+	let pending = false;
+	let lastFire = 0;
+	let rafId = 0;
+	let documentVisible = !document.hidden;
+	let latest = void 0;
+	function fire(now) {
+		lastFire = now;
+		pending = false;
+		callback(latest);
+	}
+	function cancelRaf() {
+		if (rafId !== 0) {
+			cancelAnimationFrame(rafId);
+			rafId = 0;
+		}
+	}
+	function tick() {
+		rafId = 0;
+		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);
+	}
+	function call(value) {
+		if (stopped) return;
+		latest = value;
+		if (!documentVisible) {
+			pending = true;
+			return;
+		}
+		const now = performance.now();
+		if (now - lastFire >= interval) {
+			if (leading) {
+				fire(now);
+				return;
+			}
+			lastFire = now;
+		}
+		if (trailing) {
+			pending = true;
+			scheduleRaf();
+		}
+	}
+	function flush() {
+		if (stopped || !pending) return;
+		cancelRaf();
+		fire(performance.now());
+	}
+	function cancel() {
+		if (stopped) return;
+		cancelRaf();
+		pending = false;
+		lastFire = 0;
+	}
+	function onVisibilityChange() {
+		documentVisible = !document.hidden;
+		if (stopped) return;
+		if (!documentVisible) {
+			cancelRaf();
+			if (pending) if (hidden === "flush") fire(performance.now());
+			else pending = false;
+		} else if (pending) scheduleRaf();
+	}
+	function onPageShow(event) {
+		if (!event.persisted) return;
+		documentVisible = true;
+		if (!stopped && pending) scheduleRaf();
+	}
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	window.addEventListener("pageshow", onPageShow);
+	let unlinkAbort;
+	function stop() {
+		if (stopped) return;
+		stopped = true;
+		unlinkAbort?.();
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		window.removeEventListener("pageshow", onPageShow);
+		cancelRaf();
+		pending = false;
+	}
+	unlinkAbort = linkAbortSignal(signal, stop);
+	return {
+		call,
+		flush,
+		cancel,
+		get pending() {
+			return pending;
+		},
+		stop
+	};
+}
+//#endregion
+//#region src/core/debounce/index.ts
+/**
+* Visibility-aware trailing debounce. Fires the callback with the latest
+* value once `wait` milliseconds pass without a new call. While the document
+* is hidden no timer runs: a pending call is flushed or dropped per `hidden`,
+* and new calls are recorded but wait until the document is visible again,
+* when the quiet timer restarts.
+*/
+function createDebounce(options) {
+	if (typeof document === "undefined") serverContextError("createDebounce");
+	const { callback, wait, hidden = "flush", signal } = options;
+	let stopped = false;
+	let pending = false;
+	let timer;
+	let documentVisible = !document.hidden;
+	let latest = void 0;
+	function fire() {
+		pending = false;
+		callback(latest);
+	}
+	function clearTimer() {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+	}
+	function onTimer() {
+		timer = void 0;
+		if (stopped || !pending) return;
+		fire();
+	}
+	function startTimer() {
+		clearTimer();
+		timer = setTimeout(onTimer, wait);
+	}
+	function call(value) {
+		if (stopped) return;
+		latest = value;
+		pending = true;
+		if (documentVisible) startTimer();
+	}
+	function flush() {
+		if (stopped || !pending) return;
+		clearTimer();
+		fire();
+	}
+	function cancel() {
+		if (stopped) return;
+		clearTimer();
+		pending = false;
+	}
+	function onVisibilityChange() {
+		documentVisible = !document.hidden;
+		if (stopped) return;
+		if (!documentVisible) {
+			clearTimer();
+			if (pending) if (hidden === "flush") fire();
+			else pending = false;
+		} else if (pending) startTimer();
+	}
+	function onPageShow(event) {
+		if (!event.persisted) return;
+		documentVisible = true;
+		if (!stopped && pending) startTimer();
+	}
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	window.addEventListener("pageshow", onPageShow);
+	let unlinkAbort;
+	function stop() {
+		if (stopped) return;
+		stopped = true;
+		unlinkAbort?.();
+		document.removeEventListener("visibilitychange", onVisibilityChange);
+		window.removeEventListener("pageshow", onPageShow);
+		clearTimer();
+		pending = false;
+	}
+	unlinkAbort = linkAbortSignal(signal, stop);
+	return {
+		call,
+		flush,
+		cancel,
+		get pending() {
+			return pending;
+		},
+		stop
+	};
+}
+//#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 };
 
-//# sourceMappingURL=scroll-DZvWyPQE.js.map
+//# sourceMappingURL=debounce-D5ugkrXN.js.map