Analytic Disc Picking

'use client';

import {
  useCallback,
  useEffect,
  useRef,
  useState,
  type PointerEvent as ReactPointerEvent,
} from 'react';
import * as THREE from 'three';
import { cn } from '@/lib/utils';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { damp } from '@/lib/damp';
import { createRng } from '@/lib/prng';
import { disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  ANALYTIC_DISC_PICKING_FRAG,
  ANALYTIC_DISC_PICKING_VERT,
} from '@/components/motion/shaders/analytic-disc-picking';

/* ==========================================================================
   Analytic Disc Picking
   --------------------------------------------------------------------------
   A ring of camera-facing discs, hit-tested without a raycaster.

   `THREE.Raycaster` walks the scene, builds an inverse world matrix per
   object, transforms the ray into object space, and intersects it against
   every triangle. For a flat disc facing the camera all of that is answering
   a question you can answer in four arithmetic operations: the disc lies in a
   plane whose normal is the camera's view direction, so intersect the pointer
   ray with that plane and ask whether the hit landed within `radius` of the
   centre. One dot product, one divide, one squared-distance compare. No
   allocation, no traversal, and EXACT — not an approximation of the disc's
   screen footprint, but the same circle the shader rasterises.

   It is also the only correct approach here. The billboard happens in the
   vertex shader, so the mesh's rotation never reaches the geometry: the
   `BufferGeometry` in main memory is a square lying in world XY. A raycast
   intersects that square and answers about a shape nobody can see. Turn on
   `compare` and watch the two disagree.
   ========================================================================== */

export interface AnalyticDiscPickingProps {
  /** Discs around the ring. */
  count?: number;
  /** Seconds for one revolution. */
  period?: number;
  /** Disc radius in world units. Also the pick radius — they cannot drift. */
  discRadius?: number;
  /** Ring radius in world units. */
  ringRadius?: number;
  /** Base plate colour. Any value `THREE.Color` accepts. */
  color?: string;
  /** Colour of the picked disc. */
  accent?: string;
  /** Seed for the per-disc plate pattern. Same seed, same ring every reload. */
  seed?: number | string;
  /**
   * Also run a real `Raycaster` each frame and report what it thinks was hit.
   * Off by default because it costs an `intersectObjects` traversal per frame;
   * on, it is the proof that the raycaster is wrong about a shader billboard.
   */
  compare?: boolean;
  /** Fired when a disc is clicked, with its index. */
  onPick?: (index: number) => void;
  className?: string;
}

const TAU = Math.PI * 2;

/** Camera vertical field of view, degrees. */
const FOV = 42;
/** Camera distance from the ring centre, world units. */
const CAM_Z = 5.6;
/** Camera height. Enough lean to see the ring as a ring, not a row. */
const CAM_Y = 0.75;
/** Amplitude of the vertical wave the discs ride, world units. */
const WAVE = 0.34;
/** Fraction of the hover gap left after one second. See `damp`. */
const HOVER_SMOOTHING = 0.0006;
/** How much a hovered disc grows. The pick radius grows with it. */
const HOVER_GROWTH = 0.14;

interface DiscUniforms {
  /** three types `uniforms` as an open record; without this it is not assignable. */
  [name: string]: THREE.IUniform;
  uRadius: { value: number };
  uScale: { value: number };
  uColor: { value: THREE.Color };
  uAccent: { value: THREE.Color };
  uHover: { value: number };
  uPicked: { value: number };
  uSeed: { value: number };
  uDepth: { value: number };
}

interface Disc {
  mesh: THREE.Mesh;
  material: THREE.ShaderMaterial;
  uniforms: DiscUniforms;
  /** Ring phase at t = 0, radians. */
  phase: number;
  /** Eased hover weight, 0..1. Drives both the tint and the pick radius. */
  hover: number;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.PerspectiveCamera;
  discs: Disc[];
  geometry: THREE.PlaneGeometry;
  /** Scratch, reused every frame. Allocating in a pick loop is the whole bug. */
  raycaster: THREE.Raycaster;
  plane: THREE.Plane;
  hit: THREE.Vector3;
  viewDir: THREE.Vector3;
  ndc: THREE.Vector2;
  meshes: THREE.Mesh[];
  intersects: THREE.Intersection[];
  resize: (width: number, height: number) => void;
}

export function AnalyticDiscPicking({
  count = 13,
  period = 30,
  discRadius = 0.46,
  ringRadius = 2.15,
  color = '#7d848e',
  accent = '#e8e4dc',
  seed = 'analytic-disc-picking',
  compare = false,
  onPick,
  className,
}: AnalyticDiscPickingProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  /** Pointer in NDC. Null once it leaves — a pick must not survive the exit. */
  const pointer = useRef<{ x: number; y: number } | null>(null);
  /** Ring phase in radians, integrated rather than read off a wall clock. */
  const spin = useRef(0);
  const hovered = useRef(-1);
  const pickedRef = useRef(-1);
  /** Redraw request. With reduced motion nothing is drawn until this is set. */
  const dirty = useRef(true);

  const [hover, setHover] = useState(-1);
  const [picked, setPicked] = useState(-1);
  const [ghost, setGhost] = useState(-1);

  const onPickRef = useRef(onPick);
  onPickRef.current = onPick;

  const reduced = useReducedMotion();
  const { width, height } = useResizeObserver(host);
  const ready = width > 0 && height > 0;

  const size = useRef({ width, height });
  size.current = { width, height };

  useEffect(() => {
    const el = host.current;
    if (!el || !ready) return;

    if (!hasWebGL()) {
      setUnsupported(true);
      return;
    }

    // The renderer makes its own canvas and this effect owns it start to
    // finish. A React-rendered `<canvas ref>` cannot be used: StrictMode
    // double-invokes the effect, the first cleanup calls `forceContextLoss()`,
    // and the second run is handed the same, now permanently dead, element.
    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(FOV, 1, 0.1, 100);
    camera.position.set(0, CAM_Y, CAM_Z);
    camera.lookAt(0, 0, 0);

    // One geometry for every disc. It is a SQUARE — the fragment shader carves
    // the circle out of it — which is two triangles instead of a 32-segment
    // fan and gives an analytically anti-aliased rim.
    const geometry = new THREE.PlaneGeometry(discRadius * 2, discRadius * 2);

    const rng = createRng(seed);
    const base = new THREE.Color(color);
    const tint = new THREE.Color(accent);

    const discs: Disc[] = [];
    const meshes: THREE.Mesh[] = [];

    for (let i = 0; i < count; i += 1) {
      const uniforms: DiscUniforms = {
        uRadius: { value: discRadius },
        uScale: { value: 1 },
        uColor: { value: base.clone() },
        uAccent: { value: tint.clone() },
        uHover: { value: 0 },
        uPicked: { value: 0 },
        uSeed: { value: rng() },
        uDepth: { value: 1 },
      };

      const material = new THREE.ShaderMaterial({
        vertexShader: ANALYTIC_DISC_PICKING_VERT,
        fragmentShader: ANALYTIC_DISC_PICKING_FRAG,
        uniforms,
        transparent: true,
        // Painter's algorithm. three sorts the transparent pass back to front
        // by object distance, and the object's POSITION is untouched by the
        // billboard, so that sort is exactly right. Depth testing a set of
        // discard-shaped quads would punch holes in the rim anti-aliasing.
        depthTest: false,
        depthWrite: false,
      });

      const mesh = new THREE.Mesh(geometry, material);
      // Never culled: the frustum test uses the geometry's bounding sphere at
      // the mesh's transform, and the shader moves the vertices somewhere the
      // culler cannot see.
      mesh.frustumCulled = false;
      scene.add(mesh);

      discs.push({ mesh, material, uniforms, phase: (i / count) * TAU, hover: 0 });
      meshes.push(mesh);
    }

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.aspect = w / Math.max(h, 1);
      camera.updateProjectionMatrix();
      // `setFromCamera` reads `matrixWorld`, and nothing else in this component
      // renders before the first pick can happen.
      camera.updateMatrixWorld();
      dirty.current = true;
    };

    resize(size.current.width, size.current.height);

    stage.current = {
      renderer,
      scene,
      camera,
      discs,
      geometry,
      raycaster: new THREE.Raycaster(),
      plane: new THREE.Plane(),
      hit: new THREE.Vector3(),
      viewDir: new THREE.Vector3(),
      ndc: new THREE.Vector2(),
      meshes,
      intersects: [],
      resize,
    };

    return () => {
      stage.current = null;
      for (const disc of discs) {
        scene.remove(disc.mesh);
        disc.material.dispose();
      }
      // One shared geometry, disposed once. Order matters: release GPU objects
      // while the context is still alive, then hand the context back.
      geometry.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [ready, count, discRadius, ringRadius, color, accent, seed]);

  // Resize is its own effect: a container reflow costs a `setSize` call rather
  // than a teardown and rebuild of thirteen materials.
  useEffect(() => {
    stage.current?.resize(width, height);
  }, [width, height]);

  const readPointer = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
    const el = host.current;
    if (!el) return;
    // One rect read per pointer event. NDC is what `setFromCamera` wants:
    // x right-positive, y UP-positive, both in [-1, 1].
    const rect = el.getBoundingClientRect();
    if (rect.width === 0 || rect.height === 0) return;
    pointer.current = {
      x: ((e.clientX - rect.left) / rect.width) * 2 - 1,
      y: -(((e.clientY - rect.top) / rect.height) * 2 - 1),
    };
    dirty.current = true;
  }, []);

  const clearPointer = useCallback(() => {
    pointer.current = null;
    dirty.current = true;
  }, []);

  // #region critical
  useRaf((dt) => {
    const s = stage.current;
    if (!s) return;

    // The ring phase is integrated from dt, not read from a wall clock, so
    // freezing it for reduced motion is a matter of not adding anything.
    if (!reduced) {
      spin.current = (spin.current + (TAU / period) * dt) % TAU;
      dirty.current = true;
    }

    // -- place the discs -----------------------------------------------------
    for (const disc of s.discs) {
      const a = disc.phase + spin.current;
      disc.mesh.position.set(
        Math.sin(a) * ringRadius,
        Math.sin(a * 2) * WAVE,
        Math.cos(a) * ringRadius,
      );
      // `cos(a)` is +1 at the front of the ring and -1 at the back. Remapped
      // to 0..1 it is the depth fade, and it costs nothing extra here.
      disc.uniforms.uDepth.value = Math.cos(a) * 0.5 + 0.5;
    }
    // No `updateMatrixWorld` here on purpose. The discs are direct children of
    // the scene at identity, so `mesh.position` IS the world position, and the
    // camera's matrix was made current in `resize`. The only consumer of the
    // full matrix graph is `render`, which updates it itself.

    // -- the analytic pick ---------------------------------------------------
    let best = -1;
    const p = pointer.current;
    if (p) {
      s.ndc.set(p.x, p.y);
      // The Raycaster is used for its RAY and nothing else. Building an
      // NDC-to-world ray by hand means duplicating `unproject`; the expensive
      // half of raycasting is `intersectObjects`, which is never called.
      s.raycaster.setFromCamera(s.ndc, s.camera);
      const ray = s.raycaster.ray;
      // Every disc is parallel to the image plane, so they all share one
      // normal — the camera's view direction, already unit length. Only the
      // plane's constant differs from disc to disc.
      s.camera.getWorldDirection(s.viewDir);

      let bestAlong = Infinity;
      for (let i = 0; i < s.discs.length; i += 1) {
        const disc = s.discs[i];
        if (!disc) continue;

        s.plane.setFromNormalAndCoplanarPoint(s.viewDir, disc.mesh.position);
        // `intersectPlane` returns null when the plane is behind the ray
        // origin, which rejects anything behind the camera for free. Note that
        // `Ray.distanceToPlane` returns null too but is TYPED `number` in
        // @types/three — the honest signature is on this method.
        if (ray.intersectPlane(s.plane, s.hit) === null) continue;

        // Nearest along the ray wins. Checked first so a disc that cannot
        // beat the incumbent skips its own radius test.
        const along = s.hit.distanceToSquared(ray.origin);
        if (along >= bestAlong) continue;

        // The drawn radius, hover growth included. `uScale` was eased last
        // frame and is applied by the vertex shader this frame, so the region
        // tested is the region rasterised.
        const r = disc.uniforms.uRadius.value * disc.uniforms.uScale.value;
        if (s.hit.distanceToSquared(disc.mesh.position) > r * r) continue;

        bestAlong = along;
        best = i;
      }
    }

    // -- ease the hover, which the next frame's pick will read ---------------
    for (let i = 0; i < s.discs.length; i += 1) {
      const disc = s.discs[i];
      if (!disc) continue;
      const target = i === best ? 1 : 0;
      const next = damp(disc.hover, target, HOVER_SMOOTHING, dt);
      if (Math.abs(next - disc.hover) > 0.0005) dirty.current = true;
      disc.hover = next;
      disc.uniforms.uHover.value = next;
      disc.uniforms.uScale.value = 1 + HOVER_GROWTH * next;
      disc.uniforms.uPicked.value = i === pickedRef.current ? 1 : 0;
    }

    if (best !== hovered.current) {
      hovered.current = best;
      setHover(best);
      dirty.current = true;
    }

    // -- what a real raycaster would have said -------------------------------
    if (compare) {
      let g = -1;
      if (p) {
        // The raycaster reads `matrixWorld`, which `render` would not refresh
        // until the end of this frame. The analytic path needed no such call —
        // it reads `position` directly — so this traversal is a cost the
        // comparison introduces, not one it inherits.
        s.scene.updateMatrixWorld();
        // Reused array, cleared by hand: `intersectObjects` pushes into the
        // target and sorts it, but never empties it.
        s.intersects.length = 0;
        s.raycaster.intersectObjects(s.meshes, false, s.intersects);
        const first = s.intersects[0];
        if (first) g = s.meshes.indexOf(first.object as THREE.Mesh);
      }
      if (g !== ghost) setGhost(g);
    }

    if (dirty.current) {
      dirty.current = false;
      s.renderer.render(s.scene, s.camera);
    }
  }, ready && !unsupported);
  // #endregion critical

  const commitPick = useCallback(() => {
    const next = hovered.current;
    pickedRef.current = next;
    setPicked(next);
    dirty.current = true;
    if (next >= 0) onPickRef.current?.(next);
  }, []);

  return (
    <div
      ref={host}
      className={cn(
        'relative h-full w-full select-none overflow-hidden',
        hover >= 0 ? 'cursor-pointer' : 'cursor-default',
        className,
      )}
      onPointerMove={readPointer}
      onPointerDown={readPointer}
      onPointerLeave={clearPointer}
      onClick={commitPick}
    >
      {unsupported ? (
        <div className="absolute inset-0 grid place-items-center">
          <div className="flex items-center gap-2">
            {Array.from({ length: 5 }, (_, i) => (
              <div
                key={i}
                className="h-8 w-8 rounded-full border border-line"
                style={{ opacity: 0.25 + i * 0.15 }}
              />
            ))}
          </div>
        </div>
      ) : null}

      <div className="pointer-events-none absolute bottom-3 left-3 font-mono text-[10px] uppercase tracking-[0.08em] text-faint">
        <span className={hover >= 0 ? 'text-fg' : undefined}>
          {hover >= 0 ? `plane hit ${String(hover).padStart(2, '0')}` : 'plane no hit'}
        </span>
        {compare ? (
          <>
            <span className="mx-2 text-line-strong">/</span>
            <span className={ghost >= 0 ? 'text-fg' : undefined}>
              {ghost >= 0 ? `raycast ${String(ghost).padStart(2, '0')}` : 'raycast no hit'}
            </span>
          </>
        ) : null}
        <span className="mx-2 text-line-strong">/</span>
        <span className={picked >= 0 ? 'text-accent' : undefined}>
          {picked >= 0 ? `picked ${String(picked).padStart(2, '0')}` : 'nothing picked'}
        </span>
      </div>
    </div>
  );
}

/* ==========================================================================
   Analytic Disc Picking — GLSL
   --------------------------------------------------------------------------
   A view-space billboard. The vertex shader takes only the TRANSLATION out of
   `modelViewMatrix` — the matrix applied to the origin — and adds the quad's
   local offset afterwards, in view space. The result is always exactly
   parallel to the image plane no matter where the camera is or what rotation
   the mesh carries.

   That is also why `THREE.Raycaster` cannot pick these discs. The rotation
   never reaches the vertices, so the `BufferGeometry` in main memory is still
   an axis-aligned square lying in world XY. A raycast intersects that square.
   The pick has to be done against the shape the shader actually drew, which
   is what the analytic plane test in the component does.

   Shipped as a `.ts` template literal rather than a `.glsl` file so that
   `npx shadcn add` produces something that compiles without a bundler plugin.
   ========================================================================== */

/**
 * `uRadius` is the quad's half-width, and because the offset is added after
 * the projection-free part of the transform it is ALSO the disc's radius in
 * view-space world units. The CPU pick compares against the same number, so
 * the drawn silhouette and the hit region are the same circle by construction
 * rather than by agreement.
 *
 * `uScale` multiplies that radius. The hover growth rides on it, and the pick
 * reads the same eased value in the same frame, so a disc is never pickable
 * over an area it has not grown into yet.
 */
export const ANALYTIC_DISC_PICKING_VERT = /* glsl */ `
uniform float uRadius;
uniform float uScale;

varying vec2 vDisc;

void main() {
  // Local XY normalised to the unit disc. The quad is 2*uRadius across, so
  // this lands in [-1, 1] on both axes and the fragment shader can work in
  // units of "fraction of the radius" without knowing the radius.
  vDisc = position.xy / uRadius;

  // Column 3 of modelViewMatrix is the mesh origin in view space. Taking it
  // this way discards the mesh's rotation AND its scale, which is the point:
  // the billboard must not inherit either.
  vec4 mv = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
  mv.xy += position.xy * uScale;

  gl_Position = projectionMatrix * mv;
}
`;

/**
 * Draws the disc inside the square quad and throws the corners away. Using a
 * two-triangle quad plus `discard` rather than a `CircleGeometry` fan is the
 * cheaper and better-looking half of the trade: 2 triangles instead of 32,
 * and a rim that is analytically anti-aliased instead of polygonal.
 */
export const ANALYTIC_DISC_PICKING_FRAG = /* glsl */ `
precision highp float;

uniform vec3  uColor;
uniform vec3  uAccent;
/** 0..1, eased on the CPU so hover has weight rather than snapping. */
uniform float uHover;
/** 0 or 1. Set the instant a click resolves. */
uniform float uPicked;
/** 0..1 per disc, from a seeded PRNG. Decorrelates the plate pattern. */
uniform float uSeed;
/** Depth fade, 0 at the back of the ring and 1 at the front. */
uniform float uDepth;

varying vec2 vDisc;

const float PI = 3.141592653589793;

/* Rim softness in units of the radius. At preview scale a disc is roughly
   90 px across, so 0.035 is about 1.5 px of gradient — enough to kill the
   staircase on a 1x display, narrow enough that the edge still reads as an
   edge rather than a glow. */
const float FEATHER = 0.035;
/* Outline thickness, same units. Below ~0.03 the outline drops below one
   physical pixel on the far discs and flickers as the ring turns. */
const float RIM = 0.055;

void main() {
  float d = length(vDisc);
  // The corners of the quad. Discarding is correct here rather than wasteful:
  // it is the only reason a square mesh can stand in for a circle.
  if (d > 1.0) discard;

  float disc = 1.0 - smoothstep(1.0 - FEATHER, 1.0, d);
  float rim = smoothstep(1.0 - RIM - FEATHER, 1.0 - RIM, d) * disc;

  // Procedural plate art. One angular sweep whose phase comes from the seed,
  // so a ring of discs reads as a ring of different pieces without a single
  // byte of texture being uploaded.
  float a = atan(vDisc.y, vDisc.x) + uSeed * PI * 2.0;
  float sweep = 0.5 + 0.5 * sin(a * 3.0 + d * 6.0 - uSeed * 4.0);
  float body = mix(0.30, 0.72, sweep) * (1.0 - 0.42 * d * d);

  vec3 col = uColor * body;
  col = mix(col, uAccent * 0.85, uPicked * 0.6);
  // Hover lifts the whole plate rather than only its outline: at preview size
  // an outline-only hover is invisible on the discs at the back of the ring.
  col += uHover * 0.26;
  col = mix(col, mix(uColor, uAccent, uPicked), rim * (0.30 + 0.70 * uHover));

  // Depth is faked in the shader instead of with fog so that the fade is
  // independent of the camera's near/far planes and survives a resize.
  float fade = mix(0.30, 1.0, uDepth);

  gl_FragColor = vec4(col * fade, disc);
}
`;

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

/* ==========================================================================
   Seeded randomness.
   --------------------------------------------------------------------------
   `Math.random()` in a particle field means the server and the client
   disagree, which React reports as a hydration mismatch, and it means the
   layout is different on every reload so a visual regression is invisible.
   Every component that scatters something uses a seeded generator instead.
   ========================================================================== */

export type Rng = () => number;

/**
 * mulberry32 — 32-bit, fast, and good enough for visual scatter. Returns a
 * function yielding floats in [0, 1).
 */
export function mulberry32(seed: number): Rng {
  let a = seed >>> 0;
  return function next() {
    a = (a + 0x6d2b79f5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

/** Turn any string into a 32-bit seed, so `seed="hero"` is reproducible. */
export function hashSeed(input: string): number {
  let h = 2166136261 >>> 0;
  for (let i = 0; i < input.length; i++) {
    h ^= input.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  return h >>> 0;
}

export function createRng(seed: number | string): Rng {
  return mulberry32(typeof seed === 'string' ? hashSeed(seed) : seed);
}

export function randRange(rng: Rng, min: number, max: number): number {
  return min + rng() * (max - min);
}

export function randInt(rng: Rng, min: number, maxExclusive: number): number {
  return Math.floor(randRange(rng, min, maxExclusive));
}

/**
 * Uniform point on a unit sphere. Naive angle-pairing clusters at the poles;
 * this inverts the cosine so density is even.
 */
export function randOnSphere(rng: Rng): [number, number, number] {
  const u = rng() * 2 - 1;
  const theta = rng() * Math.PI * 2;
  const r = Math.sqrt(1 - u * u);
  return [r * Math.cos(theta), r * Math.sin(theta), u];
}

/** Uniform point in a unit disc — `sqrt` prevents crowding at the centre. */
export function randInDisc(rng: Rng): [number, number] {
  const r = Math.sqrt(rng());
  const theta = rng() * Math.PI * 2;
  return [r * Math.cos(theta), r * Math.sin(theta)];
}

/** In-place Fisher-Yates using the supplied generator. */
export function shuffle<T>(rng: Rng, arr: T[]): T[] {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = randInt(rng, 0, i + 1);
    const a = arr[i] as T;
    const b = arr[j] as T;
    arr[i] = b;
    arr[j] = a;
  }
  return arr;
}

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

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