instantshader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InstantGradient (instantgradient.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# instantshader
+
+Animated WebGL gradient shaders with zero dependencies. Mount a live, resizable
+gradient into any DOM element, or render a single frame to a detached canvas
+for export pipelines. Built by [InstantGradient](https://instantgradient.com/shaders).
+
+## Install
+
+```bash
+npm install instantshader
+```
+
+## Usage
+
+```ts
+import { mountGradient, flow } from "instantshader";
+
+const handle = mountGradient(document.getElementById("bg")!, {
+  shader: flow,
+  colors: ["#4f46e5", "#ec4899", "#22d3ee"],
+});
+
+// handle.pause() / handle.resume() / handle.dispose() when done
+```

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+//#region src/renderer.d.ts
+
+type Renderer = {
+  renderAt(timeMs: number): void;
+  setColors(colors: string[]): void;
+  setParams(params: Record<string, number>): void;
+  resize(width: number, height: number): void;
+  dispose(): void;
+};
+declare function createRenderer(opts: RendererOptions): Renderer;
+//#endregion
+//#region src/types.d.ts
+/**
+* Describes a single tunable knob exposed by a shader (e.g. "frequency",
+* "warp amount"). The renderer uses this metadata to build UI controls and
+* to validate/clamp incoming values; it does not carry a value itself.
+*/
+type ParamDef = {
+  /** Param identifier. The GLSL uniform name is always "u_" + key. */
+  key: string;
+  /** Human-readable label for UI controls (sliders, etc). */
+  label: string;
+  min: number;
+  max: number;
+  step: number;
+  /** Value used when no override is supplied in MountOptions.params. */
+  default: number;
+};
+/**
+* A registered shader "look". `fragment` is raw GLSL source that assumes
+* BASE_UNIFORMS (time, resolution, palette texture, etc — defined elsewhere
+* in the kit) plus one `uniform float u_<key>` per entry in `params`.
+*/
+type ShaderDef = {
+  /** Stable identifier used to look this shader up via getShader(id). */
+  id: string;
+  label: string;
+  fragment: string;
+  params: ParamDef[];
+  /**
+  * Produces a full param set for "randomize" flows. Takes a seeded RNG
+  * (0-1 uniform) rather than calling Math.random() directly so results are
+  * reproducible when the same seed is replayed via MountOptions.seed.
+  */
+  randomParams: (rand: () => number) => Record<string, number>;
+};
+/** Options accepted by the kit's mount() entry point. */
+type MountOptions = {
+  /** The shader to render. */
+  shader: ShaderDef;
+  /** Hex color stops forming the gradient's palette ramp, in order. */
+  colors: string[];
+  /** Overrides for the shader's params; unset keys fall back to ParamDef.default. */
+  params?: Record<string, number>;
+  /** Animation speed multiplier. Defaults to 1. */
+  speed?: number;
+  /** RNG seed for any randomized/time-offset behavior. Defaults to 0. */
+  seed?: number;
+};
+/** Live handle returned by mount(), used to control a running gradient instance. */
+type MountHandle = {
+  canvas: HTMLCanvasElement;
+  setColors(colors: string[]): void;
+  setParams(params: Record<string, number>): void;
+  setSpeed(speed: number): void;
+  pause(): void;
+  resume(): void;
+  /** Jumps playback to an absolute time position, in milliseconds. */
+  seek(ms: number): void;
+  getTimeMs(): number;
+  /** Tears down the WebGL context and stops the render loop. Idempotent. */
+  dispose(): void;
+};
+/** Result of a one-shot renderGradientFrame() call: the rendered canvas plus
+* an explicit disposer for its GL context. */
+type RenderFrameResult = {
+  canvas: HTMLCanvasElement;
+  /** Releases the GL context. Call once the caller is done reading pixels
+  * from `canvas` (toDataURL/toBlob/getImageData/drawImage). */
+  dispose(): void;
+};
+/** Options accepted by createRenderer() — the low-level, seekable renderer
+* that mountGradient/renderGradientFrame both build on. */
+type RendererOptions = {
+  canvas: HTMLCanvasElement;
+  shader: ShaderDef;
+  colors: string[];
+  params: Record<string, number>;
+  seed: number;
+};
+//#endregion
+//#region src/shaders/flow.d.ts
+declare const flow: ShaderDef;
+//#endregion
+//#region src/shaders/beam.d.ts
+declare const beam: ShaderDef;
+//#endregion
+//#region src/registry.d.ts
+declare const shaders: readonly ShaderDef[];
+declare function getShader(id: string): ShaderDef | undefined;
+//#endregion
+//#region src/mount.d.ts
+/**
+* Mounts a live, animated gradient into `container` and returns a handle to
+* control it. Owns a canvas (sized to the container via ResizeObserver, DPR
+* capped at 2 to bound fill-rate cost on high-density displays) and a RAF
+* loop that runs ONLY while playing — the same lifecycle used by the
+* InstantGradient app's canvas preview, which stops scheduling
+* requestAnimationFrame entirely while paused/frozen rather than continuing
+* to tick with no-op frames. pause() cancels the
+* in-flight frame and freezes `clockMs`; resume() restarts the loop from
+* there. Since the loop is fully stopped while paused, setColors/setParams/
+* seek/resize (via the ResizeObserver) each trigger a single on-demand
+* `renderer.renderAt(clockMs)` so a paused canvas still repaints immediately
+* instead of going stale until the next resume() — this matters because
+* callers may mount many simultaneously-paused instances (e.g. a screenshot
+* grid) that must never carry a perpetual 60fps draw loop each.
+*/
+declare function mountGradient(container: HTMLElement, opts: MountOptions): MountHandle;
+//#endregion
+//#region src/frame.d.ts
+/**
+* Renders a single frame into a detached (not-in-DOM) canvas at an exact
+* pixel size, for export/thumbnail use cases that need a synchronous
+* snapshot rather than a live animation.
+*
+* The returned canvas is NOT disposed automatically — its GL context must
+* stay alive after this function returns so callers can scrape pixels from
+* it (toDataURL/toBlob/getImageData/drawImage). Once the caller is done
+* with it, release the GL context by calling the returned `dispose()`.
+*/
+declare function renderGradientFrame(opts: {
+  shader: ShaderDef;
+  colors: string[];
+  params?: Record<string, number>;
+  seed?: number;
+  timeMs?: number;
+  width: number;
+  height: number;
+}): RenderFrameResult;
+//#endregion
+//#region src/palette.d.ts
+/**
+* Builds a 1024-texel RGBA ramp (Uint8Array, length 1024*4) by interpolating
+* the given hex color stops in OKLCh space (see the top-of-file comment for
+* why polar rather than Cartesian OKLab).
+*
+* Stops are placed at evenly spaced positions: color i sits at t = i/(n-1)
+* (a single-color palette is treated as that color duplicated at t=0 and
+* t=1, so it produces a flat ramp rather than dividing by zero). The ramp
+* is NOT wrapped: texel 0 is exactly the first color, texel 1023 is exactly
+* the last. Shaders that want a mirrored/looping gradient are responsible
+* for remapping their sample coordinate (e.g. abs(fract(t)*2-1)) before
+* sampling this texture.
+*/
+declare function buildPaletteRamp(colors: string[]): Uint8Array;
+//#endregion
+export { type MountHandle, type MountOptions, type ParamDef, type RenderFrameResult, type Renderer, type RendererOptions, type ShaderDef, beam, buildPaletteRamp, createRenderer, flow, getShader, mountGradient, renderGradientFrame, shaders };

package/dist/index.js

@@ -0,0 +1,1120 @@
+//#region src/shaders/noise.ts
+/**
+* 2D simplex noise, copied VERBATIM from the standard reference
+* implementation (Ashima Arts / Ian McEwan, public domain). Do not hand-edit
+* the constants below -- they are fitted values for the simplex lattice
+* skew/unskew and permutation polynomial, not numbers you can derive or
+* "clean up".
+*/
+const SIMPLEX_2D = `
+vec3 mod289_3(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec2 mod289_2(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec3 permute(vec3 x) { return mod289_3(((x * 34.0) + 1.0) * x); }
+
+float snoise(vec2 v) {
+  const vec4 C = vec4(0.211324865405187, 0.366025403784439,
+                     -0.577350269189626, 0.024390243902439);
+  vec2 i  = floor(v + dot(v, C.yy));
+  vec2 x0 = v -   i + dot(i, C.xx);
+  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  vec4 x12 = x0.xyxy + C.xxzz;
+  x12.xy -= i1;
+  i = mod289_2(i);
+  vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0))
+                  + i.x + vec3(0.0, i1.x, 1.0));
+  vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);
+  m = m * m; m = m * m;
+  vec3 x = 2.0 * fract(p * C.www) - 1.0;
+  vec3 h = abs(x) - 0.5;
+  vec3 ox = floor(x + 0.5);
+  vec3 a0 = x - ox;
+  m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);
+  vec3 g;
+  g.x  = a0.x  * x0.x  + h.x  * x0.y;
+  g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+  return 130.0 * dot(m, g);
+}
+`;
+/**
+* Fractal Brownian motion: sums octaves of snoise at doubling frequency
+* (lacunarity 2.0) and halving amplitude (gain 0.5), so each added octave
+* layers in finer detail at proportionally less visual weight. This is
+* what turns a single flat simplex "blob" field into the layered, natural
+* texture readers associate with clouds, drifting currents, or silk. Both
+* variants divide by the total amplitude used so their output stays in
+* roughly [-1, 1] no matter how many octaves are summed -- callers can mix
+* fbm2/fbm3 output the same way they'd mix a raw snoise() call.
+*
+* fbm2 (2 octaves) is cheap and reads as a soft, single-scale warp -- good
+* for silky/large-scale distortion. fbm3 (3 octaves) adds one more, finer
+* top layer for looks that want visible internal detail, at the cost of one
+* extra snoise() evaluation per sample.
+*/
+const FBM = `
+float fbm2(vec2 p) {
+  float sum = 0.0;
+  float amp = 0.5;  // gain: each octave contributes half the previous one's weight
+  float freq = 1.0; // lacunarity: each octave doubles sampling frequency
+  sum += snoise(p * freq) * amp; amp *= 0.5; freq *= 2.0;
+  sum += snoise(p * freq) * amp;
+  return sum / 0.75; // normalize by total amplitude (0.5 + 0.25)
+}
+
+float fbm3(vec2 p) {
+  float sum = 0.0;
+  float amp = 0.5;
+  float freq = 1.0;
+  sum += snoise(p * freq) * amp; amp *= 0.5; freq *= 2.0;
+  sum += snoise(p * freq) * amp; amp *= 0.5; freq *= 2.0;
+  sum += snoise(p * freq) * amp;
+  return sum / 0.875; // normalize by total amplitude (0.5 + 0.25 + 0.125)
+}
+`;
+/**
+* Distribution shaping for palette lookups.
+*
+* `spread(x, sd)` maps a raw fbm value onto [0,1] with an approximately
+* UNIFORM distribution, so every palette stop gets its fair share of screen
+* area. It exists because the obvious remap, `x * 0.5 + 0.5`, does not:
+* summed simplex octaves are roughly Gaussian (fbm2 sd ~0.35, fbm3 sd ~0.31,
+* 90% of samples inside +-0.5), so a linear remap parks ~90% of the image in
+* the middle half of the ramp and the outer stops barely appear. Measured on
+* the linear version: 0-2% of frame for the outer stops of an 8-color bank.
+*
+* The right transform for that is the Gaussian CDF. `sd` is the standard
+* deviation of the fbm being passed in (0.35 for fbm2, 0.31 for fbm3), and
+* the algebraic sigmoid below approximates Phi(x/sd) closely out to about
+* 2 sd. Two things it is deliberately NOT:
+*
+* - not a wide linear gain, which would reach the ramp ends but clip its
+*   tails into flat posterized patches of the end colors;
+* - not a steeper sigmoid. An earlier version normalized so that |x| = 0.8
+*   hit the ramp end exactly, on the theory that the outermost stop should
+*   be reachable. But fbm has real mass well before 0.8, so that version
+*   hard-clamped ~8% of the frame onto EACH end color, and the interior
+*   stops of the 8-color banks collapsed to 3-4% of frame apiece. Reaching
+*   the end color matters much less than not drowning everything else.
+*
+* The residual 1/0.96 stretch is because the algebraic sigmoid has fatter
+* tails than a true Gaussian and would otherwise stop ~4% short of the ramp
+* ends. The clamp is effectively unreachable for real fbm input (it needs
+* |x| > 1.28 at sd 0.35) and is there as a guard, not as a shaping step.
+*/
+const SHAPE = `
+float spread(float x, float sd) {
+  float k = 1.07 * sd; // fitted at the 1-sigma point so s(sd) ~= Phi(1)
+  float s = x / sqrt(x * x + k * k);
+  return clamp(0.5 + 0.5 * s / 0.96, 0.0, 1.0);
+}
+`;
+/**
+* Cheap per-pixel hash noise for film grain -- deliberately NOT simplex
+* based. Grain needs to look like uncorrelated static at the pixel level;
+* a band-limited noise function like snoise would need an impractically
+* huge input scale to look that fine-grained, which would push it right
+* back into the float-precision dead zone described above. Matches the same
+* hash-based grain technique used for this purpose in the InstantGradient
+* app (origin repo). `time` is folded into the hash input (not just added
+* as a phase) so the grain pattern itself re-randomizes every frame instead
+* of sitting static on top of a moving gradient.
+*/
+const GRAIN = `
+float grain(vec2 uv, float time) {
+  vec2 st = uv * 200.0 + time * 0.1; // 200x: grain must read as per-pixel static, not a soft blob
+  return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453);
+}
+`;
+
+//#endregion
+//#region src/shaders/flow.ts
+const FRAGMENT$1 = `
+uniform float u_scale;
+uniform float u_drift;
+uniform float u_openness;
+uniform float u_grain;
+
+${SIMPLEX_2D}
+${FBM}
+${SHAPE}
+${GRAIN}
+
+// Curl of a scalar simplex field: the finite-difference gradient of snoise,
+// rotated 90 degrees -- (dPsi/dy, -dPsi/dx) instead of (dPsi/dx, dPsi/dy).
+// A rotated gradient is always divergence-free, which is the whole trick:
+// advecting a point along it produces swirling motion with nothing to make
+// it converge or diverge, unlike advecting along the gradient itself.
+vec2 curl(vec2 p) {
+  // Finite-difference step: small enough to approximate a derivative,
+  // large enough that snoise's own float precision doesn't swamp the
+  // difference between the two samples.
+  float eps = 0.05;
+  float dx = (snoise(p + vec2(eps, 0.0)) - snoise(p - vec2(eps, 0.0))) / (2.0 * eps);
+  float dy = (snoise(p + vec2(0.0, eps)) - snoise(p - vec2(0.0, eps))) / (2.0 * eps);
+  return vec2(dy, -dx);
+}
+
+void main() {
+  vec2 uv = worldUv();
+  // Slow crawl so currents read as continuous, not jittery. Half the rate an
+  // earlier prototype of this shader used, because this one has leverage: the
+  // drift only enters the curl coordinate, and rotating the advection field
+  // moves the sampled point much further than nudging an fbm coordinate
+  // directly would. At 0.05 (that earlier prototype's rate) the whole
+  // composition reorganized every ~3 seconds, measured as more pixel change
+  // over 3.5s than the beam prototype showed over 7.5s.
+  float drift = u_time * 0.025;
+
+  // Advect the sample point along the curl field in 3 FIXED steps (written
+  // out explicitly rather than a variable-length loop, which risks the
+  // driver's "shader too complex" downsampling heuristic on some GPUs --
+  // see BASE_UNIFORMS / project notes on avoiding uniform-array loops).
+  // Each step nudges the point further along the local current, and it is
+  // the NUMBER of steps that turns advection into rotation: one step is a
+  // plain directional shove, and at two the point still travels an almost
+  // straight chord. The third is where it curves enough to close visible
+  // eddies, which is the whole point of the look. Step gain is dropped from
+  // 0.08 to 0.055 to keep the total travel about where it was.
+  //
+  // The curl field is sampled at 0.55x the fbm's frequency, i.e. the
+  // currents are deliberately LARGER than the colour masses they carry.
+  // Sampled at the same frequency (as it was) each mass sat inside its own
+  // little eddy, so the advection only roughened mass edges and the result
+  // was indistinguishable from a plain warped fbm.
+  float curlScale = u_scale * 0.55;
+  vec2 advected = uv;
+  advected += curl(advected * curlScale + u_seed + drift) * u_drift * 0.055;
+  advected += curl(advected * curlScale + u_seed + drift) * u_drift * 0.055;
+  advected += curl(advected * curlScale + u_seed + drift) * u_drift * 0.055;
+
+  float t = fbm2(advected * u_scale + u_seed);
+
+  // Remap to [0,1]. NOT a plain t * 0.5 + 0.5: fbm2 is roughly Gaussian with
+  // sd ~0.35, so a linear remap parks ~90% of the frame in the middle half of
+  // the ramp. Measured on the linear version, the first palette colour took
+  // 0.0% of the frame on bright-8 and jewel-6. See spread() in noise.ts.
+  t = spread(t, 0.35); // 0.35 = fbm2's standard deviation
+
+  // Openness: mixing toward t*t pulls low values further down (t*t < t for
+  // t in (0,1)) while leaving values near 1 nearly untouched. Low t samples
+  // the palette's first colour, so this widens that colour into the calm
+  // negative space the look is built around, rather than dimming the whole
+  // image uniformly. It has to come AFTER spread(): applied to the raw
+  // Gaussian remap it was biasing an already centre-heavy distribution, which
+  // is what put the washed-out midtone zones on dark-8.
+  t = mix(t, t * t, u_openness);
+
+  // No mirror-wrap: spread() already bounds t to [0,1], so the old
+  // abs(fract(t*0.5)*2-1) reduced to a plain 1 - t. That silent reversal was
+  // also what turned the openness bias above into a bias toward the palette's
+  // LAST colour, which is how the first colour ended up at 0% of frame.
+  //
+  // No final smoothstep either: t is already uniformly distributed and there
+  // is no wrap fold to soften, so an S-curve here would only widen the two
+  // end colours at the expense of everything in between.
+  vec3 color = palette(t);
+
+  // Grain: cheap per-pixel dither, centered at 0 so it can darken or
+  // lighten symmetrically instead of just brightening the whole frame.
+  float g = grain(uv, u_time) - 0.5;
+  color += g * u_grain;
+
+  gl_FragColor = vec4(clamp(color, 0.0, 1.0), 1.0);
+}
+`;
+const flow = {
+	id: "flow",
+	label: "Flow",
+	fragment: FRAGMENT$1,
+	params: [
+		{
+			key: "scale",
+			label: "Scale",
+			min: .6,
+			max: 2.6,
+			step: .05,
+			default: 1.7
+		},
+		{
+			key: "drift",
+			label: "Drift",
+			min: 0,
+			max: 1,
+			step: .01,
+			default: .5
+		},
+		{
+			key: "openness",
+			label: "Openness",
+			min: 0,
+			max: 1,
+			step: .01,
+			default: .28
+		},
+		{
+			key: "grain",
+			label: "Grain",
+			min: 0,
+			max: .3,
+			step: .01,
+			default: .08
+		}
+	],
+	randomParams(rand) {
+		return {
+			scale: .6 + rand() * 2,
+			drift: rand() * 1,
+			openness: rand() * 1,
+			grain: .08
+		};
+	}
+};
+
+//#endregion
+//#region src/shaders/beam.ts
+const FRAGMENT = `
+uniform float u_scale;
+uniform float u_width;
+uniform float u_glow;
+uniform float u_angle;
+uniform float u_grain;
+
+${SIMPLEX_2D}
+${GRAIN}
+
+const float PI = 3.14159265;
+
+// Rec.709 luma weights -- used both to find the palette's darkest stop for
+// the background and to attenuate the white core-lift on bright palettes.
+const vec3 LUMA = vec3(0.2126, 0.7152, 0.0722);
+
+void main() {
+  vec2 uv = worldUv();
+
+  // ---- isotropic beam frame ---------------------------------------------
+  // worldUv() is 0-1 on BOTH axes of a 1000x562.5 world, so one uv unit of x
+  // is 1.78x more screen distance than one of y. flow can ignore that (a
+  // noise field filling the whole frame doesn't care), but a BEAM cannot:
+  // sampled in raw uv, a vertical beam renders 1.78x thinner than a
+  // horizontal one at the same u_width, and the angle param would double as
+  // a hidden thickness control. Scaling x by the world aspect makes the
+  // space isotropic -- a unit circle is a screen circle -- so thickness is
+  // angle-independent. halfIso mirrors worldUv()'s cover fit in the same
+  // space, so the frame's visible half-extents stay correct for a square
+  // preview tile and a 16:9 export alike.
+  float worldAspect = 1000.0 / 562.5;
+  float canvasAspect = u_resolution.x / u_resolution.y;
+  vec2 iso = (uv - 0.5) * vec2(worldAspect, 1.0);
+  vec2 halfIso = vec2(0.5 * min(1.0, canvasAspect / worldAspect),
+                      0.5 * min(1.0, worldAspect / canvasAspect))
+               * vec2(worldAspect, 1.0);
+
+  float ang = u_angle * PI / 180.0;
+  vec2 dir = vec2(cos(ang), sin(ang));
+  vec2 perp = vec2(-dir.y, dir.x);
+
+  // Projections of the frame's corner onto the beam axes: the largest |s|
+  // and |q| the visible frame can produce. halfSpan pins the palette ramp to
+  // the beam's visible length (below); crossHalf scales the seed's
+  // perpendicular placement so "55% toward an edge" means the same thing at
+  // every angle and aspect.
+  float halfSpan  = halfIso.x * abs(dir.x)  + halfIso.y * abs(dir.y);
+  float crossHalf = halfIso.x * abs(perp.x) + halfIso.y * abs(perp.y);
+
+  float s = dot(iso, dir);  // along the beam
+  float q = dot(iso, perp); // across the beam
+  float sn = s / halfSpan;  // -1..1 over the beam's visible length
+
+  // ---- per-instance composition, all derived from u_seed ----------------
+  // seedRow picks which horizontal SLICE of the 2D noise field this
+  // instance's bend lives on: different seeds get
+  // genuinely different curves, not the same curve translated. u_seed is
+  // pre-modded to [0,100), so seedRow stays well inside snoise's precision
+  // range.
+  float seedRow = u_seed * 0.37 + 11.0;
+
+  // Same slow crawl rate as the siblings. It slides the bend's sample window
+  // along the noise slice, so the whole beam sways -- the S migrates -- with
+  // no other motion source needed for the silhouette.
+  float drift = u_time * 0.02;
+
+  // Where the beam sits across the frame. One static seed term (placement)
+  // plus the animated bend. Placement is held to 50% of crossHalf so the
+  // beam never starts life hugging an edge; the bend adds up to ~45% more
+  // locally, and the clamp stops the sum at 75% so the worst seed still
+  // keeps the core inside the frame instead of showing only its halo.
+  float off0 = snoise(vec2(seedRow, 3.7));
+  float bend = snoise(vec2(sn * (0.55 * u_scale) + drift, seedRow));
+  float c = crossHalf * clamp(0.5 * off0 + 0.45 * bend, -0.75, 0.75);
+
+  // Breathing: the width swells ~10% over a ~57s cycle, phase-shifted along
+  // the beam (the sn * 2.0 term) so it travels as a slow peristaltic wave
+  // rather than the whole beam pulsing in lockstep, which read as a strobe
+  // precursor even at this amplitude.
+  float w = u_width * (1.0 + 0.10 * sin(u_time * 0.11 + sn * 2.0 + u_seed));
+
+  // Signed cross distance in units of the beam's own width. Everything
+  // profile-shaped below is a function of this one number.
+  float nd = (q - c) / w;
+  float nd2 = nd * nd;
+
+  // ---- the two profiles --------------------------------------------------
+  // core: exp(-nd^4). A plain Gaussian (exp(-nd^2)) was tried first and is
+  // exactly the old shader's mistake in one dimension -- its long tails mean
+  // the "edge" is a 2-width-wide smear and the silhouette dissolves. The
+  // quartic exponent gives a flat luminous top and a falloff that is soft
+  // but FAST (0.22 at one width, 0.01 at 1.3 widths), which is what makes
+  // the streak readable as a shape while still having no hard line anywhere.
+  float core = exp(-nd2 * nd2 * 1.5);
+  // halo: a wide true Gaussian, ~3x the core's width, carrying the "light
+  // leak" atmosphere into the dark. This one WANTS long tails -- it is the
+  // diffuse spill, and u_glow scales it (below) rather than the core, so
+  // the glow slider changes how far the light bleeds without ever blurring
+  // the silhouette itself.
+  float halo = exp(-nd2 * 0.28);
+
+  // ---- palette along the beam --------------------------------------------
+  // sn is -1..1 over the visible length, so this sweeps the whole ramp
+  // corner to corner. The 1.05 overdrive tucks the exact ramp ends a hair
+  // outside the frame; palette() clamps, so the first and last stops each
+  // hold a short solid run at the beam's ends instead of appearing only in
+  // the final pixel row.
+  float t = clamp(sn * 1.05 * 0.5 + 0.5, 0.0, 1.0);
+
+  // ---- internal filaments ------------------------------------------------
+  // One noise field does both filament jobs. Its anisotropy is the point:
+  // high frequency ACROSS the beam (nd * 2.6), low frequency ALONG it
+  // (0.9 * u_scale over a 2-unit sn range), so its iso-lines are long
+  // streaks running WITH the beam that wander slowly -- hair-thin light
+  // strands, not speckle. The crawl term slides the field along s at ~2.5x
+  // the sway rate, giving the "light travelling down the beam" motion the
+  // brief asks for while the silhouette itself barely moves.
+  // Sampled in ABSOLUTE cross-distance (q - c), not width-relative nd: in nd
+  // units the field gets magnified with the beam, and past width ~0.25 its
+  // ridge lines blew up into jagged chevron kinks. Absolute sampling keeps
+  // strands hair-thin at every width (26.0 = the old 2.6/nd density at the
+  // original 0.1 default, preserving the approved look there).
+  float crawl = u_time * 0.05;
+  float fil = snoise(vec2(sn * (0.9 * u_scale) - crawl, (q - c) * 26.0 + seedRow * 1.7));
+
+  // Holographic banding: the same field nudges the ramp position inside the
+  // core, so colour bands streak lengthwise through the beam (the foil-like
+  // internal banding of the second reference). 0.05 is about half a stop's
+  // width on an 8-colour bank -- enough to see, never enough to reorder the
+  // sequence. Masked by core so the banding cannot tint the background.
+  t = clamp(t + 0.05 * fil * core, 0.0, 1.0);
+
+  // Bright filament lines: the ridge transform (1 - |noise|) peaks where the
+  // field crosses zero, i.e. along thin wandering lines. The 0.78 threshold
+  // keeps only the top ~10% of the ridge, which at this anisotropy yields
+  // 2-3 visible strands inside the core.
+  //
+  // The wideFade term keeps the extended width range clean: with absolute
+  // cross-sampling a wide beam fits MANY strands, which reads busy right
+  // when the "wall of light" settings want a pure soft field. Fading the
+  // lines out over the top half of the width range hands the wide beam to
+  // the halo + grain alone.
+  float wideFade = 1.0 - smoothstep(0.25, 0.5, u_width);
+  float filLine = smoothstep(0.78, 0.97, 1.0 - abs(fil)) * wideFade;
+
+  // ---- background: the palette's darkest stop, crushed --------------------
+  // Sample three fixed ramp positions and keep the darkest (branchless --
+  // step/mix, no if-ladder). Three samples is enough: palette() is an OKLCh
+  // ramp, so the darkest point of the whole ramp is always at or near a
+  // stop, and ends+middle bracket every bank in the lab set. The 0.12
+  // multiplier is the "mixed ~88% toward black" from the art direction:
+  // dark enough that even cream-4's darkest stop reads as near-black, light
+  // enough that the tint survives (measured ~RGB 20-30 on mid banks).
+  vec3 cA = palette(0.0);
+  vec3 cB = palette(0.5);
+  vec3 cC = palette(1.0);
+  float lA = dot(cA, LUMA);
+  float lB = dot(cB, LUMA);
+  float lC = dot(cC, LUMA);
+  vec3 dk = mix(cA, cB, step(lB, lA));
+  float ld = min(lA, lB);
+  dk = mix(dk, cC, step(lC, ld));
+  vec3 bg = dk * 0.12;
+
+  // ---- compositing: additive light on the dark ----------------------------
+  // Everything below ADDS light to bg, never mixes toward it -- on a dark
+  // ground, additive is what makes the beam read as emission rather than as
+  // a painted stripe.
+  vec3 beamCol = palette(t);
+  float blum = dot(beamCol, LUMA);
+
+  // Luma-compensating gain on the whole beam stack. The stack below sums to
+  // ~1.65x beamCol at the centerline; on a bright bank (pastel-5, cream-4,
+  // whose stops sit near luma 0.9) that clipped every channel and the entire
+  // beam collapsed into one featureless white band -- the palette sequence,
+  // the filaments and the silhouette's soft edge all vanished into the
+  // clamp. Dividing by 1 + 1.2*luma^2 caps the bright banks' centerline
+  // near 0.95 (hues survive, edge survives) while the quadratic leaves dark
+  // banks -- which NEED the full additive energy to register at all --
+  // almost untouched.
+  float gain = 1.0 / (1.0 + 1.2 * blum * blum);
+
+  vec3 color = bg;
+
+  // Halo first (widest, dimmest). The 0.10 floor keeps a trace of spill even
+  // at glow 0 so the beam never looks laser-cut out of the dark; u_glow
+  // scales the rest, which is the slider's entire visible job.
+  color += beamCol * halo * (0.10 + 0.40 * u_glow) * gain;
+
+  // The core -- the beam's body. The chroma boost is the dark-bank mirror of
+  // gain: multiplying a dark stop up (rather than adding white to it)
+  // scales all three channels together, so dark-8's muted violets and blues
+  // brighten WITHOUT greying out -- the first pass leaned on the white lift
+  // alone and the whole beam read as monochrome silver on the dark banks.
+  // Cubic in (1 - luma) so it is ~1.0 for any mid-or-brighter bank and only
+  // really wakes up below luma ~0.3, where there is guaranteed headroom.
+  float boost = 1.0 + 2.0 * (1.0 - blum) * (1.0 - blum) * (1.0 - blum);
+  color += beamCol * core * gain * boost;
+
+  // A hot centerline: core^2 halves the effective width, so this reads as
+  // the brightest inner lane of the beam. Palette-coloured, not white,
+  // because a white hotline desaturated the saturated banks (neon-5) into
+  // pastel -- same failure the old shader documented for its bloom.
+  color += beamCol * core * core * 0.35 * gain;
+
+  // The one white term, and it is gated hard: (1 - luma)^2 means it only
+  // registers where the palette itself is dark. This is the floor for
+  // near-black-3, whose stops are so dark that even the chroma boost above
+  // cannot lift them to visibility (3x of luma 0.03 is still 0.09) -- some
+  // achromatic light is the only thing that can separate that bank's beam
+  // from its own backdrop. Kept smaller than the boost's contribution so it
+  // supplements the colour instead of silvering it, and quadratic (not
+  // linear) falloff, quadratic because linear still
+  // chalked the pastels.
+  color += vec3((1.0 - blum) * (1.0 - blum) * core * core * (0.08 + 0.16 * u_glow));
+
+  // Filaments ride on top, inside the core only. Mostly beam-coloured with
+  // a small dark-gated white lift so they also survive the near-black banks.
+  color += (beamCol * 0.6 + vec3(0.4 * (1.0 - blum))) * filLine * core * 0.45;
+
+  // No secondary echo streak: an earlier version had one, and the owner read
+  // it as a second competing pattern -- ONE beam is the composition, full
+  // stop. The negative space it left behind is carried by grain alone.
+
+  // Grain: cheap per-pixel dither, centered at 0 so it can darken or lighten
+  // symmetrically. It matters more here than in any sibling: the dark field
+  // is most of the frame, and grain is the only thing giving it surface --
+  // without it the negative space reads as dead #000 flatness instead of
+  // atmosphere.
+  float g = grain(uv, u_time) - 0.5;
+  color += g * u_grain;
+
+  gl_FragColor = vec4(clamp(color, 0.0, 1.0), 1.0);
+}
+`;
+const beam = {
+	id: "beam",
+	label: "Beam",
+	fragment: FRAGMENT,
+	params: [
+		{
+			key: "scale",
+			label: "Scale",
+			min: .5,
+			max: 2,
+			step: .05,
+			default: 1
+		},
+		{
+			key: "width",
+			label: "Width",
+			min: .04,
+			max: .6,
+			step: .005,
+			default: .14
+		},
+		{
+			key: "glow",
+			label: "Glow",
+			min: 0,
+			max: 1,
+			step: .01,
+			default: .5
+		},
+		{
+			key: "angle",
+			label: "Angle",
+			min: 0,
+			max: 360,
+			step: 1,
+			default: 28
+		},
+		{
+			key: "grain",
+			label: "Grain",
+			min: 0,
+			max: .3,
+			step: .01,
+			default: .08
+		}
+	],
+	randomParams(rand) {
+		return {
+			scale: .7 + rand() * .8,
+			width: .09 + rand() * .15,
+			glow: .3 + rand() * .5,
+			angle: rand() * 360,
+			grain: .08
+		};
+	}
+};
+
+//#endregion
+//#region src/registry.ts
+const shaders = [flow, beam];
+function getShader(id) {
+	return shaders.find((s) => s.id === id);
+}
+
+//#endregion
+//#region src/palette.ts
+/** Number of texels in the output ramp. Matches a typical 1D LUT texture size:
+* large enough that per-texel banding is invisible, small enough to upload
+* as a single texture row every time colors change. */
+const RAMP_SIZE = 1024;
+/**
+* Converts one sRGB channel (0-1, gamma-encoded) to linear light.
+* Piecewise per the sRGB spec: a linear segment near black avoids the
+* infinite slope a pure power curve would have at 0.
+*/
+function linearize(c) {
+	return c <= .04045 ? c / 12.92 : Math.pow((c + .055) / 1.055, 2.4);
+}
+/** Inverse of linearize(): linear light back to gamma-encoded sRGB (0-1). */
+function delinearize(c) {
+	return c <= .0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - .055;
+}
+/**
+* sRGB -> OKLab, Björn Ottosson's method (https://bottosson.github.io/posts/oklab/).
+* Coefficients copied verbatim from that reference implementation —
+* do not hand-retype these, they are fitted constants, not derivable values.
+*
+* The two 3x3 matrices convert linear sRGB to an LMS-like cone response
+* space and then to the final Lab-like OKLab space; the cube root in
+* between is what makes the space perceptually uniform.
+*/
+function rgbToOklab(r, g, b) {
+	const lr = linearize(r), lg = linearize(g), lb = linearize(b);
+	const l_ = Math.cbrt(.4122214708 * lr + .5363325363 * lg + .0514459929 * lb);
+	const m_ = Math.cbrt(.2119034982 * lr + .6806995451 * lg + .1073969566 * lb);
+	const s_ = Math.cbrt(.0883024619 * lr + .2817188376 * lg + .6299787005 * lb);
+	return [
+		.2104542553 * l_ + .793617785 * m_ - .0040720468 * s_,
+		1.9779984951 * l_ - 2.428592205 * m_ + .4505937099 * s_,
+		.0259040371 * l_ + .7827717662 * m_ - .808675766 * s_
+	];
+}
+/**
+* OKLab -> sRGB, inverse of rgbToOklab. Same fitted-constant caveat as
+* above — do not hand-retype these coefficients.
+*/
+function oklabToRgb(L, a, b) {
+	const l_ = L + .3963377774 * a + .2158037573 * b;
+	const m_ = L - .1055613458 * a - .0638541728 * b;
+	const s_ = L - .0894841775 * a - 1.291485548 * b;
+	const l = l_ * l_ * l_, m = m_ * m_ * m_, s = s_ * s_ * s_;
+	return [
+		delinearize(4.0767416621 * l - 3.3077115913 * m + .2309699292 * s),
+		delinearize(-1.2684380046 * l + 2.6097574011 * m - .3413193965 * s),
+		delinearize(-.0041960863 * l - .7034186147 * m + 1.707614701 * s)
+	];
+}
+/**
+* OKLab -> OKLCh: rectangular (L, a, b) to polar (L, C, h). C is just the
+* distance of (a, b) from the achromatic origin; h is the angle, in
+* radians, measured the same way atan2 always does (range (-pi, pi]).
+*/
+function oklabToOklch(L, a, b) {
+	return [
+		L,
+		Math.hypot(a, b),
+		Math.atan2(b, a)
+	];
+}
+/**
+* OKLCh -> OKLab: polar back to rectangular, so the existing oklabToRgb
+* matrices can be reused unchanged instead of duplicating the LMS math for
+* a polar input.
+*/
+function oklchToOklab(L, C, h) {
+	return [
+		L,
+		C * Math.cos(h),
+		C * Math.sin(h)
+	];
+}
+/**
+* Chroma below which a hue angle is noise rather than signal. Near a=b=0,
+* atan2 is numerically unstable (its output can swing wildly for a tiny
+* change in a near-zero a or b), and perceptually a near-gray stop simply
+* doesn't have a hue to speak of. Below this threshold a stop is treated as
+* achromatic for interpolation purposes: see lerpHue().
+*
+* ~0.005 in OKLCh chroma units is comfortably below any stop actually used
+* for color (the lab palettes' least-saturated non-neutral stops sit at
+* 0.075+) and comfortably above float rounding noise from the hex -> OKLab
+* round trip.
+*/
+const ACHROMATIC_CHROMA = .005;
+const TAU = Math.PI * 2;
+/**
+* Interpolates hue from h0 toward h1 by fraction t, taking the SHORTER way
+* around the circle (e.g. 350deg -> 10deg moves +20deg through 0, not -340deg
+* backward through 180deg) instead of a plain linear lerp, which would sweep
+* through every intermediate hue on the long way round.
+*
+* Two edge cases handled explicitly:
+*
+* - Achromatic endpoint: if one side's chroma is below ACHROMATIC_CHROMA,
+*   its "hue" is meaningless (see the constant's comment), so it inherits
+*   the other endpoint's hue instead of contributing its own noisy angle.
+*   Concretely this means a gray-to-color segment holds a constant hue
+*   while only chroma ramps up, rather than spiraling through unrelated
+*   hues the gray's atan2 noise happened to produce. If both endpoints are
+*   achromatic the chosen hue is never visible: C stays near zero for the
+*   whole segment (it's lerped independently, from ~0 to ~0), so whatever
+*   angle comes out of cos/sin gets multiplied by ~0.
+* - Exact opposition (180 degrees apart): both directions around the circle
+*   are equally short, so "shorter arc" is ambiguous. The wrap below always
+*   normalizes a signed delta of exactly +-pi to -pi (see the comment on
+*   the wrap), which picks one direction consistently rather than depending
+*   on float rounding to break the tie.
+*/
+function lerpHue(h0, c0, h1, c1, t) {
+	const start = c0 < ACHROMATIC_CHROMA && c1 >= ACHROMATIC_CHROMA ? h1 : h0;
+	let delta = (c1 < ACHROMATIC_CHROMA && c0 >= ACHROMATIC_CHROMA ? h0 : h1) - start;
+	delta -= TAU * Math.round(delta / TAU);
+	return start + delta * t;
+}
+/** Parses a "#rrggbb" (or "rrggbb") hex string into 0-1 sRGB components. */
+function hexToRgb(hex) {
+	const h = hex.replace("#", "");
+	return [
+		parseInt(h.substring(0, 2), 16) / 255,
+		parseInt(h.substring(2, 4), 16) / 255,
+		parseInt(h.substring(4, 6), 16) / 255
+	];
+}
+/**
+* Builds a 1024-texel RGBA ramp (Uint8Array, length 1024*4) by interpolating
+* the given hex color stops in OKLCh space (see the top-of-file comment for
+* why polar rather than Cartesian OKLab).
+*
+* Stops are placed at evenly spaced positions: color i sits at t = i/(n-1)
+* (a single-color palette is treated as that color duplicated at t=0 and
+* t=1, so it produces a flat ramp rather than dividing by zero). The ramp
+* is NOT wrapped: texel 0 is exactly the first color, texel 1023 is exactly
+* the last. Shaders that want a mirrored/looping gradient are responsible
+* for remapping their sample coordinate (e.g. abs(fract(t)*2-1)) before
+* sampling this texture.
+*/
+function buildPaletteRamp(colors) {
+	if (colors.length === 0) throw new Error("buildPaletteRamp requires at least one color");
+	const stops = colors.length === 1 ? [colors[0], colors[0]] : colors;
+	const stopCount = stops.length;
+	const stopsOklch = stops.map((hex) => {
+		const [r, g, b] = hexToRgb(hex);
+		return oklabToOklch(...rgbToOklab(r, g, b));
+	});
+	const breakpoints = [];
+	for (let j = 0; j < stopCount; j++) breakpoints.push(Math.floor(j * (RAMP_SIZE - 1) / (stopCount - 1)));
+	const out = new Uint8Array(RAMP_SIZE * 4);
+	let seg = 0;
+	for (let i = 0; i < RAMP_SIZE; i++) {
+		while (seg < stopCount - 2 && i > breakpoints[seg + 1]) seg++;
+		const segStart = breakpoints[seg];
+		const segEnd = breakpoints[seg + 1];
+		const localT = segEnd === segStart ? 0 : (i - segStart) / (segEnd - segStart);
+		const [L0, C0, h0] = stopsOklch[seg];
+		const [L1, C1, h1] = stopsOklch[seg + 1];
+		const L = L0 + (L1 - L0) * localT;
+		const [, a, bLab] = oklchToOklab(L, C0 + (C1 - C0) * localT, lerpHue(h0, C0, h1, C1, localT));
+		const [r, g, b] = oklabToRgb(L, a, bLab);
+		const idx = i * 4;
+		out[idx] = clamp255(r);
+		out[idx + 1] = clamp255(g);
+		out[idx + 2] = clamp255(b);
+		out[idx + 3] = 255;
+	}
+	return out;
+}
+/** Converts a 0-1 linear-ish sRGB channel to a clamped 0-255 byte. OKLab
+* round-trips can slightly overshoot 0-1 for saturated/out-of-gamut
+* midpoints, so clamping (rather than wrapping) is required here. */
+function clamp255(v) {
+	return Math.max(0, Math.min(255, Math.round(v * 255)));
+}
+
+//#endregion
+//#region src/renderer.ts
+/**
+* GLSL preamble prepended to every shader's fragment source. Declares the
+* uniforms/varying every InstantShader shader can rely on, plus two helpers:
+*
+* - `worldUv()`: maps the 0-1 quad UV into a fixed 1000x562.5 "world" space,
+*   cover-fit to the canvas aspect ratio. Shaders should sample noise/pattern
+*   functions with this instead of the raw UV so pattern density (frequency
+*   of waves, blobs, etc) stays identical between a small preview and a 4K
+*   export of the same scene — otherwise the same "scale" param would look
+*   like a completely different pattern at different resolutions.
+* - `palette(t)`: samples the 1D OKLCh-interpolated color ramp texture.
+*
+* `u_time` and `u_seed` arrive pre-modded (see renderAt below) so that a
+* shader doing `sin(u_time * freq)` never loses float32 precision from a
+* time value that has grown large over a long-running session.
+*/
+const BASE_UNIFORMS = `precision highp float;
+uniform vec2 u_resolution;   // canvas pixels
+uniform float u_time;        // seconds, pre-modded to [0,1000)
+uniform float u_seed;        // pre-modded to [0,100)
+uniform sampler2D u_palette; // 1024x1 OKLCh-interpolated ramp
+varying vec2 v_uv;           // 0-1 quad UV
+// World-space UV: cover-fit a fixed 1000x562.5 world so pattern density
+// is identical between the preview and a 4K export of the same scene.
+vec2 worldUv() {
+  float worldAspect = 1000.0 / 562.5;
+  float canvasAspect = u_resolution.x / u_resolution.y;
+  vec2 uv = v_uv - 0.5;
+  if (canvasAspect > worldAspect) { uv.y *= worldAspect / canvasAspect; }
+  else { uv.x *= canvasAspect / worldAspect; }
+  return uv + 0.5;
+}
+vec3 palette(float t) {
+  return texture2D(u_palette, vec2(clamp(t, 0.0, 1.0), 0.5)).rgb;
+}
+`;
+/** Fullscreen-triangle-strip vertex shader. Four vertices covering [-1,1]^2,
+* with v_uv carrying the matching 0-1 UV for the fragment shader. */
+const VERTEX_SHADER = `attribute vec2 a_position;
+varying vec2 v_uv;
+void main() {
+  v_uv = a_position * 0.5 + 0.5;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`;
+const QUAD_VERTICES = new Float32Array([
+	-1,
+	-1,
+	1,
+	-1,
+	-1,
+	1,
+	1,
+	1
+]);
+/** Non-negative modulo. JS's `%` is a remainder operator, not a mathematical
+* mod — `-5 % 100` is `-5`, not `95`. u_time/u_seed are documented to land
+* in [0, m), so a negative timeMs (e.g. from an out-of-range seek) or a
+* negative seed must still floor into that range rather than going negative
+* on the GPU. */
+function floorMod(value, m) {
+	return (value % m + m) % m;
+}
+/** Compiles one shader stage, logging the info log and throwing on failure
+* so a broken ShaderDef fails loudly at mount time instead of rendering a
+* blank canvas. */
+function compileShader(gl, type, source) {
+	const shader = gl.createShader(type);
+	if (!shader) throw new Error("[instantshader] gl.createShader returned null");
+	gl.shaderSource(shader, source);
+	gl.compileShader(shader);
+	if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+		const info = gl.getShaderInfoLog(shader);
+		gl.deleteShader(shader);
+		console.error("[instantshader] shader compile error:", info);
+		throw new Error(`[instantshader] shader compile error: ${info}`);
+	}
+	return shader;
+}
+/** Links a vertex + fragment shader pair into a program, logging and
+* throwing on link failure (e.g. varying mismatch between stages). */
+function linkProgram(gl, vertexShader, fragmentShader) {
+	const program = gl.createProgram();
+	if (!program) throw new Error("[instantshader] gl.createProgram returned null");
+	gl.attachShader(program, vertexShader);
+	gl.attachShader(program, fragmentShader);
+	gl.linkProgram(program);
+	if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+		const info = gl.getProgramInfoLog(program);
+		gl.deleteShader(vertexShader);
+		gl.deleteShader(fragmentShader);
+		gl.deleteProgram(program);
+		console.error("[instantshader] program link error:", info);
+		throw new Error(`[instantshader] program link error: ${info}`);
+	}
+	return program;
+}
+function createRenderer(opts) {
+	const { canvas, shader } = opts;
+	let colors = opts.colors;
+	let params = opts.params;
+	const seed = opts.seed;
+	const glOrNull = canvas.getContext("webgl", {
+		preserveDrawingBuffer: true,
+		antialias: false
+	});
+	if (!glOrNull) throw new Error("[instantshader] failed to acquire a WebGL context");
+	const gl = glOrNull;
+	const vertexShader = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
+	const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER, BASE_UNIFORMS + shader.fragment);
+	const program = linkProgram(gl, vertexShader, fragmentShader);
+	gl.deleteShader(vertexShader);
+	gl.deleteShader(fragmentShader);
+	gl.useProgram(program);
+	const quadBuffer = gl.createBuffer();
+	gl.bindBuffer(gl.ARRAY_BUFFER, quadBuffer);
+	gl.bufferData(gl.ARRAY_BUFFER, QUAD_VERTICES, gl.STATIC_DRAW);
+	const positionLoc = gl.getAttribLocation(program, "a_position");
+	gl.enableVertexAttribArray(positionLoc);
+	gl.vertexAttribPointer(positionLoc, 2, gl.FLOAT, false, 0, 0);
+	const paletteTexture = gl.createTexture();
+	gl.bindTexture(gl.TEXTURE_2D, paletteTexture);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+	function uploadPalette(hexColors) {
+		const ramp = buildPaletteRamp(hexColors);
+		gl.bindTexture(gl.TEXTURE_2D, paletteTexture);
+		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1024, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, ramp);
+	}
+	uploadPalette(colors);
+	const resolutionLoc = gl.getUniformLocation(program, "u_resolution");
+	const timeLoc = gl.getUniformLocation(program, "u_time");
+	const seedLoc = gl.getUniformLocation(program, "u_seed");
+	const paletteLoc = gl.getUniformLocation(program, "u_palette");
+	const paramLocs = /* @__PURE__ */ new Map();
+	for (const paramDef of shader.params) paramLocs.set(paramDef.key, gl.getUniformLocation(program, `u_${paramDef.key}`));
+	function applyParams() {
+		for (const paramDef of shader.params) {
+			const loc = paramLocs.get(paramDef.key);
+			if (loc == null) continue;
+			const value = params[paramDef.key] ?? paramDef.default;
+			gl.uniform1f(loc, value);
+		}
+	}
+	function renderAt(timeMs) {
+		gl.viewport(0, 0, canvas.width, canvas.height);
+		gl.useProgram(program);
+		gl.uniform2f(resolutionLoc, canvas.width, canvas.height);
+		const timeSec = floorMod(timeMs / 1e3, 1e3);
+		gl.uniform1f(timeLoc, timeSec);
+		gl.uniform1f(seedLoc, floorMod(seed, 100));
+		gl.activeTexture(gl.TEXTURE0);
+		gl.bindTexture(gl.TEXTURE_2D, paletteTexture);
+		gl.uniform1i(paletteLoc, 0);
+		applyParams();
+		gl.bindBuffer(gl.ARRAY_BUFFER, quadBuffer);
+		gl.enableVertexAttribArray(positionLoc);
+		gl.vertexAttribPointer(positionLoc, 2, gl.FLOAT, false, 0, 0);
+		gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+	}
+	function setColors(next) {
+		colors = next;
+		uploadPalette(colors);
+	}
+	function setParams(next) {
+		params = next;
+	}
+	function resize(width, height) {
+		canvas.width = width;
+		canvas.height = height;
+	}
+	function dispose() {
+		gl.deleteTexture(paletteTexture);
+		gl.deleteProgram(program);
+		gl.deleteBuffer(quadBuffer);
+		gl.getExtension("WEBGL_lose_context")?.loseContext();
+	}
+	return {
+		renderAt,
+		setColors,
+		setParams,
+		resize,
+		dispose
+	};
+}
+
+//#endregion
+//#region src/params.ts
+/** Builds a full param record (every ParamDef.key present) from a possibly
+* partial override map, falling back to each param's declared default. */
+function resolveParams(def, overrides) {
+	const resolved = {};
+	for (const paramDef of def.params) {
+		const value = overrides?.[paramDef.key];
+		resolved[paramDef.key] = value === void 0 ? paramDef.default : value;
+	}
+	return resolved;
+}
+
+//#endregion
+//#region src/mount.ts
+/**
+* Mounts a live, animated gradient into `container` and returns a handle to
+* control it. Owns a canvas (sized to the container via ResizeObserver, DPR
+* capped at 2 to bound fill-rate cost on high-density displays) and a RAF
+* loop that runs ONLY while playing — the same lifecycle used by the
+* InstantGradient app's canvas preview, which stops scheduling
+* requestAnimationFrame entirely while paused/frozen rather than continuing
+* to tick with no-op frames. pause() cancels the
+* in-flight frame and freezes `clockMs`; resume() restarts the loop from
+* there. Since the loop is fully stopped while paused, setColors/setParams/
+* seek/resize (via the ResizeObserver) each trigger a single on-demand
+* `renderer.renderAt(clockMs)` so a paused canvas still repaints immediately
+* instead of going stale until the next resume() — this matters because
+* callers may mount many simultaneously-paused instances (e.g. a screenshot
+* grid) that must never carry a perpetual 60fps draw loop each.
+*/
+function mountGradient(container, opts) {
+	const def = opts.shader;
+	const canvas = document.createElement("canvas");
+	canvas.style.display = "block";
+	canvas.style.width = "100%";
+	canvas.style.height = "100%";
+	container.appendChild(canvas);
+	let colors = opts.colors;
+	let params = resolveParams(def, opts.params);
+	let speed = opts.speed ?? 1;
+	const seed = opts.seed ?? 0;
+	const renderer = createRenderer({
+		canvas,
+		shader: def,
+		colors,
+		params,
+		seed
+	});
+	let clockMs = 0;
+	let epoch = performance.now();
+	let playing = true;
+	let disposed = false;
+	let rafId = 0;
+	/** Resyncs `epoch` so that (now - epoch) * speed === clockMs, i.e. the
+	* next tick continues smoothly from the current position at the current
+	* speed. Guards speed === 0 since that division is undefined and the
+	* product would be zero regardless of epoch. */
+	function resyncEpoch() {
+		const now = performance.now();
+		epoch = speed === 0 ? now : now - clockMs / speed;
+	}
+	/** Draws the current clock position once, without touching the RAF loop.
+	* Used so paused-canvas mutations (colors/params/size) show up right
+	* away instead of waiting for the next resume(). */
+	function renderOnce() {
+		renderer.renderAt(clockMs);
+	}
+	function tick() {
+		if (speed !== 0) clockMs = (performance.now() - epoch) * speed;
+		renderer.renderAt(clockMs);
+		rafId = requestAnimationFrame(tick);
+	}
+	rafId = requestAnimationFrame(tick);
+	function applySize(cssWidth, cssHeight) {
+		const dpr = Math.min(window.devicePixelRatio || 1, 2);
+		const width = Math.max(1, Math.round(cssWidth * dpr));
+		const height = Math.max(1, Math.round(cssHeight * dpr));
+		if (canvas.width !== width || canvas.height !== height) {
+			renderer.resize(width, height);
+			if (!playing) renderOnce();
+		}
+	}
+	const initialRect = container.getBoundingClientRect();
+	applySize(initialRect.width || 1, initialRect.height || 1);
+	const resizeObserver = new ResizeObserver((entries) => {
+		for (const entry of entries) applySize(entry.contentRect.width, entry.contentRect.height);
+	});
+	resizeObserver.observe(container);
+	return {
+		canvas,
+		setColors(next) {
+			colors = next;
+			renderer.setColors(colors);
+			if (!playing) renderOnce();
+		},
+		setParams(next) {
+			params = {
+				...params,
+				...next
+			};
+			renderer.setParams(params);
+			if (!playing) renderOnce();
+		},
+		setSpeed(next) {
+			if (playing && speed !== 0) clockMs = (performance.now() - epoch) * speed;
+			speed = next;
+			resyncEpoch();
+		},
+		pause() {
+			if (!playing) return;
+			if (speed !== 0) clockMs = (performance.now() - epoch) * speed;
+			playing = false;
+			cancelAnimationFrame(rafId);
+			renderOnce();
+		},
+		resume() {
+			if (playing) return;
+			playing = true;
+			resyncEpoch();
+			rafId = requestAnimationFrame(tick);
+		},
+		seek(ms) {
+			clockMs = ms;
+			resyncEpoch();
+			if (!playing) renderOnce();
+		},
+		getTimeMs() {
+			return clockMs;
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			cancelAnimationFrame(rafId);
+			resizeObserver.disconnect();
+			renderer.dispose();
+			canvas.remove();
+		}
+	};
+}
+
+//#endregion
+//#region src/frame.ts
+/**
+* Renders a single frame into a detached (not-in-DOM) canvas at an exact
+* pixel size, for export/thumbnail use cases that need a synchronous
+* snapshot rather than a live animation.
+*
+* The returned canvas is NOT disposed automatically — its GL context must
+* stay alive after this function returns so callers can scrape pixels from
+* it (toDataURL/toBlob/getImageData/drawImage). Once the caller is done
+* with it, release the GL context by calling the returned `dispose()`.
+*/
+function renderGradientFrame(opts) {
+	const def = opts.shader;
+	const canvas = document.createElement("canvas");
+	canvas.width = opts.width;
+	canvas.height = opts.height;
+	const renderer = createRenderer({
+		canvas,
+		shader: def,
+		colors: opts.colors,
+		params: resolveParams(def, opts.params),
+		seed: opts.seed ?? 0
+	});
+	renderer.renderAt(opts.timeMs ?? 0);
+	const gl = canvas.getContext("webgl");
+	if (gl) {
+		const pixel = new Uint8Array(4);
+		gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
+	}
+	return {
+		canvas,
+		dispose: renderer.dispose
+	};
+}
+
+//#endregion
+export { beam, buildPaletteRamp, createRenderer, flow, getShader, mountGradient, renderGradientFrame, shaders };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "instantshader",
+  "version": "0.1.0",
+  "description": "Animated WebGL gradient shaders. Zero dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ugolbck/instantshader.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://instantgradient.com/shaders",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "webgl",
+    "shader",
+    "gradient",
+    "mesh-gradient",
+    "animated-gradient",
+    "background"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint:pkg": "publint && attw --pack . --profile esm-only"
+  }
+}