Dot-Cloud Score Cylinder

'use client';

import { useEffect, useRef, useState } from 'react';
import * as THREE from 'three';
import { cn } from '@/lib/utils';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { createRng } from '@/lib/prng';
import { disposeObject, disposeRenderer, hasWebGL, pixelRatio } from '@/lib/webgl';
import {
  CYLINDER_DOT_SCORE_FRAG,
  CYLINDER_DOT_SCORE_VERT,
} from '@/components/motion/shaders/cylinder-dot-score';

/* ==========================================================================
   Dot-Cloud Score Cylinder
   --------------------------------------------------------------------------
   A musical score wrapped around a cylinder and rendered entirely as dots:
   measure rings, bar dividers, and note clusters that light up as a playhead
   sweeps them. Two cylinders are stacked, counter-rotated, and drawn from a
   single buffer.

   The interesting constraint is that there is no depth buffer. Every dot is
   flattened to z = 0 before projection; solidity comes from alpha and point
   size falling off with the model-space z, and the fact that notes are never
   occluded by measure dots comes from where they sit in the buffer. Draw
   order is the depth sort.
   ========================================================================== */

export interface CylinderDotScoreProps {
  /** Measure rings per cylinder, split evenly above and below the centre gap. */
  ringCount?: number;
  /** Dots in each measure ring. */
  ringDots?: number;
  /** Vertical bar dividers per cylinder. */
  dividerCount?: number;
  /** Dots making up each divider. */
  dividerDots?: number;
  /** Note groups per cylinder. The playhead cycles through them. */
  noteGroups?: number;
  /** Dots per note group. */
  noteDots?: number;
  /** Degrees of yaw per second. Linear, never eased. */
  spinSpeed?: number;
  /** Seconds each note group stays lit. */
  noteInterval?: number;
  /** Global dot size multiplier, in CSS pixels of radius. */
  dotScale?: number;
  /** Model-to-pixel scale as a fraction of the container short side. */
  viewScale?: number;
  opacity?: number;
  color?: string;
  noteColor?: string;
  seed?: number | string;
  className?: string;
}

interface Uniforms {
  /** three types `uniforms` as an open record; without this the object is not assignable. */
  [name: string]: THREE.IUniform;
  uSpin: { value: number };
  uElapsed: { value: number };
  uViewScale: { value: number };
  uViewportYOffset: { value: number };
  uPixelRatio: { value: number };
  uDotScale: { value: number };
  uOpacity: { value: number };
  uNoteInterval: { value: number };
  uGroupCount: { value: number };
  uColor: { value: THREE.Color };
  uNoteColor: { value: THREE.Color };
}

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

/** Cylinder radius in model units, before the shader's BASE_SCALE of 1.5. */
const RADIUS = 0.5;
/** Half-height of the empty band at the cylinder's equator. */
const GAP = 0.03;
/** Vertical spacing between measure rings. */
const RING_PITCH = 0.03;
/** Screen-space separation of the two cylinders. Mirrors STACK_OFFSET in GLSL. */
const STACK_OFFSET = 0.3;

const MEASURE_SCALE = 0.7;
const NOTE_SCALE = 1.4;

/** Frame drawn under reduced motion — a quarter turn in, playhead on group 0. */
const STATIC_ELAPSED = 0.4;

// #region critical
export function CylinderDotScore({
  ringCount = 10,
  ringDots = 260,
  dividerCount = 8,
  dividerDots = 34,
  noteGroups = 6,
  noteDots = 26,
  spinSpeed = 12,
  noteInterval = 1.2,
  dotScale = 1,
  viewScale = 0.62,
  opacity = 1,
  color = '#7d838c',
  noteColor = '#ffffff',
  seed = 'cylinder-dot-score',
  className,
}: CylinderDotScoreProps) {
  const host = useRef<HTMLDivElement>(null);
  const stage = useRef<Stage | null>(null);
  const [unsupported, setUnsupported] = useState(false);

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

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

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

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

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

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

    const rng = createRng(seed);

    /* ------------------------------------------------------------------
       Buffer layout IS the draw order. Points are blended in the order they
       appear, with depth testing off, so the six passes below are written
       consecutively into one pair of arrays: both cylinders' measures, then
       both cylinders' dividers, then both cylinders' notes. Notes last means
       notes on top, everywhere, without a sort and without a second object.
       ------------------------------------------------------------------ */
    const perCylinder = ringCount * ringDots + dividerCount * dividerDots + noteGroups * noteDots;
    const total = perCylinder * 2;

    const positions = new Float32Array(total * 3);
    const pointData = new Float32Array(total * 4);
    let cursor = 0;

    const write = (
      x: number,
      y: number,
      z: number,
      instance: number,
      isNote: number,
      scale: number,
      group: number,
    ) => {
      positions[cursor * 3] = x;
      positions[cursor * 3 + 1] = y;
      positions[cursor * 3 + 2] = z;
      pointData[cursor * 4] = instance;
      pointData[cursor * 4 + 1] = isNote;
      pointData[cursor * 4 + 2] = scale;
      pointData[cursor * 4 + 3] = group;
      cursor += 1;
    };

    /** y of measure ring `i`, mirrored around a gap at the equator. */
    const ringY = (i: number) => {
      const half = Math.floor(ringCount / 2);
      const step = i < half ? half - i : i - half + 1;
      return (i < half ? -1 : 1) * (GAP + step * RING_PITCH);
    };

    for (let instance = 0; instance < 2; instance += 1) {
      for (let ring = 0; ring < ringCount; ring += 1) {
        const y = ringY(ring);
        // Sorted angles, not raw ones. Points blend in buffer order, so an
        // unsorted ring interleaves near and far dots and the ring stipples
        // instead of reading as one continuous line of engraving.
        const angles = new Float32Array(ringDots);
        for (let i = 0; i < ringDots; i += 1) angles[i] = rng() * Math.PI * 2;
        angles.sort();
        for (let i = 0; i < ringDots; i += 1) {
          const a = angles[i] ?? 0;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 0, MEASURE_SCALE, 0);
        }
      }
    }

    const bandTop = GAP + Math.ceil(ringCount / 2) * RING_PITCH;
    for (let instance = 0; instance < 2; instance += 1) {
      for (let d = 0; d < dividerCount; d += 1) {
        const a = (d / dividerCount) * Math.PI * 2 + instance * 0.19;
        for (let i = 0; i < dividerDots; i += 1) {
          const t = dividerDots === 1 ? 0.5 : i / (dividerDots - 1);
          const y = -bandTop + t * bandTop * 2;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 0, MEASURE_SCALE, 0);
        }
      }
    }

    for (let instance = 0; instance < 2; instance += 1) {
      for (let g = 0; g < noteGroups; g += 1) {
        const centre = (g / noteGroups) * Math.PI * 2 + instance * 0.4;
        for (let i = 0; i < noteDots; i += 1) {
          const a = centre + (rng() - 0.5) * 0.22;
          const y = (rng() - 0.5) * 2 * bandTop;
          write(RADIUS * Math.cos(a), y, RADIUS * Math.sin(a), instance, 1, NOTE_SCALE, g);
        }
      }
    }

    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('aPointData', new THREE.BufferAttribute(pointData, 4));

    const uniforms: Uniforms = {
      uSpin: { value: 0 },
      uElapsed: { value: 0 },
      uViewScale: { value: 1 },
      uViewportYOffset: { value: 0 },
      uPixelRatio: { value: renderer.getPixelRatio() },
      uDotScale: { value: dotScale },
      uOpacity: { value: opacity },
      uNoteInterval: { value: noteInterval },
      uGroupCount: { value: noteGroups },
      uColor: { value: new THREE.Color(color) },
      uNoteColor: { value: new THREE.Color(noteColor) },
    };

    const material = new THREE.ShaderMaterial({
      vertexShader: CYLINDER_DOT_SCORE_VERT,
      fragmentShader: CYLINDER_DOT_SCORE_FRAG,
      uniforms,
      transparent: true,
      // Both off. With depth testing on, the first dot rasterised at a given
      // pixel would win and the far wall of the cylinder would punch holes in
      // the near one, because every dot is flattened to the same z.
      depthTest: false,
      depthWrite: false,
    });

    const points = new THREE.Points(geometry, material);
    points.frustumCulled = false;
    scene.add(points);

    el.appendChild(renderer.domElement);
    renderer.domElement.style.display = 'block';
    renderer.domElement.style.width = '100%';
    renderer.domElement.style.height = '100%';

    const resize = (w: number, h: number) => {
      renderer.setSize(w, h, false);
      camera.left = -w / 2;
      camera.right = w / 2;
      camera.top = h / 2;
      camera.bottom = -h / 2;
      camera.updateProjectionMatrix();
      const scale = Math.min(w, h) * viewScale;
      uniforms.uViewScale.value = scale;
      // The stack spans 0 .. STACK_OFFSET in y; pulling the whole thing down
      // by half of that puts the pair's centre on the container's centre.
      uniforms.uViewportYOffset.value = -STACK_OFFSET * 0.5 * scale;
      uniforms.uPixelRatio.value = renderer.getPixelRatio();
    };

    const draw = (elapsed: number) => {
      uniforms.uElapsed.value = elapsed;
      uniforms.uSpin.value = elapsed * spinSpeed;
      renderer.render(scene, camera);
    };

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

    return () => {
      stage.current = null;
      disposeObject(scene);
      material.dispose();
      disposeRenderer(renderer);
      renderer.domElement.remove();
    };
  }, [
    ready,
    ringCount,
    ringDots,
    dividerCount,
    dividerDots,
    noteGroups,
    noteDots,
    spinSpeed,
    noteInterval,
    dotScale,
    viewScale,
    opacity,
    color,
    noteColor,
    seed,
  ]);

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

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

  return (
    <div ref={host} className={cn('relative h-full w-full overflow-hidden', className)}>
      {unsupported ? (
        <div className="absolute inset-0 flex flex-col items-center justify-center gap-6">
          {[0, 1].map((i) => (
            <div key={i} className="flex h-10 w-[62%] flex-col justify-between">
              {Array.from({ length: 5 }, (_, k) => (
                <div key={k} className="h-px w-full bg-line-strong" style={{ opacity: 0.3 + k * 0.15 }} />
              ))}
            </div>
          ))}
        </div>
      ) : null}
    </div>
  );
}

/* ==========================================================================
   Dot-Cloud Score Cylinder — GLSL
   --------------------------------------------------------------------------
   Two cylinders' worth of dots — measure rings, bar dividers and notes — in
   one buffer, one material, one draw call. Which cylinder a dot belongs to and
   which group it is part of are packed into an attribute; the vertex shader
   applies a different transform stack per instance.

   There is no depth buffer anywhere in this file. Ordering comes from the
   order dots were written into the buffer, and the illusion of a solid
   cylinder comes entirely from alpha and point size falling off with z.
   ========================================================================== */

/**
 * `aPointData = vec4(instanceIndex, isNote, pointScale, groupIndex)`
 *
 *   instanceIndex  0 or 1 — which of the two stacked cylinders
 *   isNote         1 for a note dot, 0 for measure and divider dots
 *   pointScale     relative dot size; notes ship at 2x the measure scale
 *   groupIndex     which note group, for the playhead highlight
 */
export const CYLINDER_DOT_SCORE_VERT = /* glsl */ `
attribute vec4 aPointData;

uniform float uSpin;
uniform float uElapsed;
uniform float uViewScale;
uniform float uViewportYOffset;
uniform float uPixelRatio;
uniform float uDotScale;
uniform float uOpacity;
uniform float uNoteInterval;
uniform float uGroupCount;

varying float vAlpha;
varying float vAlphaScale;
varying float vNote;
varying float vActive;

const float DEG2RAD = 0.017453292519943295;

/* The whole cloud is modelled at unit-ish scale and blown up here rather than
   in the buffer, so changing the framing never re-uploads a vertex. */
const float BASE_SCALE = 1.5;

/* 8 degrees of X tilt. Below ~4 the cylinder collapses into a straight band
   and stops reading as a cylinder; past ~15 you are looking into the tube and
   the far wall crowds the near one. */
const float TILT = 8.0;

/* The second cylinder is mirrored in z and turned 166 degrees, so the two
   never present the same face at the same time. */
const float INSTANCE_B_YAW = -166.0;
const float INSTANCE_A_YAW = -90.0;

/* Vertical separation of the two cylinders, in model units, applied AFTER the
   rotation so it is a pure screen-space offset and the stack never tips. */
const float STACK_OFFSET = 0.3;

/* z range the depth cue is normalised over. The cloud's radius is 0.5 and
   BASE_SCALE is 1.5, so z spans +/-0.75; 0.6 slightly over-saturates the
   nearest and furthest dots, which is what stops the middle band looking flat. */
const float DEPTH_HALF_RANGE = 0.6;

const float DEPTH_MIN_SIZE = 0.65;
const float DEPTH_MAX_SIZE = 1.0;
const float NOTE_ACTIVE_SCALE = 2.0;

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

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

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

vec3 applyStack(vec3 p, float instanceIndex) {
  p *= BASE_SCALE;

  if (instanceIndex > 0.5) {
    p.z *= -1.0;
    p = rotateY(p, INSTANCE_B_YAW);
  } else {
    p = rotateY(p, INSTANCE_A_YAW);
  }

  // uSpin is in DEGREES and advances linearly. No easing anywhere: a constant
  // angular rate is what makes the object read as a machine rather than as an
  // animation that is about to arrive somewhere.
  p = rotateY(p, uSpin);
  p = rotateX(p, TILT);

  if (instanceIndex < 0.5) p.y += STACK_OFFSET;
  return p;
}

void main() {
  float instanceIndex = aPointData.x;
  float isNote        = aPointData.y;
  float pointScale    = aPointData.z;
  float noteGroup     = aPointData.w;

  vec3  transformed = applyStack(position, instanceIndex);

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

  // The playhead is derived from the same clock the rotation uses, so lighting
  // a note costs neither a React render nor a uniform write.
  float playhead   = mod(floor(uElapsed / uNoteInterval), uGroupCount);
  // Named isActive, not active: the latter is reserved for future use in
  // GLSL ES, and using it fails the whole vertex shader at compile time.
  float isActive   = isNote * step(abs(noteGroup - playhead), 0.5);
  float noteScale  = mix(1.0, NOTE_ACTIVE_SCALE, isActive);

  vNote   = isNote;
  vActive = isActive;
  // An active note ignores the depth fade: the playhead has to be legible on
  // the far wall of the cylinder as well as the near one.
  vAlpha  = mix(depthAlpha, 1.0, isActive) * uOpacity;

  gl_Position = projectionMatrix * modelViewMatrix * vec4(
    transformed.x * uViewScale,
    uViewportYOffset + transformed.y * uViewScale,
    0.0, 1.0
  );

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

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

uniform vec3 uColor;
uniform vec3 uNoteColor;

varying float vAlpha;
varying float vAlphaScale;
varying float vNote;
varying float vActive;

const float ALPHA_EPSILON = 0.003;

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

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

  vec3 tint = mix(uColor, uNoteColor, max(vNote * 0.6, vActive));
  gl_FragColor = vec4(tint, alpha);
}
`;

/* ==========================================================================
   Seeded randomness.
   --------------------------------------------------------------------------
   `Math.random()` in a particle field means the server and the client
   disagree, which React reports as a hydration mismatch, and it means the
   layout is different on every reload so a visual regression is invisible.
   Every component that scatters something uses a seeded generator instead.
   ========================================================================== */

export type Rng = () => number;

/**
 * mulberry32 — 32-bit, fast, and good enough for visual scatter. Returns a
 * function yielding floats in [0, 1).
 */
export function mulberry32(seed: number): Rng {
  let a = seed >>> 0;
  return function next() {
    a = (a + 0x6d2b79f5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

/** Turn any string into a 32-bit seed, so `seed="hero"` is reproducible. */
export function hashSeed(input: string): number {
  let h = 2166136261 >>> 0;
  for (let i = 0; i < input.length; i++) {
    h ^= input.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  return h >>> 0;
}

export function createRng(seed: number | string): Rng {
  return mulberry32(typeof seed === 'string' ? hashSeed(seed) : seed);
}

export function randRange(rng: Rng, min: number, max: number): number {
  return min + rng() * (max - min);
}

export function randInt(rng: Rng, min: number, maxExclusive: number): number {
  return Math.floor(randRange(rng, min, maxExclusive));
}

/**
 * Uniform point on a unit sphere. Naive angle-pairing clusters at the poles;
 * this inverts the cosine so density is even.
 */
export function randOnSphere(rng: Rng): [number, number, number] {
  const u = rng() * 2 - 1;
  const theta = rng() * Math.PI * 2;
  const r = Math.sqrt(1 - u * u);
  return [r * Math.cos(theta), r * Math.sin(theta), u];
}

/** Uniform point in a unit disc — `sqrt` prevents crowding at the centre. */
export function randInDisc(rng: Rng): [number, number] {
  const r = Math.sqrt(rng());
  const theta = rng() * Math.PI * 2;
  return [r * Math.cos(theta), r * Math.sin(theta)];
}

/** In-place Fisher-Yates using the supplied generator. */
export function shuffle<T>(rng: Rng, arr: T[]): T[] {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = randInt(rng, 0, i + 1);
    const a = arr[i] as T;
    const b = arr[j] as T;
    arr[i] = b;
    arr[j] = a;
  }
  return arr;
}

'use client';

import { useEffect, useRef } from 'react';

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

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

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

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

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

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

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

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

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

'use client';

import { useSyncExternalStore } from 'react';

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

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

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

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

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

function getServerSnapshot() {
  return false;
}

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

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

'use client';

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

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

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

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

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

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

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

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

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

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

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

  return size;
}

import type * as THREE from 'three';

/* ==========================================================================
   WebGL context lifecycle.
   --------------------------------------------------------------------------
   Chromium allows roughly 16 live WebGL contexts per RENDERER PROCESS (8 on
   low-end devices). Creating the 17th does not fail — it fires
   `webglcontextlost` on the OLDEST one, so an unrelated component elsewhere
   on the page goes black. Same-origin iframes share the renderer process, so
   isolating previews in iframes does not raise the ceiling.

   The only real fix is to release contexts on unmount, and `renderer.dispose()`
   ALONE DOES NOT DO THAT. It frees GPU objects but leaves the context itself
   alive until GC decides otherwise, which may be never. `forceContextLoss()`
   is the call that actually hands it back.
   ========================================================================== */

/**
 * Fully release a three.js renderer. Call this in the `useEffect` cleanup of
 * any component that constructs a `WebGLRenderer` — the preview host drives
 * unmount via `<Activity mode="hidden">`, so ordinary cleanup IS the disposal
 * path and nothing component-specific is required.
 */
export function disposeRenderer(renderer: THREE.WebGLRenderer | null | undefined): void {
  if (!renderer) return;

  // Stop the loop first: a queued frame that renders into a lost context
  // throws, and the throw escapes the cleanup function.
  renderer.setAnimationLoop(null);
  renderer.dispose();
  renderer.forceContextLoss();

  const canvas = renderer.domElement;
  if (canvas) {
    // Zeroing the backing store releases the drawing buffer immediately
    // instead of holding width×height×4 bytes until the node is collected.
    canvas.width = 0;
    canvas.height = 0;
  }
}

/**
 * Release a raw WebGL context (ogl, or hand-written GL). The extension is the
 * only portable way to do it; it is absent in some headless configurations,
 * hence the optional call.
 */
export function loseContext(gl: WebGLRenderingContext | WebGL2RenderingContext | null | undefined): void {
  if (!gl) return;
  gl.getExtension('WEBGL_lose_context')?.loseContext();
}

/** Recursively dispose geometries, materials and textures under a root. */
export function disposeObject(root: THREE.Object3D | null | undefined): void {
  if (!root) return;
  root.traverse((obj) => {
    const mesh = obj as THREE.Mesh;
    mesh.geometry?.dispose?.();
    const material = mesh.material;
    if (!material) return;
    const materials = Array.isArray(material) ? material : [material];
    for (const m of materials) {
      for (const value of Object.values(m as unknown as Record<string, unknown>)) {
        if (value && typeof value === 'object' && 'isTexture' in value) {
          (value as THREE.Texture).dispose();
        }
      }
      m.dispose?.();
    }
  });
}

/**
 * Device pixel ratio capped for fill-rate. Above 2 the visual gain is nil and
 * the cost is quadratic; on a 3x phone an uncapped full-screen shader is the
 * single most common cause of a janky first paint.
 */
export function pixelRatio(max = 2): number {
  if (typeof window === 'undefined') return 1;
  return Math.min(window.devicePixelRatio || 1, max);
}

/**
 * Whether WebGL is actually available. Some browsers expose the constructor
 * but fail to create a context (blocklisted GPU, no hardware acceleration);
 * a component that assumes success renders a permanently blank box.
 */
export function hasWebGL(): boolean {
  if (typeof document === 'undefined') return false;
  try {
    const canvas = document.createElement('canvas');
    const gl =
      canvas.getContext('webgl2') ??
      canvas.getContext('webgl') ??
      canvas.getContext('experimental-webgl');
    if (!gl) return false;
    (gl as WebGLRenderingContext).getExtension('WEBGL_lose_context')?.loseContext();
    return true;
  } catch {
    return false;
  }
}