phase 0.0.7 → 0.0.9

package/README.md

@@ -35,6 +35,13 @@ Each guarantee is a [tested invariant](#guarantees), not an aspiration. Every ex
   - [createLifecycle](#createlifecycle)
   - [createScrollProgress](#createscrollprogress)
   - [createScroll](#createscroll)
+  - [createThrottle](#createthrottle)
+  - [createDebounce](#createdebounce)
+  - [createRenderState](#createrenderstate)
+  - [createDevicePixelRatio](#createdevicepixelratio)
+  - [createMutation](#createmutation)
+  - [createPointer](#createpointer)
+  - [whenIdle](#whenidle)
   - [prefersReducedMotion](#prefersreducedmotion)
 - [Easing and math](#easing-and-math)
 - [Choosing a primitive](#choosing-a-primitive)
@@ -46,7 +53,11 @@ Each guarantee is a [tested invariant](#guarantees), not an aspiration. Every ex
   - [usePresence](#usepresence)
   - [useScrollProgress](#usescrollprogress)
   - [useScroll](#usescroll)
-  - [Utility hooks](#utility-hooks)
+  - [useThrottledCallback](#usethrottledcallback)
+  - [useDebouncedCallback](#usedebouncedcallback)
+  - [useMutation](#usemutation)
+  - [usePointer](#usepointer)
+  - [Observation and utility hooks](#observation-and-utility-hooks)
 - [React components](#react-components)
   - [How animations work](#how-animations-work)
   - [Presence](#presence)
@@ -54,7 +65,8 @@ Each guarantee is a [tested invariant](#guarantees), not an aspiration. Every ex
   - [Swap](#swap)
 - [Rendering](#rendering)
   - [Defer](#defer)
-  - [WhenIdle](#whenidle)
+  - [WhenIdle](#whenidle-1)
+  - [useIdle](#useidle)
   - [useWhenIdle](#usewhenidle)
   - [useRenderState](#userenderstate)
 - [Guarantees](#guarantees)
@@ -146,11 +158,11 @@ If a gap fails any criterion, phase closes it in the [skill](#agent-skill) (audi
 
 ## Entry points
 
-| Import        | Contents                                                                                              |
-| ------------- | ----------------------------------------------------------------------------------------------------- |
-| `phase`       | Core primitives: createLoop, createTicker, createSight, createLifecycle, createScrollProgress, errors |
-| `phase/ease`  | Easing functions and math utilities only                                                              |
-| `phase/react` | React hooks and components                                                                            |
+| Import        | Contents                                                                        |
+| ------------- | ------------------------------------------------------------------------------- |
+| `phase`       | Framework-agnostic timing, observation, lifecycle, scheduling, math, and errors |
+| `phase/ease`  | Easing functions and math utilities only                                        |
+| `phase/react` | React hooks and components                                                      |
 
 Each entry point is independently tree-shakeable. Importing `phase/ease` in a server component pulls zero browser APIs.
 
@@ -398,6 +410,157 @@ 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               |
+
+### createRenderState
+
+Reports whether the browser is rendering an element or skipping it under `content-visibility: auto`. Use it to pause raw work inside deferred content; `phase` loops already pause themselves.
+
+```ts
+import { createRenderState } from 'phase';
+
+const renderState = createRenderState({
+  element: el,
+  onPhaseChange: (phase) => {
+    if (phase === 'skipped') clock.pause();
+    else clock.resume();
+  },
+});
+
+renderState.stop();
+```
+
+It listens to `contentvisibilityautostatechange`, the browser's actual paint decision, without changing layout.
+
+### createDevicePixelRatio
+
+Tracks `devicePixelRatio` changes through a shared media-query subscription. Use it for framework-free canvas, WebGL, or worker renderers that own their buffer sizing.
+
+```ts
+import { createDevicePixelRatio } from 'phase';
+
+const dpr = createDevicePixelRatio({
+  onChange: (value) => renderer.setPixelRatio(Math.min(value, 2)),
+});
+
+// dpr.dpr is always current
+dpr.stop();
+```
+
+`useCanvas` handles DPR automatically; use this primitive only when you own the renderer.
+
+### createMutation
+
+A lifecycle-aware `MutationObserver`: records are coalesced into one callback per animation frame, observation pauses off-screen by default, and teardown is explicit.
+
+```ts
+import { createMutation } from 'phase';
+
+const mutation = createMutation({
+  element: list,
+  mutation: { childList: true },
+  onMutations: (records) => syncItems(records),
+});
+
+mutation.stop();
+```
+
+Reserve it for structural or narrow attribute changes. For dimensions, use ResizeObserver-backed `useSize`; reading layout inside `onMutations` still forces a reflow.
+
+### createPointer
+
+Tracks pointer position relative to an element, batching high-frequency events into one callback and one bounds read per animation frame. It pauses when the element is off-screen.
+
+```ts
+import { createPointer } from 'phase';
+
+const pointer = createPointer({
+  element: surface,
+  onPointer: (state) => {
+    cursor.style.transform = `translate(${state.x}px, ${state.y}px)`;
+  },
+});
+
+// pointer.state is always current
+pointer.stop();
+```
+
+Use CSS `:hover` for hover state and a gesture library for drag physics. This primitive is for continuous element-relative coordinates.
+
+### whenIdle
+
+Runs one callback when the browser is idle, with a timeout fallback for browsers without `requestIdleCallback`. The returned function cancels pending work.
+
+```ts
+import { whenIdle } from 'phase';
+
+const cancel = whenIdle(() => warmCache(), { timeout: 2000 });
+cancel();
+```
+
+In React, use `useWhenIdle` for effects, `useIdle` for a boolean, or `WhenIdle` to mount a subtree.
+
 ### prefersReducedMotion
 
 Returns `true` when reduced motion is enabled at the OS level. Use it to gate expensive setup or dynamic imports.
@@ -455,19 +618,25 @@ Easing, interpolation, and your value range are three separate concerns. `phase`
 
 ## Choosing a primitive
 
-| Need                                                     | Use                                                                                         |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| Check on-screen visibility                               | `useSight` (visibility only)                                                                |
-| Run a frame loop via `phase`                             | `useLoop` (DOM) / `useCanvas` (canvas)                                                      |
-| Pause/resume your own loop (WebGL, three.js, Web Worker) | `useLifecycle` (active/paused signal)                                                       |
-| Animate a single value in render output                  | `useTween`                                                                                  |
-| Animate mount/unmount transitions                        | `Presence` / `Swap` / `WhenVisible`                                                         |
-| Skip painting off-screen content (keep in DOM)           | `Defer`                                                                                     |
-| Defer non-critical UI until the browser is idle          | `WhenIdle` / `useIdle`                                                                      |
-| Run a side effect or prefetch when idle                  | `useWhenIdle`                                                                               |
-| 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 |
+| Need                                                                   | Use                                                                                         |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Check on-screen visibility                                             | `useSight` (visibility only)                                                                |
+| Run a frame loop via `phase`                                           | `useLoop` (DOM) / `useCanvas` (canvas)                                                      |
+| Pause/resume your own loop (WebGL, three.js, Web Worker)               | `useLifecycle` (active/paused signal)                                                       |
+| Animate a single value in render output                                | `useTween`                                                                                  |
+| Animate mount/unmount transitions                                      | `Presence` / `Swap` / `WhenVisible`                                                         |
+| Skip painting off-screen content (keep in DOM)                         | `Defer`                                                                                     |
+| Defer non-critical UI until the browser is idle                        | `WhenIdle` / `useIdle`                                                                      |
+| Run a side effect or prefetch when idle                                | `useWhenIdle`                                                                               |
+| Pause non-`phase` work inside a `Defer` subtree                        | `useRenderState`                                                                            |
+| React to DOM mutations without synchronous callback storms             | `useMutation`                                                                               |
+| Track element-relative pointer position without per-event layout reads | `usePointer`                                                                                |
+| Track DPR for a renderer you own                                       | `useDevicePixelRatio`                                                                       |
+| Check reduced motion for non-`phase` work                              | `usePrefersReducedMotion`                                                                   |
+| 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,17 +837,94 @@ 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.
 
-### Utility hooks
+### 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} />;
+}
+```
 
-| Hook                | Purpose                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------- |
-| `useSight`          | Element visibility as a phase. Pass `onVisibilityChange` for zero-re-render mode      |
-| `useSize`           | Element dimensions via shared ResizeObserver. Pass `onResize` for zero-re-render mode |
-| `useContainerQuery` | Breakpoint matching against element width                                             |
-| `useScrollProgress` | Element visibility ratio (0–1). Pass `onProgress` for zero-re-render mode             |
-| `useMediaQuery`     | CSS media query subscription (shared MQL pool)                                        |
-| `useSyncedRef`      | Ref always in sync with latest value                                                  |
-| `useStableCallback` | Stable-identity function that calls latest closure                                    |
+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} />;
+}
+```
+
+### useMutation
+
+Wraps `createMutation` with ref management and automatic teardown. Mutation records stay imperative—delivered once per animation frame—while only infrequent `observing` / `paused` phase changes re-render.
+
+```tsx
+import { useMutation } from 'phase/react';
+
+const { ref, phase } = useMutation({
+  mutation: { childList: true },
+  onMutations: (records) => syncItems(records),
+});
+
+return <ul ref={ref} data-observer-phase={phase} />;
+```
+
+Observation pauses off-screen by default. Set `visibility: 'ignore'` only for document-level coordination that must continue in the background.
+
+### usePointer
+
+Element-relative pointer tracking without per-event layout reads or per-frame React state. Position is delivered through `onPointer` and mirrored in `stateRef`; only enter/leave phase changes re-render.
+
+```tsx
+import { usePointer } from 'phase/react';
+
+const { ref } = usePointer({
+  onPointer: ({ x, y, active }) => {
+    cursorRef.current?.style.setProperty(
+      'transform',
+      `translate(${x}px, ${y}px)`,
+    );
+    cursorRef.current?.toggleAttribute('data-active', active);
+  },
+});
+
+return <div ref={ref}>{children}</div>;
+```
+
+Use it for custom cursors, canvas interaction, and tooltips—not simple hover or drag gestures.
+
+### Observation and utility hooks
+
+| Hook                      | Purpose                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `useSight`                | Element visibility as a phase. Pass `onVisibilityChange` for zero-re-render mode      |
+| `useSize`                 | Element dimensions via shared ResizeObserver. Pass `onResize` for zero-re-render mode |
+| `useContainerQuery`       | Breakpoint matching against element width                                             |
+| `useScrollProgress`       | Element visibility ratio (0–1). Pass `onProgress` for zero-re-render mode             |
+| `useMediaQuery`           | CSS media query subscription (shared MQL pool)                                        |
+| `usePrefersReducedMotion` | Reactive reduced-motion preference for non-`phase` animation                          |
+| `useDevicePixelRatio`     | Reactive DPR for renderers outside `useCanvas`                                        |
+| `useSyncedRef`            | Ref always in sync with latest value                                                  |
+| `useStableCallback`       | Stable-identity function that calls latest closure                                    |
 
 `useSight`, `useSize`, and `useScrollProgress` each support a transient mode: pass a callback (`onVisibilityChange`, `onResize`, `onProgress`) and the hook delivers updates via callback with zero re-renders. The reactive state field is omitted from the return type so accessing it is a compile-time error. An always-current ref (`phaseRef`, `sizeRef`, `progressRef`) is available in both modes.
 
@@ -860,6 +1106,19 @@ import { WhenIdle } from 'phase/react';
 
 Idle never fires during SSR, so `WhenIdle` children are absent from server HTML. Reserve it for non-critical content. For content that must be crawlable, use `Defer`. Reduced motion is automatic: `data-enter="animate"` is not stamped when reduced motion is preferred.
 
+### useIdle
+
+Returns `false`, then flips to `true` once the browser is idle. Use it when the idle signal belongs in render; use `WhenIdle` for a wrapper or `useWhenIdle` for an effect.
+
+```tsx
+import { useIdle } from 'phase/react';
+
+const idle = useIdle({ timeout: 2000 });
+return idle ? <SecondaryPanel /> : <Skeleton />;
+```
+
+Like `WhenIdle`, idle-gated content is absent from server HTML and should be non-critical.
+
 ### useWhenIdle
 
 Runs a callback once when the browser is idle after mount (the effect-shaped counterpart to `useIdle`). Use it for side effects (prefetching a chunk, warming a cache) rather than rendering. Cancels on unmount and always calls the latest callback.
@@ -974,45 +1233,49 @@ Minimal footprint is a core promise (see [Why phase](#why-phase)). Every export
 | ------------------------- | ----------------: |
 | **Core**                  |                   |
 | `createTicker`            |             834 B |
-| `createSight`             |             963 B |
-| `createLifecycle`         |           1.47 kB |
+| `createSight`             |             967 B |
+| `createLifecycle`         |           1.48 kB |
 | `createLoop`              |           2.59 kB |
-| `createScrollProgress`    |             878 B |
+| `createScrollProgress`    |             866 B |
 | `createRenderState`       |             495 B |
 | `createDevicePixelRatio`  |             544 B |
-| `createMutation`          |           1.17 kB |
-| `createPointer`           |           1.26 kB |
+| `createMutation`          |           1.18 kB |
+| `createPointer`           |           1.27 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 |
+| `useLoop`                 |           2.82 kB |
+| `useLifecycle`            |           1.68 kB |
 | `useSight`                |           1.18 kB |
 | `useCanvas`               |           3.44 kB |
 | `useMutation`             |           1.36 kB |
-| `usePointer`              |           1.48 kB |
-| `useScroll`               |           1.71 kB |
-| `useTween`                |             617 B |
-| `usePresence`             |             593 B |
-| `useScrollProgress`       |             993 B |
-| `useSize`                 |             384 B |
-| `useContainerQuery`       |             357 B |
-| `useMediaQuery`           |             245 B |
+| `usePointer`              |           1.47 kB |
+| `useScroll`               |           1.72 kB |
+| `useThrottledCallback`    |             797 B |
+| `useDebouncedCallback`    |             688 B |
+| `useTween`                |             619 B |
+| `usePresence`             |             591 B |
+| `useScrollProgress`       |             997 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-BD9K4TW4.js}

@@ -243,10 +243,7 @@ function observeIntersection(options) {
 * IO options are immutable after construction, so identical options can share.
 */
 function getPoolKey(opts) {
-	const root = opts.root ? "custom" : "null";
-	const margin = opts.rootMargin ?? "0px";
-	const threshold = Array.isArray(opts.threshold) ? opts.threshold.join(",") : String(opts.threshold ?? 0);
-	return root + "|" + margin + "|" + threshold;
+	return `${opts.root ? "custom" : "null"}|${opts.rootMargin ?? "0px"}|${Array.isArray(opts.threshold) ? opts.threshold.join(",") : String(opts.threshold ?? 0)}`;
 }
 /** Return an existing pool entry for this key, or create and register a new one. */
 function getOrCreatePoolEntry(key, options) {
@@ -1414,6 +1411,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-BD9K4TW4.js.map