Web Audio Scheduling Kit

'use client';

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

/* ==========================================================================
   Web Audio Scheduling Kit
   --------------------------------------------------------------------------
   A sequencer has two clocks and neither one can do the other's job.

   `AudioContext.currentTime` is exact — it is a sample counter, it never
   drifts, and anything you schedule against it is rendered on the audio
   thread whatever the main thread is doing. But you cannot be *notified* by
   it; there is no "wake me at 1.75 seconds".

   `setInterval` can notify you, but its accuracy is whatever the main thread
   has left over. A single 90 ms layout pass is enough to put a note audibly
   off the beat, and a hidden tab clamps it to one call per second.

   Lookahead is the resolution. The timer runs far more often than the tempo
   and its only job is to ask "which beats fall inside the next `lookahead`
   seconds?" — every one of those is scheduled onto the audio clock with an
   exact time. The timer may fire early, late, or twice in a row; the notes
   land in the same place regardless, because the timer never decides *when*
   a note plays, only *when it is queued*.

   Nothing starts until `start()` is called, and `start()` must be called
   from a user gesture: an `AudioContext` constructed outside one is
   `suspended`, and notes scheduled on a suspended context are discarded
   without an error.
   ========================================================================== */

export interface ScheduledBeat {
  /** Exact audio-clock time, in seconds. Pass this straight to `osc.start`. */
  time: number;
  /** Monotonic beat count since `start()`. */
  beat: number;
  /** `beat` wrapped into `[0, steps)`. */
  step: number;
  ctx: AudioContext;
}

export interface UseWebAudioSchedulerOptions {
  bpm?: number;
  /** Beats per bar. Only affects the wrapped `step` index. */
  steps?: number;
  /** Seconds of lookahead. Must exceed the worst-case timer gap. */
  lookahead?: number;
  /** How often the scheduling timer runs, in milliseconds. */
  intervalMs?: number;
  /**
   * Called once per beat, `lookahead` seconds early, on the timer. Schedule
   * audio here against `beat.time` — never against `Date.now()`.
   */
  onBeat?: (beat: ScheduledBeat) => void;
}

export interface WebAudioScheduler {
  /** Constructs and resumes the context, then starts the timer. Gesture only. */
  start: () => void;
  stop: () => void;
  running: boolean;
  /** The step that is audible right now, or `null` before the first beat. */
  step: number | null;
  /** Progress through the current beat, 0-1. Pinned at 0 for reduced motion. */
  phase: RefObject<number>;
}

export interface ToneOptions {
  frequency: number;
  /** Audio-clock time to sound, from `ScheduledBeat.time`. */
  at: number;
  gain?: number;
  /** Seconds from peak to -60 dB. */
  decay?: number;
  type?: OscillatorType;
}

// #region critical
/** `exponentialRampToValueAtTime` is undefined at 0, so silence is -60 dB. */
const SILENCE = 0.001;
/** Seconds after the ramp before `stop()`, so the cut is inaudible. */
const TAIL = 0.05;
/** Seconds before the first beat, absorbing the cost of `start()` itself. */
const START_LEAD = 0.08;
/** Lookahead used while the tab is hidden, in seconds. */
const HIDDEN_LOOKAHEAD = 1.5;

interface QueuedBeat {
  time: number;
  step: number;
}

/**
 * One decaying tone, scheduled and self-disposing.
 *
 * The oscillator and its gain node disconnect themselves in `onended`. A
 * sequencer that omits that leaks two nodes per beat — at 120 bpm that is
 * 7200 dead nodes an hour, all still attached to the destination.
 */
export function scheduleTone(ctx: AudioContext, options: ToneOptions): void {
  const { frequency, at, gain = 0.14, decay = 0.28, type = 'triangle' } = options;

  const osc = ctx.createOscillator();
  const env = ctx.createGain();
  osc.type = type;
  osc.frequency.setValueAtTime(frequency, at);
  env.gain.setValueAtTime(gain, at);
  env.gain.exponentialRampToValueAtTime(SILENCE, at + decay);
  osc.connect(env);
  env.connect(ctx.destination);
  osc.start(at);
  osc.stop(at + decay + TAIL);
  osc.onended = () => {
    osc.disconnect();
    env.disconnect();
  };
}

export function useWebAudioScheduler(
  options: UseWebAudioSchedulerOptions = {},
): WebAudioScheduler {
  const { bpm = 96, steps = 8, lookahead = 0.3, intervalMs = 90 } = options;
  const reduced = useReducedMotion();

  const [running, setRunning] = useState(false);
  const [step, setStep] = useState<number | null>(null);
  const phase = useRef(0);

  const ctxRef = useRef<AudioContext | null>(null);
  const timer = useRef<number | null>(null);
  const queue = useRef<QueuedBeat[]>([]);
  /** Audio time of the next beat to be scheduled. */
  const nextTime = useRef(0);
  /** Monotonic beat counter, so `step` survives a change of `steps`. */
  const counter = useRef(0);
  /** Widened while the tab is hidden, where timers are clamped to ~1 Hz. */
  const window_ = useRef(lookahead);

  const config = useRef({ bpm, steps, lookahead, intervalMs, reduced, options });
  config.current = { bpm, steps, lookahead, intervalMs, reduced, options };

  /** Queue every beat that falls inside the lookahead window. */
  const drain = useCallback(() => {
    const ctx = ctxRef.current;
    if (!ctx) return;
    const cfg = config.current;
    const secondsPerBeat = 60 / cfg.bpm;
    const horizon = ctx.currentTime + window_.current;

    // A `while`, not an `if`: one call may have to cover several beats when the
    // timer was throttled, and a fast tempo can put two beats in one window.
    while (nextTime.current < horizon) {
      const beat = counter.current;
      const at = nextTime.current;
      const index = wrapIndex(beat, cfg.steps);

      cfg.options.onBeat?.({ time: at, beat, step: index, ctx });
      queue.current.push({ time: at, step: index });

      // Accumulate from the previous beat time, never from `currentTime`.
      // Re-basing on the clock each pass folds the timer's jitter into the
      // tempo and the sequence drifts sharp within a minute.
      nextTime.current = at + secondsPerBeat;
      counter.current = beat + 1;
    }
  }, []);

  const stop = useCallback(() => {
    if (timer.current !== null) {
      clearInterval(timer.current);
      timer.current = null;
    }
    queue.current.length = 0;
    phase.current = 0;
    setRunning(false);
    setStep(null);
  }, []);

  const start = useCallback(() => {
    if (timer.current !== null) return;
    const cfg = config.current;

    let ctx = ctxRef.current;
    if (!ctx) {
      // Built inside the gesture handler that called `start`. Anywhere else
      // and the autoplay policy hands back a suspended context whose notes
      // are dropped silently.
      ctx = new AudioContext();
      ctxRef.current = ctx;
    }
    if (ctx.state === 'suspended') void ctx.resume();

    counter.current = 0;
    queue.current.length = 0;
    window_.current = document.visibilityState === 'hidden' ? HIDDEN_LOOKAHEAD : cfg.lookahead;
    nextTime.current = ctx.currentTime + START_LEAD;

    setRunning(true);
    drain();
    timer.current = window.setInterval(drain, cfg.intervalMs);
  }, [drain]);

  // The visual clock. Reading `ctx.currentTime` once per frame and popping the
  // beats that have passed keeps the highlight on the note you can hear; a
  // separate rAF counter of its own would slide out of step over a few bars.
  useRaf(() => {
    const ctx = ctxRef.current;
    if (!ctx) return;
    const now = ctx.currentTime;
    const q = queue.current;

    let current: QueuedBeat | null = null;
    while (q.length > 0) {
      const head = q[0];
      if (head === undefined || head.time > now) break;
      q.shift();
      current = head;
    }
    if (current) setStep(current.step);

    if (config.current.reduced) {
      phase.current = 0;
      return;
    }
    const secondsPerBeat = 60 / config.current.bpm;
    const head = q[0];
    // Time until the next queued beat, turned into progress through this one.
    phase.current =
      head === undefined ? 0 : clamp(1 - (head.time - now) / secondsPerBeat, 0, 1);
  }, running);

  useEffect(() => {
    if (!running) return;
    // A hidden tab clamps `setInterval` to roughly one call per second, so a
    // 0.3s window drops entire bars. Widening the window instead of stopping
    // means the bar plays through unbroken while the tab is in the background.
    const onVisibility = () => {
      window_.current =
        document.visibilityState === 'hidden' ? HIDDEN_LOOKAHEAD : config.current.lookahead;
      drain();
    };
    document.addEventListener('visibilitychange', onVisibility);
    return () => document.removeEventListener('visibilitychange', onVisibility);
  }, [running, drain]);

  useEffect(
    () => () => {
      if (timer.current !== null) clearInterval(timer.current);
      timer.current = null;
      queue.current.length = 0;
      const ctx = ctxRef.current;
      ctxRef.current = null;
      // close() cancels every note already scheduled in the future. Without
      // it a bar keeps playing after the component has gone.
      if (ctx && ctx.state !== 'closed') void ctx.close();
    },
    [],
  );
  // #endregion critical

  return { start, stop, running, step, phase };
}

/* ==========================================================================
   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,
  );
}

/* ==========================================================================
   Ring index arithmetic.
   --------------------------------------------------------------------------
   Anything that loops — a drum carousel, an infinite marquee, a cylinder of
   image planes — needs to answer "how far is item i from position p" in a way
   that treats the sequence as a circle. A plain `i - p` says item 0 is 18 away
   from item 18 in a list of 19, when really it is 1 step back.
   ========================================================================== */

/** True modulo. Unlike `%`, the result is never negative. */
export function mod(n: number, m: number): number {
  return ((n % m) + m) % m;
}

/**
 * Shortest signed distance from `position` to index `i` around a ring of
 * `count` items. Result is in `(-count/2, count/2]`; negative means "behind".
 *
 * This one function is what makes a finite array behave like an infinite one.
 */
export function wrappedOffset(i: number, position: number, count: number): number {
  if (count <= 0) return 0;
  let offset = mod(i - position, count);
  if (offset > count / 2) offset -= count;
  return offset;
}

/** Wrap `value` into `[min, max)`, e.g. an angle into `[-PI, PI)`. */
export function wrapRange(value: number, min: number, max: number): number {
  const span = max - min;
  if (span <= 0) return min;
  return mod(value - min, span) + min;
}

/** Wrap an index into `[0, count)`. Accepts fractional and negative input. */
export function wrapIndex(i: number, count: number): number {
  return count <= 0 ? 0 : mod(i, count);
}

/**
 * Shortest signed angular distance from `a` to `b` in radians, in `(-PI, PI]`.
 * Prevents a rotation tween from taking the long way round.
 */
export function shortestAngle(a: number, b: number): number {
  return wrapRange(b - a, -Math.PI, Math.PI);
}