3D scenes: scroll-linked WebGL that stays fast

// src/components/scene-canvas.tsx
"use client";

import dynamic from "next/dynamic";

const SceneGL = dynamic(() => import("./scene-gl"), { ssr: false });

/** Fixed full-viewport 3D backdrop. Poster (CSS gradient here; swap for a
 *  server-rendered AVIF/SVG matching the shader's average color in production)
 *  is always painted first so LCP/content never depend on WebGL. */
export function SceneCanvas() {
  return (
    <div aria-hidden="true" className="pointer-events-none fixed inset-0 -z-10 isolate">
      <div
        className="absolute inset-0"
        style={{ background: "radial-gradient(60% 60% at 50% 40%, #23264a 0%, #0c0d14 55%, #08090c 100%)" }}
      />
      <SceneGL />
    </div>
  );
}
// Mount once, e.g. in the marketing route's layout — gate the import itself
// (not just ssr:false) behind requestIdleCallback/IntersectionObserver if the
// hero isn't the very first thing in the viewport.

// src/lib/scroll-progress.ts
export type ScrollState = { y: number };
const state: ScrollState = { y: 0 };
let listenerCount = 0;

function onScroll() { state.y = window.scrollY; }

export function subscribeScroll(): ScrollState {
  if (typeof window === "undefined") return state;
  if (listenerCount === 0) {
    state.y = window.scrollY;
    window.addEventListener("scroll", onScroll, { passive: true });
  }
  listenerCount++;
  return state;
}

export function unsubscribeScroll() {
  listenerCount = Math.max(0, listenerCount - 1);
  if (listenerCount === 0 && typeof window !== "undefined") window.removeEventListener("scroll", onScroll);
}

export function getScrollProgress(y: number): number {
  const max = document.documentElement.scrollHeight - window.innerHeight;
  return max <= 0 ? 0 : Math.min(1, Math.max(0, y / max));
}

// src/components/scene-gl.tsx
"use client";

import { useEffect, useRef, useState } from "react";
import { Camera, Color, Mesh, Program, Renderer, Torus, Transform } from "ogl";
import { getScrollProgress, subscribeScroll, unsubscribeScroll } from "@/lib/scroll-progress";

const TARGET_FPS = 45;                         // 30-60fps range per webgl-canvas.md
const FRAME_INTERVAL_MS = 1000 / TARGET_FPS;
const MAX_DPR = 1;                              // 1 for full-viewport backdrops; ≤1.5 for smaller hero stages
const DAMPING = 0.08;

const vertex = /* glsl */ `
  attribute vec3 position;
  attribute vec3 normal;
  uniform mat4 modelViewMatrix;
  uniform mat4 projectionMatrix;
  uniform mat3 normalMatrix;
  uniform float uTime;
  uniform float uProgress;
  varying vec3 vNormal;
  varying float vDisp;
  void main() {
    vec3 pos = position;
    float wave = sin(pos.x * 4.0 + uTime * 0.6) * cos(pos.y * 4.0 + uTime * 0.4 + uProgress * 6.28318);
    float disp = wave * (0.05 + uProgress * 0.05);
    pos += normal * disp;
    vDisp = disp;
    vNormal = normalize(normalMatrix * normal);
    gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
  }
`;

const fragment = /* glsl */ `
  precision highp float;
  uniform vec3 uColorA;
  uniform vec3 uColorB;
  uniform float uProgress;
  varying vec3 vNormal;
  varying float vDisp;
  void main() {
    vec3 light = normalize(vec3(0.4, 0.6, 0.8));
    float diff = max(dot(normalize(vNormal), light), 0.0);
    vec3 base = mix(uColorA, uColorB, uProgress);
    gl_FragColor = vec4(base * (0.35 + diff * 0.85) + vDisp * 1.6, 1.0);
  }
`;

export default function SceneGL() {
  const wrapperRef = useRef<HTMLDivElement | null>(null);
  const canvasRef = useRef<HTMLCanvasElement | null>(null);
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const wrapper = wrapperRef.current;
    const canvas = canvasRef.current;
    if (!wrapper || !canvas) return;

    const reducedMotionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
    const renderer = new Renderer({ canvas, dpr: Math.min(window.devicePixelRatio || 1, MAX_DPR), alpha: false, antialias: true, powerPreference: "low-power" });
    const gl = renderer.gl;
    gl.clearColor(0.03, 0.035, 0.047, 1);

    const camera = new Camera(gl, { fov: 35 });
    camera.position.set(0, 0, 6);
    const scene = new Transform();
    const geometry = new Torus(gl, { radius: 1.1, tube: 0.42, radialSegments: 48, tubularSegments: 96 });
    const program = new Program(gl, {
      vertex, fragment,
      uniforms: { uTime: { value: 0 }, uProgress: { value: 0 }, uColorA: { value: new Color("#7c9cff") }, uColorB: { value: new Color("#ff8fd6") } },
    });
    const mesh = new Mesh(gl, { geometry, program });
    mesh.setParent(scene);

    const resize = (w: number, h: number) => { renderer.setSize(w, h); camera.perspective({ aspect: w / h }); };
    resize(window.innerWidth, window.innerHeight);
    const resizeObserver = new ResizeObserver(([entry]) => {
      if (!entry) return;
      const { width, height } = entry.contentRect;
      if (width > 0 && height > 0) resize(width, height);
    });
    resizeObserver.observe(wrapper);                       // measured on resize only, never per-frame getBoundingClientRect

    const scrollState = subscribeScroll();
    let dampedProgress = getScrollProgress(scrollState.y);

    let isIntersecting = true;
    const io = new IntersectionObserver(([entry]) => { isIntersecting = entry?.isIntersecting ?? true; syncLoop(); }, { threshold: 0 });
    io.observe(wrapper);
    const onVisibility = () => syncLoop();
    document.addEventListener("visibilitychange", onVisibility);

    let rafId: number | null = null;
    let lastFrameTime = 0;

    function renderFrame(now: number) {
      const targetProgress = getScrollProgress(scrollState.y);
      dampedProgress += (targetProgress - dampedProgress) * DAMPING;   // damped, not scroll-jacked — native scroll untouched
      program.uniforms.uTime.value = now / 1000;                       // uniforms via refs, never rebuild the program
      program.uniforms.uProgress.value = dampedProgress;
      mesh.rotation.y = dampedProgress * Math.PI * 3 + now * 0.00008;
      mesh.rotation.x = dampedProgress * Math.PI * 0.6;
      mesh.position.y = (dampedProgress - 0.5) * 1.4;
      const scale = 0.85 + dampedProgress * 0.5;
      mesh.scale.set(scale, scale, scale);
      renderer.render({ scene, camera });
    }

    function loop(now: number) {
      rafId = requestAnimationFrame(loop);
      if (now - lastFrameTime < FRAME_INTERVAL_MS) return;             // fps cap
      lastFrameTime = now;
      renderFrame(now);
    }
    function startLoop() { if (rafId === null) rafId = requestAnimationFrame(loop); }
    function stopLoop() { if (rafId !== null) { cancelAnimationFrame(rafId); rafId = null; } }  // cancel, never "skip the draw"
    function syncLoop() {
      const shouldRun = isIntersecting && !document.hidden && !reducedMotionQuery.matches;
      shouldRun ? startLoop() : stopLoop();
    }
    const onReducedMotionChange = () => { if (reducedMotionQuery.matches) { stopLoop(); renderFrame(performance.now()); } else syncLoop(); };
    reducedMotionQuery.addEventListener("change", onReducedMotionChange);

    if (reducedMotionQuery.matches) { renderFrame(performance.now()); } else { renderFrame(performance.now()); syncLoop(); }  // one static frame under RM, then stop
    setReady(true);

    const onContextLost = (e: Event) => { e.preventDefault(); stopLoop(); };
    const onContextRestored = () => syncLoop();
    canvas.addEventListener("webglcontextlost", onContextLost, false);
    canvas.addEventListener("webglcontextrestored", onContextRestored, false);

    return () => {
      stopLoop();
      resizeObserver.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      reducedMotionQuery.removeEventListener("change", onReducedMotionChange);
      canvas.removeEventListener("webglcontextlost", onContextLost);
      canvas.removeEventListener("webglcontextrestored", onContextRestored);
      unsubscribeScroll();
      geometry.remove();
      program.remove();
      (renderer.getExtension("WEBGL_lose_context") as WEBGL_lose_context | null)?.loseContext();
    };
  }, []);

  return (
    <div ref={wrapperRef} className="absolute inset-0">
      <canvas ref={canvasRef} aria-hidden="true" className="pointer-events-none h-full w-full transition-opacity duration-500" style={{ opacity: ready ? 1 : 0 }} />
    </div>
  );
}

gltf-transform inspect model.glb                                        # geometry- vs texture-heavy?
gltf-transform meshopt model.glb model.opt.glb                          # geometry/morph/animation compression, lighter decoder than Draco
gltf-transform draco model.glb model.opt.glb                            # alternative: Draco geometry compression
gltf-transform quantize model.opt.glb model.opt.glb                     # quantize attribute precision
gltf-transform uastc model.opt.glb model.final.glb                      # textures → KTX2/Basis (uastc = quality, etc1s = smaller)
# or the one-shot bundle:
gltf-transform optimize model.glb model.final.glb --compress meshopt --texture-compress webp