Realtime Cube EnvMap

'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 {
  disposeObject,
  disposeRenderer,
  hasWebGL,
  pixelRatio,
} from '@/lib/webgl';

/* ==========================================================================
   Realtime Cube EnvMap
   --------------------------------------------------------------------------
   A metal object that reflects a scene which is itself moving. There is no
   HDRI, no .env file, no loader: a `CubeCamera` sitting inside the object
   renders the six faces around it every frame, and that cube texture is
   assigned straight onto the material as its `envMap`.

   Two things make it work rather than merely run:

     1. The reflector is hidden for the duration of the capture. A mirror that
        can see itself captures its own previous frame, and the next capture
        includes that, so the surface fills with a recursive tunnel of dark
        shells within about a second.
     2. The capture is throttled independently of the render. Six faces is
        six scene renders; the visible pass is one. Refreshing the cube on
        alternate frames halves the cost of the whole component and, because
        an env map is sampled by direction and not by position, a one-frame-old
        reflection is not observable on motion this slow.
   ========================================================================== */

export interface RealtimeCubeEnvmapProps {
  /** Reflector silhouette. The knot has more curvature, so it reflects more. */
  shape?: 'knot' | 'icosahedron';
  /** Emitting panels arranged around the object. These are the reflection. */
  panelCount?: number;
  /** Ring radius in world units. The reflector is ~1.4 units across. */
  panelRadius?: number;
  /** Panel ring rotation, radians per second. */
  spinSpeed?: number;
  /** Reflector rotation, radians per second about Y. */
  objectSpin?: number;
  /** Cube face size in pixels. Cost is 6 x resolution². */
  resolution?: number;
  /** Capture the cube map every Nth frame. 1 = every frame. */
  refreshEvery?: number;
  /** Surface roughness. Above ~0.3 the reflection stops being readable. */
  roughness?: number;
  /** 1 is a mirror, 0 is a diffuse surface lit only by the env map. */
  metalness?: number;
  /** Multiplier on the reflected light. Above ~2 the highlights clip flat. */
  envMapIntensity?: number;
  /** Base hue for the panels, degrees. */
  hue?: number;
  className?: string;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.PerspectiveCamera;
  cubeTarget: THREE.WebGLCubeRenderTarget;
  /** Frames the container aspect, then redraws — a resize must not go stale. */
  resize: (width: number, height: number) => void;
  /** `forceCapture` bypasses the refresh throttle, for the first frame. */
  draw: (elapsed: number, forceCapture: boolean) => void;
}

/**
 * Camera distance at aspect >= 1. Chosen so a 1.4-unit reflector fills roughly
 * two thirds of the frame height at a 34 degree field of view.
 */
const BASE_DISTANCE = 7.2;
const FIELD_OF_VIEW = 34;

/**
 * Pose used when motion is suppressed. Deliberately not 0: at elapsed 0 the
 * knot is axis-aligned and the panels sit on the cardinal directions, which
 * reads as a technical diagram rather than a lit object.
 */
const STATIC_POSE = 0.9;

/** Vertical gradient for the surrounding shell. 4px wide — it never varies in u. */
function makeShellTexture(hue: number): HTMLCanvasElement {
  const canvas = document.createElement('canvas');
  canvas.width = 4;
  canvas.height = 256;
  const ctx = canvas.getContext('2d');
  if (!ctx) return canvas;

  const ramp = ctx.createLinearGradient(0, 0, 0, 256);
  ramp.addColorStop(0, `hsl(${hue + 8}, 22%, 26%)`);
  ramp.addColorStop(0.46, `hsl(${hue}, 16%, 11%)`);
  ramp.addColorStop(1, 'hsl(0, 0%, 4%)');
  ctx.fillStyle = ramp;
  ctx.fillRect(0, 0, 4, 256);
  return canvas;
}

// #region critical
export function RealtimeCubeEnvmap({
  shape = 'knot',
  panelCount = 7,
  panelRadius = 4.2,
  spinSpeed = 0.18,
  objectSpin = 0.32,
  resolution = 256,
  refreshEvery = 2,
  roughness = 0.08,
  metalness = 1,
  envMapIntensity = 1.4,
  hue = 208,
  className,
}: RealtimeCubeEnvmapProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);

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

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

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

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

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

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: false });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    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(FIELD_OF_VIEW, 1, 0.1, 60);
    camera.position.set(0, 0.35, BASE_DISTANCE);
    camera.lookAt(0, 0, 0);

    // The shell is the environment's floor and sky in one object: a sphere
    // turned inside out. It is what the cube camera sees in every direction
    // the panels do not cover, so without it the reflection has large holes of
    // clear-colour black and the object reads as unlit rather than dark.
    const shellTexture = new THREE.CanvasTexture(makeShellTexture(hue));
    shellTexture.colorSpace = THREE.SRGBColorSpace;
    const shellGeometry = new THREE.SphereGeometry(16, 32, 16);
    const shellMaterial = new THREE.MeshBasicMaterial({
      map: shellTexture,
      side: THREE.BackSide,
    });
    scene.add(new THREE.Mesh(shellGeometry, shellMaterial));

    // Panels. Their arrangement is a pure function of the index — there is no
    // random scatter here, so there is no seed to keep in step between the
    // server render and the client one.
    const ring = new THREE.Group();
    const panelGeometry = new THREE.PlaneGeometry(1.5, 3.4);
    const panelMaterials: THREE.MeshBasicMaterial[] = [];
    const count = Math.max(2, Math.round(panelCount));

    for (let i = 0; i < count; i += 1) {
      const material = new THREE.MeshBasicMaterial({ side: THREE.DoubleSide });
      // Alternating bright and near-black panels. An environment that is
      // uniformly bright gives a mirror nothing to contrast against and the
      // metal reads as matte plastic; the dark panels are what draw the
      // specular edges.
      const bright = i % 2 === 0;
      material.color.setHSL(
        ((hue + i * 26) % 360) / 360,
        bright ? 0.66 : 0.4,
        bright ? 0.62 : 0.08,
      );
      panelMaterials.push(material);

      const panel = new THREE.Mesh(panelGeometry, material);
      const angle = (i / count) * Math.PI * 2;
      // Golden-angle stagger on the height, so the panels do not sit in a
      // single band and the reflection has vertical structure to move through.
      const lift = Math.sin(i * 2.39996) * 0.9;
      panel.position.set(
        Math.sin(angle) * panelRadius,
        lift,
        Math.cos(angle) * panelRadius,
      );
      panel.lookAt(0, 0, 0);
      ring.add(panel);
    }
    scene.add(ring);

    const reflectorGeometry =
      shape === 'knot'
        ? new THREE.TorusKnotGeometry(0.92, 0.31, 220, 32)
        : new THREE.IcosahedronGeometry(1.35, 2);

    // Mipmaps are not optional here. `roughness` selects a mip level of the
    // env map, so a cube target without them samples level 0 at every
    // roughness and the surface stays a hard mirror no matter what you pass.
    const cubeTarget = new THREE.WebGLCubeRenderTarget(Math.max(16, Math.round(resolution)), {
      generateMipmaps: true,
      minFilter: THREE.LinearMipmapLinearFilter,
    });
    const cubeCamera = new THREE.CubeCamera(0.1, 60, cubeTarget);
    // Co-located with the reflector: an env map is sampled by direction, so
    // the capture point is the only position information it carries. Offset it
    // and the reflections belong to a different object.
    cubeCamera.position.set(0, 0, 0);
    scene.add(cubeCamera);

    const material = new THREE.MeshPhysicalMaterial({
      metalness,
      roughness,
      envMapIntensity,
      // Assigned to the material rather than `scene.environment` on purpose.
      // A live capture belongs to one object at one point in space; sharing it
      // scene-wide would give every reflector the same viewpoint.
      envMap: cubeTarget.texture,
      color: 0xffffff,
    });
    const reflector = new THREE.Mesh(reflectorGeometry, material);
    scene.add(reflector);

    const throttle = Math.max(1, Math.round(refreshEvery));
    let frames = 0;

    const draw = (elapsed: number, forceCapture: boolean) => {
      ring.rotation.y = elapsed * spinSpeed;
      reflector.rotation.y = elapsed * objectSpin;
      reflector.rotation.x = elapsed * objectSpin * 0.55;

      frames += 1;
      if (forceCapture || frames % throttle === 0) {
        // Hide, capture, show — in that order, inside one frame. Skipping the
        // hide is the classic version of this bug: the object captures itself
        // and within a second the surface is a recursive tunnel.
        reflector.visible = false;
        cubeCamera.update(renderer, scene);
        reflector.visible = true;
      }

      renderer.render(scene, camera);
    };

    const resize = (w: number, h: number) => {
      if (w < 1 || h < 1) return;
      const aspect = w / h;
      renderer.setPixelRatio(pixelRatio());
      renderer.setSize(w, h, false);
      camera.aspect = aspect;
      // Pull the camera back on narrow containers. A fixed distance frames the
      // object on height alone, so a portrait preview clips the panel ring off
      // both sides and the reflections lose their source.
      camera.position.z = BASE_DISTANCE / Math.min(1, aspect);
      camera.updateProjectionMatrix();
    };

    resize(size.current.width, size.current.height);
    stage.current = { renderer, scene, camera, cubeTarget, resize, draw };
    // First frame forces a capture: with an empty cube map a metal surface is
    // pure black, and on a throttled refresh that black would be on screen for
    // `refreshEvery` frames.
    draw(STATIC_POSE, true);

    return () => {
      stage.current = null;
      scene.remove(cubeCamera);
      // Order matters: free the scene graph's GPU objects while the context is
      // still alive, then hand the context itself back.
      disposeObject(scene);
      shellTexture.dispose();
      shellGeometry.dispose();
      shellMaterial.dispose();
      panelGeometry.dispose();
      for (const panelMaterial of panelMaterials) panelMaterial.dispose();
      reflectorGeometry.dispose();
      material.dispose();
      // The cube target is not in the scene graph, so nothing above reaches
      // it. It holds six faces plus their mip chain — at 256px that is about
      // 2 MB of GPU memory per instance.
      cubeTarget.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    shape,
    panelCount,
    panelRadius,
    spinSpeed,
    objectSpin,
    resolution,
    refreshEvery,
    roughness,
    metalness,
    envMapIntensity,
    hue,
  ]);

  // Resize in its own effect: a container reflow costs a `setSize` and one
  // redraw rather than a rebuild of the geometry and the cube target.
  useEffect(() => {
    const current = stage.current;
    if (!current) return;
    current.resize(width, height);
    current.draw(STATIC_POSE, true);
  }, [width, height, reduced]);

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

  return (
    <div className={cn('relative h-full w-full overflow-hidden bg-bg', className)}>
      <div ref={host} className="absolute inset-0" />
      {!supported ? (
        <div className="absolute inset-0 grid place-items-center">
          <div
            className="h-2/5 w-2/5 rounded-full"
            style={{
              background: `radial-gradient(circle at 34% 28%, hsl(${hue} 30% 82%), hsl(${hue} 24% 34%) 46%, hsl(${hue} 20% 8%) 100%)`,
            }}
          />
        </div>
      ) : null}
    </div>
  );
}

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