Self-Parking RAF

'use client';

import { useCallback, useEffect, useRef, useState, type RefObject } from 'react';
import { damp, perFrameToSmoothing } from '@/lib/damp';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useVisibility } from '@/hooks/use-visibility';

/* ==========================================================================
   Self-Parking RAF
   --------------------------------------------------------------------------
   An eased value never arrives. `current += (target - current) * 0.12` closes
   88% of the remaining gap every frame and therefore closes it 100% never:
   the distance shrinks toward zero asymptotically and `current !== target`
   stays true forever. A loop conditioned on that comparison runs for the life
   of the page, burning a frame callback and a paint to move something by a
   ten-thousandth of a pixel.

   The fix is one line — an epsilon snap. Below a threshold, assign the target
   exactly. Now the equality test can succeed, so the loop reaches its own
   stopping condition and unsubscribes itself. Nothing outside has to know
   when the motion ended; the motion knows.

   This is the opposite of the usual always-on rAF. The loop exists only while
   something is actually moving, which for a scrubber, a hover offset, or a
   settling counter is a small fraction of the time the page is open.
   ========================================================================== */

export interface SelfParkingOptions {
  /**
   * Fraction of the gap that REMAINS after one second. Smaller is snappier.
   * Defaults to the frame-rate-independent equivalent of `* 0.12` per frame
   * at 60fps.
   */
  smoothing?: number;
  /**
   * Distance below which `current` is assigned `target` outright. Must be
   * scaled to the unit of the value — see the note on `epsilon` below.
   */
  epsilon?: number;
  /**
   * Called with the damped value every frame while running, and once more
   * when it parks. Write to the DOM here; do not call `setState`.
   */
  onFrame: (value: number) => void;
}

export interface SelfParkingValue {
  /** True while the loop is alive. Goes false the frame it parks. */
  running: boolean;
  /** The live damped value, for reading inside another loop. */
  value: RefObject<number>;
  /** Assign `target` immediately and park, skipping the remaining travel. */
  park: () => void;
}

// #region critical
/**
 * `0.12` of the gap per frame, measured at 60fps, expressed as the retention
 * factor `damp` wants. Using the raw 0.12 with a per-frame multiply would run
 * twice as fast on a 120 Hz display; this converges in the same wall-clock
 * time on any refresh rate.
 */
const SMOOTHING = perFrameToSmoothing(0.12);
/** The snap threshold. This single line is what allows the loop to end. */
const EPSILON = 0.0002;

/**
 * A damped value that runs a frame loop only while it is moving.
 *
 * `target` is a plain prop: changing it wakes the loop, and the loop parks
 * itself once it arrives. There is no `start`, and there is no
 * `requestAnimationFrame` running when the value is at rest.
 */
export function useSelfParkingRaf(
  target: number,
  options: SelfParkingOptions,
): SelfParkingValue {
  const { smoothing = SMOOTHING, epsilon = EPSILON } = options;
  const reduced = useReducedMotion();
  const visible = useVisibility();

  const value = useRef(target);
  const [running, setRunning] = useState(false);

  const config = useRef({ smoothing, epsilon, target, options });
  config.current = { smoothing, epsilon, target, options };

  const park = useCallback(() => {
    const cfg = config.current;
    value.current = cfg.target;
    cfg.options.onFrame(value.current);
    setRunning(false);
  }, []);

  // Waking the loop is the only thing a target change does. The guard matters:
  // without it, any unrelated re-render that happens to pass the same target
  // restarts a loop that had already parked.
  useEffect(() => {
    if (value.current === target) return;
    // Nothing to interpolate: reduced motion wants the end state, and a hidden
    // tab has no observer, so both arrive in one write instead of a loop.
    if (reduced || !visible) {
      park();
      return;
    }
    setRunning(true);
  }, [target, reduced, visible, park]);

  useRaf((dt) => {
    const cfg = config.current;
    let next = damp(value.current, cfg.target, cfg.smoothing, dt);

    // The whole technique. Asymptotic approach means `next` would otherwise
    // never equal `cfg.target`, so the exit test below could never pass.
    if (Math.abs(cfg.target - next) < cfg.epsilon) next = cfg.target;

    value.current = next;
    cfg.options.onFrame(next);

    // Parking flips `running`, which drops the `useRaf` subscription. When the
    // last subscriber goes, the shared loop cancels its frame entirely.
    if (next === cfg.target) setRunning(false);
  }, running);
  // #endregion critical

  return { running, value, park };
}

/* ==========================================================================
   Frame-rate-independent interpolation.
   --------------------------------------------------------------------------
   The everywhere-idiom `x += (target - x) * 0.1` is a bug: it converges twice
   as fast on a 120 Hz display as on a 60 Hz one, so the same code feels
   different on different hardware and visibly speeds up when the browser
   drops frames. `damp` fixes it by raising the retention factor to the power
   of elapsed time, which is the exact continuous form of the same curve.
   ========================================================================== */

/**
 * Fraction of the remaining distance to close this frame.
 *
 * @param smoothing Fraction of the gap that REMAINS after one second.
 *   Smaller is snappier. 0.001 ≈ very fast, 0.01 ≈ fast, 0.1 ≈ soft,
 *   0.5 ≈ slow drift.
 * @param dt Seconds elapsed since the previous frame.
 */
export function dampFactor(smoothing: number, dt: number): number {
  return 1 - Math.pow(smoothing, dt);
}

/** Move `current` toward `target` at a rate independent of frame rate. */
export function damp(
  current: number,
  target: number,
  smoothing: number,
  dt: number,
): number {
  return current + (target - current) * dampFactor(smoothing, dt);
}

/**
 * The per-frame lerp constant an author measured at 60fps, converted into the
 * `smoothing` argument `damp` wants. Lets a source that says "0.1 per frame"
 * be ported without re-tuning by eye:
 *
 *   damp(x, t, perFrameToSmoothing(0.1), dt)
 */
export function perFrameToSmoothing(alpha: number, baseFps = 60): number {
  return Math.pow(1 - alpha, baseFps);
}

export function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

export function clamp(v: number, min: number, max: number): number {
  return v < min ? min : v > max ? max : v;
}

export function inverseLerp(a: number, b: number, v: number): number {
  return a === b ? 0 : (v - a) / (b - a);
}

export function mapRange(
  v: number,
  inMin: number,
  inMax: number,
  outMin: number,
  outMax: number,
  doClamp = true,
): number {
  const t = inverseLerp(inMin, inMax, v);
  const r = lerp(outMin, outMax, doClamp ? clamp(t, 0, 1) : t);
  return r;
}

/** GLSL `smoothstep`, same semantics, for parity between JS and shader code. */
export function smoothstep(edge0: number, edge1: number, x: number): number {
  const t = clamp(inverseLerp(edge0, edge1, x), 0, 1);
  return t * t * (3 - 2 * t);
}

/**
 * Gaussian falloff, `exp(-d²)`. Yields 1.000 / 0.368 / 0.018 / 0.0001 at
 * distances 0 / 1 / 2 / 3 — a continuous focus scalar with no thresholds and
 * no branches, which is why carousels that use it feel analogue rather than
 * stepped.
 */
export function gaussian(distance: number, falloff = 1): number {
  const d = distance * falloff;
  return Math.exp(-(d * d));
}

'use client';

import { useEffect, useRef } from 'react';

/* ==========================================================================
   One shared requestAnimationFrame loop.
   --------------------------------------------------------------------------
   Forty components each calling requestAnimationFrame means forty callbacks
   the browser schedules separately and forty chances to read layout after a
   write. One loop, one ordered pass, one place to clamp delta time.

   Delta is clamped to 100 ms. Without that, returning to a backgrounded tab
   delivers a multi-second dt and every physics integration in the page
   explodes on the first frame back.
   ========================================================================== */

export type RafCallback = (dt: number, elapsed: number) => void;

const callbacks = new Set<RafCallback>();
let frame = 0;
let last = 0;
let start = 0;

const MAX_DT = 0.1;
const DEFAULT_DT = 1 / 60;

function tick(now: number) {
  frame = requestAnimationFrame(tick);
  const dt = last === 0 ? DEFAULT_DT : Math.min((now - last) / 1000, MAX_DT);
  last = now;
  const elapsed = (now - start) / 1000;
  // Copy: a callback may unsubscribe itself (or another) mid-iteration.
  for (const cb of Array.from(callbacks)) {
    if (callbacks.has(cb)) cb(dt, elapsed);
  }
}

function subscribe(cb: RafCallback) {
  callbacks.add(cb);
  if (frame === 0) {
    start = performance.now();
    last = 0;
    frame = requestAnimationFrame(tick);
  }
  return () => {
    callbacks.delete(cb);
    if (callbacks.size === 0 && frame !== 0) {
      cancelAnimationFrame(frame);
      frame = 0;
      last = 0;
    }
  };
}

/**
 * Run `cb` every frame while `enabled`.
 *
 * The callback is held in a ref, so it does not need to be memoised and the
 * subscription is never torn down just because the closure changed identity.
 */
export function useRaf(cb: RafCallback, enabled = true): void {
  const ref = useRef(cb);
  ref.current = cb;

  useEffect(() => {
    if (!enabled) return;
    return subscribe((dt, elapsed) => ref.current(dt, elapsed));
  }, [enabled]);
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   prefers-reduced-motion, SSR-safe.
   --------------------------------------------------------------------------
   useSyncExternalStore rather than useState + useEffect: the server snapshot
   is an explicit `false`, so the markup React renders on the server and the
   markup it hydrates with agree, and the real value lands in the same commit
   as hydration instead of one frame later. A useEffect version flashes the
   animated variant before removing it — the exact thing the user asked not to
   see.

   Reduced motion is not "duration: 0". For most components here it means a
   different render: the final state, a static poster, or a paused frame.
   ========================================================================== */

const QUERY = '(prefers-reduced-motion: reduce)';

function subscribe(onChange: () => void) {
  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
  const mql = window.matchMedia(QUERY);
  mql.addEventListener('change', onChange);
  return () => mql.removeEventListener('change', onChange);
}

function getSnapshot() {
  if (typeof window === 'undefined' || !window.matchMedia) return false;
  return window.matchMedia(QUERY).matches;
}

function getServerSnapshot() {
  return false;
}

export function useReducedMotion(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

/** Generic media-query hook, same SSR guarantees. */
export function useMediaQuery(query: string): boolean {
  return useSyncExternalStore(
    (onChange) => {
      if (typeof window === 'undefined' || !window.matchMedia) return () => {};
      const mql = window.matchMedia(query);
      mql.addEventListener('change', onChange);
      return () => mql.removeEventListener('change', onChange);
    },
    () => {
      if (typeof window === 'undefined' || !window.matchMedia) return false;
      return window.matchMedia(query).matches;
    },
    () => false,
  );
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   Document visibility, shared.
   --------------------------------------------------------------------------
   A backgrounded tab still runs `setInterval`, still holds WebGL contexts,
   and — on some platforms — still gets throttled rAF ticks with multi-second
   deltas. Anything expensive should stop when the tab is hidden and resume
   when it comes back, rather than trying to catch up.

   `useSyncExternalStore` with an explicit server snapshot so SSR markup and
   the first client render agree.
   ========================================================================== */

function subscribe(onChange: () => void): () => void {
  document.addEventListener('visibilitychange', onChange);
  return () => document.removeEventListener('visibilitychange', onChange);
}

function getSnapshot(): boolean {
  return document.visibilityState === 'visible';
}

/** Assume visible on the server: the alternative flashes a paused state. */
function getServerSnapshot(): boolean {
  return true;
}

export function useVisibility(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}