Instanced Quad Particles

'use client';

import { 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 {
  INSTANCED_QUAD_PARTICLES_FRAG,
  INSTANCED_QUAD_PARTICLES_VERT,
} from '@/components/motion/shaders/instanced-quad-particles';

/* ==========================================================================
   Instanced Quad Particles
   --------------------------------------------------------------------------
   A drifting dust field of up to 1800 particles in ONE draw call, built on ogl
   rather than three because the whole component is a single instanced mesh and
   a scene graph would be dead weight.

   Every particle is a quad, not a `gl_PointSize` sprite. Point sprites are
   capped at 255px on a lot of drivers, cannot be rotated, and are culled as a
   unit the moment their centre crosses the viewport edge — a large sprite
   vanishes while half of it is still visible. Quads have per-particle size,
   spin, softness and tint, and they clip like any other geometry.

   The buffers are allocated ONCE at `maxCount` and the visible population is
   selected with `setInstancedCount`, so resizing the container changes the
   particle count without touching a byte of GPU memory.
   ========================================================================== */

export interface InstancedQuadParticlesProps {
  /** Particles per megapixel of container area. The count is derived, not fixed. */
  density?: number;
  /** Hard ceiling on the population, and the size the buffers are allocated at. */
  maxCount?: number;
  /** Particle size range in CSS pixels, biased toward the small end. */
  sizeRange?: readonly [number, number];
  /** Edge softness, 0..1. 0 is a hard silhouette, 1 is a pure gradient. */
  softness?: number;
  /** Peak spin rate in radians per second. Each particle gets a signed fraction. */
  spin?: number;
  /** Multiplier on the whole drift, including the upward march. */
  speed?: number;
  /** Sideways and vertical wander, in field units (1 = the container). */
  wander?: number;
  /** Overall alpha multiplier. */
  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 the field is composited onto. */
  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 };
  uDrift: { value: number };
  uRise: { value: number };
  uFlowScale: { value: number };
  uWander: { value: number };
  uFadeBand: { value: number };
  uColorA: { value: Color };
  uColorB: { value: Color };
  uSoftness: { value: number };
  uOpacity: { value: number };
}

interface Stage {
  renderer: Renderer;
  geometry: Geometry;
  program: Program;
  mesh: Mesh;
  uniforms: Uniforms;
  resize: (width: number, height: number) => void;
  draw: (elapsed: number) => void;
}

/** Floor on the population. Below this the field reads as a few stray specks. */
const MIN_COUNT = 250;
/** Spatial frequency of the wander sinusoids, in cycles across the field. */
const FLOW_SCALE = 1.4;
/** Field heights per second the population marches upward at `speed` 1. */
const RISE = 0.045;
/** Fraction of the field height the wrap fade occupies at each end. */
const FADE_BAND = 0.12;
/** Size distribution exponent. Above 1 crowds the population into small sizes. */
const SIZE_BIAS = 2.2;
/**
 * Additive fill is the entire cost of this component and it scales with dpr
 * squared. Dust has no fine detail that a third sample per axis would resolve,
 * so the ratio is capped well below 2.
 */
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 0..1 so wander never bares the side edges. */
const X_MIN = -0.08;
const X_MAX = 1.08;

// #region critical
export function InstancedQuadParticles({
  density = 900,
  maxCount = 1800,
  sizeRange = [5, 28],
  softness = 0.62,
  spin = 0.5,
  speed = 1,
  wander = 0.06,
  opacity = 0.55,
  colorA = '#9fb4cc',
  colorB = '#e8ddc9',
  background = '#07090d',
  seed = 'instanced-quad-particles',
  className,
}: InstancedQuadParticlesProps) {
  const host = 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 = 5, maxSize = 28] = sizeRange;

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

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

    // ogl creates its own canvas, and it is appended and removed per effect
    // run. Reusing one React-owned canvas would break under StrictMode: the
    // cleanup force-loses the context, and `getContext` on that same element
    // afterwards hands back the dead one rather than a fresh context.
    const renderer = new Renderer({
      dpr: pixelRatio(MAX_DPR),
      // Opaque, so the field owns every pixel and reads the same on a light or
      // a dark page. Additive blending onto a transparent canvas would have to
      // brighten whatever is behind it, which is the page background, which
      // the GPU cannot see.
      alpha: false,
      // Nothing is sorted and nothing occludes anything, so a depth buffer is
      // memory and a clear per frame for no result.
      depth: false,
      antialias: false,
      // The field is fill-bound, not shader-bound. Asking for the discrete GPU
      // on a laptop costs battery and buys nothing.
      powerPreference: 'low-power',
    });

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

    const bg = new Color(background);
    gl.clearColor(bg.r, bg.g, bg.b, 1);

    // Four vertices, six indices, shared by every instance.
    const quad = new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5]);
    const index = new Uint16Array([0, 1, 2, 0, 2, 3]);

    const total = Math.max(MIN_COUNT, Math.round(maxCount));
    const origins = new Float32Array(total * 2);
    const params = new Float32Array(total * 4);
    const seeds = new Float32Array(total * 4);

    const rng = createRng(seed);
    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) {
      origins[i * 2] = randRange(rng, X_MIN, X_MAX);
      origins[i * 2 + 1] = rng();

      // Biased toward small: a linear distribution puts a quarter of the
      // population in the largest quarter of the size range, and a hundred
      // 28px blobs is fog rather than dust.
      const sizeT = Math.pow(rng(), SIZE_BIAS);
      params[i * 4] = lo + (hi - lo) * sizeT;
      params[i * 4 + 1] = randRange(rng, -1, 1) * spin;
      // Big particles are dimmer. Alpha per particle rather than per pixel
      // keeps the total light roughly constant as the size scales.
      params[i * 4 + 2] = 1 - 0.78 * sizeT;
      params[i * 4 + 3] = rng();

      seeds[i * 4] = rng() * Math.PI * 2;
      seeds[i * 4 + 1] = rng() * Math.PI * 2;
      seeds[i * 4 + 2] = rng();
      // A third are discs. The rest are shards, and the shards are the only
      // reason per-particle rotation is visible at all.
      seeds[i * 4 + 3] = rng() < 0.34 ? 0 : randRange(rng, 0.55, 1);
    }

    const geometry = new Geometry(gl, {
      index: { data: index },
      position: { size: 2, data: quad },
      aOrigin: { size: 2, data: origins, instanced: 1 },
      aParams: { size: 4, data: params, instanced: 1 },
      aSeed: { size: 4, data: seeds, instanced: 1 },
    });

    const uniforms: Uniforms = {
      uResolution: { value: [1, 1] },
      uPixelRatio: { value: renderer.dpr },
      uElapsed: { value: 0 },
      uDrift: { value: speed },
      uRise: { value: RISE },
      uFlowScale: { value: FLOW_SCALE },
      uWander: { value: wander },
      uFadeBand: { value: FADE_BAND },
      uColorA: { value: new Color(colorA) },
      uColorB: { value: new Color(colorB) },
      uSoftness: { value: clamp(softness, 0, 1) },
      uOpacity: { value: opacity },
    };

    const program = new Program(gl, {
      vertex: INSTANCED_QUAD_PARTICLES_VERT,
      fragment: INSTANCED_QUAD_PARTICLES_FRAG,
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      // ogl defaults `cullFace` to BACK. The quad's index winding is not
      // guaranteed to face the way the driver expects once it is rotated in
      // the vertex shader, and a culled particle is simply absent.
      cullFace: false,
    });
    // Additive, overriding the source-over that `transparent: true` selected.
    // Order independent, so a thousand overlapping instances need no sort —
    // which is what makes one draw call possible in the first place.
    program.setBlendFunc(gl.ONE, gl.ONE);

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

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

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h);
      // `setSize` writes literal px into the canvas's inline style, which wins
      // over any class. Re-asserting percentages keeps the element fluid
      // between resize notifications.
      canvas.style.width = '100%';
      canvas.style.height = '100%';

      uniforms.uResolution.value = [gl.drawingBufferWidth, gl.drawingBufferHeight];
      uniforms.uPixelRatio.value = renderer.dpr;

      // Population from area, not from a fixed number: the same density looks
      // right in a 320px card and in a 2000px hero. The buffers already hold
      // `total` particles in scattered order, so a prefix of them is still a
      // spatially even field — no rebuild, no reallocation.
      const megapixels = (w * h) / 1_000_000;
      const count = clamp(Math.round(megapixels * density), MIN_COUNT, total);
      geometry.setInstancedCount(count);
    };

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

    resize(size.current.width, size.current.height);
    stage.current = { renderer, geometry, program, mesh, uniforms, resize, draw };
    draw(STATIC_ELAPSED);

    return () => {
      stage.current = null;
      // ogl has no `dispose()`: `remove()` on the geometry deletes its VAOs and
      // every buffer, `remove()` on the program deletes the shaders and the
      // program, and only then is the context worth handing back.
      geometry.remove();
      program.remove();
      loseContext(gl);
      canvas.width = 0;
      canvas.height = 0;
      canvas.remove();
    };
  }, [
    ready,
    density,
    maxCount,
    minSize,
    maxSize,
    softness,
    spin,
    speed,
    wander,
    opacity,
    colorA,
    colorB,
    background,
    seed,
  ]);

  // Resize is its own effect: a reflow costs a `setSize` and an instanced-count
  // change, never a buffer rebuild.
  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)}>
      {unsupported ? (
        <div
          aria-hidden
          className="h-full w-full bg-bg"
          style={{
            backgroundImage:
              'radial-gradient(circle at 30% 20%, var(--k-line-strong) 0.5px, transparent 0), radial-gradient(circle at 70% 60%, var(--k-line) 1px, transparent 0)',
            backgroundSize: '37px 41px, 53px 59px',
          }}
        />
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Instanced Quad Particles — GLSL
   --------------------------------------------------------------------------
   Every particle is a two-triangle quad, not a point sprite. Point sprites
   are capped at 255px on a lot of drivers, cannot be rotated, and are culled
   whole the moment their centre leaves the viewport — so a large sprite pops
   out of existence while half of it is still on screen. An instanced quad has
   none of those limits and still costs one draw call.

   Four vertices and six indices are shared by every instance; the per-instance
   attributes carry position, size, spin, alpha, tint and shape. The quad's
   corners are rotated in PIXEL space and only then converted to clip space, so
   a particle stays square in a container of any aspect ratio.

   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; x is
 *   seeded slightly outside that range so horizontal wander never exposes a
 *   bald strip at the edges.
 * aParams  — x: size in CSS px, y: spin rate in rad/s (signed),
 *   z: base alpha, w: tint mix between the two colours.
 * aSeed    — x, y: flow phase offsets, z: spin phase, w: shape mix.
 */
export const INSTANCED_QUAD_PARTICLES_VERT = /* glsl */ `
attribute vec2 position;
attribute vec2 aOrigin;
attribute vec4 aParams;
attribute vec4 aSeed;

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

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

const float TAU = 6.2831853;

void main() {
  float t = uElapsed * uDrift;

  /* The field marches upward and wraps. fract() is what makes it endless with
     no buffer rebuild and no per-particle state — but it also teleports a
     particle from the top edge to the bottom one, which is visible as a pop
     unless the alpha is faded to zero on approach. That is uFadeBand below. */
  vec2 p = aOrigin;
  p.y = fract(p.y + t * uRise);

  /* Two out-of-phase sinusoids sampled at the particle's own position, not at
     a global time only: neighbours drift apart instead of sliding as a sheet.
     The per-particle seed offsets stop the whole field breathing in unison. */
  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;

  float fade = smoothstep(0.0, uFadeBand, p.y) * smoothstep(0.0, uFadeBand, 1.0 - p.y);

  vec2 ndc = p * 2.0 - 1.0;

  /* Size is authored in CSS pixels, so it survives a dpr change and a resize
     without rebuilding anything. */
  float sizePx = aParams.x * uPixelRatio;

  float ang = aSeed.z * TAU + uElapsed * aParams.y;
  float s = sin(ang);
  float c = cos(ang);
  vec2 corner = vec2(position.x * c - position.y * s, position.x * s + position.y * c);

  /* Rotate in pixels, convert to clip space afterwards. Rotating in clip space
     shears the quad by the container's aspect ratio: a square particle becomes
     a lozenge that changes shape as it spins. */
  vec2 offset = corner * sizePx / uResolution * 2.0;

  gl_Position = vec4(ndc + offset, 0.0, 1.0);

  /* The UNROTATED quad coordinate is what the fragment shader gets, so the
     shape SDF is axis-aligned in quad space and the rotation comes entirely
     from the displaced corners. Rotating both would cancel out. */
  vQuad  = position;
  vAlpha = aParams.z * fade;
  vTint  = aParams.w;
  vShape = aSeed.w;
  /* One device pixel expressed in quad units. Used as a floor on the edge
     width so a hard-edged small particle still anti-aliases, without asking
     for derivatives (fwidth needs an extension under WebGL1). */
  vPixel = 1.0 / max(sizePx, 1.0);
}
`;

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

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

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

void main() {
  /* One rounded-box SDF covers both shapes. At vShape 0 the half-extents are
     0.5 and the corner radius is 0.5, which reduces exactly to length(uv)-0.5:
     a true circle. At vShape 1 it is a narrow shard, and the shard is the
     reason per-particle rotation is worth having at all — a disc looks
     identical at every angle. */
  vec2  ext    = vec2(mix(0.5, 0.17, vShape), 0.5);
  float radius = mix(0.5, 0.15, vShape);
  vec2  q = abs(vQuad) - (ext - radius);
  float d = length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - radius;

  float edge = max(uSoftness * 0.5, vPixel);
  float mask = 1.0 - smoothstep(-edge, 0.0, d);

  /* Roughly a third of the quad's area is outside the shape at vShape 1, and
     with additive blending a zero still costs a read-modify-write per
     fragment. Discarding is cheaper than blending nothing. */
  if (mask <= 0.002) discard;

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

  /* Premultiplied: the blend func is (ONE, ONE), so rgb is added to the
     framebuffer and the alpha channel is never read. Additive is order
     independent, which is the whole reason a thousand overlapping instances
     need no depth sort. */
  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;
  }
}