@kitn.ai/ui 0.18.2 → 0.20.0

package/src/components/audio-visualizer/shader-canvas.tsx

@@ -0,0 +1,846 @@
+import { createEffect, createMemo, onCleanup, untrack, type JSX } from 'solid-js';
+import { cn } from '../../utils/cn';
+
+export type UniformType =
+  | '1f' | '1i' | '1fv' | '2f' | '3f' | '3fv' | '4f' | '4fv'
+  | 'Matrix2fv' | 'Matrix3fv' | 'Matrix4fv';
+
+export interface UniformSpec {
+  type: UniformType;
+  value: number | number[];
+  /**
+   * For array uniforms (`1fv`, `3fv`, `4fv`, or a matrix type repeated), the
+   * declared length. Optional: when omitted, it is inferred from
+   * `value.length` -- see `inferArraySize`. The inferred length is exactly
+   * what the recompile check uses too (see `effectiveArraySize`), so a
+   * length change recompiles the shader whether `arraySize` was passed
+   * explicitly or left to be inferred -- e.g. a per-band uniform whose
+   * length tracks a reactive `size`/`barCount` prop stays correct across a
+   * band-count change with no extra care from the caller.
+   */
+  arraySize?: number;
+}
+
+export interface ShaderCanvasProps {
+  /**
+   * GLSL defining `mainImage(out vec4 fragColor, in vec2 fragCoord)`.
+   *
+   * MUST output PREMULTIPLIED colour: `fragColor = vec4(rgb * alpha, alpha);`,
+   * not `vec4(rgb, alpha)`. The canvas context uses the browser default
+   * `premultipliedAlpha: true` (see `ShaderCanvas`'s doc for why), so a
+   * naturally written soft/anti-aliased edge that returns straight (not
+   * premultiplied) colour composites with a dark fringe or halo -- most
+   * visible on a light page background.
+   */
+  fragment: string;
+  /**
+   * Custom uniforms. THIS CANVAS DECLARES THEM FOR YOU by injecting
+   * `uniform <type> <name>;` into the shader source. Declaring them yourself
+   * in `fragment` too is a GLSL redefinition and fails to compile.
+   */
+  uniforms?: Record<string, UniformSpec>;
+  precision?: 'lowp' | 'mediump' | 'highp';
+  /**
+   * Called when the shader cannot render at all: no WebGL context, or a
+   * compile/link failure. Not called again for a later value-only uniform
+   * update (see the reactivity note on `ShaderCanvas` below) -- only when
+   * the shader itself is rebuilt and that rebuild fails.
+   */
+  onError?: (message: string) => void;
+  /**
+   * Keep animating while the canvas is off screen. Default `false`.
+   *
+   * By default an off-screen canvas stops drawing AND hands its WebGL context
+   * back to the browser (see `ShaderCanvas`'s doc), because contexts are
+   * rationed at roughly 16 per renderer process and a page of visualizers
+   * blows through that. Set this when a canvas must keep running unseen --
+   * capturing frames, or a shader whose state must not visibly jump when it
+   * scrolls back in. The cost is one permanently-held context per canvas, so
+   * it does not scale: a page that sets this on more than a handful of
+   * visualizers is back to the eviction problem the default exists to avoid.
+   *
+   * Named to match upstream's prop of the same name, though ours opts out of
+   * something stronger: theirs only pauses the draw loop, ours also releases
+   * the context.
+   *
+   * This does NOT override `prefers-reduced-motion`. Reduced motion is applied
+   * a layer up, by the variants zeroing their own speed uniforms, so a frozen
+   * shader stays a still image whether or not this is set -- this only decides
+   * whether frames keep being drawn, never what they contain.
+   */
+  animateWhenNotVisible?: boolean;
+  class?: string;
+}
+
+/** Default accent for the shader variants, matching upstream's. */
+export const DEFAULT_SHADER_COLOR = '#1FD5F9';
+
+/**
+ * `#rrggbb` to three 0..1 floats, for a `3fv` uniform. Falls back to the
+ * default on malformed input (short forms like `#fff`, bare colour names,
+ * empty strings) rather than throwing into a render loop.
+ *
+ * Lives here, not duplicated, because wave, aurora, and custom variants all
+ * need it.
+ */
+export function hexToRgb(hex: string): [number, number, number] {
+  const m = hex.trim().match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/);
+  if (!m) return hexToRgb(DEFAULT_SHADER_COLOR);
+  const [, r, g, b] = m;
+  return [parseInt(r!, 16) / 255, parseInt(g!, 16) / 255, parseInt(b!, 16) / 255];
+}
+
+const GLSL_TYPE: Record<UniformType, string> = {
+  '1f': 'float', '1i': 'int', '1fv': 'float',
+  '2f': 'vec2', '3f': 'vec3', '3fv': 'vec3', '4f': 'vec4', '4fv': 'vec4',
+  Matrix2fv: 'mat2', Matrix3fv: 'mat3', Matrix4fv: 'mat4',
+};
+
+/**
+ * How many raw scalars make up ONE instance of an "*fv"/matrix uniform's
+ * GLSL type -- e.g. one `3fv` (a single vec3) is 3 floats, one `Matrix4fv`
+ * (a single mat4) is 16. Only these six types take an array `value` where
+ * "array" is ambiguous between "one instance, passed as an array because
+ * that is how the `*fv` GPU setters work" and "a genuine GLSL array of N
+ * instances the caller forgot to size." `inferArraySize` below uses this to
+ * tell the two apart: `value.length` equal to one unit's size is a single
+ * instance (no `[N]`); a whole-number multiple greater than one is an
+ * unsized array, so its size gets inferred.
+ */
+const UNIFORM_UNIT_SIZE: Partial<Record<UniformType, number>> = {
+  '1fv': 1, '3fv': 3, '4fv': 4,
+  Matrix2fv: 4, Matrix3fv: 9, Matrix4fv: 16,
+};
+
+/**
+ * When a caller omits `arraySize` on an array-capable uniform (`1fv`, `3fv`,
+ * `4fv`, or a matrix type) but `value` is longer than one instance of that
+ * type, infer the array length from `value.length` instead of silently
+ * declaring a scalar.
+ *
+ * This closes a real internal inconsistency: without it, `{ type: '1fv',
+ * value: [a, b, c] }` declared `uniform float name;` (scalar) while
+ * `setUniform` unconditionally called `gl.uniform1fv(location, [a, b, c])`
+ * -- a mismatch WebGL reports as `INVALID_OPERATION` with no JS exception
+ * and no `onError`, just a stale or zero value on screen. This function is
+ * what keeps the declaration and the setter from ever being able to
+ * disagree.
+ */
+function inferArraySize(u: UniformSpec): number | undefined {
+  const unit = UNIFORM_UNIT_SIZE[u.type];
+  if (!unit || !Array.isArray(u.value)) return undefined;
+  const instances = u.value.length / unit;
+  return instances > 1 && Number.isInteger(instances) ? instances : undefined;
+}
+
+/**
+ * The array length a uniform will actually be declared and compiled with:
+ * the caller's explicit `arraySize` if given, otherwise `inferArraySize`'s
+ * guess from `value.length`.
+ *
+ * `buildFragmentSource` (the declaration) and `uniformShapeKey` (the
+ * recompile trigger) both call this SAME function, on purpose -- it is the
+ * one source of truth for "how big is this array," so the two can never
+ * disagree. Before this existed, an uninferred array uniform's declaration
+ * came from `value.length` but the recompile check only looked at the
+ * explicit `arraySize` field: a reactive `value.length` change (e.g. a
+ * `uBands` uniform whose length tracks a `size`/`barCount` prop, which does
+ * change while a shader variant stays mounted) would silently NOT recompile,
+ * reintroducing the exact declaration/setter mismatch this file exists to
+ * prevent, just one door over. Routing both call sites through the same
+ * function makes that impossible rather than merely documented.
+ */
+function effectiveArraySize(u: UniformSpec): number | undefined {
+  return u.arraySize ?? inferArraySize(u);
+}
+
+/** Every ShaderToy built-in we support, declared for every shader. */
+const BUILTINS = [
+  'uniform float iTime;',
+  'uniform vec2 iResolution;',
+  'uniform vec4 iMouse;',
+  'uniform int iFrame;',
+  'uniform vec4 iDate;',
+].join('\n');
+
+const VERTEX_SOURCE = `
+attribute vec3 aVertexPosition;
+void main() { gl_Position = vec4(aVertexPosition, 1.0); }
+`;
+
+/**
+ * Assemble the full fragment shader: precision, built-ins, auto-declared
+ * custom uniforms, the caller's body, and a `main()` that forwards to
+ * `mainImage`.
+ *
+ * Declares every entry in `uniforms` for the caller (`uniform <type>
+ * <name>;`, injected right after the precision qualifier). Declaring the
+ * SAME uniform name inside `fragment` too is a GLSL redefinition and fails
+ * to compile -- that is the contract this function exists to protect.
+ *
+ * Split out from the component because it is the only part testable without
+ * a GPU (jsdom has no WebGL at all), and it is where both a compile-breaking
+ * duplicate declaration and an array-size mismatch would show up.
+ */
+export function buildFragmentSource(
+  fragment: string,
+  uniforms: Record<string, UniformSpec>,
+  precision: string,
+): string {
+  const declarations = Object.entries(uniforms)
+    .map(([name, u]) => {
+      const arraySize = effectiveArraySize(u);
+      const size = arraySize ? `[${arraySize}]` : '';
+      return `uniform ${GLSL_TYPE[u.type]} ${name}${size};`;
+    })
+    .join('\n');
+
+  return [
+    `precision ${precision} float;`,
+    BUILTINS,
+    declarations,
+    fragment,
+    'void main() { mainImage(gl_FragColor, gl_FragCoord.xy); }',
+  ].join('\n');
+}
+
+/**
+ * A stable fingerprint of the uniforms' STRUCTURE -- name, GLSL type, and
+ * EFFECTIVE array size (`effectiveArraySize`, explicit or inferred, never
+ * raw `u.arraySize` alone) -- deliberately excluding `value` itself. Two
+ * calls with the same names/types/sizes but different values return the
+ * same string; two calls where an array's `value.length` differs, even with
+ * no explicit `arraySize` on either side, return DIFFERENT strings, because
+ * that length difference is exactly what `buildFragmentSource` would
+ * declare differently.
+ *
+ * This is what lets the component recompile only when the shader itself
+ * must change, not every time a uniform's value updates (which, for an
+ * audio-reactive uniform, is every animation frame) -- while still
+ * recompiling on every change that actually changes the declared source,
+ * including a length-only change to an inferred-size array.
+ */
+function uniformShapeKey(uniforms: Record<string, UniformSpec>): string {
+  return Object.keys(uniforms)
+    .sort()
+    .map((name) => {
+      const u = uniforms[name]!;
+      return `${name}:${u.type}:${effectiveArraySize(u) ?? ''}`;
+    })
+    .join('|');
+}
+
+function compile(gl: WebGLRenderingContext, type: number, source: string): WebGLShader | string {
+  const shader = gl.createShader(type);
+  if (!shader) return 'Could not create a WebGL shader.';
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader) ?? 'Unknown shader compile error.';
+    gl.deleteShader(shader);
+    return log;
+  }
+  return shader;
+}
+
+/** Push one uniform value to the GPU, dispatching on its declared type. */
+function setUniform(
+  gl: WebGLRenderingContext,
+  location: WebGLUniformLocation,
+  spec: UniformSpec,
+): void {
+  const v = spec.value;
+  switch (spec.type) {
+    case '1f': gl.uniform1f(location, v as number); break;
+    case '1i': gl.uniform1i(location, v as number); break;
+    case '1fv': gl.uniform1fv(location, v as number[]); break;
+    case '2f': gl.uniform2fv(location, v as number[]); break;
+    case '3f': case '3fv': gl.uniform3fv(location, v as number[]); break;
+    case '4f': case '4fv': gl.uniform4fv(location, v as number[]); break;
+    case 'Matrix2fv': gl.uniformMatrix2fv(location, false, v as number[]); break;
+    case 'Matrix3fv': gl.uniformMatrix3fv(location, false, v as number[]); break;
+    case 'Matrix4fv': gl.uniformMatrix4fv(location, false, v as number[]); break;
+  }
+}
+
+/**
+ * A full-screen fragment shader on a canvas, ShaderToy-compatible.
+ *
+ * Deliberately does NOT support textures, `iChannel` inputs, video,
+ * multipass, or device orientation. Those are what make upstream's runner
+ * 988 lines, and an audio visualizer needs none of them.
+ *
+ * Renders with a fully transparent clear colour (`gl.clearColor(0,0,0,0)`).
+ * Compositing over the page comes from the canvas context's default
+ * `premultipliedAlpha: true`, NOT from `gl.blendFunc` (see the comment at
+ * the blend call site for why that call has no effect on today's
+ * single-pass output). Because of that default, `fragment` MUST output
+ * premultiplied colour -- see the doc on the `fragment` prop for the exact
+ * contract.
+ *
+ * Reactivity note: only `fragment`, `precision`, and the STRUCTURE of
+ * `uniforms` (which names exist, with which types/sizes) trigger a rebuild
+ * of the GL program. A uniform's VALUE is read fresh every animation frame
+ * without forcing a rebuild -- see `uniformShapeKey` above. This matters
+ * because a caller typically re-creates the `uniforms` object every render
+ * (e.g. `{ uVolume: { type: '1f', value: volume() } }`); tracking that
+ * object directly would tear down and recompile the whole program on every
+ * frame the volume changes. `fragment` and `precision` are ALSO read through
+ * their own memos, not directly, for the same reason: a variant's `precision`
+ * is commonly computed from a prop (`size`) that arrives via a dispatcher
+ * spread bundling unrelated fast-changing signals (`bands`), so an unmemoized
+ * read can mark this effect stale on every one of those, even though
+ * `precision`'s resolved value never changes. See the comment above
+ * `fragmentMemo`/`precisionMemo` below for the measured failure this caused.
+ *
+ * Visibility: while the canvas is off screen this canvas RELEASES its WebGL
+ * context outright, and takes it back when the canvas returns -- see the
+ * `ContextState` block inside the component for the whole mechanism and the
+ * context-budget measurement that forced it. There is no prop for this; it is
+ * always on.
+ */
+export function ShaderCanvas(props: ShaderCanvasProps): JSX.Element {
+  let canvas!: HTMLCanvasElement;
+
+  const shapeKey = createMemo(() => uniformShapeKey(props.uniforms ?? {}));
+  // `fragment` and `precision` get the SAME insulation as `shapeKey` above,
+  // and for the same underlying reason. A variant's props are commonly built
+  // with `{...shared()}` (see index.tsx's dispatcher: `shared()` returns
+  // `state`/`size`/`bands`/`frozen`/`color` together). Solid's spread-prop
+  // merging re-invokes the WHOLE source function on ANY property read from
+  // the merged result -- so a variant computing `precision` from `props.size`
+  // (e.g. aurora/wave's `props.size === 'icon' || ... ? 'mediump' :
+  // 'highp'`) transitively re-runs `shared()`, and thus re-reads `bands()`,
+  // on every read of `precision`, even though `size` itself never changes.
+  // Reading `props.precision` directly inside the compile effect below
+  // subscribed it to THAT transitive `bands()` read -- at ~31 band updates a
+  // second, `precision`'s own resolved value never changed, but the effect
+  // reran on every single one anyway, tearing down and recompiling the whole
+  // GL program 15-20 times a second in production (measured on the Aurora
+  // story: ~70 recompiles in 4s, `iTime` pinned under 0.33s and periodically
+  // NEGATIVE from `start` being re-stamped mid-flight). `shapeKey` already
+  // proved this class of leak is real for `uniforms`; `fragment`/`precision`
+  // needed the identical fix, matching the one just applied to
+  // `use-sequencer.ts` for the same root cause (an effect transitively
+  // subscribed to a signal it should not be, via a prop getter chain) --
+  // wrap in a memo so only the RESOLVED value, never the act of reading it,
+  // can mark the effect stale.
+  const fragmentMemo = createMemo(() => props.fragment);
+  const precisionMemo = createMemo(() => props.precision ?? 'highp');
+
+  // ------------------------------------------------------------------------
+  // Context lifecycle.
+  //
+  // Chrome caps LIVE WebGL contexts at about 16 per renderer process and
+  // silently evicts the oldest past that -- a budget shared across
+  // same-origin iframes too, so splitting the page up buys nothing (measured:
+  // the AudioVisualizer docs page wanted 18, got 16, and 2 canvases failed to
+  // compile with no error anywhere). Holding a context for the component's
+  // whole life is what made that page unable to host the shader stories at
+  // all.
+  //
+  // Merely pausing the draw loop off screen -- which is all upstream's
+  // runner does -- does NOT return a slot: an idle context still occupies
+  // one. So an off-screen canvas gives the context BACK, via
+  // `WEBGL_lose_context`'s `loseContext()`, and asks for it again with
+  // `restoreContext()` on the way in. Consequence worth stating plainly: N
+  // off-screen visualizers now hold ZERO contexts between them, and a page
+  // holds one per canvas actually in the viewport.
+  //
+  // All of this state is COMPONENT-scoped rather than living inside the
+  // compile effect, because a context belongs to the CANVAS, which outlives
+  // any one run of that effect. A shader released while off screen must still
+  // be restorable after a recompile (a `size`/band-count change genuinely
+  // rebuilds the shader while a tile is scrolled away).
+  // ------------------------------------------------------------------------
+
+  /**
+   * Where the canvas's context is, independent of whether a program is
+   * currently compiled against it (that is `teardown`).
+   *
+   * `losing` and `restoring` are the IN-FLIGHT states, and they are the whole
+   * reason this is a state machine rather than a boolean:
+   * `loseContext()`/`restoreContext()` do not take effect synchronously --
+   * the browser answers later with `webglcontextlost`/`webglcontextrestored`.
+   * A canvas that scrolls out and back in before the answer arrives must sit
+   * in the in-flight state and re-decide when the event lands, never start a
+   * second draw loop or compile against a context that is still gone.
+   */
+  type ContextState = 'none' | 'live' | 'losing' | 'lost' | 'restoring';
+  let contextState: ContextState = 'none';
+  let context: WebGLRenderingContext | null = null;
+  /**
+   * Cached WHILE THE CONTEXT IS ALIVE, deliberately: a lost context answers
+   * `getExtension` with null, so re-fetching it on the way back in is a dead
+   * end. This handle is the only thing that can restore what we released.
+   */
+  let loseExtension: WEBGL_lose_context | null = null;
+
+  /** Undoes everything the current activation built. Null when nothing is built. */
+  let teardown: (() => void) | null = null;
+  /** The current frame callback. Null when nothing is built. */
+  let drawFrame: ((now: number) => void) | null = null;
+  /** The pending animation frame id, or 0 when the loop is stopped. */
+  let raf = 0;
+
+  /** The assembled source and the uniform snapshot it was assembled from. */
+  let build: { source: string; uniforms: Record<string, UniformSpec> } | null = null;
+  /** THIS build cannot compile; reset whenever the effect produces a new one. */
+  let buildFailed = false;
+  /** No WebGL at all. Permanent for this mount, matching `onError`'s contract. */
+  let noWebGL = false;
+  /** The BROWSER took the context away (not us). Permanent for this mount. */
+  let hardLost = false;
+  let disposed = false;
+
+  let visibility: IntersectionObserver | undefined;
+  let wired = false;
+  /**
+   * Whether the canvas is on screen. Starts true and STAYS true when there is
+   * no `IntersectionObserver` to consult (SSR, jsdom, older browsers), which
+   * is what keeps that environment on exactly the pre-observer behaviour:
+   * compile on mount, draw forever.
+   */
+  let onScreen = true;
+  /**
+   * The resolved `animateWhenNotVisible`, cached rather than read from props
+   * inside `sync`. `sync` runs inside the compile effect, and a props read
+   * there would subscribe that effect to this flag -- rebuilding the entire GL
+   * program every time a caller toggled it, the exact leak the fragment /
+   * precision / shapeKey memos above exist to prevent. Its own effect below is
+   * the single writer.
+   */
+  let alwaysAnimate = false;
+
+  /**
+   * The shader clock, deliberately outliving both a release and a recompile.
+   *
+   * `iTime` is ON-SCREEN time: it accumulates only while the loop runs, so a
+   * canvas that comes back after a minute off screen picks up exactly where
+   * the viewer last saw it rather than jumping a minute forward. Freezing
+   * rather than tracking wall-clock is a choice -- nothing here is
+   * synchronised to real time, so the only observable difference is a
+   * discontinuity on scroll-in, and there is no reason to have one.
+   *
+   * What it must never do is RESTART. A previous round shipped a defect where
+   * a spuriously re-running compile effect re-stamped the clock's origin every
+   * few frames, pinning `iTime` under 0.33s forever (shaders looked like they
+   * were looping a third of a second). The memos above are the fix for that
+   * cause; keeping the clock out here means even a legitimate recompile -- a
+   * band-count change, say -- no longer snaps the animation back to zero, so
+   * the whole class of "the shader restarted" bugs has one fewer door.
+   * `frame` (`iFrame`) is kept monotonic for the same reason.
+   */
+  let elapsedMs = 0;
+  let runStartedAt = 0;
+  let frame = 0;
+
+  const acquireContext = (): WebGLRenderingContext | null => {
+    if (context) return context;
+    context = (canvas.getContext('webgl') ??
+      canvas.getContext('experimental-webgl')) as WebGLRenderingContext | null;
+    if (context) {
+      contextState = 'live';
+      // Optional call: every real context implements `getExtension`, but a
+      // context stub that does not should degrade to "cannot release" rather
+      // than throwing out of the compile path.
+      loseExtension = context.getExtension?.('WEBGL_lose_context') ?? null;
+    }
+    return context;
+  };
+
+  const startLoop = () => {
+    // The one gate that makes a second concurrent loop impossible, however
+    // fast visibility toggles: a loop is running iff `raf !== 0` (a real
+    // animation-frame id is never 0).
+    if (raf !== 0 || !drawFrame || disposed) return;
+    runStartedAt = performance.now();
+    raf = requestAnimationFrame(drawFrame);
+  };
+
+  const stopLoop = () => {
+    if (raf === 0) return;
+    cancelAnimationFrame(raf);
+    raf = 0;
+    // Bank what was drawn so `iTime` resumes from here, not from zero.
+    elapsedMs += Math.max(0, performance.now() - runStartedAt);
+  };
+
+  /** Drop the compiled program/shaders/buffer, leaving the context itself alone. */
+  const release = () => {
+    stopLoop();
+    const run = teardown;
+    teardown = null;
+    run?.();
+  };
+
+  const requestLoss = () => {
+    if (!loseExtension || contextState !== 'live') return;
+    contextState = 'losing';
+    loseExtension.loseContext();
+  };
+
+  const requestRestore = () => {
+    if (!loseExtension) return;
+    contextState = 'restoring';
+    loseExtension.restoreContext();
+  };
+
+  /**
+   * Reconcile what is built against where the canvas is. Every input --
+   * a visibility change, a context event, a new compiled source -- routes
+   * through here rather than acting directly, which is what keeps the
+   * in-flight windows from producing two loops or a half-initialised context.
+   */
+  const sync = () => {
+    if (disposed || noWebGL || hardLost) return;
+    // The ONE place visibility policy is decided. `animateWhenNotVisible`
+    // overrides the observer's verdict here rather than anywhere upstream of
+    // it, so there is still exactly one writer deciding whether this canvas
+    // should be drawing -- a runtime flip of the flag is just another call
+    // into this same reconciler, like a scroll or a context event.
+    if (onScreen || alwaysAnimate) {
+      // Mid-flight: the `webglcontextlost`/`webglcontextrestored` handler
+      // re-enters here once the browser answers.
+      if (contextState === 'losing' || contextState === 'restoring') return;
+      if (contextState === 'lost') { requestRestore(); return; }
+      activate();
+    } else if (loseExtension && contextState === 'live') {
+      // Resources first, THEN the context: deleting GPU objects after the
+      // context is gone is a spec no-op, which leaks them for as long as the
+      // driver keeps the dead context around.
+      release();
+      requestLoss();
+    } else {
+      // No way to hand the context back (no extension), or it is already
+      // gone. Stop burning frames either way -- upstream's pause, as the
+      // floor rather than the ceiling.
+      stopLoop();
+    }
+  };
+
+  const setOnScreen = (next: boolean) => {
+    if (next === onScreen || disposed) return;
+    onScreen = next;
+    sync();
+  };
+
+  const onContextLost = (e: Event) => {
+    // Required by spec to even ALLOW a later `webglcontextrestored` --
+    // including for the losses this component asks for itself.
+    e.preventDefault();
+    const deliberate = contextState === 'losing';
+    contextState = 'lost';
+    release();
+    if (deliberate) {
+      // Ours, to free the budget while off screen. If the canvas scrolled
+      // back in while the event was in flight, this is where it gets restored.
+      sync();
+      return;
+    }
+    // The browser evicted us -- most commonly because the page blew past the
+    // context cap. Permanent for this mount: `onError` is what lets the
+    // dispatcher fall back to bars. Without this the draw loop would keep
+    // issuing GL calls that are all silent no-ops on a lost context, leaving a
+    // shader frozen mid-frame with nothing reported anywhere.
+    hardLost = true;
+    props.onError?.('WebGL context was lost.');
+  };
+
+  const onContextRestored = () => {
+    contextState = 'live';
+    // Rebuild if the canvas is still on screen, or hand the context straight
+    // back if it scrolled away again while the restore was in flight.
+    sync();
+  };
+
+  const wireCanvas = () => {
+    if (wired) return;
+    wired = true;
+    canvas.addEventListener('webglcontextlost', onContextLost, false);
+    canvas.addEventListener('webglcontextrestored', onContextRestored, false);
+
+    if (typeof IntersectionObserver === 'undefined') return;
+
+    // The observer is installed even when `animateWhenNotVisible` is set, and
+    // its verdict is ignored in `sync` instead. Skipping the observer in that
+    // mode would be marginally cheaper, but it would leave `onScreen` frozen
+    // at a stale default, so flipping the flag OFF at runtime would need the
+    // observer wired up right then and would keep drawing until its first
+    // callback landed -- a second control path, and a wrong answer in the
+    // meantime. Keeping it always-on means `onScreen` is continuously
+    // accurate and a flip in either direction is a single `sync()` call.
+    // An IntersectionObserver that never fires costs essentially nothing.
+    //
+    // With an observer, NOTHING is built until it reports the canvas on
+    // screen -- unless `animateWhenNotVisible` says otherwise, which `sync`
+    // resolves below. That is the load-bearing half of the fix: a page
+    // mounting 18 visualizers otherwise creates 18 contexts in the mount task
+    // and has 2 evicted by the browser before the first observer callback
+    // could possibly run -- and an evicted context is a permanent failure,
+    // not a recoverable one.
+    onScreen = false;
+    visibility = new IntersectionObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (entry) setOnScreen(entry.isIntersecting);
+    }, { threshold: 0 });
+    visibility.observe(canvas);
+  };
+
+  const activate = () => {
+    if (disposed || noWebGL || hardLost || buildFailed) return;
+    const current = build;
+    if (!current) return;
+
+    // Already built and only the loop was stopped (the no-extension path
+    // above): re-arm it rather than recompiling.
+    if (teardown) { startLoop(); return; }
+
+    const gl = acquireContext();
+    if (!gl) {
+      noWebGL = true;
+      props.onError?.('WebGL is not available in this browser.');
+      return;
+    }
+    if (gl.isContextLost()) {
+      // Released earlier -- possibly by a PREVIOUS run of the compile effect,
+      // which is why `loseExtension` is cached at component scope. Ask for it
+      // back and let `webglcontextrestored` re-enter here.
+      requestRestore();
+      return;
+    }
+
+    const { source, uniforms } = current;
+
+    const vs = compile(gl, gl.VERTEX_SHADER, VERTEX_SOURCE);
+    if (typeof vs === 'string') {
+      buildFailed = true;
+      props.onError?.(vs);
+      return;
+    }
+    const fs = compile(gl, gl.FRAGMENT_SHADER, source);
+    if (typeof fs === 'string') {
+      gl.deleteShader(vs);
+      buildFailed = true;
+      props.onError?.(fs);
+      return;
+    }
+
+    const program = gl.createProgram();
+    if (!program) {
+      gl.deleteShader(vs);
+      gl.deleteShader(fs);
+      buildFailed = true;
+      props.onError?.('Could not create a WebGL program.');
+      return;
+    }
+    gl.attachShader(program, vs);
+    gl.attachShader(program, fs);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      const log = gl.getProgramInfoLog(program) ?? 'Shader program failed to link.';
+      gl.deleteProgram(program);
+      gl.deleteShader(vs);
+      gl.deleteShader(fs);
+      buildFailed = true;
+      props.onError?.(log);
+      return;
+    }
+    gl.useProgram(program);
+
+    // Two triangles covering clip space. The fragment shader does the rest.
+    const buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 0, 1, -1, 0, -1, 1, 0, 1, 1, 0]),
+      gl.STATIC_DRAW,
+    );
+    const attr = gl.getAttribLocation(program, 'aVertexPosition');
+    gl.enableVertexAttribArray(attr);
+    gl.vertexAttribPointer(attr, 3, gl.FLOAT, false, 0, 0);
+
+    // This blendFunc has NO effect on today's output: `gl.clear` runs
+    // immediately before the single `gl.drawArrays` every frame (see draw()
+    // below), so the framebuffer is always transparent-black at draw time --
+    // there is nothing behind the draw call to blend against. The actual
+    // transparency mechanism is the canvas context's default
+    // `premultipliedAlpha: true` combined with `clearColor(0,0,0,0)` below:
+    // the browser composites the canvas's own premultiplied RGBA buffer over
+    // the page. That default is also why `fragment` must output premultiplied
+    // colour (see the `fragment` prop's doc) -- an unpremultiplied translucent
+    // edge produces a dark fringe on a light page.
+    //
+    // The call stays enabled anyway: it is exactly what a future multipass or
+    // non-clearing render path would need, and silently dropping it now would
+    // be a behavioural change for that later path, not a cleanup.
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+
+    const loc = (name: string) => gl.getUniformLocation(program, name);
+    const uTime = loc('iTime');
+    const uResolution = loc('iResolution');
+    const uMouse = loc('iMouse');
+    const uFrame = loc('iFrame');
+    const uDate = loc('iDate');
+    const customLocations = Object.keys(uniforms).map((n) => [n, loc(n)] as const);
+
+    // Only .xy (pointer position) is implemented. ShaderToy's iMouse.zw
+    // carries click-down position; this canvas has no pointerdown tracking,
+    // so .zw stays permanently zero.
+    const mouse = [0, 0, 0, 0];
+    const onMove = (e: PointerEvent) => {
+      const r = canvas.getBoundingClientRect();
+      mouse[0] = e.clientX - r.left;
+      mouse[1] = r.height - (e.clientY - r.top);
+    };
+    canvas.addEventListener('pointermove', onMove, { passive: true });
+
+    // Match the backing store to the displayed size so the shader is not blurry.
+    const resize = () => {
+      const dpr = globalThis.devicePixelRatio ?? 1;
+      const w = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+      const h = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+      if (canvas.width !== w || canvas.height !== h) {
+        canvas.width = w;
+        canvas.height = h;
+        gl.viewport(0, 0, w, h);
+      }
+    };
+
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(resize) : undefined;
+    ro?.observe(canvas);
+    resize();
+
+    const draw = (now: number) => {
+      // Belt-and-braces alongside the `webglcontextlost` listener: if a
+      // context goes away by some path that does not fire the event
+      // synchronously before the next frame, this still stops issuing GL
+      // calls against it.
+      if (hardLost || gl.isContextLost()) return;
+      resize();
+      // Clamped at 0: a browser's rAF callback receives the timestamp for
+      // when the current frame BEGAN, captured before this component's
+      // synchronous setup finishes and stamps `runStartedAt` -- so the very
+      // first frame or two can compute a few milliseconds negative even with
+      // nothing wrong. Harmless and self-correcting either way (confirmed:
+      // the pathological, CONTINUOUSLY-recurring negative values reported in
+      // production were the clock origin being re-stamped by a spuriously
+      // re-running effect, not this), but there is no reason `iTime` should
+      // ever go negative for a caller, so it does not.
+      const seconds = Math.max(0, (elapsedMs + (now - runStartedAt)) / 1000);
+
+      if (uTime) gl.uniform1f(uTime, seconds);
+      if (uResolution) gl.uniform2fv(uResolution, [canvas.width, canvas.height]);
+      if (uMouse) gl.uniform4fv(uMouse, mouse);
+      if (uFrame) gl.uniform1i(uFrame, frame);
+      if (uDate) {
+        const d = new Date();
+        gl.uniform4fv(uDate, [
+          d.getFullYear(), d.getMonth(), d.getDate(),
+          d.getHours() * 3600 + d.getMinutes() * 60 + d.getSeconds(),
+        ]);
+      }
+
+      // Read straight off props, not the closed-over `uniforms` snapshot, so
+      // a value change (e.g. volume ticking every frame) takes effect
+      // immediately without going through the compile effect above at all.
+      for (const [name, location] of customLocations) {
+        const spec = props.uniforms?.[name];
+        if (spec && location) setUniform(gl, location, spec);
+      }
+
+      gl.clearColor(0, 0, 0, 0);
+      gl.clear(gl.COLOR_BUFFER_BIT);
+      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+
+      frame++;
+      raf = requestAnimationFrame(draw);
+    };
+
+    teardown = () => {
+      drawFrame = null;
+      ro?.disconnect();
+      canvas.removeEventListener('pointermove', onMove);
+      gl.deleteProgram(program);
+      gl.deleteShader(vs);
+      gl.deleteShader(fs);
+      gl.deleteBuffer(buffer);
+    };
+    drawFrame = draw;
+    startLoop();
+  };
+
+  onCleanup(() => {
+    disposed = true;
+    visibility?.disconnect();
+    if (wired) {
+      canvas.removeEventListener('webglcontextlost', onContextLost);
+      canvas.removeEventListener('webglcontextrestored', onContextRestored);
+    }
+    release();
+    // Hand the budget back NOW rather than waiting for the detached canvas to
+    // be collected: switching variants, or navigating a page full of tiles,
+    // otherwise leaves dead contexts holding slots for a while.
+    if (loseExtension && contextState === 'live') loseExtension.loseContext();
+  });
+
+  // Registered before the compile effect so `alwaysAnimate` already holds the
+  // caller's policy the first time `sync()` runs, avoiding one reconcile pass
+  // that could only ever decide to do nothing. Measured, not assumed: putting
+  // this effect AFTER the compile effect passes every test in this file
+  // unchanged, because both run in the same synchronous flush either way and
+  // the canvas is built before anything can observe it. So this is tidiness,
+  // NOT a correctness requirement -- what actually guarantees an opted-out
+  // canvas builds without waiting on an observer callback is `sync`'s
+  // `onScreen || alwaysAnimate`, which is the thing under test.
+  //
+  // Wrapped in its own memo for the same reason `fragment`/`precision` are:
+  // a variant's props arrive through a dispatcher spread that bundles
+  // fast-changing signals, so an unmemoized read would re-run this effect at
+  // band cadence even though the resolved boolean never changed.
+  const animateWhenNotVisibleMemo = createMemo(() => props.animateWhenNotVisible ?? false);
+  createEffect(() => {
+    alwaysAnimate = animateWhenNotVisibleMemo();
+    // Route the change through the reconciler rather than acting on it here:
+    // whether this means "build now", "release now", or "nothing changes"
+    // depends on state `sync` already owns.
+    sync();
+  });
+
+  createEffect(() => {
+    // Reads ONLY the three memos below -- never `props.fragment` /
+    // `props.precision` / `props.uniforms` directly -- so this effect's
+    // dependency set is exactly {fragmentMemo, precisionMemo, shapeKey}, and
+    // nothing a caller's props chain does elsewhere (spread-derived or not)
+    // can mark it stale without one of those three RESOLVED values actually
+    // changing.
+    //
+    // Note what this effect does NOT do any more: touch the GPU. It resolves
+    // the source and hands it to `sync`, which owns every decision about
+    // whether a context should exist right now. That split is what lets the
+    // SAME setup path serve a first mount, a recompile, and a scroll-back-in
+    // restore, instead of one path per trigger.
+    const fragment = fragmentMemo();
+    const precision = precisionMemo();
+    shapeKey();
+    const uniforms = untrack(() => props.uniforms ?? {});
+
+    build = { source: buildFragmentSource(fragment, uniforms, precision), uniforms };
+    // A new source gets a fresh attempt: a shader that failed to compile must
+    // not poison the next one the caller supplies.
+    buildFailed = false;
+
+    wireCanvas();
+    sync();
+
+    // Runs before the NEXT execution of this effect as well as on unmount, so
+    // a source change always drops the program compiled from the old source
+    // before `sync` builds the new one. The context itself deliberately
+    // survives -- it is the expensive, rationed thing, and the new source
+    // needs it immediately.
+    onCleanup(release);
+  });
+
+  return <canvas ref={canvas} part="canvas" class={cn('block h-full w-full', props.class)} />;
+}