Text-Target Particle Glyphs

'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, damp } from '@/lib/damp';
import { createRng, type Rng } from '@/lib/prng';
import { disposeObject, disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  TEXT_TARGET_PARTICLE_GLYPHS_FRAG,
  TEXT_TARGET_PARTICLE_GLYPHS_VERT,
} from '@/components/motion/shaders/text-target-particle-glyphs';

/* ==========================================================================
   Text-Target Particle Glyphs
   --------------------------------------------------------------------------
   A particle cloud that gathers into a word and lets it go again. The word is
   not an image and not a mesh: it is drawn once with `fillText` into an
   offscreen 2D canvas using a font that is already on the page, and the
   opaque pixels of that raster become the particle destinations.

   Three decisions carry the technique:

     1. Sampling. Every covered pixel is collected in one pass into a coverage
        list, and particles draw from that list. Rejection sampling — guess a
        pixel, keep it if it is inked — is the obvious approach and the wrong
        one: text covers something like 5% of its box, so the average particle
        needs twenty guesses and the worst case has no bound at all.

     2. Normalised targets. The destination is stored in glyph-box units, not
        world units, and scaled by a uniform in the vertex shader. A container
        resize is then two uniform writes instead of a re-raster and a
        re-upload of every buffer.

     3. Order. The per-particle stagger is keyed to the destination's own x, so
        the word assembles left to right. It is written, not faded in — and
        that reads as language rather than as a transition.

   Nothing is shipped but code: no glyph atlas, no texture, no font file.
   ========================================================================== */

export interface TextTargetParticleGlyphsProps {
  /** The word to write. One line — a newline is not laid out. */
  text?: string;
  /**
   * CSS font family list. Defaults to the host element's computed family, so
   * the raster uses a font the page has already loaded rather than one this
   * component ships.
   */
  fontFamily?: string;
  /** CSS font weight for the raster. Heavier strokes hold more particles. */
  fontWeight?: string | number;
  /** Particle count. One buffer, one draw call, cost is linear. */
  count?: number;
  /** Particle diameter in CSS pixels for a landed particle, before jitter. */
  size?: number;
  /** Ceiling on the perspective-grown size, in CSS pixels. */
  maxSize?: number;
  /** Fraction of the visible width the written word spans. */
  fill?: number;
  /**
   * Authoritative morph, 0 (scattered) to 1 (written). Supply it to drive the
   * word from scroll or from a timeline; leave it out and the component runs
   * its own write / hold / dissolve cycle.
   *
   * Held in a ref and deliberately NOT an effect dependency: a scroll-driven
   * value changes every frame, and rebuilding on each one would re-rasterise
   * the text sixty times a second.
   */
  progress?: number;
  /** Write, hold, dissolve, repeat. Ignored while `progress` is supplied. */
  loop?: boolean;
  /** Seconds the finished word is held before it dissolves. */
  holdWritten?: number;
  /** Seconds the cloud drifts before the next write. */
  holdScattered?: number;
  /** Resting cloud size as a multiple of the visible frame. */
  homeSpread?: number;
  /** Resting drift amplitude, as a fraction of the visible height. */
  homeDrift?: number;
  /** Residual drift once written, as a fraction of the word width. */
  glyphDrift?: number;
  /** Mid-flight bow, as a fraction of the word width. */
  swarm?: number;
  /** Overall alpha multiplier applied in the vertex shader. */
  opacity?: number;
  /** Tint of the scattered cloud. */
  colorCloud?: string;
  /** Tint of the written word. */
  colorGlyph?: string;
  /** Vertical field of view in degrees. */
  fov?: number;
  seed?: number | string;
  className?: string;
}

interface Uniforms {
  /** three types `uniforms` as an open record; without this the object is not assignable. */
  [name: string]: THREE.IUniform;
  uElapsed: { value: number };
  uMorph: { value: number };
  /** Visible world size of the frame at the word's depth. */
  uViewSize: { value: THREE.Vector2 };
  uHomeDepth: { value: number };
  uWordWidth: { value: number };
  uThickness: { value: number };
  uHomeDrift: { value: number };
  uGlyphDrift: { value: number };
  uSwarm: { value: number };
  uSize: { value: number };
  /** Device pixels, because `gl_PointSize` is. */
  uMaxSize: { value: number };
  /** `pixelRatio * cameraDistance` — see the vertex shader. */
  uSizeScale: { value: number };
  uOpacity: { value: number };
  uColorCloud: { value: THREE.Color };
  uColorGlyph: { value: THREE.Color };
}

interface Stage {
  resize: (width: number, height: number) => void;
  step: (dt: number, elapsed: number) => void;
  still: () => void;
}

/** Covered pixels of the raster, plus the box they actually occupy. */
interface GlyphMask {
  /** Packed pixel indices: `x = i % width`, `y = (i - x) / width`. */
  pixels: Int32Array;
  width: number;
  minX: number;
  minY: number;
  maxX: number;
  maxY: number;
}

/**
 * Raster size. Wide enough that a long word still gets several pixels across a
 * stroke — the mask is the only description of the letterforms there is, and a
 * stroke narrower than about three pixels samples into a dotted line.
 */
const RASTER_WIDTH = 1024;
const RASTER_HEIGHT = 320;
/** Text is fitted to this fraction of the raster, leaving room for overshoot. */
const RASTER_FILL = 0.92;
/** Cap on the fitted size so a two-letter word does not overflow vertically. */
const RASTER_CAP = 0.66;
/** Font size the text is measured at. Fitting is a ratio, so the value is free. */
const PROBE_SIZE = 100;
/**
 * Alpha above which a pixel counts as inked. Anti-aliasing puts a one-pixel
 * skirt of low alpha around every stroke; including it thickens the word and
 * softens its corners, which is exactly the crispness the raster was for.
 */
const ALPHA_THRESHOLD = 120;
/**
 * Below this the raster is a failure, not a short word — an unloaded font, an
 * empty string, a zero-size canvas. Rendering it anyway crushes every particle
 * onto a handful of pixels, so the target is rejected and the cloud keeps
 * drifting instead.
 */
const MIN_COVERAGE_PIXELS = 1200;

/** Camera distance to the word plane. Fixed; the fit moves the word, not the camera. */
const CAMERA_DISTANCE = 6;
/** Vertical bound on the fit, so a wide word in a short frame is not clipped. */
const FILL_HEIGHT = 0.72;
/** Home cloud depth as a fraction of the visible height. */
const HOME_DEPTH = 0.6;
/** Word thickness in z, as a fraction of its width. Enough for perspective to read. */
const THICKNESS = 0.02;
/**
 * Container width the default `size` was authored at. The word always spans the
 * same fraction of the frame, so its strokes are thinner in CSS pixels on a
 * small card; particles have to shrink with them or the letters fill in.
 */
const REFERENCE_WIDTH = 880;
const MIN_SIZE_SCALE = 0.55;
const MAX_SIZE_SCALE = 1.15;

/** Fraction of the gap left after one second while writing. ~2s to write. */
const WRITE_SMOOTHING = 0.05;
/** Dissolving is quicker than writing: the word has already been read. */
const DISSOLVE_SMOOTHING = 0.012;
/** Following an external `progress` — tight enough to track a scrub. */
const SCRUB_SMOOTHING = 0.02;
/** `damp` is asymptotic; the last stagger window needs a true 1.0 to close. */
const MORPH_EPSILON = 0.9995;

/** Fully written, no drift — the reduced-motion still. */
const STATIC_MORPH = 1;
const STATIC_ELAPSED = 0;

// #region critical
/**
 * Draw `text` into an offscreen canvas with a font already on the page and
 * collect every inked pixel. Returns `null` when the raster is unusable rather
 * than handing back a target that would render as a half-word.
 */
function rasteriseGlyphs(text: string, weight: string | number, family: string): GlyphMask | null {
  const line = text.trim();
  if (!line) return null;

  const canvas = document.createElement('canvas');
  canvas.width = RASTER_WIDTH;
  canvas.height = RASTER_HEIGHT;
  // `willReadFrequently` moves the canvas to a CPU backing store. There is
  // exactly one `getImageData` here, but on a GPU-backed canvas that single
  // read is a pipeline stall of several milliseconds.
  const ctx = canvas.getContext('2d', { willReadFrequently: true });
  if (!ctx) return null;

  const release = () => {
    canvas.width = 0;
    canvas.height = 0;
  };

  // Measure at a probe size and scale: `measureText` is linear in font size, so
  // one measurement gives the exact fit that a search would converge to.
  ctx.font = `${weight} ${PROBE_SIZE}px ${family}`;
  const probe = ctx.measureText(line).width;
  if (!(probe > 0)) {
    release();
    return null;
  }

  const fontSize = Math.min(
    (RASTER_WIDTH * RASTER_FILL * PROBE_SIZE) / probe,
    RASTER_HEIGHT * RASTER_CAP,
  );
  ctx.font = `${weight} ${fontSize}px ${family}`;
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';
  ctx.fillStyle = '#ffffff';
  ctx.fillText(line, RASTER_WIDTH / 2, RASTER_HEIGHT / 2);

  const data = ctx.getImageData(0, 0, RASTER_WIDTH, RASTER_HEIGHT).data;

  // Allocate for the worst case and slice down. Growing a plain array to tens
  // of thousands of entries reallocates repeatedly inside the hot pass.
  const scratch = new Int32Array(RASTER_WIDTH * RASTER_HEIGHT);
  let covered = 0;
  let minX = RASTER_WIDTH;
  let minY = RASTER_HEIGHT;
  let maxX = -1;
  let maxY = -1;

  for (let y = 0; y < RASTER_HEIGHT; y += 1) {
    for (let x = 0; x < RASTER_WIDTH; x += 1) {
      const p = y * RASTER_WIDTH + x;
      if ((data[p * 4 + 3] ?? 0) <= ALPHA_THRESHOLD) continue;
      scratch[covered] = p;
      covered += 1;
      if (x < minX) minX = x;
      if (x > maxX) maxX = x;
      if (y < minY) minY = y;
      if (y > maxY) maxY = y;
    }
  }

  release();
  if (covered < MIN_COVERAGE_PIXELS || maxX <= minX || maxY <= minY) return null;

  // The measured ink box, not the canvas box. Ascenders, descenders and side
  // bearings differ per string; fitting to the canvas would leave the word
  // floating off-centre by whatever margin this particular string happens to
  // have.
  return { pixels: scratch.slice(0, covered), width: RASTER_WIDTH, minX, minY, maxX, maxY };
}

/**
 * Draw `count` destinations uniformly from the coverage list, in glyph-box
 * units: x spans -0.5..0.5 and y carries the box's aspect ratio so a single
 * width uniform scales both axes.
 */
function sampleGlyphTargets(mask: GlyphMask, count: number, rng: Rng): Float32Array {
  const targets = new Float32Array(count * 2);
  const boxW = mask.maxX - mask.minX;
  const boxH = mask.maxY - mask.minY;
  const aspect = boxH / boxW;

  for (let i = 0; i < count; i += 1) {
    const at = Math.min(mask.pixels.length - 1, Math.floor(rng() * mask.pixels.length));
    const packed = mask.pixels[at] ?? 0;
    const px = packed % mask.width;
    const py = (packed - px) / mask.width;

    // Sub-pixel jitter. Without it every particle sits on an integer pixel
    // centre and the word shows the raster lattice as soon as the container is
    // wide enough for a pixel to cover more than a particle.
    const u = (px + rng() - mask.minX) / boxW;
    const v = (py + rng() - mask.minY) / boxH;

    targets[i * 2] = u - 0.5;
    targets[i * 2 + 1] = (0.5 - v) * aspect;
  }
  return targets;
}

/** True when the family is not resolvable yet, so the raster must be redone later. */
function fontPending(spec: string): boolean {
  if (typeof document === 'undefined' || !document.fonts) return false;
  try {
    return !document.fonts.check(spec);
  } catch {
    return false;
  }
}

export function TextTargetParticleGlyphs({
  text = 'KINETIC',
  fontFamily,
  fontWeight = 700,
  count = 14000,
  size = 2.2,
  maxSize = 18,
  fill = 0.86,
  progress,
  loop = true,
  holdWritten = 2.4,
  holdScattered = 1.1,
  homeSpread = 1.15,
  homeDrift = 0.05,
  glyphDrift = 0.0016,
  swarm = 0.05,
  opacity = 0.95,
  colorCloud = '#5d6875',
  colorGlyph = '#ffffff',
  fov = 34,
  seed = 'text-target-particle-glyphs',
  className,
}: TextTargetParticleGlyphsProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  const progressRef = useRef(progress);
  progressRef.current = progress;

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

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

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

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

    const total = Math.max(1, Math.round(count));
    // A font already on the page, not one this component ships. The computed
    // family is whatever the host inherits, so the word matches its context.
    const family = fontFamily || window.getComputedStyle(el).fontFamily || 'sans-serif';
    const probeSpec = `${fontWeight} ${PROBE_SIZE}px ${family}`;

    // The renderer owns its canvas and it is appended here, per effect run.
    // Under StrictMode a React-owned `<canvas ref>` survives the double invoke
    // while the context does not, and the second mount is handed a context that
    // cleanup already killed.
    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);
    const dpr = renderer.getPixelRatio();

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(fov, 1, 0.1, CAMERA_DISTANCE * 4);
    camera.position.z = CAMERA_DISTANCE;

    const rng = createRng(seed);
    const home = new Float32Array(total * 3);
    const rands = new Float32Array(total * 4);
    for (let i = 0; i < total; i += 1) {
      home[i * 3] = rng();
      home[i * 3 + 1] = rng();
      home[i * 3 + 2] = rng();
      rands[i * 4] = rng();
      rands[i * 4 + 1] = rng();
      rands[i * 4 + 2] = rng();
      rands[i * 4 + 3] = rng();
    }

    const mask = rasteriseGlyphs(text, fontWeight, family);
    let glyphAspect = mask ? (mask.maxY - mask.minY) / (mask.maxX - mask.minX) : 1;
    let hasTarget = mask !== null;

    // One destination buffer for the life of the effect. The font-load reraster
    // writes through it in place rather than allocating a second one.
    const targetData = new Float32Array(total * 2);
    if (mask) targetData.set(sampleGlyphTargets(mask, total, createRng(seed)));
    const targetAttr = new THREE.BufferAttribute(targetData, 2);

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(home, 3));
    geometry.setAttribute('aTarget', targetAttr);
    geometry.setAttribute('aRand', new THREE.BufferAttribute(rands, 4));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uMorph: { value: 0 },
      uViewSize: { value: new THREE.Vector2(1, 1) },
      uHomeDepth: { value: 1 },
      uWordWidth: { value: 1 },
      uThickness: { value: THICKNESS },
      uHomeDrift: { value: homeDrift },
      uGlyphDrift: { value: glyphDrift },
      uSwarm: { value: swarm },
      uSize: { value: size },
      uMaxSize: { value: maxSize * dpr },
      uSizeScale: { value: dpr * CAMERA_DISTANCE },
      uOpacity: { value: opacity },
      uColorCloud: { value: new THREE.Color(colorCloud) },
      uColorGlyph: { value: new THREE.Color(colorGlyph) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: TEXT_TARGET_PARTICLE_GLYPHS_VERT,
      fragmentShader: TEXT_TARGET_PARTICLE_GLYPHS_FRAG,
      uniforms,
      transparent: true,
      // No depth at all. Sorting fourteen thousand points per frame on the CPU
      // is not affordable, and it is not needed: the coverage list is drawn
      // from at random, so buffer order is uncorrelated with depth and the
      // unsorted blend averages into even density rather than into layers.
      depthTest: false,
      depthWrite: false,
      blending: THREE.NormalBlending,
    });

    const points = new THREE.Points(geometry, material);
    // Every position in this component is computed in the vertex shader, where
    // the frustum culler cannot see it. The bounding sphere three derives from
    // the raw attribute — a unit cube of 0..1 values — has nothing to do with
    // where the particles end up, and the whole cloud vanishes at some angles.
    points.frustumCulled = false;
    scene.add(points);

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

    let morph = 0;
    let goal = 1;
    let hold = 0;

    const fit = (w: number) => {
      // Visible extent of the frame at the word's depth. Everything the shader
      // scales by comes from here, so the layout is derived from the camera
      // rather than guessed in world units and re-guessed per breakpoint.
      const vHalf = (camera.fov * Math.PI) / 360;
      const viewH = 2 * CAMERA_DISTANCE * Math.tan(vHalf);
      const viewW = viewH * camera.aspect;

      // Bound the word on both axes: width for the usual case, height for a
      // short wide frame where a tall word would otherwise run off the top.
      const wordWidth = Math.min(viewW * fill, (viewH * FILL_HEIGHT) / Math.max(0.05, glyphAspect));

      uniforms.uViewSize.value.set(viewW * homeSpread, viewH * homeSpread);
      uniforms.uHomeDepth.value = viewH * HOME_DEPTH;
      uniforms.uWordWidth.value = wordWidth;
      uniforms.uThickness.value = wordWidth * THICKNESS;

      const ratio = renderer.getPixelRatio();
      uniforms.uSizeScale.value = ratio * CAMERA_DISTANCE;
      uniforms.uMaxSize.value = maxSize * ratio;
      uniforms.uSize.value = size * clamp(w / REFERENCE_WIDTH, MIN_SIZE_SCALE, MAX_SIZE_SCALE);
    };

    const resize = (w: number, h: number) => {
      if (w <= 0 || h <= 0) return;
      renderer.setSize(w, h, false);
      camera.aspect = w / h;
      camera.updateProjectionMatrix();
      fit(w);
    };

    const render = () => {
      uniforms.uMorph.value = morph;
      renderer.render(scene, camera);
    };

    const step = (dt: number, elapsed: number) => {
      const scrub = progressRef.current;
      if (!hasTarget) {
        // No usable raster: the cloud drifts and nothing is ever written. Half a
        // word is worse than no word.
        morph = 0;
      } else if (scrub !== undefined) {
        // Damped rather than assigned, so a scroll value that jumps a hundred
        // pixels between frames does not teleport the letters.
        morph = damp(morph, clamp(scrub, 0, 1), SCRUB_SMOOTHING, dt);
      } else if (hold > 0) {
        hold -= dt;
      } else {
        morph = damp(morph, goal, goal === 1 ? WRITE_SMOOTHING : DISSOLVE_SMOOTHING, dt);
        if (goal === 1 && morph >= MORPH_EPSILON) {
          morph = 1;
          if (loop) {
            hold = holdWritten;
            goal = 0;
          }
        } else if (goal === 0 && morph <= 1 - MORPH_EPSILON) {
          morph = 0;
          hold = holdScattered;
          goal = 1;
        }
      }
      uniforms.uElapsed.value = elapsed;
      render();
    };

    const still = () => {
      morph = hasTarget ? STATIC_MORPH : 0;
      uniforms.uElapsed.value = STATIC_ELAPSED;
      render();
    };

    resize(box.current.width, box.current.height);
    stage.current = { resize, step, still };
    render();

    // A webfont that is still loading measures and rasters as the fallback
    // family, so the particles would land on the wrong letterforms and stay
    // there. Redo the raster once the page's fonts settle, reusing the seed so
    // the cloud does not reshuffle — only the destinations change.
    let live = true;
    if (fontPending(probeSpec)) {
      document.fonts.ready
        .then(() => {
          if (!live) return;
          const next = rasteriseGlyphs(text, fontWeight, family);
          if (!next) return;
          hasTarget = true;
          glyphAspect = (next.maxY - next.minY) / (next.maxX - next.minX);
          targetData.set(sampleGlyphTargets(next, total, createRng(seed)));
          targetAttr.needsUpdate = true;
          fit(box.current.width);
          render();
        })
        .catch(() => undefined);
    }

    return () => {
      live = false;
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    text,
    fontFamily,
    fontWeight,
    count,
    size,
    maxSize,
    fill,
    loop,
    holdWritten,
    holdScattered,
    homeSpread,
    homeDrift,
    glyphDrift,
    swarm,
    opacity,
    colorCloud,
    colorGlyph,
    fov,
    seed,
  ]);

  // Resize is its own effect: a container reflow costs a `setSize` and a refit,
  // never a re-raster of the text or a re-upload of the destinations.
  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.still();
  }, [width, height, reduced]);

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

  return (
    <div ref={host} className={cn('relative h-full w-full overflow-hidden', className)}>
      {unsupported ? (
        <div className="absolute inset-0 grid place-items-center px-6">
          <span
            className="select-none text-center text-4xl font-bold tracking-[0.14em] text-fg/80 sm:text-6xl"
            style={{
              backgroundImage:
                'radial-gradient(circle at 50% 50%, rgba(255,255,255,0.16) 1px, transparent 1.4px)',
              backgroundSize: '4px 4px',
              WebkitBackgroundClip: 'text',
            }}
          >
            {text}
          </span>
        </div>
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Text-Target Particle Glyphs — GLSL
   --------------------------------------------------------------------------
   Two positions per particle and one number that moves between them.

   Both positions are stored NORMALISED — the home cloud in 0..1 per axis, the
   glyph target in glyph-box units — and scaled to world space here in the
   shader. That is what makes a container resize a matter of writing two
   uniforms rather than re-rasterising the text and re-uploading the buffers.

   The order of the morph is the load-bearing detail. `order` is the target's
   own horizontal position, so the stagger writes the word LEFT TO RIGHT
   instead of fading it in everywhere at once, and the eye reads it as
   typesetting rather than as a cross-fade.
   ========================================================================== */

/**
 * position — normalised home scatter, 0..1 on each axis. Mapped to the visible
 *   frustum, so the resting cloud fills whatever the container is.
 * aTarget  — glyph destination in glyph-box units: x is -0.5..0.5 across the
 *   word, y is already multiplied by the rasterised bounding box's aspect so a
 *   single `uWordWidth` scales both axes without squashing the letters.
 * aRand    — x, y: drift phases. z: depth within the word's thickness.
 *   w: size and brightness jitter.
 */
export const TEXT_TARGET_PARTICLE_GLYPHS_VERT = /* glsl */ `
attribute vec2 aTarget;
attribute vec4 aRand;

uniform float uElapsed;
uniform float uMorph;
uniform vec2  uViewSize;
uniform float uHomeDepth;
uniform float uWordWidth;
uniform float uThickness;
uniform float uHomeDrift;
uniform float uGlyphDrift;
uniform float uSwarm;
uniform float uSize;
uniform float uMaxSize;
uniform float uSizeScale;
uniform float uOpacity;

varying float vAlpha;
varying float vTint;

const float TAU = 6.2831853;
const float PI  = 3.14159265;

/* Stagger and window sum to 1.0: the rightmost particle starts last and
   finishes exactly as uMorph reaches 1, so there is no dead time at either end
   of the write. */
const float STAGGER = 0.45;
const float WINDOW  = 0.55;

void main() {
  /* Order from the DESTINATION, not from the buffer index. Index order is
     random, which dissolves the word into place; destination order writes it. */
  float order = clamp(aTarget.x + 0.5, 0.0, 1.0);
  float form  = smoothstep(order * STAGGER, order * STAGGER + WINDOW, uMorph);

  vec3 home = vec3(
    (position.x - 0.5) * uViewSize.x,
    (position.y - 0.5) * uViewSize.y,
    (position.z - 0.5) * uHomeDepth
  );

  /* One uWordWidth scales both axes because aTarget.y already carries the
     rasterised bounding box's aspect ratio. Scaling x and y independently is
     how particle text ends up stretched at one container width and squashed at
     another. */
  vec3 glyph = vec3(aTarget * uWordWidth, (aRand.z - 0.5) * uThickness);

  vec3 pos = mix(home, glyph, form);

  vec3 drift = vec3(
    sin(uElapsed * 0.21 + aRand.x * TAU),
    cos(uElapsed * 0.17 + aRand.y * TAU),
    sin(uElapsed * 0.13 + aRand.x * TAU)
  );
  /* The drift amplitude collapses as the particle lands: a loose cloud at rest,
     a barely-breathing letterform once written. Two separate motion states
     would need cross-fading; one interpolated amplitude does not. */
  pos += drift * mix(uHomeDrift * uViewSize.y, uGlyphDrift * uWordWidth, form);

  /* Mid-flight swarm. sin(form * PI) is zero at both ends and peaks at the
     halfway point, so the travel bows outward instead of running down the
     straight line between the two positions — which is what makes it read as
     particles moving rather than as a lerp. */
  float turb = sin(form * PI);
  pos.xy += vec2(cos(aRand.x * TAU), sin(aRand.y * TAU)) * turb * uSwarm * uWordWidth;

  vec4 mv = modelViewMatrix * vec4(pos, 1.0);
  gl_Position = projectionMatrix * mv;

  /* Perspective-correct size. uSizeScale is pixelRatio * the camera's distance
     to the word plane, so uSize is a literal CSS-pixel diameter for a particle
     that has landed, rather than a constant found by trial. max(0.1, -mv.z)
     guards the particle that drifts across the near plane: the unguarded
     division asks for an enormous point size, and some drivers answer by
     dropping the draw call for that frame. */
  float jitter = 0.6 + aRand.w * 1.2;
  float px = uSize * jitter * mix(0.85, 1.0, form) * uSizeScale / max(0.1, -mv.z);
  gl_PointSize = clamp(px, 1.0, uMaxSize);

  vTint  = form;
  vAlpha = uOpacity * mix(0.42, 1.0, form) * (0.6 + 0.4 * aRand.w);
}
`;

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

uniform vec3 uColorCloud;
uniform vec3 uColorGlyph;

varying float vAlpha;
varying float vTint;

/* Just under 1/255. Below it the fragment cannot change an 8-bit framebuffer,
   and the sprite quads overlap heavily inside a letter stroke, so most of that
   area is falloff that would otherwise cost a blend each. */
const float ALPHA_EPSILON = 0.003;

void main() {
  float d = length(gl_PointCoord - vec2(0.5));

  /* Soft all the way in rather than a hard disc with a thin anti-aliased band.
     Inside a stroke these overlap by the dozen, and hard edges accumulate into
     visible circles where the intent is a continuous mark. */
  float a = smoothstep(0.5, 0.06, d) * vAlpha;
  if (a <= ALPHA_EPSILON) discard;

  gl_FragColor = vec4(mix(uColorCloud, uColorGlyph, vTint), 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;
}