Layout Lerp Scalar

'use client';

import gsap from 'gsap';
import { useEffect, useMemo, 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 { gaussian } from '@/lib/damp';
import {
  disposeObject,
  disposeRenderer,
  hasWebGL,
  pixelRatio,
} from '@/lib/webgl';
import { mod, wrapIndex, wrappedOffset } from '@/lib/wrap';
import {
  layoutLerpScalarFragmentShader,
  layoutLerpScalarVertexShader,
} from '@/components/motion/shaders/layout-lerp-scalar';

/* ==========================================================================
   Layout Lerp Scalar
   --------------------------------------------------------------------------
   Four arrangements — a row, a stack, a drum, a fan — that are not four
   layouts at all. There is one placement function of seven numbers, and each
   "layout" is only a set of values for those numbers. Switching between them
   is `gsap.to(params, preset)`: a tween over an object literal, no bespoke
   animation code, no per-item choreography.

   The important part is *what* is being interpolated. Cross-fading two
   layouts means blending their outputs, `lerp(f(a), f(b), s)`, which sends
   every card along a straight line between its two endpoints — straight
   through the middle of the drum, through its neighbours, through the camera.
   Blending the inputs instead, `f(lerp(a, b, s))`, keeps every intermediate
   frame a valid member of the same family: at any `s` the cards are on a
   well-formed helix, just one with a different radius and pitch. Because the
   function is nonlinear those two are genuinely different animations, and
   only the second one looks like the shape is transforming rather than the
   items relocating.

   The layout is CPU-side scalars written into `position`, `rotation` and
   `scale`, and the vertex shader is the default transform. That is what keeps
   frustum culling and three's transparency sort correct without help: both
   read the CPU matrix, and here the CPU matrix is where the card really is.
   ========================================================================== */

export type LayoutName = 'row' | 'column' | 'drum' | 'fan';

/**
 * Every number the placement function takes. Nothing here is a mode, a branch
 * or an enum — that is the whole design. A parameter you can only switch is a
 * parameter you cannot tween.
 */
export interface LayoutParams {
  /** Drum radius in world units. 0 collapses the ring to a straight line. */
  radius: number;
  /** World units of vertical travel per index step. */
  spacing: number;
  /** Fraction of the camera-derived full-width row step, per index. */
  rowSpread: number;
  /** Revolutions the ring spans across the whole set. */
  turns: number;
  /** World units each card recedes per index step away from the focus. */
  depth: number;
  /** How strongly the gaussian focus falloff is applied, 0-1. */
  focus: number;
  /** Overall card scale. */
  scale: number;
}

export interface LayoutLerpScalarProps {
  /** How many cards. They wrap, so this is also the ring's period. */
  count?: number;
  /** Which preset the parameters are tweened toward. */
  layout?: LayoutName;
  /** Override individual parameters on top of the preset. */
  params?: Partial<LayoutParams>;
  /** Seconds of the morph between presets. */
  duration?: number;
  /** Index steps per second of idle travel. 0 parks it. */
  drift?: number;
  /** First card's hue, 0-360. */
  hueStart?: number;
  /** Degrees of hue between adjacent cards. */
  hueStep?: number;
  /** Alpha multiplier applied before the focus falloff. */
  opacity?: number;
  /** Fires when a different card takes the focus position. */
  onFocusChange?: (index: number) => void;
  className?: string;
}

/* --------------------------------------------------------------------------
   The four presets. Each is nothing but a point in the seven-dimensional
   parameter space the placement function is defined over; the morph is a
   straight line between two points in that space.
   -------------------------------------------------------------------------- */
const PRESETS: Record<LayoutName, LayoutParams> = {
  row: { radius: 0, spacing: 0, rowSpread: 1, turns: 0, depth: 0.1, focus: 0.2, scale: 0.42 },
  column: { radius: 0, spacing: 0.95, rowSpread: 0, turns: 0, depth: 0.35, focus: 0.65, scale: 0.8 },
  drum: { radius: 2.55, spacing: 0.74, rowSpread: 0, turns: 2, depth: 0, focus: 1, scale: 1 },
  fan: { radius: 3.1, spacing: 0.14, rowSpread: 0.3, turns: 0.34, depth: 0, focus: 0.75, scale: 0.78 },
};

const CAMERA_FOV = 42;
const CAMERA_Z = 7.2;
/** Card height as a fraction of the frustum's visible height at z = 0. */
const CARD_HEIGHT_RATIO = 0.4;
/** Card width over card height. */
const CARD_ASPECT = 0.7;
/** Corner radius, in units of card height. */
const CARD_CORNER = 0.055;
/** Fraction of the visible width the flat row spans. */
const ROW_FILL = 0.92;
/** Scale an entirely out-of-focus card keeps. */
const SCALE_FLOOR = 0.72;

const MORPH_EASE = 'power3.inOut';
const TWO_PI = Math.PI * 2;
const DEG_TO_RAD = Math.PI / 180;

/** Uniform bag, as a type alias so it keeps its implicit index signature and
 *  is assignable to `ShaderMaterial`'s `{ [name: string]: THREE.IUniform }`. */
type CardUniforms = {
  uColorA: { value: THREE.Color };
  uColorB: { value: THREE.Color };
  uAspect: { value: number };
  uCorner: { value: number };
  uFocus: { value: number };
  uOpacity: { value: number };
};

interface Card {
  mesh: THREE.Mesh;
  uniforms: CardUniforms;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.PerspectiveCamera;
  geometry: THREE.PlaneGeometry;
  material: THREE.ShaderMaterial;
  cards: Card[];
}

export function LayoutLerpScalar({
  count = 12,
  layout = 'drum',
  params,
  duration = 1.25,
  drift = 0.16,
  hueStart = 232,
  hueStep = 17,
  opacity = 1,
  onFocusChange,
  className,
}: LayoutLerpScalarProps) {
  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();

  // `hasWebGL` touches `document`, so it cannot run during render without
  // disagreeing with the server. Start optimistic and correct after mount:
  // both renders then agree and nothing hydrates twice.
  const [supported, setSupported] = useState(true);
  useEffect(() => setSupported(hasWebGL()), []);

  /** The live parameter vector. GSAP tweens this object in place. */
  const live = useRef<LayoutParams>({ ...PRESETS[layout], ...params });
  /** Fractional index at the focus position. */
  const position = useRef(0);
  const focusedRef = useRef(-1);

  const notify = useRef(onFocusChange);
  notify.current = onFocusChange;

  const overrideKey = JSON.stringify(params ?? {});
  const ready = width > 1 && height > 1 && supported;

  /* ---- scene construction ------------------------------------------------ */

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

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    // Capped, not raw. A 3x phone with an uncapped ratio pays 9x the fill rate
    // for a difference nobody can see.
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(
      CAMERA_FOV,
      el.clientWidth / Math.max(el.clientHeight, 1),
      0.1,
      100,
    );
    camera.position.z = CAMERA_Z;

    // One 1x1 plane for every card; the size is `mesh.scale`, so a resize
    // costs nothing and no geometry is rebuilt. Two triangles each: the card
    // face is drawn in the fragment shader, so there is nothing to subdivide.
    const geometry = new THREE.PlaneGeometry(1, 1);
    // A shared prototype only for the source strings — each card clones it so
    // it can own its colours. three keys its program cache on the shader
    // source, so all the clones still share one compiled program.
    const prototype = new THREE.ShaderMaterial({
      vertexShader: layoutLerpScalarVertexShader,
      fragmentShader: layoutLerpScalarFragmentShader,
      transparent: true,
      side: THREE.DoubleSide,
      // No depth write: a transparent card must not stop the card behind it
      // from drawing. Order therefore comes entirely from three's painter
      // sort, which ranks transparent meshes by their CPU-side view depth —
      // correct here precisely because the CPU is what positions them.
      depthWrite: false,
    });

    const cards: Card[] = [];
    for (let i = 0; i < count; i++) {
      const hue = mod(hueStart + i * hueStep, 360) / 360;
      const uniforms: CardUniforms = {
        // setHSL is told the values are sRGB, so three converts them into the
        // linear working space. Skip that and every card renders lighter and
        // flatter than the CSS colours beside it.
        uColorA: { value: new THREE.Color().setHSL(hue, 0.52, 0.62, THREE.SRGBColorSpace) },
        uColorB: {
          value: new THREE.Color().setHSL(
            mod(hue + 0.05, 1),
            0.5,
            0.14,
            THREE.SRGBColorSpace,
          ),
        },
        uAspect: { value: CARD_ASPECT },
        uCorner: { value: CARD_CORNER },
        uFocus: { value: 1 },
        uOpacity: { value: opacity },
      };

      const material = prototype.clone();
      material.uniforms = uniforms;
      const mesh = new THREE.Mesh(geometry, material);
      // Culling is left ON, unlike every drum that bends its planes in the
      // vertex shader. The bounding sphere is computed from the geometry and
      // the CPU matrix, and here that matrix is the truth, so three can cull
      // the far side of the ring correctly and for free.
      scene.add(mesh);
      cards.push({ mesh, uniforms });
    }

    stage.current = { renderer, scene, camera, geometry, material: prototype, cards };
    renderer.render(scene, camera);

    return () => {
      stage.current = null;
      for (const card of cards) scene.remove(card.mesh);
      disposeObject(scene);
      geometry.dispose();
      prototype.dispose();
      // dispose() frees GPU objects and leaves the context alive. Only
      // forceContextLoss, which disposeRenderer calls, hands it back.
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // `opacity` only seeds a uniform the frame loop overwrites immediately.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, count, hueStart, hueStep]);

  /* ---- size -------------------------------------------------------------- */

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.renderer.setPixelRatio(pixelRatio());
    // `false` — the canvas is sized by CSS at 100%/100%; letting three write
    // inline pixel dimensions makes it fight the flex parent on every resize.
    current.renderer.setSize(width, height, false);
    current.camera.aspect = width / height;
    current.camera.updateProjectionMatrix();
  }, [width, height]);

  // #region critical
  /* ---- the morph: one tween over an object literal ------------------------ */

  useEffect(() => {
    const target: LayoutParams = { ...PRESETS[layout], ...params };
    const current = live.current;

    if (reduced) {
      Object.assign(current, target);
      return;
    }

    // Every parameter eases together, so the shape passes through a continuous
    // family of shapes rather than each card taking its own path. `overwrite`
    // matters: switch layout twice quickly and the second tween must take the
    // parameters from wherever the first one had got to, not fight it.
    const tween = gsap.to(current, { ...target, duration, ease: MORPH_EASE, overwrite: true });
    return () => {
      tween.kill();
    };
    // `params` is compared by value through `overrideKey`; the object literal
    // most callers pass is a new reference on every render.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [layout, overrideKey, duration, reduced]);

  useEffect(() => {
    const current = live.current;
    return () => {
      gsap.killTweensOf(current);
    };
  }, []);

  /* ---- the frame ---------------------------------------------------------- */

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const n = current.cards.length;
      if (n === 0) return;

      const p = live.current;
      const speed = reduced ? 0 : drift;
      // Wrapped rather than left to grow: at 0.16 steps/s an unwrapped
      // accumulator is fine for days, but the modulo costs nothing and keeps
      // float precision constant no matter how long the tab stays open.
      position.current = mod(position.current + dt * speed, n);
      const pos = position.current;

      // The one place the camera and the layout meet. `visibleHeight` is the
      // frustum's height at z = 0 — `2 * z * tan(fov/2)` — and the width is
      // that times the aspect. Deriving the row step from it is why the row
      // spans the frame at any viewport instead of being a guessed constant.
      const visibleHeight = 2 * Math.tan((CAMERA_FOV * DEG_TO_RAD) / 2) * CAMERA_Z;
      const visibleWidth = visibleHeight * current.camera.aspect;
      const step = (visibleWidth * ROW_FILL) / Math.max(n - 1, 1);
      const cardHeight = visibleHeight * CARD_HEIGHT_RATIO;
      const cardWidth = cardHeight * CARD_ASPECT;

      for (let i = 0; i < n; i++) {
        const card = current.cards[i];
        if (!card) continue;

        // The call that makes a finite array behave like an endless ring:
        // card 0 is one step BEFORE card 11, not eleven steps after it.
        const offset = wrappedOffset(i, pos, n);
        const angle = (offset / n) * TWO_PI * p.turns;

        // The placement function. Seven scalars in, one transform out, and
        // every layout this component has is somewhere in here.
        card.mesh.position.set(
          p.radius * Math.sin(angle) + offset * p.rowSpread * step,
          -offset * p.spacing,
          // cos(angle) - 1 keeps the focused card at z = 0 whatever the
          // radius, so growing the drum pushes the ring back rather than
          // pulling the front card into the camera. The depth term is what
          // gives the flat layouts a strictly monotonic z, which is what lets
          // three sort them back-to-front without any renderOrder fixing.
          p.radius * (Math.cos(angle) - 1) - p.depth * Math.abs(offset),
        );
        card.mesh.rotation.y = angle;

        // exp(-d^2): 1.000 at the focus, 0.368 one step out, 0.018 two,
        // 0.0001 three. Continuous and branchless, and `focus` scales how much
        // of it applies — at 0 every card is lit equally, which is what makes
        // the flat row read as an index rather than as a selection.
        const f = 1 - p.focus * (1 - gaussian(offset));
        const s = p.scale * (SCALE_FLOOR + (1 - SCALE_FLOOR) * f);
        card.mesh.scale.set(cardWidth * s, cardHeight * s, 1);
        card.uniforms.uFocus.value = f;
        card.uniforms.uOpacity.value = opacity;
      }

      const nextFocus = wrapIndex(Math.round(pos), n);
      if (nextFocus !== focusedRef.current) {
        focusedRef.current = nextFocus;
        notify.current?.(nextFocus);
      }

      current.renderer.render(current.scene, current.camera);
    },
    ready && inView && visible,
  );
  // #endregion critical

  const fallback = useMemo(
    () => (
      <div className="flex h-full w-full items-center justify-center">
        <ol className="flex max-w-full gap-1 overflow-hidden px-4">
          {Array.from({ length: Math.min(count, 7) }, (_unused, index) => (
            <li
              key={index}
              className="h-24 w-8 shrink-0 rounded-sm"
              style={{
                background: `linear-gradient(160deg, hsl(${hueStart + index * hueStep} 50% 14%), hsl(${hueStart + index * hueStep + 18} 52% 62%))`,
              }}
            />
          ))}
        </ol>
      </div>
    ),
    [count, hueStart, hueStep],
  );

  return (
    <div className={cn('relative h-full w-full overflow-hidden', className)}>
      <div ref={host} className="absolute inset-0" aria-hidden="true" />
      {!supported ? fallback : null}
    </div>
  );
}

/* ==========================================================================
   Layout Lerp Scalar — GLSL, as TypeScript template literals.
   --------------------------------------------------------------------------
   Shipped as .ts and not .glsl on purpose: a .glsl import forces every
   consumer to install and configure a bundler plugin before the component
   will compile, while a template literal is a plain module every bundler
   already understands.

   The notable thing about this pair is how little it knows. The layout — row,
   column, drum, fan and every blend between them — happens entirely on the
   CPU, as scalars written into mesh.position, mesh.rotation and mesh.scale.
   The vertex shader is the default transform and nothing else, which is what
   keeps frustum culling and three's transparency sort telling the truth: both
   read the CPU-side matrix, and here the CPU-side matrix is where the card
   actually is.

   So the fragment shader is free to be the whole picture. It draws a card —
   rounded rectangle, gradient, hairlines, rim — from six uniforms and no
   texture, so the component ships no image and fetches nothing.
   ========================================================================== */

export const layoutLerpScalarVertexShader = /* glsl */ `
varying vec2  vUv;
varying float vFacing;

void main() {
  vUv = uv;

  // How square-on this card is to the camera, straight from the transformed
  // normal. Cards turning edge-on around the drum darken with no light in the
  // scene and no second pass -- one dot product standing in for shading.
  // abs() because the material is double-sided and the back face's normal
  // points away.
  vec3 n = normalize(normalMatrix * normal);
  vFacing = abs(n.z);

  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}
`;

export const layoutLerpScalarFragmentShader = /* glsl */ `
uniform vec3  uColorA;
uniform vec3  uColorB;
uniform float uAspect;
uniform float uCorner;
uniform float uFocus;
uniform float uOpacity;

varying vec2  vUv;
varying float vFacing;

/* Signed distance to a rounded rectangle, in units of card height: negative
   inside, zero on the edge. Cheaper and sharper than a corner-radius texture,
   and it stays crisp at any scale because the card is drawn, not sampled. */
float sdRoundedBox(vec2 p, vec2 b, float r) {
  vec2 q = abs(p) - b + r;
  return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - r;
}

void main() {
  // Local space where y spans 1.0 and x spans the aspect, so one corner
  // radius is the same number of world units on both axes.
  vec2 p = (vUv - 0.5) * vec2(uAspect, 1.0);
  vec2 ext = vec2(uAspect, 1.0) * 0.5;
  float d = sdRoundedBox(p, ext, uCorner);

  // One pixel, measured in the same units as d. fwidth is core in WebGL2, and
  // the max() keeps smoothstep well-formed if a driver ever hands back 0.
  float aa = max(fwidth(d), 1e-4);
  float mask = 1.0 - smoothstep(-aa, aa, d);
  if (mask < 0.002) discard;

  float ramp = clamp(vUv.y * 0.92 + (vUv.x - 0.5) * 0.22 + 0.04, 0.0, 1.0);
  vec3 color = mix(uColorB, uColorA, ramp);

  // Hairlines. A smooth gradient hides rotation completely -- there has to be
  // structure on the card for the eye to read the turn of the drum.
  float ticks = vUv.y * 9.0;
  float toLine = 0.5 - abs(fract(ticks) - 0.5);
  float lineWidth = fwidth(ticks) * 1.1;
  color += (1.0 - smoothstep(0.0, lineWidth, toLine)) * 0.055;

  // Inset rim, one pixel wide, at 0.5% of card height in from the edge.
  float rim = 1.0 - smoothstep(0.0, aa * 2.0, abs(d + 0.005));
  color = mix(color, vec3(1.0), rim * 0.16);

  // Out-of-focus cards lose light and colour rather than blurring: a real
  // blur needs a render target, and desaturating toward luminance reads the
  // same at this size for one dot product.
  float grey = dot(color, vec3(0.2126, 0.7152, 0.0722));
  color = mix(vec3(grey), color, mix(0.25, 1.0, uFocus));
  color *= mix(0.36, 1.0, uFocus);
  color *= mix(0.52, 1.0, vFacing);

  gl_FragColor = vec4(color, mask * uOpacity * mix(0.24, 1.0, uFocus));

  // ShaderMaterial gets no automatic output conversion -- three only injects
  // this chunk into its own materials. Without it every colour ships raw
  // linear values into an sRGB framebuffer and the scene looks washed out.
  #include <colorspace_fragment>
}
`;

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

/* ==========================================================================
   Ring index arithmetic.
   --------------------------------------------------------------------------
   Anything that loops — a drum carousel, an infinite marquee, a cylinder of
   image planes — needs to answer "how far is item i from position p" in a way
   that treats the sequence as a circle. A plain `i - p` says item 0 is 18 away
   from item 18 in a list of 19, when really it is 1 step back.
   ========================================================================== */

/** True modulo. Unlike `%`, the result is never negative. */
export function mod(n: number, m: number): number {
  return ((n % m) + m) % m;
}

/**
 * Shortest signed distance from `position` to index `i` around a ring of
 * `count` items. Result is in `(-count/2, count/2]`; negative means "behind".
 *
 * This one function is what makes a finite array behave like an infinite one.
 */
export function wrappedOffset(i: number, position: number, count: number): number {
  if (count <= 0) return 0;
  let offset = mod(i - position, count);
  if (offset > count / 2) offset -= count;
  return offset;
}

/** Wrap `value` into `[min, max)`, e.g. an angle into `[-PI, PI)`. */
export function wrapRange(value: number, min: number, max: number): number {
  const span = max - min;
  if (span <= 0) return min;
  return mod(value - min, span) + min;
}

/** Wrap an index into `[0, count)`. Accepts fractional and negative input. */
export function wrapIndex(i: number, count: number): number {
  return count <= 0 ? 0 : mod(i, count);
}

/**
 * Shortest signed angular distance from `a` to `b` in radians, in `(-PI, PI]`.
 * Prevents a rotation tween from taking the long way round.
 */
export function shortestAngle(a: number, b: number): number {
  return wrapRange(b - a, -Math.PI, Math.PI);
}