In-Shader Mouse Bulge

'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 { damp } from '@/lib/damp';
import {
  disposeObject,
  disposeRenderer,
  hasWebGL,
  pixelRatio,
} from '@/lib/webgl';
import {
  ndcMouseBulgeFragmentShader,
  ndcMouseBulgeVertexShader,
} from '@/components/motion/shaders/ndc-mouse-bulge';

/* ==========================================================================
   In-Shader Mouse Bulge
   --------------------------------------------------------------------------
   A soft lens that follows the cursor across a textured plane, with no
   raycaster, no picking buffer and no CPU geometry work at all.

   The pointer arrives in normalised device coordinates and stays there. Each
   vertex projects itself once to find out where it is on screen, compares
   that against the pointer, and displaces itself by the result.
   ========================================================================== */

export interface NdcMouseBulgeProps {
  /** Peak displacement weight. 0 disables the effect. */
  strength?: number;
  /** Gaussian tightness. Higher is a smaller, sharper lens. */
  falloff?: number;
  /** World units the crown of the bulge rises toward the camera. */
  lift?: number;
  /** How far the lens magnifies at the crown, in UV units. */
  magnify?: number;
  /** Extra brightness at the crown. */
  sheen?: number;
  /** Plane subdivisions per axis. The bulge is per-vertex, so this is its resolution. */
  segments?: number;
  /** Draw the surface. Default paints a ruled hue field. */
  paint?: (
    ctx: CanvasRenderingContext2D,
    size: { width: number; height: number },
  ) => void;
  className?: string;
}

const CAMERA_FOV = 45;
const CAMERA_Z = 3;
const TEXTURE_SIZE = 1024;
const STRENGTH_SMOOTHING = 0.0008;

interface BulgeUniforms {
  [name: string]: THREE.IUniform;
  uTexture: THREE.IUniform<THREE.Texture | null>;
  uMouseNdc: THREE.IUniform<THREE.Vector2>;
  uAspect: THREE.IUniform<number>;
  uStrength: THREE.IUniform<number>;
  uFalloff: THREE.IUniform<number>;
  uLift: THREE.IUniform<number>;
  uMagnify: THREE.IUniform<number>;
  uSheen: THREE.IUniform<number>;
}

interface Stage {
  renderer: THREE.WebGLRenderer;
  scene: THREE.Scene;
  camera: THREE.PerspectiveCamera;
  mesh: THREE.Mesh;
  geometry: THREE.PlaneGeometry;
  material: THREE.ShaderMaterial;
  texture: THREE.CanvasTexture;
  uniforms: BulgeUniforms;
}

function paintSurface(
  ctx: CanvasRenderingContext2D,
  size: { width: number; height: number },
): void {
  const { width, height } = size;

  const ramp = ctx.createLinearGradient(0, 0, width, height);
  ramp.addColorStop(0, 'hsl(248, 46%, 15%)');
  ramp.addColorStop(0.55, 'hsl(212, 52%, 38%)');
  ramp.addColorStop(1, 'hsl(166, 56%, 60%)');
  ctx.fillStyle = ramp;
  ctx.fillRect(0, 0, width, height);

  // A regular lattice. The lens is measured by how the cells swell as it
  // passes; on a plain gradient there is nothing to swell.
  const cell = width / 22;
  ctx.strokeStyle = 'rgba(255, 255, 255, 0.2)';
  ctx.lineWidth = Math.max(1, width / 900);
  for (let x = cell; x < width; x += cell) {
    ctx.beginPath();
    ctx.moveTo(x, 0);
    ctx.lineTo(x, height);
    ctx.stroke();
  }
  for (let y = cell; y < height; y += cell) {
    ctx.beginPath();
    ctx.moveTo(0, y);
    ctx.lineTo(width, y);
    ctx.stroke();
  }

  ctx.fillStyle = 'rgba(255, 255, 255, 0.9)';
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';
  ctx.font = `600 ${Math.round(height * 0.085)}px ui-sans-serif, system-ui, sans-serif`;
  ctx.fillText('UNDER GLASS', width / 2, height / 2);
}

// #region critical
export function NdcMouseBulge({
  strength = 1,
  falloff = 5,
  lift = 0.5,
  magnify = 0.12,
  sheen = 0.18,
  segments = 128,
  paint,
  className,
}: NdcMouseBulgeProps) {
  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();
  // Already in NDC, which is exactly the space the shader compares in — no
  // conversion, no cached bounding rect to go stale on scroll.
  const pointer = useSmoothPointer({ target: host, smoothing: 0.0008 });

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

  const engaged = useRef(0);

  const live = useRef({ strength, falloff, lift, magnify, sheen });
  live.current = { strength, falloff, lift, magnify, sheen };

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

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

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(pixelRatio());
    renderer.setSize(el.clientWidth, el.clientHeight, false);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';
    el.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(CAMERA_FOV, 1, 0.1, 100);
    camera.position.z = CAMERA_Z;

    const canvas = document.createElement('canvas');
    canvas.width = TEXTURE_SIZE;
    canvas.height = TEXTURE_SIZE;
    const ctx = canvas.getContext('2d');
    if (ctx) (paint ?? paintSurface)(ctx, { width: TEXTURE_SIZE, height: TEXTURE_SIZE });

    const texture = new THREE.CanvasTexture(canvas);
    texture.colorSpace = THREE.SRGBColorSpace;
    texture.wrapS = THREE.ClampToEdgeWrapping;
    texture.wrapT = THREE.ClampToEdgeWrapping;
    texture.anisotropy = Math.min(4, renderer.capabilities.getMaxAnisotropy());

    const uniforms: BulgeUniforms = {
      uTexture: { value: texture },
      uMouseNdc: { value: new THREE.Vector2(0, 0) },
      uAspect: { value: 1 },
      uStrength: { value: 0 },
      uFalloff: { value: falloff },
      uLift: { value: lift },
      uMagnify: { value: magnify },
      uSheen: { value: sheen },
    };

    // Dense. The bulge is evaluated per vertex, so the lens can only be as
    // round as the mesh is fine: at 16 segments the Gaussian resolves into a
    // faceted pyramid that follows the cursor.
    const geometry = new THREE.PlaneGeometry(1, 1, segments, segments);
    const material = new THREE.ShaderMaterial({
      vertexShader: ndcMouseBulgeVertexShader,
      fragmentShader: ndcMouseBulgeFragmentShader,
      uniforms,
    });
    const mesh = new THREE.Mesh(geometry, material);
    // The lift happens after the bounding sphere was computed; leaving culling
    // on lets three blank a plane that is filling the viewport.
    mesh.frustumCulled = false;
    scene.add(mesh);

    stage.current = { renderer, scene, camera, mesh, geometry, material, texture, uniforms };

    return () => {
      stage.current = null;
      scene.remove(mesh);
      // Inside `uniforms`, where `disposeObject` cannot see it.
      texture.dispose();
      disposeObject(scene);
      geometry.dispose();
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [ready, segments, paint]);

  useEffect(() => {
    const current = stage.current;
    if (!current || width < 1 || height < 1) return;
    const aspect = width / height;
    current.renderer.setPixelRatio(pixelRatio());
    current.renderer.setSize(width, height, false);
    current.camera.aspect = aspect;
    current.camera.updateProjectionMatrix();

    // Cover the frustum exactly at z = 0. Derived from the camera, because the
    // visible extent at this distance has no fixed relationship to the pixel
    // width of the container.
    const visibleHeight = 2 * Math.tan((CAMERA_FOV * Math.PI) / 360) * CAMERA_Z;
    current.mesh.scale.set(visibleHeight * aspect, visibleHeight, 1);
    // The shader corrects its screen-space distance with this, so a stale
    // value turns the lens into an ellipse the moment the container reshapes.
    current.uniforms.uAspect.value = aspect;
  }, [width, height]);

  useRaf(
    (dt) => {
      const current = stage.current;
      if (!current) return;
      const { strength: peak, falloff: tightness, lift: rise, magnify: zoom, sheen: light } =
        live.current;

      // Fade the whole effect in and out with the pointer rather than snapping
      // it. Snapping leaves a lens sitting at the last known position for one
      // frame after the cursor leaves, which flickers.
      const wanted = pointer.current.active && !reduced ? peak : 0;
      engaged.current = damp(engaged.current, wanted, STRENGTH_SMOOTHING, dt);

      current.uniforms.uMouseNdc.value.set(pointer.current.ndcX, pointer.current.ndcY);
      current.uniforms.uStrength.value = engaged.current;
      current.uniforms.uFalloff.value = tightness;
      current.uniforms.uLift.value = rise;
      current.uniforms.uMagnify.value = zoom;
      current.uniforms.uSheen.value = light;

      current.renderer.render(current.scene, current.camera);
    },
    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={{
            background:
              'linear-gradient(135deg, hsl(248 46% 15%), hsl(212 52% 38%), hsl(166 56% 60%))',
          }}
        />
      ) : null}
    </div>
  );
}

/* ==========================================================================
   In-Shader Mouse Bulge — GLSL as TypeScript template literals.
   --------------------------------------------------------------------------
   The pointer is a screen-space thing and the mesh is a world-space thing, so
   somebody has to convert. The usual answer is a raycast on the CPU, which
   gives you one hit point and costs a matrix inversion per frame.

   This does the opposite and cheaper thing: it projects each VERTEX into
   screen space and compares it against the pointer there. Every vertex gets
   its own distance, so the falloff is exact even on a surface the CPU thinks
   is flat, and the only cost is one extra matrix multiply per vertex.
   ========================================================================== */

export const ndcMouseBulgeVertexShader = /* glsl */ `
uniform vec2  uMouseNdc;
uniform float uAspect;
uniform float uStrength;
uniform float uFalloff;
uniform float uLift;

varying vec2  vUv;
varying float vBulge;

void main() {
  vec3 pos = position;

  // Projection one, the probe. This answers 'where does this vertex land on
  // screen right now', which is the only way to measure a screen-space
  // pointer against a mesh without leaving the GPU.
  vec4 probe = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
  vec2 ndc = probe.xy / probe.w;

  // NDC is -1..1 on both axes regardless of the viewport, so a raw distance
  // is stretched by the aspect ratio: on a 16:9 canvas an unweighted circle
  // is an ellipse 1.78 times too wide. Weighting x by the aspect makes the
  // falloff round on screen.
  vec2 delta = vec2((ndc.x - uMouseNdc.x) * uAspect, ndc.y - uMouseNdc.y);

  // Gaussian, not a linear or smoothstep falloff. It never reaches zero, so
  // there is no ring where the deformation visibly stops, and its own
  // derivative is smooth, so the highlight has no hard edge either.
  float bulge = exp(-dot(delta, delta) * uFalloff) * uStrength;

  pos.z += bulge * uLift;
  vBulge = bulge;

  vUv = uv;
  // Projection two, the one that actually ships the vertex, after the
  // displacement the first projection made possible.
  gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
}
`;

export const ndcMouseBulgeFragmentShader = /* glsl */ `
uniform sampler2D uTexture;
uniform float uMagnify;
uniform float uSheen;

varying vec2  vUv;
varying float vBulge;

void main() {
  // Push the centred UV outward by the same weight that lifted the vertex.
  // Displacement alone is a bump; displacement plus magnification is a lens,
  // and the difference is what makes it read as glass over the surface rather
  // than a dent in it.
  vec2 centered = vUv - 0.5;
  vec2 lensed = vUv + centered * vBulge * uMagnify;

  vec4 texel = texture2D(uTexture, clamp(lensed, 0.0, 1.0));

  // A little extra light at the crown of the bulge. Cheap, and it is what
  // sells the surface as curved rather than merely offset.
  gl_FragColor = vec4(texel.rgb * (1.0 + vBulge * uSheen), texel.a);

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

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

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

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

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

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

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

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

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

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

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

'use client';

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  return state;
}

'use client';

import { useEffect, useRef } from 'react';

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

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

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

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

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

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

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

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

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

'use client';

import { useSyncExternalStore } from 'react';

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

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

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

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

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

function getServerSnapshot() {
  return false;
}

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

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

'use client';

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

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

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

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

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

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

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

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

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

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

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

  return size;
}

'use client';

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