Multipass Offscreen Composite

'use client';

import { useEffect, useRef, useState } from 'react';
import * as THREE from 'three';
import { cn } from '@/lib/utils';
import { useInView } from '@/hooks/use-in-view';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { useVisibility } from '@/hooks/use-visibility';
import { clamp } from '@/lib/damp';
import { disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  MULTIPASS_BLOOM_FRAG,
  MULTIPASS_COMPOSITE_FRAG,
  MULTIPASS_DISC_FRAG,
  MULTIPASS_DISC_VERT,
  MULTIPASS_FLAT_VERT,
  MULTIPASS_RAMP_FRAG,
} from '@/components/motion/shaders/multipass-offscreen-composite';

/* ==========================================================================
   Multipass Offscreen Composite
   --------------------------------------------------------------------------
   A hero field assembled from four passes into two render targets, where the
   canvas is written exactly once, by the last pass.

     1. an angled three-stop ramp        -> scene target (cleared)
     2. three additive gradient discs    -> scene target (NOT cleared)
     3. bright-pass + tent blur          -> bloom target at half size
     4. scene + bloom + vignette + dither -> canvas

   The discipline that makes this work is 'renderer.autoClear = false'. three
   clears before every render() by default, so pass 2 would wipe pass 1 and the
   layering would silently collapse into whatever was drawn last. With autoClear
   off, clearing is something this component does deliberately, once per target.

   Why offscreen at all, when passes 1 and 2 could draw straight to the canvas:
   the bright-pass needs the accumulated image as an input, and a colour buffer
   cannot be sampled while it is bound. Everything else — HDR headroom for
   additive overlap, a half-size blur, one dither at the end — follows from
   owning the intermediate buffer.
   ========================================================================== */

export interface MultipassOffscreenCompositeProps {
  /**
   * Scroll-style progress, 0..1. The fills bloom in over the last 30% of it;
   * below REVEAL_START only the ramp is visible.
   */
  reveal?: number;
  /** How much of the blurred bright-pass is added back in pass 4. */
  bloomStrength?: number;
  /** Luminance where the bright-pass starts contributing. */
  bloomThreshold?: number;
  /** Bloom target size relative to the scene target. */
  bloomScale?: number;
  /** Corner darkening in the composite, 0..1. */
  vignette?: number;
  /** Multiplier on the fills' drift speed. */
  drift?: number;
  /** Ramp direction in degrees, measured counter-clockwise from +x. */
  rampAngle?: number;
  /** Ramp stops: start, bend, end. */
  rampColors?: readonly [string, string, string];
  /** The three additive fills. */
  fillColors?: readonly [string, string, string];
  /** Device pixel ratio cap. Four passes at 3x is a lot of fragments. */
  maxDpr?: number;
  className?: string;
}

/* Module scope, so a caller that omits the prop gets a stable identity and the
   effect below does not tear the whole GL stack down on every render. */
const RAMP_COLORS = ['#0a0f1a', '#16283c', '#070a12'] as const;
const FILL_COLORS = ['#3f7ae0', '#2fd0b4', '#a866f0'] as const;

/** From the source: fills come in over p = 0.7 -> 0.9 and hold. */
const REVEAL_START = 0.7;
const REVEAL_SPAN = 0.2;

/** Blur reach in bloom-target texels. Above ~2 the 3x3 tent starts to alias. */
const BLOOM_RADIUS = 1.4;

/** ~1/255. Enough to break an 8-bit band, below the threshold of visible noise. */
const DITHER = 0.004;

/** Gaussian tightness of a fill. Higher is a smaller, harder core. */
const DISC_SOFTNESS = 3.1;

/** Fills are round in their own plane; the plane is tilted, so they read squashed. */
const DISC_SQUASH = 0.62;
const PLANE_TILT = -0.19;

/** Frame drawn when motion is suppressed — mid-drift, so the composition is not degenerate. */
const STATIC_ELAPSED = 6.2;

interface DiscSpec {
  /** Orbit radius in world units (half-height = 1). */
  radius: number;
  /** Diameter in world units before the squash. */
  size: number;
  /** Revolutions per second; negative counter-rotates. */
  speed: number;
  /** Starting angle in radians. */
  phase: number;
  /** Peak alpha at full reveal. */
  intensity: number;
}

const DISCS: readonly DiscSpec[] = [
  { radius: 0.6, size: 1.5, speed: 0.05, phase: 0, intensity: 0.62 },
  { radius: 0.42, size: 1.05, speed: -0.08, phase: 2.1, intensity: 0.5 },
  { radius: 0.78, size: 0.8, speed: 0.11, phase: 4.35, intensity: 0.36 },
];

interface RampUniforms {
  [name: string]: THREE.IUniform;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uAngle: THREE.IUniform<number>;
  uColorA: THREE.IUniform<THREE.Color>;
  uColorB: THREE.IUniform<THREE.Color>;
  uColorC: THREE.IUniform<THREE.Color>;
}

interface DiscUniforms {
  [name: string]: THREE.IUniform;
  uColor: THREE.IUniform<THREE.Color>;
  uIntensity: THREE.IUniform<number>;
  uSoftness: THREE.IUniform<number>;
}

interface BloomUniforms {
  [name: string]: THREE.IUniform;
  uSource: THREE.IUniform<THREE.Texture | null>;
  uTexel: THREE.IUniform<THREE.Vector2>;
  uThreshold: THREE.IUniform<number>;
  uRadius: THREE.IUniform<number>;
}

interface CompositeUniforms {
  [name: string]: THREE.IUniform;
  uScene: THREE.IUniform<THREE.Texture | null>;
  uBloom: THREE.IUniform<THREE.Texture | null>;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uBloomStrength: THREE.IUniform<number>;
  uVignette: THREE.IUniform<number>;
  uDither: THREE.IUniform<number>;
}

interface Stage {
  resize(width: number, height: number): void;
  draw(elapsed: number): void;
}

function makeTarget(width: number, height: number): THREE.WebGLRenderTarget {
  return new THREE.WebGLRenderTarget(width, height, {
    // Half float. Three additive fills overlap past 1.0, and on an unsigned
    // byte target that overlap clips flat before the bright-pass ever sees it —
    // the bloom then has no idea where the image was actually hot.
    type: THREE.HalfFloatType,
    // Linear, unlike a ping-pong trail. The bloom pass samples this at half
    // resolution, so bilinear filtering is doing a free 2x2 box downsample on
    // every tap; nearest would make the blur crawl on sub-pixel motion.
    minFilter: THREE.LinearFilter,
    magFilter: THREE.LinearFilter,
    // Nothing here is depth-sorted: the passes are ordered by hand and the
    // fills are additive. A depth buffer would be width x height x 3 bytes of
    // bandwidth per pass for nothing.
    depthBuffer: false,
    stencilBuffer: false,
  });
}

// #region critical
export function MultipassOffscreenComposite({
  reveal = 1,
  bloomStrength = 0.85,
  bloomThreshold = 0.34,
  bloomScale = 0.5,
  vignette = 0.38,
  drift = 1,
  rampAngle = 141,
  rampColors = RAMP_COLORS,
  fillColors = FILL_COLORS,
  maxDpr = 2,
  className,
}: MultipassOffscreenCompositeProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

  const { width, height } = useResizeObserver(host);
  const { inView } = useInView(host, { threshold: 0 });
  const visible = useVisibility();
  const reduced = useReducedMotion();

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

  /* Everything that only feeds a uniform lives here and is read inside the
     draw loop. None of it belongs in the effect's dependency list: rebuilding
     two render targets because a vignette changed by 0.01 would drop frames. */
  const live = useRef({ reveal, bloomStrength, bloomThreshold, vignette, drift });
  live.current = { reveal, bloomStrength, bloomThreshold, vignette, drift };

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

  /* Joined, not spread. Array props are compared by identity, so an inline
     literal would be a new value every render and the effect would thrash. */
  const colorKey = `${rampColors.join('|')}/${fillColors.join('|')}`;

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

    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      // Opaque. Pass 4 covers every pixel with alpha 1, so an alpha channel
      // would only cost bandwidth and force the compositor to blend.
      alpha: false,
      depth: false,
      stencil: false,
    });
    renderer.setPixelRatio(pixelRatio(maxDpr));
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 1);
    // The single most important line in the file. See the header.
    renderer.autoClear = false;
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const buffer = new THREE.Vector2();
    renderer.getDrawingBufferSize(buffer);
    const bufferW = Math.max(2, Math.round(buffer.x));
    const bufferH = Math.max(2, Math.round(buffer.y));
    const bloomW = Math.max(2, Math.round(bufferW * bloomScale));
    const bloomH = Math.max(2, Math.round(bufferH * bloomScale));

    const sceneTarget = makeTarget(bufferW, bufferH);
    const bloomTarget = makeTarget(bloomW, bloomH);

    // Two cameras. The flat one is for the clip-space quads, whose vertex
    // shader ignores both matrices; the ortho one gives the fills a stable
    // -aspect..aspect x -1..1 space to move in.
    const flatCamera = new THREE.Camera();
    const contentCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 10);
    contentCamera.position.z = 1;

    const flatGeometry = new THREE.PlaneGeometry(2, 2);
    const discGeometry = new THREE.PlaneGeometry(1, 1);

    const [rampA = '#000000', rampB = '#000000', rampC = '#000000'] = rampColors;
    const rampUniforms: RampUniforms = {
      uResolution: { value: new THREE.Vector2(bufferW, bufferH) },
      uAngle: { value: (rampAngle * Math.PI) / 180 },
      uColorA: { value: new THREE.Color(rampA) },
      uColorB: { value: new THREE.Color(rampB) },
      uColorC: { value: new THREE.Color(rampC) },
    };
    const rampMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_RAMP_FRAG,
      uniforms: rampUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const rampScene = new THREE.Scene();
    const rampQuad = new THREE.Mesh(flatGeometry, rampMaterial);
    rampQuad.frustumCulled = false;
    rampScene.add(rampQuad);

    const fillScene = new THREE.Scene();
    // One group, rotated once: the fills share a plane, and tilting the group
    // is what makes their paths read as one ellipse seen at an angle rather
    // than three unrelated circles.
    const fillGroup = new THREE.Group();
    fillGroup.rotation.z = PLANE_TILT;
    fillScene.add(fillGroup);

    const discMaterials: THREE.ShaderMaterial[] = [];
    const discMeshes: THREE.Mesh[] = [];
    for (let i = 0; i < DISCS.length; i++) {
      const spec = DISCS[i];
      if (!spec) continue;
      const uniforms: DiscUniforms = {
        uColor: { value: new THREE.Color(fillColors[i] ?? '#ffffff') },
        uIntensity: { value: 0 },
        uSoftness: { value: DISC_SOFTNESS },
      };
      const material = new THREE.ShaderMaterial({
        vertexShader: MULTIPASS_DISC_VERT,
        fragmentShader: MULTIPASS_DISC_FRAG,
        uniforms,
        transparent: true,
        blending: THREE.AdditiveBlending,
        depthTest: false,
        depthWrite: false,
      });
      const mesh = new THREE.Mesh(discGeometry, material);
      mesh.scale.set(spec.size, spec.size * DISC_SQUASH, 1);
      mesh.frustumCulled = false;
      fillGroup.add(mesh);
      discMaterials.push(material);
      discMeshes.push(mesh);
    }

    const bloomUniforms: BloomUniforms = {
      uSource: { value: sceneTarget.texture },
      uTexel: { value: new THREE.Vector2(1 / bloomW, 1 / bloomH) },
      uThreshold: { value: bloomThreshold },
      uRadius: { value: BLOOM_RADIUS },
    };
    const bloomMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_BLOOM_FRAG,
      uniforms: bloomUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const bloomScene = new THREE.Scene();
    const bloomQuad = new THREE.Mesh(flatGeometry, bloomMaterial);
    bloomQuad.frustumCulled = false;
    bloomScene.add(bloomQuad);

    const compositeUniforms: CompositeUniforms = {
      uScene: { value: sceneTarget.texture },
      uBloom: { value: bloomTarget.texture },
      uResolution: { value: new THREE.Vector2(bufferW, bufferH) },
      uBloomStrength: { value: bloomStrength },
      uVignette: { value: vignette },
      uDither: { value: DITHER },
    };
    const compositeMaterial = new THREE.ShaderMaterial({
      vertexShader: MULTIPASS_FLAT_VERT,
      fragmentShader: MULTIPASS_COMPOSITE_FRAG,
      uniforms: compositeUniforms,
      depthTest: false,
      depthWrite: false,
    });
    const compositeScene = new THREE.Scene();
    const compositeQuad = new THREE.Mesh(flatGeometry, compositeMaterial);
    compositeQuad.frustumCulled = false;
    compositeScene.add(compositeQuad);

    stage.current = {
      resize(w, h) {
        renderer.setPixelRatio(pixelRatio(maxDpr));
        renderer.setSize(w, h, false);
        renderer.getDrawingBufferSize(buffer);
        const bw = Math.max(2, Math.round(buffer.x));
        const bh = Math.max(2, Math.round(buffer.y));

        const aspect = w / h;
        contentCamera.left = -aspect;
        contentCamera.right = aspect;
        contentCamera.updateProjectionMatrix();

        // setSize, never new. Allocating a pair of half-float targets is a
        // synchronous driver call; doing it from a ResizeObserver during a
        // window drag is how a smooth resize turns into a slideshow — and the
        // old targets would leak unless every one of them were disposed.
        sceneTarget.setSize(bw, bh);
        rampUniforms.uResolution.value.set(bw, bh);
        compositeUniforms.uResolution.value.set(bw, bh);

        const sw = Math.max(2, Math.round(bw * bloomScale));
        const sh = Math.max(2, Math.round(bh * bloomScale));
        bloomTarget.setSize(sw, sh);
        // Texel size is per target, and this one is not the canvas. Leaving it
        // at the old size makes the blur radius drift with the window.
        bloomUniforms.uTexel.value.set(1 / sw, 1 / sh);
      },

      draw(elapsed) {
        const state = live.current;

        // The source ties the fills to scroll with exactly this ramp.
        const fade = clamp((state.reveal - REVEAL_START) / REVEAL_SPAN, 0, 1);

        for (let i = 0; i < discMeshes.length; i++) {
          const mesh = discMeshes[i];
          const spec = DISCS[i];
          const material = discMaterials[i];
          if (!mesh || !spec || !material) continue;
          const angle = spec.phase + elapsed * spec.speed * state.drift * Math.PI * 2;
          mesh.position.set(Math.cos(angle) * spec.radius, Math.sin(angle) * spec.radius, 0);
          const intensity = material.uniforms.uIntensity;
          if (intensity) intensity.value = spec.intensity * fade;
        }

        // Passes 1 and 2 — one clear, two renders. The absence of a clear
        // between them IS the composite.
        renderer.setRenderTarget(sceneTarget);
        renderer.clear(true, false, false);
        renderer.render(rampScene, flatCamera);
        renderer.render(fillScene, contentCamera);

        // Pass 3 — bright-pass and blur at bloomScale. Nothing accumulates, so
        // this target never needs to survive a frame.
        bloomUniforms.uThreshold.value = state.bloomThreshold;
        renderer.setRenderTarget(bloomTarget);
        renderer.clear(true, false, false);
        renderer.render(bloomScene, flatCamera);

        // Pass 4 — the only write to the canvas.
        compositeUniforms.uBloomStrength.value = state.bloomStrength;
        compositeUniforms.uVignette.value = state.vignette;
        renderer.setRenderTarget(null);
        renderer.clear(true, false, false);
        renderer.render(compositeScene, flatCamera);
      },
    };

    stage.current.resize(el.clientWidth, el.clientHeight);
    stage.current.draw(0);

    return () => {
      stage.current = null;
      // Explicit, not disposeObject over the scenes: flatGeometry is shared by
      // three of them, and a traversal would dispose it three times.
      flatGeometry.dispose();
      discGeometry.dispose();
      rampMaterial.dispose();
      bloomMaterial.dispose();
      compositeMaterial.dispose();
      for (const material of discMaterials) material.dispose();
      // Both targets. Nothing walks a render target for you — each holds a
      // half-float texture and a framebuffer object.
      sceneTarget.dispose();
      bloomTarget.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, colorKey, rampAngle, bloomScale, maxDpr]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.resize(width, height);
    // No pass reads its own previous contents, so a resized target needs no
    // clear-and-settle — but a still frame does need redrawing, since resizing
    // a target discards what it held.
    if (reduced) current.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

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

  return (
    <div className={cn('relative h-full w-full overflow-hidden', className)}>
      <div ref={host} className="absolute inset-0" />
      {!supported ? (
        <div
          className="absolute inset-0"
          style={{
            background: `radial-gradient(60% 60% at 32% 38%, ${fillColors[0]}55, transparent 70%), radial-gradient(50% 50% at 68% 62%, ${fillColors[1]}44, transparent 70%), linear-gradient(${
              90 - rampAngle
            }deg, ${rampColors[0]}, ${rampColors[1]}, ${rampColors[2]})`,
          }}
        />
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Multipass Offscreen Composite — GLSL
   --------------------------------------------------------------------------
   Four passes, four fragment programs, two render targets:

     1. RAMP        -> scene target   an angled three-stop colour ramp
     2. DISC        -> scene target   additive gradient discs, no clear between
     3. BLOOM       -> bloom target   bright-pass plus a 3x3 tent, at half size
     4. COMPOSITE   -> canvas         scene + bloom + vignette + dither

   Every pass here is a ShaderMaterial, and three only injects its output
   colour-space conversion into its own built-in materials. So there is no
   conversion anywhere in this chain: the numbers in the ramp uniforms are the
   numbers that land in the framebuffer. That is a choice, not an oversight —
   one conversion in the middle of a multipass chain is far harder to reason
   about than none at all.

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

/**
 * Clip-space quad for the passes that cover the whole target. PlaneGeometry(2,
 * 2) already spans -1..1, so no matrices are needed and each pass costs four
 * vertices.
 */
export const MULTIPASS_FLAT_VERT = /* glsl */ `
void main() {
  gl_Position = vec4(position.xy, 0.0, 1.0);
}
`;

/** Pass 1 — the background ramp. */
export const MULTIPASS_RAMP_FRAG = /* glsl */ `
precision mediump float;

uniform vec2  uResolution;
uniform float uAngle;
uniform vec3  uColorA;
uniform vec3  uColorB;
uniform vec3  uColorC;

void main() {
  vec2 uv  = gl_FragCoord.xy / uResolution;
  vec2 dir = vec2(cos(uAngle), sin(uAngle));

  /* Project onto the ramp axis, then normalise by abs(dir.x) + abs(dir.y) —
     the maximum the projection can reach inside the unit square. Without that
     term the ramp saturates before the far corner at every angle except the
     axes, and the corner reads as a flat plate of the end colour. */
  float t = clamp(dot(uv - 0.5, dir) / (abs(dir.x) + abs(dir.y)) + 0.5, 0.0, 1.0);

  /* Three stops, not two. A straight A-to-B mix is the flat look of a CSS
     gradient; the mid stop is where the hue bends, and the bend is what makes
     it read as light in a space. */
  vec3 c = t < 0.5
    ? mix(uColorA, uColorB, t * 2.0)
    : mix(uColorB, uColorC, (t - 0.5) * 2.0);

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

/** Pass 2 — one gradient disc. Needs the model matrix, so not the flat vert. */
export const MULTIPASS_DISC_VERT = /* glsl */ `
varying vec2 vUv;

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

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

uniform vec3  uColor;
uniform float uIntensity;
uniform float uSoftness;

varying vec2 vUv;

void main() {
  float d = length(vUv - vec2(0.5)) * 2.0;

  /* A Gaussian, not a smoothstep. smoothstep has a discontinuity in its second
     derivative at the outer edge, and three of these stacked additively make
     that discontinuity visible as a faint ring. exp(-d*d*k) never ends, so
     there is no edge to see. */
  float fall = exp(-d * d * uSoftness);

  float alpha = fall * uIntensity;
  if (alpha <= 0.002) discard;

  /* NOT premultiplied. three's AdditiveBlending is (SrcAlpha, One), so the
     blender multiplies by alpha; doing it here as well squares it and the discs
     all but disappear. */
  gl_FragColor = vec4(uColor, alpha);
}
`;

/** Pass 3 — bright-pass and blur, rendered into the half-size target. */
export const MULTIPASS_BLOOM_FRAG = /* glsl */ `
precision mediump float;

uniform sampler2D uSource;
uniform vec2      uTexel;
uniform float     uThreshold;
uniform float     uRadius;

const vec3 LUMA = vec3(0.2126, 0.7152, 0.0722);

vec3 bright(vec2 uv) {
  vec3  c = texture2D(uSource, uv).rgb;
  float l = dot(c, LUMA);
  /* Soft knee over a quarter of the range. With a hard step the bright region's
     boundary snaps from pixel to pixel as the discs drift, and the bloom edge
     crawls — the most common giveaway of a hand-rolled bloom. */
  return c * smoothstep(uThreshold, uThreshold + 0.25, l);
}

void main() {
  vec2 uv = gl_FragCoord.xy * uTexel;
  vec2 o  = uTexel * uRadius;

  /* 3x3 tent, weights 4 / 2 / 1, normalised by 16. uTexel is the HALF-size
     target's texel, so every offset covers two source pixels: the blur radius
     doubles because of where this pass renders, not because of extra taps. */
  vec3 sum = bright(uv) * 4.0;
  sum += (
      bright(uv + vec2(o.x, 0.0))
    + bright(uv - vec2(o.x, 0.0))
    + bright(uv + vec2(0.0, o.y))
    + bright(uv - vec2(0.0, o.y))
  ) * 2.0;
  sum +=
      bright(uv + o)
    + bright(uv - o)
    + bright(uv + vec2(o.x, -o.y))
    + bright(uv + vec2(-o.x, o.y));

  gl_FragColor = vec4(sum / 16.0, 1.0);
}
`;

/** Pass 4 — the only pass that touches the canvas. */
export const MULTIPASS_COMPOSITE_FRAG = /* glsl */ `
precision mediump float;

uniform sampler2D uScene;
uniform sampler2D uBloom;
uniform vec2      uResolution;
uniform float     uBloomStrength;
uniform float     uVignette;
uniform float     uDither;

float hash(vec2 p) {
  return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
}

void main() {
  vec2 uv = gl_FragCoord.xy / uResolution;

  vec3 scene = texture2D(uScene, uv).rgb;
  /* The bloom target is half size, so this read is a bilinear upsample — a
     free extra blur, which is most of the reason to render bloom small rather
     than a reason to apologise for it. */
  vec3 bloom = texture2D(uBloom, uv).rgb;

  vec3 c = scene + bloom * uBloomStrength;

  /* Vignette measured in a square space, so it stays a circle in a wide box
     instead of stretching into a lens-shaped band across the sides. */
  vec2 v = (uv - vec2(0.5)) * vec2(uResolution.x / uResolution.y, 1.0);
  c *= mix(1.0, 1.0 - uVignette, smoothstep(0.25, 0.95, length(v)));

  /* Triangular-PDF dither: the difference of two uniform samples, which has a
     flatter error spectrum than a single one. The ramp crosses only a few
     hundred 8-bit codes over a thousand pixels, and without a sub-LSB
     perturbation that shows up as hard contour lines across the whole frame. */
  float n = hash(gl_FragCoord.xy) - hash(gl_FragCoord.xy + 17.0);

  gl_FragColor = vec4(c + n * uDither, 1.0);
}
`;

/* ==========================================================================
   Frame-rate-independent interpolation.
   --------------------------------------------------------------------------
   The everywhere-idiom `x += (target - x) * 0.1` is a bug: it converges twice
   as fast on a 120 Hz display as on a 60 Hz one, so the same code feels
   different on different hardware and visibly speeds up when the browser
   drops frames. `damp` fixes it by raising the retention factor to the power
   of elapsed time, which is the exact continuous form of the same curve.
   ========================================================================== */

/**
 * Fraction of the remaining distance to close this frame.
 *
 * @param smoothing Fraction of the gap that REMAINS after one second.
 *   Smaller is snappier. 0.001 ≈ very fast, 0.01 ≈ fast, 0.1 ≈ soft,
 *   0.5 ≈ slow drift.
 * @param dt Seconds elapsed since the previous frame.
 */
export function dampFactor(smoothing: number, dt: number): number {
  return 1 - Math.pow(smoothing, dt);
}

/** Move `current` toward `target` at a rate independent of frame rate. */
export function damp(
  current: number,
  target: number,
  smoothing: number,
  dt: number,
): number {
  return current + (target - current) * dampFactor(smoothing, dt);
}

/**
 * The per-frame lerp constant an author measured at 60fps, converted into the
 * `smoothing` argument `damp` wants. Lets a source that says "0.1 per frame"
 * be ported without re-tuning by eye:
 *
 *   damp(x, t, perFrameToSmoothing(0.1), dt)
 */
export function perFrameToSmoothing(alpha: number, baseFps = 60): number {
  return Math.pow(1 - alpha, baseFps);
}

export function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

export function clamp(v: number, min: number, max: number): number {
  return v < min ? min : v > max ? max : v;
}

export function inverseLerp(a: number, b: number, v: number): number {
  return a === b ? 0 : (v - a) / (b - a);
}

export function mapRange(
  v: number,
  inMin: number,
  inMax: number,
  outMin: number,
  outMax: number,
  doClamp = true,
): number {
  const t = inverseLerp(inMin, inMax, v);
  const r = lerp(outMin, outMax, doClamp ? clamp(t, 0, 1) : t);
  return r;
}

/** GLSL `smoothstep`, same semantics, for parity between JS and shader code. */
export function smoothstep(edge0: number, edge1: number, x: number): number {
  const t = clamp(inverseLerp(edge0, edge1, x), 0, 1);
  return t * t * (3 - 2 * t);
}

/**
 * Gaussian falloff, `exp(-d²)`. Yields 1.000 / 0.368 / 0.018 / 0.0001 at
 * distances 0 / 1 / 2 / 3 — a continuous focus scalar with no thresholds and
 * no branches, which is why carousels that use it feel analogue rather than
 * stepped.
 */
export function gaussian(distance: number, falloff = 1): number {
  const d = distance * falloff;
  return Math.exp(-(d * d));
}

'use client';

import { useEffect, useRef, useState, type RefObject } from 'react';

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

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

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

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

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

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

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

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

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

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

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

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

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

  return state;
}

'use client';

import { useEffect, useRef } from 'react';

/* ==========================================================================
   One shared requestAnimationFrame loop.
   --------------------------------------------------------------------------
   Forty components each calling requestAnimationFrame means forty callbacks
   the browser schedules separately and forty chances to read layout after a
   write. One loop, one ordered pass, one place to clamp delta time.

   Delta is clamped to 100 ms. Without that, returning to a backgrounded tab
   delivers a multi-second dt and every physics integration in the page
   explodes on the first frame back.
   ========================================================================== */

export type RafCallback = (dt: number, elapsed: number) => void;

const callbacks = new Set<RafCallback>();
let frame = 0;
let last = 0;
let start = 0;

const MAX_DT = 0.1;
const DEFAULT_DT = 1 / 60;

function tick(now: number) {
  frame = requestAnimationFrame(tick);
  const dt = last === 0 ? DEFAULT_DT : Math.min((now - last) / 1000, MAX_DT);
  last = now;
  const elapsed = (now - start) / 1000;
  // Copy: a callback may unsubscribe itself (or another) mid-iteration.
  for (const cb of Array.from(callbacks)) {
    if (callbacks.has(cb)) cb(dt, elapsed);
  }
}

function subscribe(cb: RafCallback) {
  callbacks.add(cb);
  if (frame === 0) {
    start = performance.now();
    last = 0;
    frame = requestAnimationFrame(tick);
  }
  return () => {
    callbacks.delete(cb);
    if (callbacks.size === 0 && frame !== 0) {
      cancelAnimationFrame(frame);
      frame = 0;
      last = 0;
    }
  };
}

/**
 * Run `cb` every frame while `enabled`.
 *
 * The callback is held in a ref, so it does not need to be memoised and the
 * subscription is never torn down just because the closure changed identity.
 */
export function useRaf(cb: RafCallback, enabled = true): void {
  const ref = useRef(cb);
  ref.current = cb;

  useEffect(() => {
    if (!enabled) return;
    return subscribe((dt, elapsed) => ref.current(dt, elapsed));
  }, [enabled]);
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   prefers-reduced-motion, SSR-safe.
   --------------------------------------------------------------------------
   useSyncExternalStore rather than useState + useEffect: the server snapshot
   is an explicit `false`, so the markup React renders on the server and the
   markup it hydrates with agree, and the real value lands in the same commit
   as hydration instead of one frame later. A useEffect version flashes the
   animated variant before removing it — the exact thing the user asked not to
   see.

   Reduced motion is not "duration: 0". For most components here it means a
   different render: the final state, a static poster, or a paused frame.
   ========================================================================== */

const QUERY = '(prefers-reduced-motion: reduce)';

function subscribe(onChange: () => void) {
  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
  const mql = window.matchMedia(QUERY);
  mql.addEventListener('change', onChange);
  return () => mql.removeEventListener('change', onChange);
}

function getSnapshot() {
  if (typeof window === 'undefined' || !window.matchMedia) return false;
  return window.matchMedia(QUERY).matches;
}

function getServerSnapshot() {
  return false;
}

export function useReducedMotion(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

/** Generic media-query hook, same SSR guarantees. */
export function useMediaQuery(query: string): boolean {
  return useSyncExternalStore(
    (onChange) => {
      if (typeof window === 'undefined' || !window.matchMedia) return () => {};
      const mql = window.matchMedia(query);
      mql.addEventListener('change', onChange);
      return () => mql.removeEventListener('change', onChange);
    },
    () => {
      if (typeof window === 'undefined' || !window.matchMedia) return false;
      return window.matchMedia(query).matches;
    },
    () => false,
  );
}

'use client';

import { useEffect, useState, type RefObject } from 'react';

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

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

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

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

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

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

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

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

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

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

  return size;
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   Document visibility, shared.
   --------------------------------------------------------------------------
   A backgrounded tab still runs `setInterval`, still holds WebGL contexts,
   and — on some platforms — still gets throttled rAF ticks with multi-second
   deltas. Anything expensive should stop when the tab is hidden and resume
   when it comes back, rather than trying to catch up.

   `useSyncExternalStore` with an explicit server snapshot so SSR markup and
   the first client render agree.
   ========================================================================== */

function subscribe(onChange: () => void): () => void {
  document.addEventListener('visibilitychange', onChange);
  return () => document.removeEventListener('visibilitychange', onChange);
}

function getSnapshot(): boolean {
  return document.visibilityState === 'visible';
}

/** Assume visible on the server: the alternative flashes a paused state. */
function getServerSnapshot(): boolean {
  return true;
}

export function useVisibility(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

import type * as THREE from 'three';

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

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

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

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

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

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

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

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

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