Sequence Hero

/**
 * SequenceHero — a hero that flies through a volumetric cloud scene while three
 * chapters of copy cross-fade over it.
 *
 * One long section holds a sticky stage. Scrolling through the section is the
 * only input: it drives the camera through the scene's waypoints and, at the
 * same time, decides which chapter is showing. Nothing hijacks the scroll, so
 * the page behaves normally — a wheel gesture goes exactly as far as it should,
 * and the back button, the scrollbar and a keyboard PageDown all still work.
 *
 * The scene is WebGL2 and declines to run rather than degrade: reduced motion,
 * no WebGL2, or a first thirty frames too slow, and it hides itself. That is
 * why the stage carries its own gradient ground — when the canvas is absent the
 * hero is still a designed thing rather than a hole.
 *
 * Depends on `./lib/volsample`, its renderer, and on nothing else. Take both
 * files if you take this component.
 */
import { useEffect, useRef, useState } from "react";
import { initVolsample, type VolsampleHandle } from "./lib/volsample";

export interface SequenceChapter {
  heading: string;
  /** Rendered in the accent, inline within the heading where {accent} appears. */
  accent?: string;
  body: string;
}

export interface SequenceLink {
  label: string;
  href: string;
}

export interface SequenceHeroProps {
  heading?: string;
  /** Rendered in the accent at the end of the heading. */
  accent?: string;
  subhead?: string;
  /** The small paragraph along the bottom of the opening frame. */
  footnote?: string;
  links?: SequenceLink[];
  /** The chapters that cross-fade as the scene moves. Three is the design. */
  chapters?: SequenceChapter[];
  /**
   * How much scrolling the whole sequence takes, in viewport heights. Lower is
   * faster to get through; below about 3 the chapters start to feel rushed.
   */
  scrollLength?: number;
  tone?: "dark" | "light";
}

const DEFAULTS = {
  heading: "Digital systems for a",
  accent: "changing world",
  subhead:
    "We help teams rethink, rebuild and strengthen the technology layer behind their growth — and prepare it for what comes next.",
  footnote:
    "A technical practice for complex industries. We turn deep expertise into clear systems, and clear systems into work that reaches the people who need it.",
  links: [
    { label: "X", href: "#" },
    { label: "LinkedIn", href: "#" },
    { label: "Instagram", href: "#" },
  ] as SequenceLink[],
  chapters: [
    {
      heading: "The",
      accent: "problem",
      body: "Expectations keep rising — faster answers, clearer communication, smoother products. Most teams meet them on ageing platforms, manual processes and tooling that was never joined up, which makes the work harder to run and harder to grow.",
    },
    {
      heading: "New",
      accent: "opportunities",
      body: "What can be built, automated and improved has changed — support, workflows, products, content, the leverage in your own data. It only turns into value when it is attached to a real problem rather than added because it is available.",
    },
    {
      heading: "Where we",
      accent: "come in",
      body: "We look at the whole technology layer behind a business — experience, platforms, workflows, product systems, operations — and move it from disconnected legacy tooling to something coherent enough to build on.",
    },
  ] as SequenceChapter[],
  scrollLength: 4,
  tone: "dark" as const,
};

/**
 * The block's own styling, scoped to its data attribute.
 *
 * Every element that takes a face is named, including the spans inside the
 * headings: a rule that targets an element directly beats the family it would
 * otherwise inherit, so an accent word set inside a heading would quietly
 * render in the body face.
 */
const STYLES = `
[data-block="SequenceHero"],
[data-block="SequenceHero"] :is(p, a, span, li) {
  font-family: "Inter Variable", Inter, ui-sans-serif, system-ui, -apple-system, sans-serif;
}
[data-block="SequenceHero"] :is(h1, h2),
[data-block="SequenceHero"] :is(h1, h2) span {
  font-family: "Space Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif;
  font-weight: 500;
}
[data-block="SequenceHero"] {
  --seq-ink: #ffffff;
  --seq-body: rgba(255, 255, 255, 0.72);
  --seq-muted: rgba(255, 255, 255, 0.46);
  --seq-line: rgba(255, 255, 255, 0.16);
  --seq-ground: #121212;
  --seq-accent-a: #bce6f0;
  --seq-accent-b: #8b5cf6;
  --seq-ease: cubic-bezier(0.23, 1, 0.32, 1);
}
[data-block="SequenceHero"][data-tone="light"] {
  --seq-ink: #0a0a0a;
  --seq-body: rgba(0, 0, 0, 0.68);
  --seq-muted: rgba(0, 0, 0, 0.45);
  --seq-line: rgba(0, 0, 0, 0.14);
  --seq-ground: #e9eef2;
  --seq-accent-a: #2b6f86;
  --seq-accent-b: #6d4bd8;
}
/* The ground under the canvas. It is what you see when the scene has declined
   to run, so it is designed rather than flat. */
[data-block="SequenceHero"] .seq-stage {
  background:
    radial-gradient(120% 80% at 50% 0%, color-mix(in srgb, var(--seq-accent-b) 16%, transparent), transparent 70%),
    var(--seq-ground);
}
[data-block="SequenceHero"] .seq-canvas {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  display: block;
}
[data-block="SequenceHero"] .seq-accent {
  background: linear-gradient(100deg, var(--seq-accent-a), var(--seq-accent-b));
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}
/* Chapters occupy the same box and cross-fade; only the active one takes
   pointer events, so a link in a faded chapter is not a trap. */
[data-block="SequenceHero"] .seq-frame {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  opacity: 0;
  pointer-events: none;
  transform: translateY(1.25rem);
  transition: opacity 0.6s var(--seq-ease), transform 0.6s var(--seq-ease);
}
[data-block="SequenceHero"] .seq-frame[data-active="true"] {
  opacity: 1;
  pointer-events: auto;
  transform: none;
}
[data-block="SequenceHero"] .seq-rule {
  height: 1px;
  background: var(--seq-line);
}
[data-block="SequenceHero"] .seq-fill {
  height: 100%;
  background: linear-gradient(90deg, var(--seq-accent-a), var(--seq-accent-b));
  transition: width 0.4s var(--seq-ease);
}
[data-block="SequenceHero"] a:focus-visible {
  outline: 2px solid var(--seq-accent-a);
  outline-offset: 3px;
}
/* Without motion the sequence is not a sequence: the stage stops sticking and
   every chapter is simply shown, one after another, as text on a page. */
@media (prefers-reduced-motion: reduce) {
  [data-block="SequenceHero"] .seq-sticky {
    position: static;
    height: auto;
  }
  [data-block="SequenceHero"] .seq-track {
    height: auto !important;
  }
  [data-block="SequenceHero"] .seq-frames {
    position: static;
    display: grid;
    gap: 4rem;
    padding-block: 4rem;
  }
  [data-block="SequenceHero"] .seq-frame {
    position: static;
    opacity: 1;
    transform: none;
    pointer-events: auto;
  }
  [data-block="SequenceHero"] .seq-progress {
    display: none;
  }
}
`;

/** Split a heading so an accent phrase can be coloured inline. */
function Heading({ text, accent }: { text: string; accent?: string }) {
  if (!accent) return <>{text}</>;
  return (
    <>
      {text} <span className="seq-accent">{accent}</span>
    </>
  );
}

export function SequenceHero(props: SequenceHeroProps) {
  const p = { ...DEFAULTS, ...props };
  const chapters = p.chapters.length ? p.chapters : DEFAULTS.chapters;

  const trackRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  /** Read by the render loop every frame, so it must not go through state. */
  const progressRef = useRef(0);
  const [frame, setFrame] = useState(0);

  useEffect(() => {
    const track = trackRef.current;
    if (!track) return;

    /** 0 at the top of the track, 1 when its last viewport-height is reached. */
    function readProgress() {
      const rect = track!.getBoundingClientRect();
      const span = rect.height - window.innerHeight;
      if (span <= 0) return 0;
      return Math.max(0, Math.min(1, -rect.top / span));
    }

    let handle: VolsampleHandle | null = null;
    let raf = 0;
    let lastFrame = -1;

    function onScroll() {
      progressRef.current = readProgress();
      // Frame 0 is the opening; the chapters divide what is left, so the hero
      // holds while the camera starts moving rather than cutting immediately.
      const step = 1 / (chapters.length + 1);
      const next = Math.min(chapters.length, Math.floor(progressRef.current / step));
      if (next !== lastFrame) {
        lastFrame = next;
        setFrame(next);
      }
    }

    /**
     * A screenshot runner sets `window.__uiCapture` before the page loads. Under
     * software GL every frame is "too slow", so the scene's own performance gate
     * would tear it down and the still would photograph the fallback instead of
     * the work — and a WebGL canvas screenshots blank without a preserved
     * buffer. Both are capture concerns, and both stay off for real visitors.
     */
    const capturing = (window as unknown as { __uiCapture?: boolean }).__uiCapture === true;

    handle = initVolsample(canvasRef.current, {
      getProgress: () => progressRef.current,
      perfGate: !capturing,
      preserveDrawingBuffer: capturing,
    });

    onScroll();
    window.addEventListener("scroll", onScroll, { passive: true });
    window.addEventListener("resize", onScroll);
    return () => {
      window.removeEventListener("scroll", onScroll);
      window.removeEventListener("resize", onScroll);
      cancelAnimationFrame(raf);
      handle?.destroy();
    };
  }, [chapters.length]);

  const total = chapters.length;
  const current = Math.max(1, Math.min(total, frame));
  const pad = (n: number) => String(n).padStart(2, "0");

  return (
    <section data-block="SequenceHero" data-tone={p.tone} style={{ color: "var(--seq-body)" }}>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />

      <div ref={trackRef} className="seq-track relative" style={{ height: `${p.scrollLength * 100}vh` }}>
        <div className="seq-sticky sticky top-0 h-screen overflow-hidden">
          <div className="seq-stage absolute inset-0">
            <canvas ref={canvasRef} className="seq-canvas" aria-hidden="true" />
          </div>

          <div className="seq-frames absolute inset-0">
            {/* Frame 0 — the opening. */}
            <div className="seq-frame" data-active={frame === 0}>
              <div className="mx-auto flex h-full w-full max-w-[80rem] flex-col justify-between px-6 py-16 sm:py-20">
                <div className="flex flex-1 items-center">
                  <div className="max-w-3xl">
                    <h1
                      className="text-balance text-[clamp(2.75rem,7vw,5.5rem)] leading-[0.95] tracking-[-0.04em]"
                      style={{ color: "var(--seq-ink)" }}
                    >
                      <Heading text={p.heading} accent={p.accent} />
                    </h1>
                    {p.subhead && (
                      <p className="mt-7 max-w-xl text-[1.0625rem] font-light leading-relaxed">{p.subhead}</p>
                    )}
                  </div>
                </div>

                <div className="flex flex-wrap items-end justify-between gap-6">
                  {p.footnote && <p className="max-w-md text-sm font-light leading-relaxed">{p.footnote}</p>}
                  {p.links.length > 0 && (
                    <ul className="flex list-none gap-5 p-0">
                      {p.links.map((link) => (
                        <li key={link.label}>
                          <a
                            href={link.href}
                            className="text-xs uppercase tracking-[0.16em] no-underline transition-colors"
                            style={{ color: "var(--seq-muted)" }}
                          >
                            {link.label}
                          </a>
                        </li>
                      ))}
                    </ul>
                  )}
                </div>
              </div>
            </div>

            {/* Frames 1..n — the chapters. */}
            {chapters.map((chapter, index) => (
              <div key={chapter.heading + index} className="seq-frame" data-active={frame === index + 1}>
                <div className="mx-auto w-full max-w-[80rem] px-6">
                  <div className="max-w-3xl">
                    <h2
                      className="text-balance text-[clamp(2rem,5vw,3.75rem)] leading-[1.02] tracking-[-0.03em]"
                      style={{ color: "var(--seq-ink)" }}
                    >
                      <Heading text={chapter.heading} accent={chapter.accent} />
                    </h2>
                    <p className="mt-6 max-w-2xl text-[1.0625rem] font-light leading-relaxed">{chapter.body}</p>
                  </div>
                </div>
              </div>
            ))}
          </div>

          {/* The reader's place in the sequence. Decorative: the chapters are
              the content, and they are all in the document already. */}
          <div className="seq-progress absolute bottom-8 right-6 flex items-center gap-4" aria-hidden="true">
            <span className="text-xs tabular-nums tracking-[0.16em]" style={{ color: "var(--seq-muted)" }}>
              {pad(current)} <span style={{ opacity: 0.5 }}>/</span> {pad(total)}
            </span>
            <span className="seq-rule block w-24 overflow-hidden rounded-full">
              <span className="seq-fill block" style={{ width: `${(current / total) * 100}%` }} />
            </span>
          </div>
        </div>
      </div>
    </section>
  );
}

/* A named export as well as the default, so a project that takes this file can
   import it either way. */
export default SequenceHero;

/**
 * Volumetric cloud renderer — a raymarched WebGL2 scene the camera flies through.
 *
 * Ported from the "volsample" adaptive-sampling technique by **Huw Bowles and
 * Daniel Zimmermann (MIT, 2015)** — https://www.shadertoy.com/view/lss3zr — and
 * kept under that licence. The MIT notice travels with this file; leave it in
 * place if you take the component.
 *
 * No dependencies. Raw WebGL2 and one procedurally generated noise texture, so
 * the scene ships as source rather than as an asset.
 *
 * It declines to run rather than degrade badly:
 *   - `prefers-reduced-motion: reduce` → returns null, canvas hidden
 *   - no WebGL2 → returns null, canvas hidden
 *   - first 30 frames slower than 24ms → hides itself and tears down
 * A caller that gets null should show its static fallback and carry on.
 *
 * Progress (0..1) drives the camera through five waypoints — HERO, three
 * slides, then EXIT — with every numeric field of the scene interpolated
 * between them, so a scroll position becomes a camera move, a light move and a
 * colour grade at once.
 */

/** Every interpolatable field of the scene. Each is lerped between waypoints. */
export interface VolsampleState {
  posX: number; posY: number; posZ: number;
  lookX: number; lookY: number; lookZ: number;
  fovScale: number;
  windX: number; windY: number; windZ: number;
  densityBias: number;
  cloudTintR: number; cloudTintG: number; cloudTintB: number;
  lightForward: number; lightUp: number; lightLateral: number;
  lightR: number; lightG: number; lightB: number;
  lightIntensity: number;
  lightFalloff: number;
  ambientR: number; ambientG: number; ambientB: number;
  skyTopR: number; skyTopG: number; skyTopB: number;
  skyBotR: number; skyBotG: number; skyBotB: number;
  samplesCurvature: number;
}

export type WaypointName = "HERO" | "SLIDE_1" | "SLIDE_2" | "SLIDE_3" | "EXIT";

export interface VolsampleOptions {
  /** Returns 0..1 each frame. Without it the scene sits at the HERO waypoint. */
  getProgress?: () => number;
  /** Merged into the base state before the waypoints are built, so they inherit it. */
  baseOverrides?: Partial<VolsampleState>;
  /** Merged into the named waypoints after they are built. */
  waypointOverrides?: Partial<Record<WaypointName, Partial<VolsampleState>>>;
  /** Fraction of device pixels to render at. 0.5 is plenty for cloud. */
  renderScale?: number;
  /**
   * Tear the scene down when the first frames are too slow (default true).
   *
   * Turn it off only to capture a still: a screenshot runner on software GL is
   * always "too slow", and would photograph the fallback rather than the scene.
   */
  perfGate?: boolean;
  /**
   * Keep the drawing buffer after compositing (default false).
   *
   * Also a capture concern — a headless screenshot of a WebGL canvas is
   * routinely blank without it. It costs memory and bandwidth, so it stays off
   * for normal viewing.
   */
  preserveDrawingBuffer?: boolean;
}

export interface VolsampleHandle {
  destroy(): void;
  /** Force a fixed progress, or null to resume reading `getProgress`. */
  setProgressOverride(value: number | null): void;
}

const VS = `#version 300 es
void main() {
  vec2 p = vec2((gl_VertexID == 1) ? 3.0 : -1.0,
                (gl_VertexID == 2) ? 3.0 : -1.0);
  gl_Position = vec4(p, 0.0, 1.0);
}`;

const FS = `#version 300 es
precision highp float;
out vec4 fragColor;
uniform vec2  uRes;
uniform float uTime;
uniform sampler2D uNoise;
uniform vec3  uCameraPos;
uniform vec3  uLookDir;
uniform vec3  uLightPos;
uniform vec3  uLightColor;
uniform float uLightIntensity;
uniform float uLightFalloff;
uniform vec3  uWind;
uniform float uDensityBias;
uniform vec3  uCloudTint;
uniform float uSamplesCurvature;
uniform vec3  uSkyTop;
uniform vec3  uSkyBottom;
uniform vec3  uAmbientColor;
uniform float uFovScale;

#define SAMPLE_COUNT 32
#define DIST_MAX 128.
#define SAMPLES_ADAPTIVITY 0.2

float noise(vec3 x) {
  vec3 p = floor(x);
  vec3 f = fract(x);
  f = f*f*(3.0 - 2.0*f);
  vec2 uv = (p.xy + vec2(37.0, 17.0)*p.z) + f.xy;
  vec2 rg = textureLod(uNoise, (uv + 0.5)/256.0, 0.0).yx;
  return mix(rg.x, rg.y, f.z);
}

vec4 map(vec3 p) {
  // uWind carries a JS-integrated phase offset (a cumulative position), so a
  // change of wind speed alters the rate of drift without teleporting the field.
  vec3 q = p + uWind;
  float macro = noise(vec3(q.x*0.4, 0.0, q.z*0.4)) * 2.0 - 1.0;
  float d = 0.1 + .8 * macro - p.y + uDensityBias;
  float f;
  f  = 0.5000*noise(q); q = q*2.02;
  f += 0.2500*noise(q); q = q*2.03;
  f += 0.1250*noise(q); q = q*2.01;
  f += 0.0625*noise(q);
  d += 2.75 * f;
  d = clamp(d, 0.0, 1.0);
  vec4 res = vec4(d);
  vec3 col = 1.15 * uCloudTint;
  col += vec3(1., 0., 0.) * exp2(res.x*10. - 10.);
  res.xyz = mix(col, vec3(0.7, 0.7, 0.7), res.x);
  return res;
}

float spacing(float t) {
  t = max(t, 0.);
  float pdf = 1. / (SAMPLES_ADAPTIVITY*t + 1.);
  float norm = (1. / SAMPLES_ADAPTIVITY) * log(1. + SAMPLES_ADAPTIVITY*DIST_MAX);
  pdf /= norm;
  return 1. / (float(SAMPLE_COUNT) * pdf);
}

float mov_mod(float x, float y) {
  return mod(x + dot(uCameraPos, uLookDir), y);
}
bool on_boundary(float x, float y) {
  float fix = y*0.25;
  return mov_mod(x + fix, y) < y*0.5;
}

void firstT(out float t, out float dt, out float wt, out bool even) {
  dt = exp2(floor(log2(spacing(0.))));
  t = 0.;
  t = dt - mov_mod(t, dt);
  even = on_boundary(t, 2.*dt);
  wt = 1.;
}
void nextT(inout float t, inout float dt, inout float wt, inout bool even) {
  float s = spacing(t);
  if (s < dt) { dt /= 2.; even = true; }
  else if (even && s > 2.*dt) { dt *= 2.; wt = 1.; even = on_boundary(t, 2.*dt); }
  if (even) wt = clamp(2. - s/dt, 0., 1.);
  t += dt;
  even = !even;
}
float sampleWt(float wt, bool even) {
  return even ? (2. - wt) : wt;
}

vec4 raymarch(vec3 ro, vec3 rd) {
  vec4 sum = vec4(0.0);
  float t, dt, wt; bool even;
  firstT(t, dt, wt, even);
  for (int i = 0; i < SAMPLE_COUNT; i++) {
    if (sum.a > 0.99) { nextT(t, dt, wt, even); continue; }
    vec3 pos = ro + t*rd;
    vec4 col = map(pos);
    vec3 ld = uLightPos - pos;
    float lDist = length(ld);
    ld /= max(lDist, 0.0001);
    float atten = uLightIntensity / (1.0 + uLightFalloff*lDist + uLightFalloff*lDist*lDist*0.5);
    float dif = clamp((col.w - map(pos + 0.6*ld).w)/0.6, 0.0, 1.0);
    vec3 ambient = uAmbientColor;
    vec3 lin = ambient + uLightColor * dif * atten;
    col.xyz *= lin;
    col.xyz *= col.xyz;
    col.a *= 0.35;
    col.rgb *= col.a;
    float fadeout = 1. - clamp((t/(DIST_MAX*.3) - .85)/.15, 0., 1.);
    float thisDt = dt * sampleWt(wt, even);
    thisDt = sqrt(thisDt/5.) * 5.;
    sum += thisDt * col * (1.0 - sum.a) * fadeout;
    nextT(t, dt, wt, even);
  }
  sum.xyz /= (0.001 + sum.w);
  return clamp(sum, 0.0, 1.0);
}

vec3 sky(vec3 rd) {
  vec3 col = mix(uSkyBottom, uSkyTop, rd.y * 0.5 + 0.5);
  vec3 toLight = normalize(uLightPos - uCameraPos);
  float aim = clamp(dot(toLight, rd), 0.0, 1.0);
  col += uLightColor * 0.28 * pow(aim, 8.0);
  col += uLightColor * 0.10 * pow(aim, 64.0);
  return col;
}

void main() {
  vec2 q = gl_FragCoord.xy / uRes.xy;
  vec2 p = -1.0 + 2.0*q;
  p.x *= uRes.x / uRes.y;
  vec3 ro = uCameraPos;
  vec3 ta = ro + uLookDir;
  vec3 ww = normalize(ta - ro);
  vec3 uu = normalize(cross(vec3(0.0, 1.0, 0.0), ww));
  vec3 vv = normalize(cross(ww, uu));
  vec3 rd = normalize(p.x*uu + 1.2*p.y*vv + uFovScale*ww);
  vec3 col = sky(rd);
  vec3 rd_layout = rd / mix(dot(rd, ww), 1.0, uSamplesCurvature);
  vec4 clouds = raymarch(ro, rd_layout);
  col = mix(col, clouds.xyz, clouds.w);
  col = clamp(col, 0., 1.);
  col = smoothstep(0., 1., col);
  col *= pow(16.0*q.x*q.y*(1.0-q.x)*(1.0-q.y), 0.12);
  fragColor = vec4(col, 1.0);
}`;

/** The scene at rest. Waypoints are clones of this with the camera moved. */
const BASE_STATE: VolsampleState = {
  posX: 0.0, posY: 1.9, posZ: 0.0,
  lookX: -1.0, lookY: 0.0, lookZ: 0.0,
  fovScale: 1.14,
  windX: 0.0, windY: -0.61, windZ: -1.05,
  densityBias: 0.07,
  cloudTintR: 188 / 255, cloudTintG: 230 / 255, cloudTintB: 240 / 255,
  lightForward: 1.1, lightUp: 1.3, lightLateral: -1.2,
  lightR: 237 / 255, lightG: 237 / 255, lightB: 237 / 255,
  lightIntensity: 0.95,
  lightFalloff: 0.11,
  ambientR: 0.378, ambientG: 0.405, ambientB: 0.495,
  skyTopR: 18 / 255, skyTopG: 18 / 255, skyTopB: 18 / 255,
  skyBotR: 33 / 255, skyBotG: 33 / 255, skyBotB: 33 / 255,
  samplesCurvature: 0.0,
};

const WAYPOINT_ORDER: WaypointName[] = ["HERO", "SLIDE_1", "SLIDE_2", "SLIDE_3", "EXIT"];

const DPR_CAP = 1.5;
const PERF_FRAMES = 30;
const PERF_THRESHOLD_MS = 24;

type Vec3 = [number, number, number];

function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}
function smoothstep01(t: number): number {
  return t * t * (3 - 2 * t);
}
function norm3v(x: number, y: number, z: number): Vec3 {
  const m = Math.hypot(x, y, z) || 1;
  return [x / m, y / m, z / m];
}

function makeWaypoint(base: VolsampleState, pos: Vec3, look: Vec3): VolsampleState {
  return { ...base, posX: pos[0], posY: pos[1], posZ: pos[2], lookX: look[0], lookY: look[1], lookZ: look[2] };
}

function makeDefaultWaypoints(base: VolsampleState): Record<WaypointName, VolsampleState> {
  return {
    HERO: makeWaypoint(base, [0.0, 1.9, 0.0], [-1.0, 0.0, 0.0]),
    SLIDE_1: makeWaypoint(base, [-3.0, 2.4, 1.5], [-1.0, 0.18, 0.12]),
    SLIDE_2: makeWaypoint(base, [-6.0, 3.4, -1.0], [-1.0, -0.3, -0.1]),
    SLIDE_3: makeWaypoint(base, [-9.0, 1.8, 0.5], [-1.0, 0.02, -0.05]),
    EXIT: makeWaypoint(base, [-9.0, 1.8, 0.5], [-1.0, 0.02, -0.05]),
  };
}

/** Interpolate every field between the two waypoints the progress falls across. */
function stateAtProgress(waypoints: Record<WaypointName, VolsampleState>, s: number): VolsampleState {
  const segs = WAYPOINT_ORDER.length - 1;
  const x = Math.max(0, Math.min(1, s)) * segs;
  const i = Math.min(Math.floor(x), segs - 1);
  const f = smoothstep01(x - i);
  const a = waypoints[WAYPOINT_ORDER[i]];
  const b = waypoints[WAYPOINT_ORDER[i + 1]];
  const out = {} as VolsampleState;
  for (const key of Object.keys(a) as (keyof VolsampleState)[]) out[key] = lerp(a[key], b[key], f);
  return out;
}

/** Light sits relative to the camera: forward along the look, up, and lateral. */
function computeLightPos(state: VolsampleState): Vec3 {
  const look = norm3v(state.lookX, state.lookY, state.lookZ);
  const up: Vec3 = [0, 1, 0];
  const rx = up[1] * look[2] - up[2] * look[1];
  const ry = up[2] * look[0] - up[0] * look[2];
  const rz = up[0] * look[1] - up[1] * look[0];
  const rm = Math.hypot(rx, ry, rz) || 1;
  return [
    state.posX + look[0] * state.lightForward + up[0] * state.lightUp + (rx / rm) * state.lightLateral,
    state.posY + look[1] * state.lightForward + up[1] * state.lightUp + (ry / rm) * state.lightLateral,
    state.posZ + look[2] * state.lightForward + up[2] * state.lightUp + (rz / rm) * state.lightLateral,
  ];
}

/** Build the 256×256 noise the shader samples. Generated, so nothing is fetched. */
function createNoiseTexture(gl: WebGL2RenderingContext): WebGLTexture | null {
  const N = 256;
  const data = new Uint8Array(N * N * 4);
  let seed = 0x9e3779b9 | 0;
  const next = () => {
    seed ^= seed << 13;
    seed ^= seed >>> 17;
    seed ^= seed << 5;
    return (seed >>> 0) & 0xff;
  };
  for (let i = 0; i < N * N; i++) {
    data[i * 4] = next();
    data[i * 4 + 3] = 255;
  }
  // Second channel is the first, offset — the shader mixes the two to get a
  // cheap third dimension out of a 2D texture.
  for (let y = 0; y < N; y++) {
    for (let x = 0; x < N; x++) {
      const sx = (((x - 37) % N) + N) % N;
      const sy = (((y - 17) % N) + N) % N;
      data[(y * N + x) * 4 + 1] = data[(sy * N + sx) * 4];
    }
  }
  const tex = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, tex);
  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, N, N, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.REPEAT);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
  return tex;
}

/**
 * Start the scene on a canvas. Returns null when it has decided not to run —
 * reduced motion, no WebGL2, or a failed compile — having hidden the canvas.
 */
export function initVolsample(canvas: HTMLCanvasElement | null, options: VolsampleOptions = {}): VolsampleHandle | null {
  if (!canvas) return null;

  const reduced = typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  if (reduced) {
    canvas.style.display = "none";
    return null;
  }

  const gl = canvas.getContext("webgl2", {
    antialias: false,
    alpha: false,
    depth: false,
    stencil: false,
    powerPreference: "low-power",
    preserveDrawingBuffer: options.preserveDrawingBuffer ?? false,
  });
  if (!gl) {
    canvas.style.display = "none";
    return null;
  }

  const renderScale = options.renderScale ?? 0.5;
  const base: VolsampleState = { ...BASE_STATE, ...options.baseOverrides };
  const waypoints = makeDefaultWaypoints(base);
  for (const [name, overrides] of Object.entries(options.waypointOverrides ?? {})) {
    const target = waypoints[name as WaypointName];
    if (target && overrides) Object.assign(target, overrides);
  }

  const getProgress = options.getProgress ?? (() => 0);
  let progressOverride: number | null = null;

  const noiseTex = createNoiseTexture(gl);

  function compile(type: number, src: string): WebGLShader | null {
    const sh = gl!.createShader(type);
    if (!sh) return null;
    gl!.shaderSource(sh, src);
    gl!.compileShader(sh);
    if (!gl!.getShaderParameter(sh, gl!.COMPILE_STATUS)) {
      console.error("[volsample] shader error:", gl!.getShaderInfoLog(sh));
      return null;
    }
    return sh;
  }

  const vs = compile(gl.VERTEX_SHADER, VS);
  const fs = compile(gl.FRAGMENT_SHADER, FS);
  if (!vs || !fs) {
    canvas.style.display = "none";
    return null;
  }
  const prog = gl.createProgram();
  if (!prog) {
    canvas.style.display = "none";
    return null;
  }
  gl.attachShader(prog, vs);
  gl.attachShader(prog, fs);
  gl.linkProgram(prog);
  if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
    console.error("[volsample] link error:", gl.getProgramInfoLog(prog));
    canvas.style.display = "none";
    return null;
  }
  gl.useProgram(prog);

  const u = {
    res: gl.getUniformLocation(prog, "uRes"),
    time: gl.getUniformLocation(prog, "uTime"),
    noise: gl.getUniformLocation(prog, "uNoise"),
    cameraPos: gl.getUniformLocation(prog, "uCameraPos"),
    lookDir: gl.getUniformLocation(prog, "uLookDir"),
    lightPos: gl.getUniformLocation(prog, "uLightPos"),
    lightColor: gl.getUniformLocation(prog, "uLightColor"),
    lightIntensity: gl.getUniformLocation(prog, "uLightIntensity"),
    lightFalloff: gl.getUniformLocation(prog, "uLightFalloff"),
    wind: gl.getUniformLocation(prog, "uWind"),
    densityBias: gl.getUniformLocation(prog, "uDensityBias"),
    cloudTint: gl.getUniformLocation(prog, "uCloudTint"),
    samplesCurvature: gl.getUniformLocation(prog, "uSamplesCurvature"),
    skyTop: gl.getUniformLocation(prog, "uSkyTop"),
    skyBottom: gl.getUniformLocation(prog, "uSkyBottom"),
    ambientColor: gl.getUniformLocation(prog, "uAmbientColor"),
    fovScale: gl.getUniformLocation(prog, "uFovScale"),
  };
  gl.activeTexture(gl.TEXTURE0);
  gl.bindTexture(gl.TEXTURE_2D, noiseTex);
  gl.uniform1i(u.noise, 0);

  function resize() {
    const dpr = Math.min(window.devicePixelRatio || 1, DPR_CAP);
    const w = Math.max(1, Math.floor(canvas!.clientWidth * dpr * renderScale));
    const h = Math.max(1, Math.floor(canvas!.clientHeight * dpr * renderScale));
    if (canvas!.width !== w || canvas!.height !== h) {
      canvas!.width = w;
      canvas!.height = h;
      gl!.viewport(0, 0, w, h);
    }
  }
  resize();
  const onResize = () => resize();
  window.addEventListener("resize", onResize);

  // Don't burn a GPU on a scene nobody is looking at, or on a hidden tab.
  let visible = true;
  const observer =
    "IntersectionObserver" in window
      ? new IntersectionObserver((entries) => { visible = entries[0].isIntersecting; }, { threshold: 0.01 })
      : null;
  observer?.observe(canvas);

  let tabVisible = !document.hidden;
  const onVisChange = () => { tabVisible = !document.hidden; };
  document.addEventListener("visibilitychange", onVisChange);

  // Wind is integrated here rather than in the shader, so changing its speed
  // between waypoints alters the rate of drift instead of jumping the field.
  let windX = 0;
  let windY = 0;
  let windZ = 0;
  let prevDrawTime: number | null = null;

  function draw(time: number, state: VolsampleState) {
    if (prevDrawTime !== null) {
      const dt = Math.min(time - prevDrawTime, 0.1);
      windX += state.windX * dt;
      windY += state.windY * dt;
      windZ += state.windZ * dt;
    }
    prevDrawTime = time;
    const lp = computeLightPos(state);
    const look = norm3v(state.lookX, state.lookY, state.lookZ);
    gl!.uniform2f(u.res, canvas!.width, canvas!.height);
    gl!.uniform1f(u.time, time);
    gl!.uniform3f(u.cameraPos, state.posX, state.posY, state.posZ);
    gl!.uniform3f(u.lookDir, look[0], look[1], look[2]);
    gl!.uniform3f(u.lightPos, lp[0], lp[1], lp[2]);
    gl!.uniform3f(u.lightColor, state.lightR, state.lightG, state.lightB);
    gl!.uniform1f(u.lightIntensity, state.lightIntensity);
    gl!.uniform1f(u.lightFalloff, state.lightFalloff);
    gl!.uniform3f(u.wind, windX, windY, windZ);
    gl!.uniform1f(u.densityBias, state.densityBias);
    gl!.uniform3f(u.cloudTint, state.cloudTintR, state.cloudTintG, state.cloudTintB);
    gl!.uniform1f(u.samplesCurvature, state.samplesCurvature);
    gl!.uniform3f(u.skyTop, state.skyTopR, state.skyTopG, state.skyTopB);
    gl!.uniform3f(u.skyBottom, state.skyBotR, state.skyBotG, state.skyBotB);
    gl!.uniform3f(u.ambientColor, state.ambientR, state.ambientG, state.ambientB);
    gl!.uniform1f(u.fovScale, state.fovScale);
    gl!.drawArrays(gl!.TRIANGLES, 0, 3);
  }

  let rafId: number | null = null;
  let killed = false;
  let perfDecided = options.perfGate === false;
  let perfStart = 0;
  let frameCount = 0;

  function cleanup() {
    killed = true;
    if (rafId !== null) cancelAnimationFrame(rafId);
    window.removeEventListener("resize", onResize);
    document.removeEventListener("visibilitychange", onVisChange);
    observer?.disconnect();
  }

  function tick(now: number) {
    if (killed) return;
    const s = progressOverride ?? getProgress();
    const state = stateAtProgress(waypoints, s);

    // A machine that cannot hold frame rate gets one frame and then the static
    // fallback, rather than a slideshow.
    if (!perfDecided) {
      if (perfStart === 0) perfStart = now;
      frameCount++;
      if (frameCount >= PERF_FRAMES) {
        if ((now - perfStart) / frameCount > PERF_THRESHOLD_MS) {
          draw(now / 1000, state);
          canvas!.style.display = "none";
          cleanup();
          return;
        }
        perfDecided = true;
      }
    }

    if (visible && tabVisible) draw(now / 1000, state);
    rafId = requestAnimationFrame(tick);
  }
  rafId = requestAnimationFrame(tick);

  return {
    destroy: cleanup,
    setProgressOverride(value) {
      progressOverride = value == null ? null : Math.max(0, Math.min(1, value));
    },
  };
}