Radial Mask Spotlight

'use client';

import { useEffect, useRef, type ReactNode } from 'react';
import { useRaf } from '@/hooks/use-raf';
import { useSmoothPointer } from '@/hooks/use-smooth-pointer';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Radial Mask Spotlight
   --------------------------------------------------------------------------
   A layer is masked to a soft disc that follows the pointer, so content is
   lit rather than revealed — the difference from a clip-path mask is that the
   edge is a falloff, not a boundary.

   The gradient stops are the whole design:

       #000 0%, #000 30%, transparent 72%

   Solid black out to 30% of the radius, THEN a ramp. That flat core is what
   makes it read as a light with a beam rather than a smudge. A gradient that
   starts falling off at 0% has no lit region at all — it has a bright point
   that fades, which the eye reads as blur.

   Position comes from `useSmoothPointer` and is written once per frame in a
   rAF, not per `pointermove`. Mask writes are paint-invalidating and a fast
   pointer can deliver several events between frames, so writing per event
   means doing the same work two or three times for one visible result.
   ========================================================================== */

export interface RadialMaskSpotlightProps {
  children: ReactNode;
  /** Radius of the beam in CSS px. */
  radius?: number;
  /**
   * Fraction of the gap remaining after one second. Lower is tighter.
   * Passed straight to `useSmoothPointer`.
   */
  smoothing?: number;
  className?: string;
}

// #region critical
/** Where the solid core ends, as a fraction of `radius`. */
const CORE_STOP = 0.3;
/** Where the falloff reaches full transparency, as a fraction of `radius`. */
const EDGE_STOP = 0.72;
const FADE_MS = 260;

export function RadialMaskSpotlight({
  children,
  radius = 220,
  smoothing = 0.0006,
  className,
}: RadialMaskSpotlightProps) {
  const root = useRef<HTMLDivElement>(null);
  const lit = useRef<HTMLDivElement>(null);
  const enabled = useRef(false);
  const visible = useRef(false);

  const pointer = useSmoothPointer({
    target: root,
    smoothing,
    // Touch is explicitly off: this component is fine-pointer only, and
    // letting touch drags drive the mask would move the beam under the finger.
    touch: false,
  });

  useEffect(() => {
    const el = root.current;
    const layer = lit.current;
    if (!el || !layer) return;

    const fine = window.matchMedia('(pointer: fine)').matches;
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

    if (!fine) {
      /* No pointer to track. Rather than leaving a masked layer invisible, the
         mask is removed entirely so the lit layer simply shows in full — the
         content stays readable and nothing is hidden behind an effect that
         cannot be operated. */
      layer.style.maskImage = '';
      layer.style.webkitMaskImage = '';
      layer.style.opacity = '1';
      return;
    }

    enabled.current = !reduced;

    if (reduced) {
      /* Reduced motion keeps the spotlight — it is a hover affordance, not
         gratuitous movement — but pins it. A beam that chases the pointer with
         inertia is the part that was objected to, so the mask is written once,
         parked, and never updated again. */
      const rect = el.getBoundingClientRect();
      writeMask(layer, rect.width * 0.5, rect.height * 0.45, radius);
      layer.style.opacity = '1';
      return;
    }

    const onEnter = () => {
      visible.current = true;
      layer.style.opacity = '1';
    };
    const onLeave = () => {
      visible.current = false;
      layer.style.opacity = '0';
    };

    el.addEventListener('pointerenter', onEnter);
    el.addEventListener('pointerleave', onLeave);

    return () => {
      el.removeEventListener('pointerenter', onEnter);
      el.removeEventListener('pointerleave', onLeave);
      enabled.current = false;
      layer.style.maskImage = '';
      layer.style.webkitMaskImage = '';
      layer.style.opacity = '';
    };
  }, [radius]);

  useRaf(() => {
    const layer = lit.current;
    if (!layer || !enabled.current) return;
    const p = pointer.current;
    // `active` is false until a real pointer has been seen. Writing before
    // that would place the beam at the hook's centre-parked seed value, which
    // flashes a spotlight the user never asked for.
    if (!p.active) return;
    writeMask(layer, p.x, p.y, radius);
  });

  return (
    <div ref={root} className={cn('relative isolate overflow-hidden', className)}>
      <div
        ref={lit}
        className="absolute inset-0"
        style={{
          opacity: 0,
          transition: `opacity ${FADE_MS}ms ease-out`,
          // Seeded off-panel so the very first painted frame cannot show an
          // unmasked layer before rAF runs.
          maskImage: restMask(radius),
          WebkitMaskImage: restMask(radius),
        }}
      >
        {children}
      </div>
    </div>
  );
}

function maskFor(x: number, y: number, radius: number): string {
  /* `circle <radius>px at <x>px <y>px` — an explicit px radius rather than a
     percentage, because a percentage radius in a radial gradient resolves
     against the box and would make the beam a different physical size on
     every panel it is dropped into. */
  return `radial-gradient(circle ${radius}px at ${x}px ${y}px, #000 0%, #000 ${
    CORE_STOP * 100
  }%, transparent ${EDGE_STOP * 100}%)`;
}

function restMask(radius: number): string {
  return maskFor(-radius * 2, -radius * 2, radius);
}

function writeMask(layer: HTMLElement, x: number, y: number, radius: number) {
  const value = maskFor(x, y, radius);
  /* Both spellings. Safari has shipped unprefixed `mask-image` for years but
     still mishandles gradient masks without `-webkit-` in enough released
     versions that dropping the prefix means the layer is either fully visible
     or fully gone on those browsers — a total failure, not a degraded one. */
  layer.style.maskImage = value;
  layer.style.webkitMaskImage = value;
}
// #endregion critical

/* ==========================================================================
   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 { useEffect, useRef, type RefObject } from 'react';
import { useRaf } from '@/hooks/use-raf';
import { damp } from '@/lib/damp';

/* ==========================================================================
   Pointer position, smoothed, in several coordinate spaces at once.
   --------------------------------------------------------------------------
   Almost every cursor effect wants the same four things and computes them
   slightly differently each time: client pixels, element-local pixels, 0..1
   normalised, and -1..1 NDC for shaders. Producing all four from one damped
   source keeps a cursor dot and the shader it drives exactly in step.

   Exposed via ref for the same reason as scroll velocity: per-frame values
   must not re-render.
   ========================================================================== */

export interface PointerState {
  /** Viewport pixels. */
  clientX: number;
  clientY: number;
  /** Pixels relative to the target element's top-left. */
  x: number;
  y: number;
  /** 0..1 across the element. */
  nx: number;
  ny: number;
  /** -1..1, y up. Feed straight into a shader uniform. */
  ndcX: number;
  ndcY: number;
  /** Whether the pointer has been seen. Nothing should render before. */
  active: boolean;
}

export interface UseSmoothPointerOptions {
  /** Fraction of the gap remaining after one second. Lower = tighter. */
  smoothing?: number;
  /** Listen on this element rather than the window. */
  target?: RefObject<HTMLElement | null>;
  /** Follow touch drags as well as mouse moves. */
  touch?: boolean;
}

function makeInitialState(): PointerState {
  return {
    clientX: 0,
    clientY: 0,
    x: 0,
    y: 0,
    nx: 0.5,
    ny: 0.5,
    ndcX: 0,
    ndcY: 0,
    active: false,
  };
}

export function useSmoothPointer(
  options: UseSmoothPointerOptions = {},
): { current: PointerState } {
  const { smoothing = 0.001, target, touch = true } = options;

  const state = useRef<PointerState>(makeInitialState());
  // `null` means "no real pointer yet", which is distinct from a legitimate
  // pointer at (0, 0) in the top-left corner.
  const targetPos = useRef<{ clientX: number; clientY: number } | null>(null);
  const seeded = useRef(false);

  // Options the listener needs but that must not re-subscribe it on change.
  const touchRef = useRef(touch);
  touchRef.current = touch;

  useEffect(() => {
    const el = target?.current ?? null;
    const node: HTMLElement | Window = el ?? window;

    const onMove = (event: Event) => {
      const e = event as PointerEvent;
      if (!touchRef.current && e.pointerType === 'touch') return;
      targetPos.current = { clientX: e.clientX, clientY: e.clientY };
    };

    node.addEventListener('pointermove', onMove, { passive: true });
    return () => node.removeEventListener('pointermove', onMove);
    // `target` is a ref object; its identity is stable for the component's
    // lifetime, so this subscribes once.
  }, [target]);

  useRaf((dt) => {
    const el = target?.current ?? null;
    const rect = el
      ? el.getBoundingClientRect()
      : {
          left: 0,
          top: 0,
          width: window.innerWidth,
          height: window.innerHeight,
        };

    const pointer = targetPos.current;

    if (pointer === null) {
      // Park at the centre until a real pointer arrives, so the first move
      // eases out from the middle rather than snapping in from (0, 0). Done
      // once — re-centring every frame would fight a slow first movement.
      if (!seeded.current && rect.width > 0 && rect.height > 0) {
        seeded.current = true;
        const cx = rect.left + rect.width / 2;
        const cy = rect.top + rect.height / 2;
        state.current = {
          ...state.current,
          clientX: cx,
          clientY: cy,
          x: cx - rect.left,
          y: cy - rect.top,
        };
      }
      return;
    }

    const clientX = damp(state.current.clientX, pointer.clientX, smoothing, dt);
    const clientY = damp(state.current.clientY, pointer.clientY, smoothing, dt);

    const x = clientX - rect.left;
    const y = clientY - rect.top;
    const nx = rect.width > 0 ? x / rect.width : 0.5;
    const ny = rect.height > 0 ? y / rect.height : 0.5;

    state.current = {
      clientX,
      clientY,
      x,
      y,
      nx,
      ny,
      ndcX: nx * 2 - 1,
      ndcY: -(ny * 2 - 1),
      active: true,
    };
  });

  return state;
}