Dual-Canvas Depth Split

'use client';

import { type ReactNode, useEffect, useRef, useState } from 'react';
import { Color, Geometry, Mesh, Program, Renderer } from 'ogl';
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 } from '@/lib/damp';
import { createRng, randRange } from '@/lib/prng';
import { hasWebGL, loseContext, pixelRatio } from '@/lib/webgl';
import {
  DUAL_CANVAS_Z_SPLIT_FRAG,
  DUAL_CANVAS_Z_SPLIT_VERT,
} from '@/components/motion/shaders/dual-canvas-z-split';

/* ==========================================================================
   Dual-Canvas Depth Split
   --------------------------------------------------------------------------
   Two stacked canvases render the SAME particle system with opposite
   `uZSign`, and the page content sits between them. Particles with negative
   depth pass behind the text, positive ones pass in front, and because size,
   parallax rate, brightness and softness are one continuous ramp across the
   depth axis, the plane where the split happens is invisible. The text does
   not sit on a field; it sits inside one.

   Doing this with one canvas is not possible: the DOM has to interleave, and a
   canvas is a single stacking-context leaf. The cost is two WebGL contexts out
   of the ~16 a Chromium renderer process allows, which is why both are
   released on unmount rather than left to GC.
   ========================================================================== */

export interface DualCanvasZSplitProps {
  /** Content rendered between the two particle layers. */
  children?: ReactNode;
  /** Particles per megapixel of container area. The count is derived, not fixed. */
  density?: number;
  /** Population ceiling, and the size the buffers are allocated at. */
  maxCount?: number;
  /** Fraction of the population placed in FRONT of the content. */
  split?: number;
  /** Disc diameter in CSS pixels at the far and near ends of the depth ramp. */
  sizeRange?: readonly [number, number];
  /** Multiplier on the whole drift. */
  speed?: number;
  /** Sinusoidal wander amplitude in field units, where 1 is the container. */
  wander?: number;
  /** Overall alpha multiplier. The front layer takes a fraction of it. */
  opacity?: number;
  /** First tint. Any value `ogl`'s `Color` accepts. */
  colorA?: string;
  /** Second tint; each particle mixes between the two. */
  colorB?: string;
  /** Opaque clear colour of the BACK canvas. The front canvas is transparent. */
  background?: string;
  /** Seed for the scatter. Same seed, same field every reload. */
  seed?: number | string;
  className?: string;
}

interface Uniforms {
  /** ogl types `uniforms` as an open record; the index signature keeps it assignable. */
  [name: string]: { value: unknown };
  uResolution: { value: [number, number] };
  uPixelRatio: { value: number };
  uElapsed: { value: number };
  uZSign: { value: number };
  uDrift: { value: number };
  uRise: { value: number };
  uFlowScale: { value: number };
  uWander: { value: number };
  uFadeBand: { value: number };
  uMinSize: { value: number };
  uMaxSize: { value: number };
  uColorA: { value: Color };
  uColorB: { value: Color };
  uOpacity: { value: number };
}

interface Layer {
  renderer: Renderer;
  geometry: Geometry;
  program: Program;
  mesh: Mesh;
  uniforms: Uniforms;
  canvas: HTMLCanvasElement;
}

interface Stage {
  layers: Layer[];
  resize: (width: number, height: number) => void;
  draw: (elapsed: number) => void;
}

interface FieldData {
  quad: Float32Array;
  index: Uint16Array;
  origins: Float32Array;
  depths: Float32Array;
  seeds: Float32Array;
}

/** Floor on the population. Below this the field reads as a few stray specks. */
const MIN_COUNT = 250;
/** Cycles of wander across the field. */
const FLOW_SCALE = 1.3;
/** Field heights per second at `speed` 1, before the per-particle depth factor. */
const RISE = 0.05;
/** Fraction of the field height the wrap fade occupies at each end. */
const FADE_BAND = 0.14;
/**
 * The front layer is deliberately dimmer than the back one. Dust in front of
 * body copy is a legibility cost, and at parity the text reads as fogged.
 */
const FRONT_OPACITY = 0.55;
/** Fill is the whole cost here and it scales with the square of the ratio. */
const MAX_DPR = 1.5;
/** `elapsed` for the reduced-motion still and for post-resize redraws. */
const STATIC_ELAPSED = 0;

/** Field-space x range, wider than the container so wander never bares an edge. */
const X_MIN = -0.08;
const X_MAX = 1.08;
/** Dead zone around the content plane. A particle at depth 0 belongs to neither side. */
const DEPTH_FLOOR = 0.05;

// #region critical
function createLayer(
  host: HTMLElement,
  data: FieldData,
  opts: {
    zSign: number;
    opaque: boolean;
    background: Color;
    colorA: Color;
    colorB: Color;
    speed: number;
    wander: number;
    opacity: number;
    minSize: number;
    maxSize: number;
  },
): Layer {
  const renderer = new Renderer({
    dpr: pixelRatio(MAX_DPR),
    // The back layer owns its pixels, so it is opaque and can blend
    // additively. The front layer sits over live DOM text and must be
    // transparent, which rules additive out — there is nothing on the GPU to
    // add to. It blends premultiplied source-over instead.
    alpha: !opts.opaque,
    premultipliedAlpha: !opts.opaque,
    // Nothing occludes anything in either layer; the depth ORDER is expressed
    // by which canvas a particle lands on, not by a z-buffer.
    depth: false,
    antialias: false,
    powerPreference: 'low-power',
  });

  const gl = renderer.gl;
  const canvas = gl.canvas;

  if (opts.opaque) gl.clearColor(opts.background.r, opts.background.g, opts.background.b, 1);
  else gl.clearColor(0, 0, 0, 0);

  // Each layer needs its own attribute descriptors — ogl writes the buffer
  // handle and the element count into the object it is handed — but the
  // underlying typed arrays are shared, so the two contexts hold identical
  // particles rather than two independent fields.
  const geometry = new Geometry(gl, {
    index: { data: data.index },
    position: { size: 2, data: data.quad },
    aOrigin: { size: 2, data: data.origins, instanced: 1 },
    aDepth: { size: 1, data: data.depths, instanced: 1 },
    aSeed: { size: 4, data: data.seeds, instanced: 1 },
  });

  const uniforms: Uniforms = {
    uResolution: { value: [1, 1] },
    uPixelRatio: { value: renderer.dpr },
    uElapsed: { value: 0 },
    uZSign: { value: opts.zSign },
    uDrift: { value: opts.speed },
    uRise: { value: RISE },
    uFlowScale: { value: FLOW_SCALE },
    uWander: { value: opts.wander },
    uFadeBand: { value: FADE_BAND },
    uMinSize: { value: opts.minSize },
    uMaxSize: { value: opts.maxSize },
    uColorA: { value: opts.colorA },
    uColorB: { value: opts.colorB },
    uOpacity: { value: opts.opacity },
  };

  const program = new Program(gl, {
    vertex: DUAL_CANVAS_Z_SPLIT_VERT,
    fragment: DUAL_CANVAS_Z_SPLIT_FRAG,
    uniforms,
    transparent: true,
    depthTest: false,
    depthWrite: false,
    // ogl defaults `cullFace` to BACK, and a culled particle is absent with no
    // error anywhere. Nothing here has a back face worth culling.
    cullFace: false,
  });
  if (opts.opaque) program.setBlendFunc(gl.ONE, gl.ONE);
  else program.setBlendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);

  const mesh = new Mesh(gl, { geometry, program });

  host.appendChild(canvas);
  canvas.style.display = 'block';

  return { renderer, geometry, program, mesh, uniforms, canvas };
}

export function DualCanvasZSplit({
  children,
  density = 850,
  maxCount = 1600,
  split = 0.38,
  sizeRange = [3, 34],
  speed = 1,
  wander = 0.05,
  opacity = 0.6,
  colorA = '#8ea6c4',
  colorB = '#e6d9c4',
  background = '#06080c',
  seed = 'dual-canvas-z-split',
  className,
}: DualCanvasZSplitProps) {
  const host = useRef<HTMLDivElement>(null);
  const backHost = useRef<HTMLDivElement>(null);
  const frontHost = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

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

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

  const [minSize = 3, maxSize = 34] = sizeRange;

  useEffect(() => {
    const back = backHost.current;
    const front = frontHost.current;
    if (!back || !front || !ready) return;

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

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const data: FieldData = {
      quad: new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]),
      index: new Uint16Array([0, 1, 2, 0, 2, 3]),
      origins: new Float32Array(total * 2),
      depths: new Float32Array(total),
      seeds: new Float32Array(total * 4),
    };

    const rng = createRng(seed);
    const frontShare = clamp(split, 0, 1);
    const lo = Math.max(1, Math.min(minSize, maxSize));
    const hi = Math.max(lo + 0.5, Math.max(minSize, maxSize));

    for (let i = 0; i < total; i += 1) {
      data.origins[i * 2] = randRange(rng, X_MIN, X_MAX);
      data.origins[i * 2 + 1] = rng();

      // The sign picks the canvas, the magnitude drives size, parallax,
      // brightness and softness. A particle exactly at 0 would be on the
      // content plane and belongs to neither layer, so the range excludes it.
      const inFront = rng() < frontShare;
      data.depths[i] = inFront
        ? randRange(rng, DEPTH_FLOOR, 1)
        : -randRange(rng, DEPTH_FLOOR, 1);

      data.seeds[i * 4] = rng() * Math.PI * 2;
      data.seeds[i * 4 + 1] = rng() * Math.PI * 2;
      data.seeds[i * 4 + 2] = rng();
      // Size jitter on top of the depth ramp. Without it the depth ordering is
      // perfectly legible from size alone, which reads as a diagram.
      data.seeds[i * 4 + 3] = randRange(rng, 0.7, 1.3);
    }

    const colA = new Color(colorA);
    const colB = new Color(colorB);
    const bg = new Color(background);
    const shared = {
      background: bg,
      colorA: colA,
      colorB: colB,
      speed,
      wander,
      minSize: lo,
      maxSize: hi,
    };

    const layers = [
      createLayer(back, data, { ...shared, zSign: -1, opaque: true, opacity }),
      createLayer(front, data, {
        ...shared,
        zSign: 1,
        opaque: false,
        opacity: opacity * FRONT_OPACITY,
      }),
    ];

    const resize = (w: number, h: number) => {
      // Population from area, not a fixed number, so one density reads right in
      // a 320px card and a 2000px hero. The buffers already hold `total`
      // particles in scattered order, so a prefix is still an even field —
      // nothing is reallocated.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);

      for (const layer of layers) {
        layer.renderer.setSize(w, h);
        // `setSize` writes literal px into the canvas's inline style, which
        // beats any class. Re-asserting percentages keeps it fluid.
        layer.canvas.style.width = '100%';
        layer.canvas.style.height = '100%';
        layer.uniforms.uResolution.value = [
          layer.renderer.gl.drawingBufferWidth,
          layer.renderer.gl.drawingBufferHeight,
        ];
        layer.uniforms.uPixelRatio.value = layer.renderer.dpr;
        layer.geometry.setInstancedCount(count);
      }
    };

    const draw = (elapsed: number) => {
      for (const layer of layers) {
        layer.uniforms.uElapsed.value = elapsed;
        layer.renderer.render({ scene: layer.mesh });
      }
    };

    resize(size.current.width, size.current.height);
    stage.current = { layers, resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      for (const layer of layers) {
        // ogl has no `dispose()`: `remove()` deletes the VAOs and every buffer,
        // then the program and its shaders, and only `WEBGL_lose_context` gives
        // the context itself back. This component holds two of them.
        layer.geometry.remove();
        layer.program.remove();
        loseContext(layer.renderer.gl);
        layer.canvas.width = 0;
        layer.canvas.height = 0;
        layer.canvas.remove();
      }
    };
  }, [
    ready,
    density,
    maxCount,
    split,
    minSize,
    maxSize,
    speed,
    wander,
    opacity,
    colorA,
    colorB,
    background,
    seed,
  ]);

  // Resize is its own effect: a reflow costs two `setSize` calls and an
  // instanced-count change, never a rebuild of the shared buffers.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

  useRaf(
    (_dt, elapsed) => stage.current?.draw(elapsed),
    ready && inView && visible && !reduced && !unsupported,
  );
  // #endregion critical

  return (
    <div ref={host} className={cn('relative h-full w-full overflow-hidden', className)}>
      <div
        ref={backHost}
        aria-hidden
        className="absolute inset-0 z-0"
        style={
          unsupported
            ? {
                backgroundImage:
                  'radial-gradient(circle at 30% 20%, var(--k-line) 1px, transparent 0), radial-gradient(circle at 70% 65%, var(--k-line-strong) 1px, transparent 0)',
                backgroundSize: '43px 47px, 61px 67px',
              }
            : undefined
        }
      />

      {/* The content is a sibling BETWEEN the two canvases. Nothing about it is
          drawn on the GPU, so it stays selectable, focusable and screen-readable
          while particles pass on both sides of it. */}
      <div className="relative z-10 h-full w-full">{children}</div>

      {/* The front canvas covers the content, so it must never take a click. */}
      <div ref={frontHost} aria-hidden className="pointer-events-none absolute inset-0 z-20" />
    </div>
  );
}

/* ==========================================================================
   Dual-Canvas Depth Split — GLSL
   --------------------------------------------------------------------------
   One particle system, one buffer, rendered twice into two stacked canvases
   with opposite uZSign. The DOM content sits between them, so the particles
   whose signed depth is negative pass behind it and the positive ones pass in
   front. That is the entire illusion: the text is not on top of a field, it is
   inside one.

   aDepth is the CAMERA AXIS, not a distance. -1 is far behind the content
   plane, +1 is close to the viewer, and 0 is the content plane itself. Size,
   parallax rate, brightness and edge softness are all one continuous ramp in
   that value, which is why the split at zero is invisible.

   Rejection happens in the vertex shader: a particle on the wrong side is
   given a clip-space position outside the frustum, so all four of its vertices
   are discarded before rasterisation and it costs no fragments at all.

   GLSL ES 1.00, so the same source compiles under a WebGL1 fallback context.
   ========================================================================== */

/**
 * position — the shared unit quad, -0.5..0.5 on both axes.
 * aOrigin  — rest position in field space; 0..1 covers the container, with x
 *   seeded slightly wider so wander never bares the side edges.
 * aDepth   — signed depth, -1..1. Sign picks the canvas; magnitude drives
 *   everything else.
 * aSeed    — x, y: flow phase offsets. z: tint mix. w: size jitter.
 */
export const DUAL_CANVAS_Z_SPLIT_VERT = /* glsl */ `
attribute vec2  position;
attribute vec2  aOrigin;
attribute float aDepth;
attribute vec4  aSeed;

uniform vec2  uResolution;
uniform float uPixelRatio;
uniform float uElapsed;
uniform float uZSign;
uniform float uDrift;
uniform float uRise;
uniform float uFlowScale;
uniform float uWander;
uniform float uFadeBand;
uniform float uMinSize;
uniform float uMaxSize;

varying vec2  vQuad;
varying float vAlpha;
varying float vTint;
varying float vSoft;
varying float vPixel;

const float TAU = 6.2831853;

void main() {
  vQuad  = position;
  vTint  = aSeed.z;

  /* Wrong side of the content plane: park the vertex outside the frustum. w is
     1.0 on purpose — vec4(2.0) would divide down to exactly the boundary and
     survive clipping. Setting vAlpha first keeps the varying defined for
     drivers that interpolate before clipping. */
  if (aDepth * uZSign <= 0.0) {
    vAlpha = 0.0;
    vSoft  = 0.0;
    vPixel = 1.0;
    gl_Position = vec4(2.0, 2.0, 2.0, 1.0);
    return;
  }

  float depth01 = aDepth * 0.5 + 0.5;

  /* Parallax: near particles travel further per second than far ones. This is
     the only depth cue that survives a still frame being described in prose,
     and the one the eye trusts most. */
  float par = 0.35 + 0.65 * depth01;

  float t = uElapsed * uDrift;

  vec2 p = aOrigin;
  p.y = fract(p.y + t * uRise * par);

  float wx = sin(p.y * uFlowScale * TAU + aSeed.x + t * TAU * 0.11);
  float wy = cos(p.x * uFlowScale * TAU + aSeed.y + t * TAU * 0.09);
  p += vec2(wx, wy) * uWander * par;

  /* fract() teleports a particle across the field; without a fade at both ends
     that seam is a visible pop, and at these counts something crosses it every
     few frames. */
  float fade = smoothstep(0.0, uFadeBand, p.y) * smoothstep(0.0, uFadeBand, 1.0 - p.y);

  float sizePx = mix(uMinSize, uMaxSize, depth01) * aSeed.w * uPixelRatio;

  /* The corner offset is scaled in PIXELS and converted to clip space after,
     so a disc stays circular in a container of any aspect ratio. */
  vec2 offset = position * sizePx / uResolution * 2.0;

  gl_Position = vec4(p * 2.0 - 1.0 + offset, 0.0, 1.0);

  vAlpha = fade * mix(0.35, 0.9, depth01);
  /* Near particles are softer, as a lens would render them. The defocus is
     what stops the front layer reading as dirt on the screen. */
  vSoft  = mix(0.3, 1.0, depth01);
  vPixel = 1.0 / max(sizePx, 1.0);
}
`;

export const DUAL_CANVAS_Z_SPLIT_FRAG = /* glsl */ `
precision mediump float;

uniform vec3  uColorA;
uniform vec3  uColorB;
uniform float uOpacity;

varying vec2  vQuad;
varying float vAlpha;
varying float vTint;
varying float vSoft;
varying float vPixel;

void main() {
  /* Analytic disc. No point sprites anywhere in this component: gl_PointCoord
     would cap the size at 255px on many drivers, and the near particles are
     deliberately larger than that at full width. */
  float d = length(vQuad) - 0.5;

  /* One device pixel is the floor on the edge width, which anti-aliases the
     hardest particles without derivatives — fwidth needs an extension under
     WebGL1 and this shader is ES 1.00 so it can run there. */
  float edge = max(vSoft * 0.5, vPixel);
  float mask = 1.0 - smoothstep(-edge, 0.0, d);
  if (mask <= 0.002) discard;

  float a = mask * vAlpha * uOpacity;
  vec3  tint = mix(uColorA, uColorB, vTint);

  /* Premultiplied output, which is what both layers need for different
     reasons: the back canvas is opaque and blends additively (ONE, ONE), the
     front canvas is transparent over live DOM text and blends source-over
     (ONE, ONE_MINUS_SRC_ALPHA). Same fragment, same colour, one output form. */
  gl_FragColor = vec4(tint * a, a);
}
`;

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