Fractional Render Scale

'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 { useSmoothPointer } from '@/hooks/use-smooth-pointer';
import { useVisibility } from '@/hooks/use-visibility';
import { clamp, perFrameToSmoothing } from '@/lib/damp';
import { disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  FRACTIONAL_SCALE_FRAG,
  FRACTIONAL_SCALE_VERT,
} from '@/components/motion/shaders/fractional-render-scale';

/* ==========================================================================
   Fractional Render Scale
   --------------------------------------------------------------------------
   A full-bleed shader field whose backing store is 0.6x the size of the box it
   fills. The CSS size stays 1x, so the browser upscales — and 0.6 linear is
   0.36 of the pixels, a 64% cut in fragment shader work. A 2560x1440 window
   is 3.7 M fragments a frame at 1x and 1.3 M at 0.6x; the same window on a 2x
   screen is 14.7 M against 5.3 M.

   Everything else in the file exists to make that invisible:

     - the fog has no detail finer than a dozen pixels, so bilinear upsampling
       has nothing to soften that was not already soft;
     - the grid's line width is specified in BACKING-STORE pixels, so it gets
       wider in CSS terms as the scale drops instead of thinner — a line
       authored in CSS pixels would fall below one texel at 0.6 and stipple;
     - the canvas keeps the browser's default smoothing. `image-rendering:
       pixelated` on this element would undo the entire technique.

   The scale is applied through the device pixel ratio, so it composes with a
   3x screen instead of fighting it: 0.6 always means "0.36 of the fragments
   this display would otherwise ask for".
   ========================================================================== */

export interface FractionalRenderScaleProps {
  /** Backing store size relative to the display's own pixel ratio. */
  renderScale?: number;
  /** Cap on the device pixel ratio before the scale is applied. */
  maxDpr?: number;
  /** Grid spacing in CSS pixels. */
  gridSize?: number;
  /** Every nth line is a major one. */
  majorEvery?: number;
  /** Minor line width in BACKING-STORE pixels. Not CSS pixels — see the header. */
  lineWidth?: number;
  /** Cursor glow radius in CSS pixels. */
  glowRadius?: number;
  /** Darkest colour of the field. */
  baseColor?: string;
  /** Colour the fog lifts toward. */
  fogColor?: string;
  /** Grid line colour. */
  lineColor?: string;
  /** Additive colour under the pointer. */
  glowColor?: string;
  className?: string;
}

/**
 * The source eases the pointer with `x += (target - x) * 0.05` every frame,
 * which is frame-rate dependent by design: it makes the glow trail the cursor
 * rather than stick to it. `perFrameToSmoothing` reproduces that feel exactly
 * at 60 Hz — 0.95^60 of the gap left after a second — while behaving the same
 * on a 120 Hz display, where the raw form would arrive twice as fast.
 */
const POINTER_ALPHA = 0.05;
const POINTER_SMOOTHING = perFrameToSmoothing(POINTER_ALPHA);

/** Below this the grid's one-texel line is wider than a third of a cell. */
const MIN_SCALE = 0.25;

/** Pointer movement, in normalised units, that is worth a redraw when frozen. */
const POINTER_EPSILON = 0.0002;

interface Uniforms {
  [name: string]: THREE.IUniform;
  uResolution: THREE.IUniform<THREE.Vector2>;
  uScale: THREE.IUniform<number>;
  uTime: THREE.IUniform<number>;
  uPointer: THREE.IUniform<THREE.Vector2>;
  uGridSize: THREE.IUniform<number>;
  uMajorEvery: THREE.IUniform<number>;
  uLineWidth: THREE.IUniform<number>;
  uGlowRadius: THREE.IUniform<number>;
  uBaseColor: THREE.IUniform<THREE.Color>;
  uFogColor: THREE.IUniform<THREE.Color>;
  uLineColor: THREE.IUniform<THREE.Color>;
  uGlowColor: THREE.IUniform<THREE.Color>;
}

interface Stage {
  resize(width: number, height: number): void;
  draw(time: number, pointerX: number, pointerY: number): void;
}

// #region critical
export function FractionalRenderScale({
  renderScale = 0.6,
  maxDpr = 2,
  gridSize = 44,
  majorEvery = 5,
  lineWidth = 1,
  glowRadius = 240,
  baseColor = '#080b12',
  fogColor = '#1d3350',
  lineColor = '#8fb6df',
  glowColor = '#3f7fd0',
  className,
}: FractionalRenderScaleProps) {
  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 pointer = useSmoothPointer({ target: host, smoothing: POINTER_SMOOTHING });

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

  /* Read inside resize and draw. Keeping them out of the effect's dependency
     list means dragging a render-scale slider re-sizes the backing store
     rather than tearing down the GL context on every step. */
  const live = useRef({ renderScale, maxDpr, gridSize, majorEvery, lineWidth, glowRadius });
  live.current = { renderScale, maxDpr, gridSize, majorEvery, lineWidth, glowRadius };

  const lastPointer = useRef<{ x: number; y: number } | null>(null);

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

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

    const renderer = new THREE.WebGLRenderer({
      // Nothing in the field has a geometric edge, so MSAA has nothing to
      // sample — and at a fractional scale it would be antialiasing the wrong
      // grid anyway.
      antialias: false,
      // Opaque: the shader covers every pixel, and an alpha channel would make
      // the compositor blend the canvas over the page for no reason.
      alpha: false,
      depth: false,
      stencil: false,
      // The entire point of the component. On a laptop with switchable
      // graphics this keeps a decorative background off the discrete GPU.
      powerPreference: 'low-power',
    });
    renderer.setClearColor(0x000000, 1);
    renderer.domElement.style.display = 'block';
    // CSS size is 1x and fixed to the box; the backing store is set separately
    // by setSize(..., false). The gap between the two IS the render scale.
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.Camera();

    // One oversized triangle, not a quad. It covers the viewport with three
    // vertices and no diagonal seam for the GPU to shade twice.
    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute(
      'position',
      new THREE.BufferAttribute(new Float32Array([-1, -1, 0, 3, -1, 0, -1, 3, 0]), 3),
    );

    const uniforms: Uniforms = {
      uResolution: { value: new THREE.Vector2(1, 1) },
      uScale: { value: 1 },
      uTime: { value: 0 },
      uPointer: { value: new THREE.Vector2(0.5, 0.5) },
      uGridSize: { value: gridSize },
      uMajorEvery: { value: majorEvery },
      uLineWidth: { value: lineWidth },
      uGlowRadius: { value: glowRadius },
      uBaseColor: { value: new THREE.Color(baseColor) },
      uFogColor: { value: new THREE.Color(fogColor) },
      uLineColor: { value: new THREE.Color(lineColor) },
      uGlowColor: { value: new THREE.Color(glowColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: FRACTIONAL_SCALE_VERT,
      fragmentShader: FRACTIONAL_SCALE_FRAG,
      uniforms,
      depthTest: false,
      depthWrite: false,
    });

    const mesh = new THREE.Mesh(geometry, material);
    // The triangle's vertices sit outside a unit bounding sphere, and there is
    // no camera transform to cull against in the first place.
    mesh.frustumCulled = false;
    scene.add(mesh);

    const buffer = new THREE.Vector2();

    stage.current = {
      resize(w, h) {
        const state = live.current;
        const scale = clamp(state.renderScale, MIN_SCALE, 1);
        // Scale folded into the pixel ratio: three then multiplies it through
        // setSize for the backing store while the CSS size stays whatever the
        // stylesheet says. One number, no second sizing path to keep in sync.
        renderer.setPixelRatio(pixelRatio(state.maxDpr) * scale);
        renderer.setSize(w, h, false);

        renderer.getDrawingBufferSize(buffer);
        const bw = Math.max(1, Math.round(buffer.x));
        const bh = Math.max(1, Math.round(buffer.y));
        uniforms.uResolution.value.set(bw, bh);
        // Measured, not assumed. setSize floors, so the achieved ratio differs
        // from dpr * scale by up to a pixel — and the grid is authored in CSS
        // pixels, which would then drift against the layout.
        uniforms.uScale.value = w > 0 ? bw / w : 1;

        uniforms.uGridSize.value = Math.max(4, state.gridSize);
        uniforms.uMajorEvery.value = Math.max(1, Math.round(state.majorEvery));
        uniforms.uLineWidth.value = Math.max(0.5, state.lineWidth);
        uniforms.uGlowRadius.value = Math.max(1, state.glowRadius);
      },

      draw(time, pointerX, pointerY) {
        uniforms.uTime.value = time;
        uniforms.uPointer.value.set(pointerX, pointerY);
        renderer.render(scene, camera);
      },
    };

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

    return () => {
      stage.current = null;
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, baseColor, fogColor, lineColor, glowColor]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    current.resize(width, height);
    // Resizing a canvas clears its drawing buffer. When time is frozen the
    // loop skips every frame in which the pointer has not moved, so the
    // redraw has to happen here or the field stays blank until it does. When
    // time is running the next frame covers it a few milliseconds later.
    if (reduced) {
      const state = pointer.current;
      current.draw(0, state.nx, 1 - state.ny);
      lastPointer.current = { x: state.nx, y: 1 - state.ny };
    }
  }, [
    width,
    height,
    reduced,
    renderScale,
    maxDpr,
    gridSize,
    majorEvery,
    lineWidth,
    glowRadius,
    pointer,
  ]);

  useRaf(
    (_dt, elapsed) => {
      const current = stage.current;
      if (!current) return;

      const state = pointer.current;
      const px = state.nx;
      // GL's y axis points up; the pointer's does not.
      const py = 1 - state.ny;

      // Reduced motion freezes time at 0 rather than stopping the render, so
      // the fog, the vignette and the cursor glow all survive — only the drift
      // is gone. With time constant the image is a pure function of the
      // pointer, so a frame where the pointer has not moved is skippable.
      if (reduced) {
        const last = lastPointer.current;
        if (
          last &&
          Math.abs(px - last.x) < POINTER_EPSILON &&
          Math.abs(py - last.y) < POINTER_EPSILON
        ) {
          return;
        }
      }

      lastPointer.current = { x: px, y: py };
      current.draw(reduced ? 0 : elapsed, px, py);
    },
    ready && inView && visible,
  );
  // #endregion critical

  return (
    <div className={cn('relative h-full w-full overflow-hidden', className)}>
      <div ref={host} className="absolute inset-0" />
      {!supported ? (
        <div
          className="absolute inset-0"
          style={{
            backgroundColor: baseColor,
            backgroundImage: `radial-gradient(70% 70% at 50% 45%, ${fogColor}, transparent 75%), repeating-linear-gradient(0deg, ${lineColor}22 0 1px, transparent 1px ${gridSize}px), repeating-linear-gradient(90deg, ${lineColor}22 0 1px, transparent 1px ${gridSize}px)`,
          }}
        />
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Fractional Render Scale — GLSL
   --------------------------------------------------------------------------
   A field that is deliberately rendered into a backing store smaller than the
   element it fills, and is written so the upscale cannot be seen.

   Two rules make that possible, and both live in this file:

     1. Nothing has a hard edge. The fog is smoothstepped into mush, so
        bilinear upsampling has nothing to blur that was not already blurred.
     2. The one thing that DOES have an edge — the grid — is measured in
        BACKING-STORE pixels, not in CSS pixels. A line specified as one
        backing pixel is 1/scale CSS pixels after the upscale: softer and
        wider as the scale drops, never thinner, so it can never fall through
        the sampling grid and break into dashes.

   Note the absence of fwidth(). The grid is axis-aligned in screen space, so
   the derivative of the cell coordinate is a constant this shader already
   knows — uScale * uGridSize backing pixels per cell. Computing it directly
   is exact, costs one multiply, and needs no derivatives extension.
   ========================================================================== */

/**
 * A single triangle covering the viewport, not a quad.
 *
 * Two triangles meet along the diagonal, and every quad-based fullscreen pass
 * pays for that seam: the GPU shades in 2x2 quads, so the pixels along the
 * diagonal are shaded by both triangles. One oversized triangle is three
 * vertices, no seam, and a marginally better cache pattern.
 */
export const FRACTIONAL_SCALE_VERT = /* glsl */ `
void main() {
  gl_Position = vec4(position.xy, 0.0, 1.0);
}
`;

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

uniform vec2  uResolution;
uniform float uScale;
uniform float uTime;
uniform vec2  uPointer;
uniform float uGridSize;
uniform float uMajorEvery;
uniform float uLineWidth;
uniform float uGlowRadius;
uniform vec3  uBaseColor;
uniform vec3  uFogColor;
uniform vec3  uLineColor;
uniform vec3  uGlowColor;

/* Distance to the nearest cell boundary, in BACKING-STORE pixels. cell is the
   coordinate in cell units; pxPerCell converts back. The 0.5 offsets put the
   boundary at integer cell values. */
float gridBand(vec2 cell, float pxPerCell, float width) {
  vec2 d = abs(fract(cell - 0.5) - 0.5) * pxPerCell;
  float nearest = min(d.x, d.y);
  /* A one-pixel ramp centred on the requested width. Because the units are
     backing pixels, this ramp is always exactly one texel wide whatever the
     render scale — which is the whole trick. */
  return 1.0 - smoothstep(width - 0.5, width + 0.5, nearest);
}

void main() {
  vec2 frag = gl_FragCoord.xy;
  vec2 uv   = frag / uResolution;
  /* CSS pixels, y up. Everything a designer would specify in px is measured
     here, so the layout does not change when uScale does. */
  vec2 css  = frag / uScale;

  float aspect = uResolution.x / uResolution.y;
  vec2  p = uv * vec2(aspect, 1.0);

  /* Three sines and a hard smoothstep. This is not trying to be fbm — it is
     trying to have no detail smaller than a dozen pixels, which is what makes
     rendering it at 0.6 and letting the browser stretch it undetectable. */
  float fog = 0.5 + 0.5 * sin(p.x * 2.3 + uTime * 0.21);
  fog *= 0.5 + 0.5 * sin(p.y * 3.1 - uTime * 0.17 + 1.7);
  fog += 0.35 * sin((p.x + p.y) * 1.7 + uTime * 0.11);
  fog = smoothstep(-0.15, 1.15, fog);

  vec3 color = mix(uBaseColor, uFogColor, fog * 0.85);

  /* Pointer arrives 0..1 with y already flipped to GL's up. Converting it to
     CSS pixels means the glow radius is a real px value and does not stretch
     with the aspect ratio of the box. */
  vec2  pointerCss = uPointer * (uResolution / uScale);
  float d = length(css - pointerCss) / max(uGlowRadius, 1.0);
  float glow = exp(-d * d * 2.2);

  float pxPerCell = uScale * uGridSize;
  float minor = gridBand(css / uGridSize, pxPerCell, uLineWidth);
  float major = gridBand(css / (uGridSize * uMajorEvery), pxPerCell * uMajorEvery, uLineWidth * 1.6);

  /* The grid is mostly latent and the cursor develops it. A grid at full
     strength everywhere is a background; a grid that appears under the pointer
     is the surface reacting to being touched. */
  float lines = max(minor * 0.34, major * 0.7) * (0.18 + 0.82 * glow);

  color = mix(color, uLineColor, lines);
  color += uGlowColor * glow * 0.36;

  /* Square-space vignette, so it stays circular in a wide box. */
  vec2 v = (uv - vec2(0.5)) * vec2(aspect, 1.0);
  color *= 1.0 - 0.55 * smoothstep(0.28, 1.0, length(v));

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

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

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

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

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

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

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

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

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

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

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

'use client';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  return state;
}

'use client';

import { useEffect, useRef } from 'react';

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

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

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

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

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

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

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

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

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

'use client';

import { useSyncExternalStore } from 'react';

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

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

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

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

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

function getServerSnapshot() {
  return false;
}

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

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

'use client';

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

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

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

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

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

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

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

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

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

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

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

  return size;
}

'use client';

import { useEffect, useRef, type RefObject } from 'react';
import { useRaf } from '@/hooks/use-raf';
import { damp } from '@/lib/damp';

/* ==========================================================================
   Pointer position, smoothed, in several coordinate spaces at once.
   --------------------------------------------------------------------------
   Almost every cursor effect wants the same four things and computes them
   slightly differently each time: client pixels, element-local pixels, 0..1
   normalised, and -1..1 NDC for shaders. Producing all four from one damped
   source keeps a cursor dot and the shader it drives exactly in step.

   Exposed via ref for the same reason as scroll velocity: per-frame values
   must not re-render.
   ========================================================================== */

export interface PointerState {
  /** Viewport pixels. */
  clientX: number;
  clientY: number;
  /** Pixels relative to the target element's top-left. */
  x: number;
  y: number;
  /** 0..1 across the element. */
  nx: number;
  ny: number;
  /** -1..1, y up. Feed straight into a shader uniform. */
  ndcX: number;
  ndcY: number;
  /** Whether the pointer has been seen. Nothing should render before. */
  active: boolean;
}

export interface UseSmoothPointerOptions {
  /** Fraction of the gap remaining after one second. Lower = tighter. */
  smoothing?: number;
  /** Listen on this element rather than the window. */
  target?: RefObject<HTMLElement | null>;
  /** Follow touch drags as well as mouse moves. */
  touch?: boolean;
}

function makeInitialState(): PointerState {
  return {
    clientX: 0,
    clientY: 0,
    x: 0,
    y: 0,
    nx: 0.5,
    ny: 0.5,
    ndcX: 0,
    ndcY: 0,
    active: false,
  };
}

export function useSmoothPointer(
  options: UseSmoothPointerOptions = {},
): { current: PointerState } {
  const { smoothing = 0.001, target, touch = true } = options;

  const state = useRef<PointerState>(makeInitialState());
  // `null` means "no real pointer yet", which is distinct from a legitimate
  // pointer at (0, 0) in the top-left corner.
  const targetPos = useRef<{ clientX: number; clientY: number } | null>(null);
  const seeded = useRef(false);

  // Options the listener needs but that must not re-subscribe it on change.
  const touchRef = useRef(touch);
  touchRef.current = touch;

  useEffect(() => {
    const el = target?.current ?? null;
    const node: HTMLElement | Window = el ?? window;

    const onMove = (event: Event) => {
      const e = event as PointerEvent;
      if (!touchRef.current && e.pointerType === 'touch') return;
      targetPos.current = { clientX: e.clientX, clientY: e.clientY };
    };

    node.addEventListener('pointermove', onMove, { passive: true });
    return () => node.removeEventListener('pointermove', onMove);
    // `target` is a ref object; its identity is stable for the component's
    // lifetime, so this subscribes once.
  }, [target]);

  useRaf((dt) => {
    const el = target?.current ?? null;
    const rect = el
      ? el.getBoundingClientRect()
      : {
          left: 0,
          top: 0,
          width: window.innerWidth,
          height: window.innerHeight,
        };

    const pointer = targetPos.current;

    if (pointer === null) {
      // Park at the centre until a real pointer arrives, so the first move
      // eases out from the middle rather than snapping in from (0, 0). Done
      // once — re-centring every frame would fight a slow first movement.
      if (!seeded.current && rect.width > 0 && rect.height > 0) {
        seeded.current = true;
        const cx = rect.left + rect.width / 2;
        const cy = rect.top + rect.height / 2;
        state.current = {
          ...state.current,
          clientX: cx,
          clientY: cy,
          x: cx - rect.left,
          y: cy - rect.top,
        };
      }
      return;
    }

    const clientX = damp(state.current.clientX, pointer.clientX, smoothing, dt);
    const clientY = damp(state.current.clientY, pointer.clientY, smoothing, dt);

    const x = clientX - rect.left;
    const y = clientY - rect.top;
    const nx = rect.width > 0 ? x / rect.width : 0.5;
    const ny = rect.height > 0 ? y / rect.height : 0.5;

    state.current = {
      clientX,
      clientY,
      x,
      y,
      nx,
      ny,
      ndcX: nx * 2 - 1,
      ndcY: -(ny * 2 - 1),
      active: true,
    };
  });

  return state;
}

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