Cursor-Reactive Shader Glow

'use client';

import { useEffect, useRef, useState, type ReactNode } from 'react';
import * as THREE from 'three';
import { cn } from '@/lib/utils';
import { useInView } from '@/hooks/use-in-view';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { useVisibility } from '@/hooks/use-visibility';
import { clamp, damp } from '@/lib/damp';
import { disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  cursorReactiveShaderGlowFragmentShader,
  cursorReactiveShaderGlowVertexShader,
} from '@/components/motion/shaders/cursor-reactive-shader-glow';

/* ==========================================================================
   Cursor-Reactive Shader Glow
   --------------------------------------------------------------------------
   A hero backdrop: a slow warped-noise atmosphere with a light that follows
   the cursor through it. Three decisions carry the whole thing.

   1. THE POINTER IS DAMPED ON THE CPU, NEVER WRITTEN STRAIGHT INTO A UNIFORM.
      A `pointermove` handler that assigns the uniform hands the shader one
      raw sample per event: on a 120Hz trackpad that is a staircase, and on a
      dropped frame it is a jump. The handler records a TARGET; the render loop
      damps toward it with `damp(current, target, smoothing, dt)`, which is
      frame-rate independent by construction. A per-frame constant like
      `x += (t - x) * 0.1` converges twice as fast at 120Hz as at 60Hz, so the
      glow would trail differently on different hardware.

   2. THE POINTER ENTERS THE NOISE THREE TIMES, WEAKLY. Once on each warp
      channel with opposite signs, once on the final sample. Three weak
      influences read as "the atmosphere responds to you"; one strong influence
      reads as "the atmosphere is glued to the cursor".

   3. THE OUTPUT HAS A LUMINANCE CEILING. This is a backdrop, so the thing that
      matters is that copy stays readable over it. The shader measures the
      Rec.709 luminance of the colour it composed and scales the whole vector
      until it fits under `ceiling`. Turning `glowGain` up cannot break the
      contrast of the text on top, which means the parameter is safe to tune.

   `energy` is measured from the FOLLOWER's speed, not the raw pointer's. The
   follower is already smooth, so the measurement needs no second filter and a
   single stray event cannot spike it.
   ========================================================================== */

export interface CursorReactiveShaderGlowProps {
  /** Overlay content. Pointer-transparent, so the canvas keeps receiving moves. */
  children?: ReactNode;
  /** Rec.709 luminance the output may never exceed. The contrast guarantee. */
  ceiling?: number;
  /** Radius of the tight glow core, in aspect-corrected UV units. */
  coreRadius?: number;
  /** Radius of the wide halo. Squared in the shader, so it has no edge. */
  haloRadius?: number;
  /** Noise frequency. Below 1 the features are larger than the screen. */
  scale?: number;
  /** How far the two warp channels push the third noise sample. */
  warp?: number;
  /** Peak brightness the noise field adds over `base`. */
  fieldGain?: number;
  /** Peak brightness the cursor glow adds over `base`. */
  glowGain?: number;
  /** Fraction of the pointer gap still remaining after one second. */
  smoothing?: number;
  /** Deepest colour, linear 0..1 RGB. */
  base?: readonly [number, number, number];
  /** Colour the noise field lifts toward. */
  tint?: readonly [number, number, number];
  /** Colour of the cursor light. */
  glowTint?: readonly [number, number, number];
  maxDpr?: number;
  className?: string;
}

// #region critical
/**
 * UV units per second the follower must cover for `uEnergy` to read 1. A slow
 * deliberate sweep across a hero is roughly 0.6/s; above ~2.5 the reading
 * saturates on ordinary movement and the brightness stops meaning anything.
 */
const ENERGY_FULL_SCALE = 1.8;
/** Fast: energy must track the hand, or the brightening arrives after the move. */
const ENERGY_SMOOTHING = 0.002;
/** Slow: presence is a fade in and out, and 400ms of it reads as a light. */
const PRESENCE_SMOOTHING = 0.02;
/** Fixed time slice for the reduced-motion still. Not 0 — that is a flat frame. */
const STILL_TIME = 8.2;
/** Where the light sits in the reduced-motion still. Off-centre reads composed. */
const STILL_POINTER: readonly [number, number] = [0.34, 0.6];
const STILL_ENERGY = 0.35;

const BASE: readonly [number, number, number] = [0.03, 0.031, 0.038];
const TINT: readonly [number, number, number] = [0.62, 0.7, 0.95];
const GLOW_TINT: readonly [number, number, number] = [1, 0.94, 0.86];

interface GlowUniforms {
  /** three types `uniforms` as an open record; the index signature matches it. */
  [name: string]: THREE.IUniform;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uTime: THREE.IUniform<number>;
  uPointer: THREE.IUniform<THREE.Vector2>;
  uPresence: THREE.IUniform<number>;
  uEnergy: THREE.IUniform<number>;
  uScale: THREE.IUniform<number>;
  uWarp: THREE.IUniform<number>;
  uCoreRadius: THREE.IUniform<number>;
  uHaloRadius: THREE.IUniform<number>;
  uFieldGain: THREE.IUniform<number>;
  uGlowGain: THREE.IUniform<number>;
  uCeiling: THREE.IUniform<number>;
  uBase: THREE.IUniform<THREE.Color>;
  uTint: THREE.IUniform<THREE.Color>;
  uGlowTint: THREE.IUniform<THREE.Color>;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.OrthographicCamera;
  geometry: THREE.PlaneGeometry;
  material: THREE.ShaderMaterial;
  uniforms: GlowUniforms;
}

export function CursorReactiveShaderGlow({
  children,
  ceiling = 0.175,
  coreRadius = 0.22,
  haloRadius = 0.85,
  scale = 0.7,
  warp = 0.9,
  fieldGain = 0.08,
  glowGain = 0.1,
  smoothing = 0.0016,
  base = BASE,
  tint = TINT,
  glowTint = GLOW_TINT,
  maxDpr = 2,
  className,
}: CursorReactiveShaderGlowProps) {
  const host = useRef<HTMLDivElement>(null);
  const mount = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { rootMargin: '10%' });
  const visible = useVisibility();
  const reduced = useReducedMotion();

  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  /* Raw pointer target in 0..1 with y up. `null` means no real pointer has been
     seen, which is distinct from a legitimate pointer in the bottom-left
     corner — the glow must not exist before the first move. */
  const target = useRef<{ x: number; y: number } | null>(null);
  const inside = useRef(false);
  /** The damped follower. Seeded at the centre so the first move eases outward. */
  const pos = useRef({ x: 0.5, y: 0.5 });
  const presence = useRef(0);
  const energy = useRef(0);

  /* Live config, read by the loop. Changing a number must not rebuild the
     renderer: Chromium kills the OLDEST context past ~16 per process, so a
     rebuild on every prop change blanks an unrelated canvas on the page. */
  const live = useRef({
    ceiling,
    coreRadius,
    haloRadius,
    scale,
    warp,
    fieldGain,
    glowGain,
    smoothing,
  });
  live.current = {
    ceiling,
    coreRadius,
    haloRadius,
    scale,
    warp,
    fieldGain,
    glowGain,
    smoothing,
  };

  const ready = supported && width > 1 && height > 1;

  useEffect(() => {
    const slot = mount.current;
    if (!slot || !ready) return;

    /* The canvas is created here, not owned by React. `reactStrictMode` is on,
       so this effect runs twice on mount; the first cleanup calls
       `forceContextLoss()`, and asking a React-owned <canvas> for a context
       afterwards hands back the DEAD one rather than a fresh context, leaving
       the preview permanently blank. A canvas created and removed per effect
       run has no such history. */
    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      alpha: false,
      powerPreference: 'low-power',
    });
    renderer.setPixelRatio(pixelRatio(maxDpr));
    renderer.setSize(width, height, false);
    const canvas = renderer.domElement;
    canvas.style.display = 'block';
    canvas.style.width = '100%';
    canvas.style.height = '100%';
    /* `touch-action: none` is deliberately NOT set. This is a decorative
       backdrop; swallowing a touch scroll to feed a glow nobody can see under
       their own finger is a straight downgrade. */
    slot.appendChild(canvas);

    const uniforms: GlowUniforms = {
      uResolution: { value: new THREE.Vector2(width, height) },
      uTime: { value: 0 },
      uPointer: { value: new THREE.Vector2(pos.current.x, pos.current.y) },
      uPresence: { value: 0 },
      uEnergy: { value: 0 },
      uScale: { value: scale },
      uWarp: { value: warp },
      uCoreRadius: { value: coreRadius },
      uHaloRadius: { value: haloRadius },
      uFieldGain: { value: fieldGain },
      uGlowGain: { value: glowGain },
      uCeiling: { value: ceiling },
      uBase: { value: new THREE.Color(base[0], base[1], base[2]) },
      uTint: { value: new THREE.Color(tint[0], tint[1], tint[2]) },
      uGlowTint: { value: new THREE.Color(glowTint[0], glowTint[1], glowTint[2]) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: cursorReactiveShaderGlowVertexShader,
      fragmentShader: cursorReactiveShaderGlowFragmentShader,
      uniforms,
    });

    // A 2x2 plane under an identity ortho camera is a full-screen quad with no
    // projection maths and no camera to keep in sync on resize.
    const geometry = new THREE.PlaneGeometry(2, 2);
    const scene = new THREE.Scene();
    scene.add(new THREE.Mesh(geometry, material));
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

    /* Listener on the CANVAS, not the window: no document-level handler
       survives to drive a disposed renderer, and the rect it measures is the
       rect it draws into. Passive, because nothing here ever calls
       preventDefault and a non-passive move listener on a scrollable page
       forces the compositor to wait for JS on every event. */
    const onMove = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      if (rect.width === 0 || rect.height === 0) return;
      target.current = {
        x: (event.clientX - rect.left) / rect.width,
        // Flipped: UV y is up, client y is down.
        y: 1 - (event.clientY - rect.top) / rect.height,
      };
      inside.current = true;
    };
    const onLeave = () => {
      // Presence only. Leaving the position alone dims the light where it
      // stands; tweening it away drags a visible streak off the edge.
      inside.current = false;
    };

    canvas.addEventListener('pointermove', onMove, { passive: true });
    canvas.addEventListener('pointerleave', onLeave, { passive: true });

    stage.current = { renderer, scene, camera, geometry, material, uniforms };
    renderer.render(scene, camera);

    return () => {
      stage.current = null;
      canvas.removeEventListener('pointermove', onMove);
      canvas.removeEventListener('pointerleave', onLeave);
      // `dispose()` frees GPU objects but leaves the context alive until GC
      // decides otherwise, which may be never. `disposeRenderer` is the one
      // that calls `forceContextLoss()` and actually hands it back.
      disposeRenderer(renderer);
      geometry.dispose();
      material.dispose();
      canvas.remove();
    };
    // Colours and gains are pushed through `live`/`uniforms` from the loop, so
    // they must not appear here — a rebuild per prop change leaks contexts.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, maxDpr]);

  // Resize is its own effect, so a reflow never touches the renderer's lifetime.
  useEffect(() => {
    const s = stage.current;
    if (!s || width < 1 || height < 1) return;
    s.renderer.setPixelRatio(pixelRatio(maxDpr));
    s.renderer.setSize(width, height, false);
    // CSS pixels, not the drawing buffer: the shader only takes the ratio.
    s.uniforms.uResolution.value.set(width, height);
    // Render once, or a resize while paused stretches the previous framebuffer
    // until the pointer moves again.
    s.renderer.render(s.scene, s.camera);
  }, [width, height, maxDpr]);

  useRaf(
    (dt, elapsed) => {
      const s = stage.current;
      if (!s) return;
      const cfg = live.current;

      const previousX = pos.current.x;
      const previousY = pos.current.y;

      const aim = target.current;
      if (aim) {
        pos.current.x = damp(pos.current.x, aim.x, cfg.smoothing, dt);
        pos.current.y = damp(pos.current.y, aim.y, cfg.smoothing, dt);
      }

      // Speed of the follower, in UV units per second. Dividing by dt is what
      // makes it a velocity rather than a per-frame delta that reads twice as
      // large at 60Hz as at 120Hz for the same physical hand movement.
      const travelled = Math.hypot(pos.current.x - previousX, pos.current.y - previousY);
      const speed = travelled / Math.max(dt, 0.0001);
      energy.current = damp(
        energy.current,
        clamp(speed / ENERGY_FULL_SCALE, 0, 1),
        ENERGY_SMOOTHING,
        dt,
      );
      presence.current = damp(
        presence.current,
        inside.current && aim !== null ? 1 : 0,
        PRESENCE_SMOOTHING,
        dt,
      );

      const u = s.uniforms;
      u.uTime.value = elapsed;
      u.uPointer.value.set(pos.current.x, pos.current.y);
      u.uPresence.value = presence.current;
      u.uEnergy.value = energy.current;
      u.uScale.value = cfg.scale;
      u.uWarp.value = cfg.warp;
      u.uCoreRadius.value = cfg.coreRadius;
      u.uHaloRadius.value = cfg.haloRadius;
      u.uFieldGain.value = cfg.fieldGain;
      u.uGlowGain.value = cfg.glowGain;
      u.uCeiling.value = cfg.ceiling;

      s.renderer.render(s.scene, s.camera);
    },
    ready && inView && visible && !reduced,
  );

  /* Reduced motion gets a composed picture, not an empty box: one frame at a
     fixed time slice with the light parked off-centre. Nothing ever moves, and
     the pointer listener stays attached but its target is never consumed. */
  useEffect(() => {
    const s = stage.current;
    if (!s || !reduced || width < 1 || height < 1) return;
    const [stillX = 0.34, stillY = 0.6] = STILL_POINTER;
    s.uniforms.uTime.value = STILL_TIME;
    s.uniforms.uPointer.value.set(stillX, stillY);
    s.uniforms.uPresence.value = 1;
    s.uniforms.uEnergy.value = STILL_ENERGY;
    s.renderer.render(s.scene, s.camera);
  }, [reduced, width, height, ready]);
  // #endregion critical

  return (
    <div
      ref={host}
      className={cn('relative isolate h-full w-full overflow-hidden bg-bg', className)}
    >
      <div ref={mount} aria-hidden className="absolute inset-0 z-0" />
      {supported ? null : (
        <div
          aria-hidden
          className="absolute inset-0 z-0"
          style={{
            backgroundImage:
              'radial-gradient(60% 60% at 34% 40%, var(--k-surface), transparent 70%), linear-gradient(160deg, var(--k-bg-subtle), var(--k-bg))',
          }}
        />
      )}
      {children ? (
        // Pointer-transparent: the canvas underneath must keep receiving moves,
        // and a full-bleed content layer would otherwise swallow every one of
        // them over the copy, which is exactly where the glow is wanted.
        <div className="pointer-events-none relative z-10 h-full w-full">{children}</div>
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Cursor-Reactive Shader Glow — GLSL
   --------------------------------------------------------------------------
   Shaders ship as `.ts` template literals, never `.glsl`. The registry item
   type enum has no GLSL member, and a `.glsl` import would force every
   consumer to install a bundler plugin — `npx shadcn add` would land a
   component that does not compile.

   Written for three.js `ShaderMaterial`, which prepends `position`, `uv` and
   the matrices, so those are not declared here. GLSL ES 1.00, which is what
   `ShaderMaterial` compiles to unless `glslVersion` says otherwise.

   Two ideas live in this file.

   1. THE POINTER ENTERS THE FIELD THREE TIMES, WEAKLY. Once on each of the
      two warp channels with opposite signs so they shear against each other,
      and once more on the final sample. Three weak influences read as "the
      atmosphere responds to you". One strong influence reads as "the
      atmosphere is glued to the cursor", which is a completely different and
      much worse effect.

   2. THE BRIGHTNESS BUDGET. The composed colour's Rec.709 luminance is
      measured and the whole vector is scaled down until it fits under
      `uCeiling`. The glow can therefore be tuned to taste without ever
      eating the contrast of white text sitting on top of it — the guarantee
      is enforced in the shader rather than promised in a comment.
   ========================================================================== */

export const cursorReactiveShaderGlowVertexShader = /* glsl */ `
  varying vec2 vUv;

  void main() {
    vUv = uv;
    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
  }
`;

export const cursorReactiveShaderGlowFragmentShader = /* glsl */ `
  precision highp float;

  uniform vec2  uResolution;
  uniform float uTime;
  /** Pointer in 0..1 with y up, ALREADY damped on the CPU. Writing a raw
      pointer here makes the field jump one full mouse-jerk per event. */
  uniform vec2  uPointer;
  /** 0..1. Damped up while the pointer is over the canvas, down on leave, so
      the glow dims where it stands instead of sliding away to a corner. */
  uniform float uPresence;
  /** 0..1 follower speed. A moving cursor burns brighter than a resting one. */
  uniform float uEnergy;
  /** Noise frequency. Below 1.0 the features are LARGER than the screen. */
  uniform float uScale;
  /** How far the two warp channels push the third sample. */
  uniform float uWarp;
  uniform float uCoreRadius;
  uniform float uHaloRadius;
  uniform float uFieldGain;
  uniform float uGlowGain;
  /** Hard ceiling on output luminance. The contrast guarantee. */
  uniform float uCeiling;
  uniform vec3  uBase;
  uniform vec3  uTint;
  uniform vec3  uGlowTint;

  varying vec2 vUv;

  /* --------------------------------------------------------------------------
     Sin-free hash. The usual fract(sin(dot(p, k)) * 43758.5) breaks down once
     the argument to sin() reaches a few thousand radians: the fractional part
     of the angle is quantised, the noise grows visible repeating bands, and it
     fails on mobile GPUs long before it fails on the desktop it was written
     on. This one is pure multiply-and-fract, so it has no such range limit.
     -------------------------------------------------------------------------- */
  vec2 hash22(vec2 p) {
    vec3 q = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));
    q += dot(q, q.yzx + 33.33);
    return -1.0 + 2.0 * fract((q.xx + q.yz) * q.zy);
  }

  /* Gradient noise, not value noise: the lattice value is a DOT PRODUCT with a
     random gradient, which is zero at every lattice point. That is what stops
     the cell corners reading as a faint dot grid in the flat areas — the exact
     artefact you cannot smoothstep away afterwards. */
  float gnoise(vec2 p) {
    vec2 i = floor(p);
    vec2 f = fract(p);
    /* Hermite fade. Linear interpolation leaves creases along the cell walls
       because the first derivative is discontinuous there. */
    vec2 u = f * f * (3.0 - 2.0 * f);

    float a = dot(hash22(i + vec2(0.0, 0.0)), f - vec2(0.0, 0.0));
    float b = dot(hash22(i + vec2(1.0, 0.0)), f - vec2(1.0, 0.0));
    float c = dot(hash22(i + vec2(0.0, 1.0)), f - vec2(0.0, 1.0));
    float d = dot(hash22(i + vec2(1.0, 1.0)), f - vec2(1.0, 1.0));

    return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
  }

  /* Two octaves, amplitude 0.6 then 0.3. Standard fbm runs four to six; two is
     enough because the result is immediately crushed by smoothstep(0.25, 0.85)
     and the extra detail is thrown away. fbm IS the cost of this shader, so
     halving the octave count halves the shader.

     The 0.8/0.6 rotation between octaves is not decoration. Both octaves share
     one axis-aligned lattice, and without a rotation their cell walls line up
     and the sum reads as a grid rather than as cloud. */
  const mat2 OCTAVE_ROT = mat2(0.8, 0.6, -0.6, 0.8);

  float fbm(vec2 p) {
    float sum = 0.0;
    float amp = 0.6;
    for (int i = 0; i < 2; i++) {
      sum += amp * gnoise(p);
      p = OCTAVE_ROT * p * 1.93;
      amp *= 0.5;
    }
    return sum;
  }

  void main() {
    float aspect = uResolution.x / max(uResolution.y, 1.0);

    /* Correct BOTH the sample space and the pointer. Correcting only the sample
       space leaves the glow as an ellipse 1.78x too wide on a 16:9 canvas. */
    vec2 p = vUv;
    p.x *= aspect;
    vec2 m = uPointer;
    m.x *= aspect;

    /* Extremely slow, and deliberately so. At 60fps the field advances 0.0005
       units per frame: weather, not animation. */
    float t = uTime * 0.03;
    /* Time as a 2D drift rather than a third noise dimension. 2D gradient noise
       costs four hashes per sample where 3D costs eight, and a slice through a
       3D field looks no different once it has been through the smoothstep. */
    vec2 sp = p * uScale + vec2(t, -t * 0.42);

    /* Domain warp. Two decorrelated fbm samples become an offset fed into a
       third. The vec2(2.3, 1.1) shift on the second channel is what
       decorrelates it — without it both channels return the same number and the
       warp degenerates into a plain diagonal translation.

       The pointer appears on all three samples with a sign flip between the two
       warp channels, so they shear against each other. */
    vec2 q = vec2(
      fbm(sp + m * 0.20),
      fbm(sp + vec2(2.3, 1.1) - m * 0.20)
    );
    float n = fbm(sp + q * uWarp + m * 0.12) * 0.5 + 0.5;
    float shade = smoothstep(0.25, 0.85, n);

    /* Two FALLING ramps. smoothstep(a, b, x) with a > b falls from 1 at the
       pointer to 0 at the radius — cheaper and clearer than
       1.0 - smoothstep(0.0, r, d), and it is one instruction either way.

       The halo is squared. A single smoothstep has a visible termination ring
       at its outer edge on a dark background because the eye is very good at
       finding the point where a gradient stops; squaring pushes the last few
       percent of the falloff below the 8-bit quantisation floor and the ring
       disappears. */
    float d = distance(p, m);
    float core = smoothstep(uCoreRadius, 0.0, d);
    float halo = smoothstep(uHaloRadius, 0.0, d);
    halo *= halo;
    float glow = (core * 0.65 + halo * 0.35) * uPresence;
    /* A resting cursor is an ember; a moving one is a torch. The floor is 0.72
       rather than 0 so stopping dims the glow instead of extinguishing it. */
    glow *= mix(0.72, 1.0, uEnergy);

    /* A vertical lift tied to pointer height. Tiny, and the only cue that the
       field knows where the cursor is when it is nowhere near the glow. */
    float lift = (uPointer.y - 0.5) * 0.03;

    vec3 col = uBase
             + uTint * (uFieldGain * shade + lift)
             + uGlowTint * (uGlowGain * glow);

    /* THE BRIGHTNESS BUDGET. Scale the whole vector, never clamp per channel:
       clamping crushes one channel first and the glow core visibly shifts hue
       as it brightens. Scaling preserves the ratio, so the colour is identical
       and only the level is capped. */
    float lum = dot(col, vec3(0.2126, 0.7152, 0.0722));
    col *= min(1.0, uCeiling / max(lum, 0.0001));

    /* Multiply, do not subtract. Scaling the whole result keeps the glow inside
       the vignette instead of letting it punch through at the corners. */
    float vig = smoothstep(1.25, 0.5, distance(vUv, vec2(0.5)));
    col *= mix(0.85, 1.0, vig);

    gl_FragColor = vec4(col, 1.0);
  }
`;

/* ==========================================================================
   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, useState, type RefObject } from 'react';

/* ==========================================================================
   IntersectionObserver, sharing one observer per option set.
   --------------------------------------------------------------------------
   A hundred cards each constructing their own observer is a hundred observers
   the compositor has to service. Keying a shared observer by its options
   collapses that to one per distinct configuration — in practice, two or
   three for the whole site.
   ========================================================================== */

export interface InViewState {
  inView: boolean;
  /** 0-1. The preview slot allocator ranks candidates by this. */
  ratio: number;
}

export interface UseInViewOptions {
  root?: Element | null;
  rootMargin?: string;
  /** Single number or list, same meaning as the native option. */
  threshold?: number | number[];
  /** Stop observing after the first time it becomes visible. */
  once?: boolean;
}

type Entry = {
  observer: IntersectionObserver;
  handlers: Map<Element, (e: IntersectionObserverEntry) => void>;
};

const pools = new Map<string, Entry>();

function poolFor(options: UseInViewOptions): Entry {
  const key = JSON.stringify({
    rootMargin: options.rootMargin ?? '0px',
    threshold: options.threshold ?? 0,
  });
  const existing = pools.get(key);
  if (existing) return existing;

  const handlers = new Map<Element, (e: IntersectionObserverEntry) => void>();
  const observer = new IntersectionObserver(
    (entries) => {
      for (const entry of entries) handlers.get(entry.target)?.(entry);
    },
    {
      root: options.root ?? null,
      rootMargin: options.rootMargin ?? '0px',
      threshold: options.threshold ?? 0,
    },
  );
  const created: Entry = { observer, handlers };
  pools.set(key, created);
  return created;
}

export function useInView(
  ref: RefObject<Element | null>,
  options: UseInViewOptions = {},
): InViewState {
  const [state, setState] = useState<InViewState>({ inView: false, ratio: 0 });
  const { root = null, rootMargin = '0px', once = false } = options;
  const thresholdKey = JSON.stringify(options.threshold ?? 0);
  const done = useRef(false);

  useEffect(() => {
    const el = ref.current;
    if (!el || typeof IntersectionObserver === 'undefined') return;
    if (once && done.current) return;

    const pool = poolFor({
      root,
      rootMargin,
      threshold: JSON.parse(thresholdKey) as number | number[],
    });

    const handle = (entry: IntersectionObserverEntry) => {
      setState({ inView: entry.isIntersecting, ratio: entry.intersectionRatio });
      if (once && entry.isIntersecting) {
        done.current = true;
        pool.handlers.delete(el);
        pool.observer.unobserve(el);
      }
    };

    pool.handlers.set(el, handle);
    pool.observer.observe(el);

    return () => {
      pool.handlers.delete(el);
      pool.observer.unobserve(el);
    };
  }, [ref, root, rootMargin, thresholdKey, once]);

  return state;
}

'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 { useEffect, useState, type RefObject } from 'react';

/* ==========================================================================
   Element size, from one shared ResizeObserver.
   --------------------------------------------------------------------------
   Sized from the element rather than the window because a preview in a grid
   cell resizes when the grid reflows, not when the viewport does. Reading
   `window.innerWidth` is the reason so many canvas components are correct on
   load and wrong after a sidebar opens.
   ========================================================================== */

export interface Size {
  width: number;
  height: number;
}

type Handler = (size: Size) => void;

let observer: ResizeObserver | null = null;
const handlers = new Map<Element, Handler>();

function ensureObserver(): ResizeObserver | null {
  if (typeof ResizeObserver === 'undefined') return null;
  observer ??= new ResizeObserver((entries) => {
    for (const entry of entries) {
      const box = entry.contentBoxSize?.[0];
      const size: Size = box
        ? { width: box.inlineSize, height: box.blockSize }
        : { width: entry.contentRect.width, height: entry.contentRect.height };
      handlers.get(entry.target)?.(size);
    }
  });
  return observer;
}

export function useResizeObserver(ref: RefObject<Element | null>): Size {
  const [size, setSize] = useState<Size>({ width: 0, height: 0 });

  useEffect(() => {
    const el = ref.current;
    const ro = ensureObserver();
    if (!el || !ro) return;

    // Seed synchronously: waiting for the first observer callback leaves one
    // frame where a canvas is sized 0x0, which some drivers log as an error.
    const rect = el.getBoundingClientRect();
    setSize({ width: rect.width, height: rect.height });

    handlers.set(el, (next) =>
      setSize((prev) =>
        prev.width === next.width && prev.height === next.height ? prev : next,
      ),
    );
    ro.observe(el);

    return () => {
      handlers.delete(el);
      ro.unobserve(el);
    };
  }, [ref]);

  return size;
}

'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);
}

import type * as THREE from 'three';

/* ==========================================================================
   WebGL context lifecycle.
   --------------------------------------------------------------------------
   Chromium allows roughly 16 live WebGL contexts per RENDERER PROCESS (8 on
   low-end devices). Creating the 17th does not fail — it fires
   `webglcontextlost` on the OLDEST one, so an unrelated component elsewhere
   on the page goes black. Same-origin iframes share the renderer process, so
   isolating previews in iframes does not raise the ceiling.

   The only real fix is to release contexts on unmount, and `renderer.dispose()`
   ALONE DOES NOT DO THAT. It frees GPU objects but leaves the context itself
   alive until GC decides otherwise, which may be never. `forceContextLoss()`
   is the call that actually hands it back.
   ========================================================================== */

/**
 * Fully release a three.js renderer. Call this in the `useEffect` cleanup of
 * any component that constructs a `WebGLRenderer` — the preview host drives
 * unmount via `<Activity mode="hidden">`, so ordinary cleanup IS the disposal
 * path and nothing component-specific is required.
 */
export function disposeRenderer(renderer: THREE.WebGLRenderer | null | undefined): void {
  if (!renderer) return;

  // Stop the loop first: a queued frame that renders into a lost context
  // throws, and the throw escapes the cleanup function.
  renderer.setAnimationLoop(null);
  renderer.dispose();
  renderer.forceContextLoss();

  const canvas = renderer.domElement;
  if (canvas) {
    // Zeroing the backing store releases the drawing buffer immediately
    // instead of holding width×height×4 bytes until the node is collected.
    canvas.width = 0;
    canvas.height = 0;
  }
}

/**
 * Release a raw WebGL context (ogl, or hand-written GL). The extension is the
 * only portable way to do it; it is absent in some headless configurations,
 * hence the optional call.
 */
export function loseContext(gl: WebGLRenderingContext | WebGL2RenderingContext | null | undefined): void {
  if (!gl) return;
  gl.getExtension('WEBGL_lose_context')?.loseContext();
}

/** Recursively dispose geometries, materials and textures under a root. */
export function disposeObject(root: THREE.Object3D | null | undefined): void {
  if (!root) return;
  root.traverse((obj) => {
    const mesh = obj as THREE.Mesh;
    mesh.geometry?.dispose?.();
    const material = mesh.material;
    if (!material) return;
    const materials = Array.isArray(material) ? material : [material];
    for (const m of materials) {
      for (const value of Object.values(m as unknown as Record<string, unknown>)) {
        if (value && typeof value === 'object' && 'isTexture' in value) {
          (value as THREE.Texture).dispose();
        }
      }
      m.dispose?.();
    }
  });
}

/**
 * Device pixel ratio capped for fill-rate. Above 2 the visual gain is nil and
 * the cost is quadratic; on a 3x phone an uncapped full-screen shader is the
 * single most common cause of a janky first paint.
 */
export function pixelRatio(max = 2): number {
  if (typeof window === 'undefined') return 1;
  return Math.min(window.devicePixelRatio || 1, max);
}

/**
 * Whether WebGL is actually available. Some browsers expose the constructor
 * but fail to create a context (blocklisted GPU, no hardware acceleration);
 * a component that assumes success renders a permanently blank box.
 */
export function hasWebGL(): boolean {
  if (typeof document === 'undefined') return false;
  try {
    const canvas = document.createElement('canvas');
    const gl =
      canvas.getContext('webgl2') ??
      canvas.getContext('webgl') ??
      canvas.getContext('experimental-webgl');
    if (!gl) return false;
    (gl as WebGLRenderingContext).getExtension('WEBGL_lose_context')?.loseContext();
    return true;
  } catch {
    return false;
  }
}