instantshader 0.1.0 → 0.3.0

package/README.md

@@ -22,3 +22,51 @@ const handle = mountGradient(document.getElementById("bg")!, {
 
 // handle.pause() / handle.resume() / handle.dispose() when done
 ```
+
+## Seamless loops
+
+Set `loopSeconds` and the animation repeats exactly, with no visible seam at
+the wrap — the frame at `t` and at `t + loopSeconds` are identical pixel for
+pixel. Built for video export and for backgrounds that must not betray a
+restart.
+
+```ts
+mountGradient(el, { shader: flow, colors, loopSeconds: 30 });
+```
+
+It works the same on the one-shot renderer, which is how you'd drive an
+encoder:
+
+```ts
+const LOOP = 20;
+for (let frame = 0; frame < 30 * LOOP; frame++) {
+  const { canvas, dispose } = renderGradientFrame({
+    shader: flow,
+    colors,
+    loopSeconds: LOOP,
+    timeMs: (frame / 30) * 1000,
+    width: 1920,
+    height: 1080,
+  });
+  // ...encode canvas, then:
+  dispose();
+}
+```
+
+Notes:
+
+- The period is measured in **animation** seconds, so it interacts with
+  `speed`: a 90s loop at `speed: 4` completes in 22.5 wall-clock seconds while
+  still containing 90 seconds of motion. That pairing is how you get a short,
+  light video file without slowing the animation down.
+- **`flow` ties its travel speed to the loop length.** It animates by
+  translating in a straight line through a noise field that tiles, and it
+  covers exactly one tile per cycle — so a short loop flows fast and a long
+  one flows slowly. The hand-tuned drift rate corresponds to a period around
+  60–90s; below ~30s the currents move noticeably faster than the look was
+  designed for. Compensate with `speed` rather than by shortening the loop.
+- **`beam` freezes its width swell below ~29s.** Its natural cycle is ~57s and
+  cannot be squeezed into a short loop without becoming a throb, so under that
+  threshold the swell holds still instead. Everything else still animates.
+- Any loop necessarily revisits the same state every N seconds; a long period
+  is what buys the impression of never repeating.

package/dist/index.d.ts

@@ -4,6 +4,9 @@ type Renderer = {
   renderAt(timeMs: number): void;
   setColors(colors: string[]): void;
   setParams(params: Record<string, number>): void;
+  /** Sets the seamless-loop period in animation seconds; 0/undefined disables
+  * looping. See RendererOptions.loopSeconds. */
+  setLoopSeconds(seconds: number | undefined): void;
   resize(width: number, height: number): void;
   dispose(): void;
 };
@@ -56,6 +59,23 @@ type MountOptions = {
   speed?: number;
   /** RNG seed for any randomized/time-offset behavior. Defaults to 0. */
   seed?: number;
+  /**
+  * Makes the animation repeat exactly every `loopSeconds`, with no visible
+  * seam at the wrap — the frame at t and at t + loopSeconds are identical
+  * pixel for pixel. Intended for video export and for backgrounds that must
+  * not betray a restart. Omit (the default) for an animation that never
+  * repeats.
+  *
+  * Measured in ANIMATION seconds, so it interacts with `speed`: a 10s loop
+  * at speed 2 completes in 5 wall-clock seconds. Leave `speed` at 1 when
+  * exporting to a fixed-length video.
+  *
+  * Short periods are where the cost shows. Under ~29s beam's width swell
+  * stops animating (see loopFreq in the GLSL preamble), and below ~10s the
+  * rotation of the drift direction becomes noticeable as a slow circling of
+  * the whole composition. 15-60s is the comfortable range.
+  */
+  loopSeconds?: number;
 };
 /** Live handle returned by mount(), used to control a running gradient instance. */
 type MountHandle = {
@@ -63,6 +83,11 @@ type MountHandle = {
   setColors(colors: string[]): void;
   setParams(params: Record<string, number>): void;
   setSpeed(speed: number): void;
+  /** Changes the seamless-loop period; pass undefined (or 0) to stop looping.
+  * See MountOptions.loopSeconds. Takes effect on the next painted frame, and
+  * because the shader clock wraps at the period, changing this mid-playback
+  * jumps the animation rather than easing into the new cycle. */
+  setLoopSeconds(seconds: number | undefined): void;
   pause(): void;
   resume(): void;
   /** Jumps playback to an absolute time position, in milliseconds. */
@@ -87,6 +112,9 @@ type RendererOptions = {
   colors: string[];
   params: Record<string, number>;
   seed: number;
+  /** Seamless-loop period in animation seconds; omitted/0 disables looping.
+  * See MountOptions.loopSeconds. */
+  loopSeconds?: number;
 };
 //#endregion
 //#region src/shaders/flow.d.ts
@@ -135,6 +163,11 @@ declare function renderGradientFrame(opts: {
   params?: Record<string, number>;
   seed?: number;
   timeMs?: number;
+  /** Seamless-loop period in animation seconds. Only meaningful here in that
+  * it makes `timeMs` and `timeMs + loopSeconds * 1000` render the same
+  * frame — which is exactly how a loop is verified. See
+  * MountOptions.loopSeconds. */
+  loopSeconds?: number;
   width: number;
   height: number;
 }): RenderFrameResult;

package/dist/index.js

@@ -36,6 +36,69 @@ float snoise(vec2 v) {
 }
 `;
 /**
+* Classic 2D Perlin noise with an EXPLICIT TILING PERIOD, copied from the
+* standard reference implementation (Stefan Gustavson / Ashima Arts
+* webgl-noise, public domain). As with SIMPLEX_2D, the constants are fitted
+* values — do not "tidy" them.
+*
+* Why this exists alongside snoise: a shader that animates by translating
+* its sample point through a noise field can only loop if the field repeats
+* along the direction of travel. Simplex cannot do that at any useful
+* distance (its permutation repeats every 289 skewed lattice cells), so a
+* looping translation has to be bent into a circle instead — which reads as
+* the composition swaying back and forth rather than flowing. `pnoise` wraps
+* its integer lattice at `rep`, so travelling exactly `rep` units lands on a
+* bit-identical field and the motion can stay perfectly straight.
+*
+* `rep` MUST be integral (it is fed to mod() on lattice coordinates); a
+* fractional period silently produces a discontinuity at the wrap.
+*/
+const PERIODIC_2D = `
+vec4 mod289_4(vec4 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec4 permute4(vec4 x) { return mod289_4(((x * 34.0) + 1.0) * x); }
+vec4 taylorInvSqrt4(vec4 r) { return 1.79284291400159 - 0.85373472095314 * r; }
+vec2 fade2(vec2 t) { return t * t * t * (t * (t * 6.0 - 15.0) + 10.0); }
+
+float pnoise(vec2 P, vec2 rep) {
+  vec4 Pi = floor(P.xyxy) + vec4(0.0, 0.0, 1.0, 1.0);
+  vec4 Pf = fract(P.xyxy) - vec4(0.0, 0.0, 1.0, 1.0);
+  Pi = mod(Pi, rep.xyxy); // the tiling itself
+  Pi = mod289_4(Pi);      // keeps the permutation away from float truncation
+  vec4 ix = Pi.xzxz;
+  vec4 iy = Pi.yyww;
+  vec4 fx = Pf.xzxz;
+  vec4 fy = Pf.yyww;
+
+  vec4 i = permute4(permute4(ix) + iy);
+
+  vec4 gx = fract(i * (1.0 / 41.0)) * 2.0 - 1.0;
+  vec4 gy = abs(gx) - 0.5;
+  vec4 tx = floor(gx + 0.5);
+  gx = gx - tx;
+
+  vec2 g00 = vec2(gx.x, gy.x);
+  vec2 g10 = vec2(gx.y, gy.y);
+  vec2 g01 = vec2(gx.z, gy.z);
+  vec2 g11 = vec2(gx.w, gy.w);
+
+  vec4 norm = taylorInvSqrt4(vec4(dot(g00, g00), dot(g01, g01), dot(g10, g10), dot(g11, g11)));
+  g00 *= norm.x;
+  g01 *= norm.y;
+  g10 *= norm.z;
+  g11 *= norm.w;
+
+  float n00 = dot(g00, vec2(fx.x, fy.x));
+  float n10 = dot(g10, vec2(fx.y, fy.y));
+  float n01 = dot(g01, vec2(fx.z, fy.z));
+  float n11 = dot(g11, vec2(fx.w, fy.w));
+
+  vec2 fade_xy = fade2(Pf.xy);
+  vec2 n_x = mix(vec2(n00, n01), vec2(n10, n11), fade_xy.x);
+  float n_xy = mix(n_x.x, n_x.y, fade_xy.y);
+  return 2.3 * n_xy;
+}
+`;
+/**
 * 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
@@ -129,27 +192,38 @@ float grain(vec2 uv, float time) {
 //#region src/shaders/flow.ts
 const FRAGMENT$1 = `
 uniform float u_scale;
+uniform float u_curl;
 uniform float u_drift;
 uniform float u_openness;
 uniform float u_grain;
 
 ${SIMPLEX_2D}
+${PERIODIC_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.
+// Curl of a scalar potential field: the finite-difference gradient, 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.
+//
+// The potential is pnoise, not snoise, and it is pnoise in BOTH looping and
+// non-looping modes on purpose. A tiling field is what lets the drift travel
+// in a straight line and still return (see loopTravel), and having the two
+// modes disagree about which noise they use would mean tuning a look in one
+// and shipping the other. The fbm below still uses snoise: it never sees the
+// drift, so it never needed to tile, and leaving it alone keeps the colour
+// masses' texture exactly as it was.
+vec2 curl(vec2 p, float tile) {
+  // Finite-difference step: small enough to approximate a derivative, large
+  // enough that the noise'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);
+  vec2 rep = vec2(tile);
+  float dx = (pnoise(p + vec2(eps, 0.0), rep) - pnoise(p - vec2(eps, 0.0), rep)) / (2.0 * eps);
+  float dy = (pnoise(p + vec2(0.0, eps), rep) - pnoise(p - vec2(0.0, eps), rep)) / (2.0 * eps);
   return vec2(dy, -dx);
 }
 
@@ -162,7 +236,37 @@ void main() {
   // 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;
+  //
+  // Curl field frequency, relative to the fbm's. Below 1.0 the currents are
+  // LARGER than the colour masses they carry, which is the look: sampled at
+  // the same frequency each mass sits inside its own little eddy, the
+  // advection only roughens mass edges, and the result is indistinguishable
+  // from a plain warped fbm.
+  //
+  // u_curl replaces what was a hardcoded 0.55, and its default is 1.05
+  // because the potential is pnoise now. Classic Perlin's lattice is a unit
+  // grid while simplex's skewed cells are roughly 0.7 units, so the same
+  // input scale yields visibly coarser features -- fewer closed eddies. 1.05
+  // was matched by eye against a reference render of the pre-pnoise look.
+  //
+  // The visible frame spans curlScale units of noise, so the tile has to be
+  // at least twice that or the field repeats inside a single frame, which
+  // looks like wallpaper; ceil keeps it integral, which pnoise requires.
+  float curlScale = u_scale * u_curl;
+  float tile = max(2.0, ceil(curlScale * 2.0));
+
+  // Straight-line travel through a tiling field: the direction never changes,
+  // so this reads as continuous flow rather than the sway a circular path
+  // gives. One tile per loop, hence rate = tile/u_loop -- a short loop flows
+  // fast and a long one slowly, which is the price of the straight line.
+  // At the default scale that is tile 2 over a 60s loop = 0.033/sec, near
+  // enough to the hand-tuned 0.025*sqrt(2) that the look is preserved.
+  //
+  // vec2(1.0) -- not vec2(1.0, 0.0) -- because this drift was originally a
+  // SCALAR added to a vec2 coordinate, i.e. a diagonal translation.
+  // loopTravel takes its non-looping speed from |dir|, so dropping the
+  // diagonal here would quietly slow the unlooped look down by 30%.
+  vec2 drift = loopTravel(0.025, vec2(1.0), tile);
 
   // Advect the sample point along the curl field in 3 FIXED steps (written
   // out explicitly rather than a variable-length loop, which risks the
@@ -172,19 +276,18 @@ void main() {
   // 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.
+  // eddies, which is the whole point of the look.
   //
-  // 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;
+  // Step gain 0.19, up from the 0.055 that was tuned against a simplex
+  // potential. pnoise carries shallower gradients, so the old gain advected
+  // the point far too little and the eddies stopped closing -- the frame went
+  // to soft diagonal bands. The gain absorbs that difference rather than the
+  // default of u_drift, which stays at 0.5 in its published 0-1 range so the
+  // knob means the same thing it always did.
   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;
+  advected += curl(advected * curlScale + u_seed + drift, tile) * u_drift * 0.19;
+  advected += curl(advected * curlScale + u_seed + drift, tile) * u_drift * 0.19;
+  advected += curl(advected * curlScale + u_seed + drift, tile) * u_drift * 0.19;
 
   float t = fbm2(advected * u_scale + u_seed);
 
@@ -234,6 +337,14 @@ const flow = {
 			step: .05,
 			default: 1.7
 		},
+		{
+			key: "curl",
+			label: "Curl",
+			min: .3,
+			max: 1.6,
+			step: .05,
+			default: 1.05
+		},
 		{
 			key: "drift",
 			label: "Drift",
@@ -262,7 +373,8 @@ const flow = {
 	randomParams(rand) {
 		return {
 			scale: .6 + rand() * 2,
-			drift: rand() * 1,
+			curl: .6 + rand() * .7000000000000001,
+			drift: .25 + rand() * .75,
 			openness: rand() * 1,
 			grain: .08
 		};
@@ -335,7 +447,14 @@ void main() {
   // 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;
+  //
+  // Along x only (vec2(1.0, 0.0)) when not looping, matching the original
+  // scalar offset. When looping, loopDrift bends that into a circle, so the
+  // sample window also travels a little in y -- i.e. onto neighbouring noise
+  // slices. That reads as the bend MORPHING as well as migrating, which is
+  // if anything richer than pure translation, and it is what avoids the
+  // visible back-and-forth reversal a one-axis sine would give.
+  vec2 drift = loopDrift(0.02, vec2(1.0, 0.0));
 
   // 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
@@ -343,14 +462,21 @@ void main() {
   // 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 bend = snoise(vec2(sn * (0.55 * u_scale), seedRow) + drift);
   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));
+  //
+  // loopFreq snaps 0.11 to a whole number of cycles per loop. Loops of ~29s
+  // and up get one swell per cycle (at 57s that IS 0.11, unchanged). Shorter
+  // loops round to zero and the swell holds still at its along-beam phase --
+  // the deliberate choice, since the alternative at e.g. an 8s loop is a
+  // frequency 7x the tuned rate, i.e. exactly the strobe this amplitude was
+  // picked to avoid.
+  float w = u_width * (1.0 + 0.10 * sin(loopFreq(0.11) * u_time + 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.
@@ -393,8 +519,10 @@ void main() {
   // 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));
+  // Negative dir keeps the pre-loop sign (the coordinate subtracted crawl),
+  // so the strands still travel the same way along the beam.
+  vec2 crawl = loopDrift(0.05, vec2(-1.0, 0.0));
+  float fil = snoise(vec2(sn * (0.9 * u_scale), (q - c) * 26.0 + seedRow * 1.7) + crawl);
 
   // Holographic banding: the same field nudges the ramp position inside the
   // core, so colour bands streak lengthwise through the beam (the foil-like
@@ -766,11 +894,18 @@ function clamp255(v) {
 * `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.
+*
+* Two more helpers exist so shaders can be made seamlessly loopable without
+* each one reinventing the maths — see loopDrift/loopFreq below. Any shader
+* whose only time dependence goes through those two (plus grain(), which
+* loops for free because u_time itself wraps at the period) is exactly
+* periodic with period `u_loop`.
 */
 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_time;        // seconds, pre-modded to [0,1000), or to [0,u_loop) when looping
 uniform float u_seed;        // pre-modded to [0,100)
+uniform float u_loop;        // seconds per seamless cycle; 0 = never repeat
 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
@@ -786,6 +921,77 @@ vec2 worldUv() {
 vec3 palette(float t) {
   return texture2D(u_palette, vec2(clamp(t, 0.0, 1.0), 0.5)).rgb;
 }
+
+const float TAU = 6.2831853;
+
+// Time-varying offset for a noise sample coordinate.
+//
+// Not looping (u_loop == 0): a plain linear translation, dir * rate * t.
+// This is the arithmetic the shaders used before looping existed, so the
+// default path is bit-identical to the pre-loop renderer.
+//
+// Looping: the same walk, bent into a closed circle of circumference
+// rate * |dir| * u_loop. Because the offset returns to exactly where it
+// started after u_loop seconds, every value derived from it does too --
+// that is the whole loop. A circle (rather than, say, a sine ping-pong on
+// one axis) is what keeps this invisible: the drift DIRECTION rotates
+// smoothly through 360 degrees over the cycle and never reverses, which on
+// an isotropic noise field is indistinguishable from continuing to travel
+// in a straight line. The radius is set from arc length, so the sampled
+// point covers the same distance per second whether looping or not and the
+// animation runs at an identical apparent speed either way.
+//
+// |dir| matters and is easy to get wrong: a shader adding a scalar drift to
+// both components of a vec2 is translating along the diagonal at rate*sqrt(2),
+// not at rate. Passing dir un-normalized lets each call site keep its
+// original speed exactly.
+//
+// Radii stay small (rate 0.05 over a 60s loop gives r ~ 0.48, well under the
+// noise field's ~1-unit feature size), so this never approaches the
+// float-precision ceiling noise.ts warns about.
+vec2 loopDrift(float rate, vec2 dir) {
+  if (u_loop <= 0.0) return dir * (rate * u_time);
+  float phase = TAU * u_time / u_loop;
+  return vec2(cos(phase), sin(phase)) * (rate * length(dir) * u_loop / TAU);
+}
+
+// Straight-line travel that still loops, for shaders sampling a noise field
+// that TILES with period "tile" (see PERIODIC_2D in shaders/noise.ts).
+//
+// This is the better half of loopDrift, and the difference is the whole
+// reason it exists. loopDrift has to curve, because a simplex field never
+// repeats, so the only way back to the start is to come around -- and a
+// drift direction that rotates through 360 degrees per cycle is perceived as
+// the composition swaying back and forth. Against a tiling field the path can
+// stay perfectly straight: travel exactly one tile and the field you are
+// standing in is bit-identical to the one you left. The motion never turns,
+// so it reads as continuous flow.
+//
+// The cost is that speed is no longer free. Travel per cycle is pinned to the
+// tile size, so rate becomes tile/u_loop: a short loop flows fast, a long one
+// slowly. The tile cannot simply be shrunk to compensate, because a tile
+// narrower than the visible frame means the field repeats WITHIN one frame,
+// which is a far worse artifact than any of this. Callers should size it
+// from their own sampling frequency.
+vec2 loopTravel(float rate, vec2 dir, float tile) {
+  if (u_loop <= 0.0) return dir * (rate * u_time);
+  return dir * (tile * u_time / u_loop);
+}
+
+// Snaps an angular frequency to a whole number of cycles per loop, which is
+// what makes sin(loopFreq(w) * u_time + anything) exactly periodic.
+//
+// Rounding to ZERO is deliberate and is the useful case, not a degenerate
+// one: when the loop is shorter than about half the oscillation's natural
+// period, the nearest legal frequency would be far faster than the shader
+// was tuned for, turning a slow swell into a throb. Returning 0 instead
+// freezes the oscillation at its per-pixel phase, so a spatially-varying
+// term stays spatially varying and simply stops animating -- a far less
+// visible change than speeding it up.
+float loopFreq(float w) {
+  if (u_loop <= 0.0) return w;
+  return TAU * floor(w * u_loop / TAU + 0.5) / u_loop;
+}
 `;
 /** Fullscreen-triangle-strip vertex shader. Four vertices covering [-1,1]^2,
 * with v_uv carrying the matching 0-1 UV for the fragment shader. */
@@ -848,11 +1054,19 @@ function linkProgram(gl, vertexShader, fragmentShader) {
 	}
 	return program;
 }
+/** Normalizes a loop period to the "off" sentinel the GLSL side expects.
+* Non-finite and non-positive values all mean "don't loop", so callers can
+* pass through user input without pre-validating it. */
+function normalizeLoop(seconds) {
+	if (seconds === void 0 || !Number.isFinite(seconds) || seconds <= 0) return 0;
+	return seconds;
+}
 function createRenderer(opts) {
 	const { canvas, shader } = opts;
 	let colors = opts.colors;
 	let params = opts.params;
 	const seed = opts.seed;
+	let loopSeconds = normalizeLoop(opts.loopSeconds);
 	const glOrNull = canvas.getContext("webgl", {
 		preserveDrawingBuffer: true,
 		antialias: false
@@ -886,6 +1100,7 @@ function createRenderer(opts) {
 	const resolutionLoc = gl.getUniformLocation(program, "u_resolution");
 	const timeLoc = gl.getUniformLocation(program, "u_time");
 	const seedLoc = gl.getUniformLocation(program, "u_seed");
+	const loopLoc = gl.getUniformLocation(program, "u_loop");
 	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}`));
@@ -901,9 +1116,10 @@ function createRenderer(opts) {
 		gl.viewport(0, 0, canvas.width, canvas.height);
 		gl.useProgram(program);
 		gl.uniform2f(resolutionLoc, canvas.width, canvas.height);
-		const timeSec = floorMod(timeMs / 1e3, 1e3);
+		const timeSec = floorMod(timeMs / 1e3, loopSeconds > 0 ? loopSeconds : 1e3);
 		gl.uniform1f(timeLoc, timeSec);
 		gl.uniform1f(seedLoc, floorMod(seed, 100));
+		gl.uniform1f(loopLoc, loopSeconds);
 		gl.activeTexture(gl.TEXTURE0);
 		gl.bindTexture(gl.TEXTURE_2D, paletteTexture);
 		gl.uniform1i(paletteLoc, 0);
@@ -920,6 +1136,9 @@ function createRenderer(opts) {
 	function setParams(next) {
 		params = next;
 	}
+	function setLoopSeconds(seconds) {
+		loopSeconds = normalizeLoop(seconds);
+	}
 	function resize(width, height) {
 		canvas.width = width;
 		canvas.height = height;
@@ -934,6 +1153,7 @@ function createRenderer(opts) {
 		renderAt,
 		setColors,
 		setParams,
+		setLoopSeconds,
 		resize,
 		dispose
 	};
@@ -986,7 +1206,8 @@ function mountGradient(container, opts) {
 		shader: def,
 		colors,
 		params,
-		seed
+		seed,
+		loopSeconds: opts.loopSeconds
 	});
 	let clockMs = 0;
 	let epoch = performance.now();
@@ -1043,6 +1264,10 @@ function mountGradient(container, opts) {
 			renderer.setParams(params);
 			if (!playing) renderOnce();
 		},
+		setLoopSeconds(seconds) {
+			renderer.setLoopSeconds(seconds);
+			if (!playing) renderOnce();
+		},
 		setSpeed(next) {
 			if (playing && speed !== 0) clockMs = (performance.now() - epoch) * speed;
 			speed = next;
@@ -1102,7 +1327,8 @@ function renderGradientFrame(opts) {
 		shader: def,
 		colors: opts.colors,
 		params: resolveParams(def, opts.params),
-		seed: opts.seed ?? 0
+		seed: opts.seed ?? 0,
+		loopSeconds: opts.loopSeconds
 	});
 	renderer.renderAt(opts.timeMs ?? 0);
 	const gl = canvas.getContext("webgl");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instantshader",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Animated WebGL gradient shaders. Zero dependencies.",
   "type": "module",
   "license": "MIT",