Depth Fade And Travelling Pulse

'use client';

import { useEffect, useRef, useState } from 'react';
import * as THREE from 'three';
import { cn } from '@/lib/utils';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { createRng } from '@/lib/prng';
import { disposeObject, disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  DEPTH_PULSE_WAVE_FRAG,
  DEPTH_PULSE_WAVE_VERT,
} from '@/components/motion/shaders/depth-pulse-travelling-wave';

/* ==========================================================================
   Depth Fade And Travelling Pulse
   --------------------------------------------------------------------------
   A lattice of dots bent around a shallow arc, breathing. Two techniques are
   stacked, and the whole point is that they compose:

   1. Depth fade. Model-space z drives alpha AND point size together, so the
      curved edges of the lattice recede without a depth buffer, a perspective
      camera, or a sort.

   2. Travelling pulse. Every column carries its own phase offset, so the
      cosine crest sweeps across the lattice instead of the whole field
      pulsing in unison. The crest also pushes dots toward the viewer, which
      feeds back into (1): the wave arrives as a moving band of brighter,
      larger dots.

   In unison, a pulsing field reads as a loading spinner. In sequence, it
   reads as something passing through.
   ========================================================================== */

export interface DepthPulseTravellingWaveProps {
  /** Columns across the arc. */
  columns?: number;
  /** Rows down each column. */
  rows?: number;
  /** Arc the lattice is bent around, in degrees. */
  arcSpan?: number;
  /** Half-depth of the arc in model units — how far the edges recede. */
  arcDepth?: number;
  /** Lattice height in model units. */
  fieldHeight?: number;
  /** Seconds per pulse. */
  pulseCycle?: number;
  /** Wavelengths visible across the lattice at any instant. */
  waveTurns?: number;
  /** How far a crest pushes a dot toward the viewer, in model units. */
  waveDepth?: number;
  /** Peak yaw of the whole lattice, in degrees. */
  yawAmplitude?: number;
  /** Yaw oscillations per second. */
  yawSpeed?: number;
  /** Dot radius multiplier, in CSS pixels. */
  dotScale?: number;
  /** Model-to-pixel scale as a fraction of the container short side. */
  viewScale?: number;
  opacity?: number;
  color?: string;
  crestColor?: string;
  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 };
  uViewScale: { value: number };
  uPixelRatio: { value: number };
  uDotScale: { value: number };
  uOpacity: { value: number };
  uPulseCycle: { value: number };
  uWaveDepth: { value: number };
  uYaw: { value: number };
  uColor: { value: THREE.Color };
  uCrestColor: { value: THREE.Color };
}

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

/**
 * Frame drawn under reduced motion. Past INTRO_SECONDS (1.0) so the pulse is
 * at full amplitude, and a third of the way through the default cycle so the
 * crest sits inside the lattice rather than off its edge.
 */
const STATIC_ELAPSED = 1.9;

/** Tiny row contribution to the phase, so the crest leans instead of being a vertical bar. */
const ROW_PHASE_LEAN = 0.12;

// #region critical
export function DepthPulseTravellingWave({
  columns = 110,
  rows = 44,
  arcSpan = 110,
  arcDepth = 0.34,
  fieldHeight = 1.1,
  pulseCycle = 3,
  waveTurns = 1.4,
  waveDepth = 0.18,
  yawAmplitude = 16,
  yawSpeed = 0.25,
  dotScale = 1,
  viewScale = 0.46,
  opacity = 1,
  color = '#6f757e',
  crestColor = '#ffffff',
  seed = 'depth-pulse-travelling-wave',
  className,
}: DepthPulseTravellingWaveProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

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

  const reduced = useReducedMotion();
  const ready = width > 0 && height > 0;

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

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

    const renderer = new THREE.WebGLRenderer({ antialias: false, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setClearAlpha(0);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const rng = createRng(seed);

    const total = columns * rows;
    const positions = new Float32Array(total * 3);
    const wave = new Float32Array(total * 2);

    /* ------------------------------------------------------------------
       The arc. Columns are placed by angle, then z is renormalised so the
       centre column sits at +arcDepth and the two edges at -arcDepth
       exactly. Without the renormalisation the usable z range depends on
       arcSpan, and the depth fade would get weaker every time the arc was
       flattened — the cue would silently stop working at shallow spans.
       ------------------------------------------------------------------ */
    const halfSpan = (arcSpan * Math.PI) / 360;
    const cosEdge = Math.cos(halfSpan);
    // Guard the degenerate case: a 0 degree span has no depth to normalise.
    const depthSpan = Math.max(1e-4, 1 - cosEdge);

    let cursor = 0;
    for (let c = 0; c < columns; c += 1) {
      const colT = columns === 1 ? 0.5 : c / (columns - 1);
      const angle = (colT - 0.5) * 2 * halfSpan;
      const x = Math.sin(angle);
      const z = ((Math.cos(angle) - cosEdge) / depthSpan) * 2 * arcDepth - arcDepth;

      for (let r = 0; r < rows; r += 1) {
        const rowT = rows === 1 ? 0.5 : r / (rows - 1);
        // Sub-cell jitter, seeded. A perfect lattice moirés against the pixel
        // grid and shows banding as the field yaws.
        const jx = (rng() - 0.5) * (1 / columns) * 0.9;
        const jy = (rng() - 0.5) * (1 / rows) * 0.9;

        positions[cursor * 3] = x + jx;
        positions[cursor * 3 + 1] = (rowT - 0.5 + jy) * fieldHeight;
        positions[cursor * 3 + 2] = z;

        // Phase is what makes it travel. Constant phase across the lattice
        // would give a field that breathes in unison.
        wave[cursor * 2] = colT * waveTurns + rowT * ROW_PHASE_LEAN;
        wave[cursor * 2 + 1] = rng() - 0.5;
        cursor += 1;
      }
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aWave', new THREE.BufferAttribute(wave, 2));

    const uniforms: Uniforms = {
      uElapsed: { value: 0 },
      uViewScale: { value: 1 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uDotScale: { value: dotScale },
      uOpacity: { value: opacity },
      uPulseCycle: { value: pulseCycle },
      uWaveDepth: { value: waveDepth },
      uYaw: { value: 0 },
      uColor: { value: new THREE.Color(color) },
      uCrestColor: { value: new THREE.Color(crestColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: DEPTH_PULSE_WAVE_VERT,
      fragmentShader: DEPTH_PULSE_WAVE_FRAG,
      uniforms,
      transparent: true,
      // Every dot is projected at z = 0; the depth cue is alpha and size, not
      // the depth buffer. Leaving these on would let near dots reject far ones
      // that were rasterised first and punch holes through the lattice.
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    // Positions are unit-scale around the origin and the real placement happens
    // in the shader, so three's bounding sphere does not describe what is on
    // screen and culling against it would blank the field at some sizes.
    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%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      uniforms.uViewScale.value = Math.min(w, h) * viewScale;
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      // Yaw oscillates rather than spins. A full rotation would carry columns
      // through the arc's own depth range and the travelling crest would stop
      // being readable as a wave.
      uniforms.uYaw.value = Math.sin(elapsed * yawSpeed * Math.PI * 2) * yawAmplitude;
      renderer.render(scene, camera);
    };

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

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    columns,
    rows,
    arcSpan,
    arcDepth,
    fieldHeight,
    pulseCycle,
    waveTurns,
    waveDepth,
    yawAmplitude,
    yawSpeed,
    dotScale,
    viewScale,
    opacity,
    color,
    crestColor,
    seed,
  ]);

  useEffect(() => {
    stage.current?.resize(width, height);
    if (reduced) stage.current?.draw(STATIC_ELAPSED);
  }, [width, height, reduced]);

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

  return (
    <div ref={host} className={cn('relative h-full w-full overflow-hidden', className)}>
      {unsupported ? (
        <div className="absolute inset-0 flex items-center justify-center">
          <div className="flex h-[55%] w-[70%] flex-col justify-between">
            {Array.from({ length: 9 }, (_, i) => (
              <div
                key={i}
                className="h-px w-full bg-line-strong"
                style={{ opacity: 0.25 + Math.sin((i / 8) * Math.PI) * 0.5 }}
              />
            ))}
          </div>
        </div>
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Depth Fade And Travelling Pulse — GLSL
   --------------------------------------------------------------------------
   Two techniques that belong together, because each one covers for the other's
   weakness.

   The depth cue: model-space z drives BOTH alpha and point size, so a dot
   further from the viewer is dimmer AND smaller. Alpha alone reads as a grey
   copy of the near dots; size alone reads as a resolution change. Together
   they read as distance, with no depth buffer and no perspective camera.

   The pulse: every column carries its own phase, so the cosine peaks sweep
   along the lattice instead of the whole field breathing in unison. A field
   that pulses in unison looks like a loading state; one that pulses in
   sequence looks like something is passing through it.
   ========================================================================== */

/** `aWave = vec2(phase 0..1, per-dot jitter -0.5..0.5)`. */
export const DEPTH_PULSE_WAVE_VERT = /* glsl */ `
attribute vec2 aWave;

uniform float uElapsed;
uniform float uViewScale;
uniform float uPixelRatio;
uniform float uDotScale;
uniform float uOpacity;
uniform float uPulseCycle;
uniform float uWaveDepth;
uniform float uYaw;

varying float vAlpha;
varying float vAlphaScale;
varying float vPulse;

const float TAU = 6.283185307179586;
const float DEG2RAD = 0.017453292519943295;

/* One pulse every 3 seconds. Faster than ~2s and the crest overtakes the eye's
   ability to follow it along the lattice; slower than ~5s and it stops reading
   as a wave and starts reading as an idle shimmer. */
const float DEFAULT_CYCLE = 3.0;

/* The pulse ramps in over the first second so it does not fight whatever
   entrance the field is doing. Without it the very first frame lands on an
   arbitrary point of the cosine and the field flashes. */
const float INTRO_SECONDS = 1.0;

/* Pulse rides between 0.30 and 1.00 of nominal. A trough of 0 would make dots
   disappear entirely and the lattice would look like it is dropping frames. */
const float PULSE_BASE = 0.65;
const float PULSE_SWING = 0.35;

/* z range the depth cue normalises over. The arc itself only spans +/-0.34 and
   the wave adds up to +0.18 on top, so 0.55 leaves headroom at both ends: no
   dot ever sits at exactly 0 or 1 and the falloff never visibly clips. */
const float DEPTH_HALF_RANGE = 0.55;
const float DEPTH_MIN_SIZE = 0.65;
const float DEPTH_MAX_SIZE = 1.0;

const float MIN_POINT_SIZE = 2.0;
const float UNCLAMPED_MIN_POINT_SIZE = 1.0;

vec3 rotateY(vec3 p, float degrees) {
  float a = degrees * DEG2RAD;
  float c = cos(a);
  float s = sin(a);
  return vec3(c * p.x + s * p.z, p.y, -s * p.x + c * p.z);
}

void main() {
  float phase  = aWave.x;
  float jitter = aWave.y;

  // The travelling wave. Subtracting the phase inside the cosine is what makes
  // the crest move ALONG the lattice: at any instant, columns further through
  // the phase range are further through the cycle.
  float cycle  = uPulseCycle > 0.0 ? uPulseCycle : DEFAULT_CYCLE;
  float raw    = PULSE_BASE + PULSE_SWING * cos(TAU * (uElapsed / cycle - phase));
  float intro  = clamp(uElapsed / INTRO_SECONDS, 0.0, 1.0);
  float pulse  = 1.0 + (raw - 1.0) * intro;

  // Crest normalised to 0..1, used to push the dot toward the viewer. This is
  // what makes the two techniques visibly interact: the wave moves dots in z,
  // and the depth cue then brightens and enlarges them for it.
  float crest = (raw - (PULSE_BASE - PULSE_SWING)) / (2.0 * PULSE_SWING);

  vec3 p = position;
  p.z += crest * uWaveDepth * (1.0 + jitter * 0.3);
  p = rotateY(p, uYaw);

  float depthT     = clamp((p.z + DEPTH_HALF_RANGE) / (2.0 * DEPTH_HALF_RANGE), 0.0, 1.0);
  float depthAlpha = 0.25 + 0.75 * depthT;
  float depthSize  = DEPTH_MIN_SIZE + depthT * (DEPTH_MAX_SIZE - DEPTH_MIN_SIZE);

  vPulse = crest;
  vAlpha = depthAlpha * pulse * uOpacity;

  gl_Position = projectionMatrix * modelViewMatrix * vec4(p.xy * uViewScale, 0.0, 1.0);

  float raw2      = uDotScale * pulse * depthSize * 2.0 * uPixelRatio;
  float unclamped = max(UNCLAMPED_MIN_POINT_SIZE, raw2);
  float clamped   = max(MIN_POINT_SIZE, raw2);
  vAlphaScale  = (unclamped * unclamped) / (clamped * clamped);
  gl_PointSize = clamped;
}
`;

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

uniform vec3 uColor;
uniform vec3 uCrestColor;

varying float vAlpha;
varying float vAlphaScale;
varying float vPulse;

const float ALPHA_EPSILON = 0.003;

void main() {
  vec2  centered = gl_PointCoord - vec2(0.5);
  float disc = 1.0 - smoothstep(0.43, 0.5, length(centered));

  float alpha = vAlpha * vAlphaScale * disc;
  if (alpha <= ALPHA_EPSILON) discard;

  // Tint only the top third of the crest. Colouring the whole cosine washes
  // the tint across the entire field and the wave stops having a location.
  gl_FragColor = vec4(mix(uColor, uCrestColor, smoothstep(0.65, 1.0, vPulse)), alpha);
}
`;

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

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;
  }
}