@vysmo/transitions 0.1.0

package/src/transitions/bloom-reveal.ts

@@ -0,0 +1,106 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Multi-pass transition. As a noise-masked reveal of to emerges, its
+ * bright highlights bloom outward with big cinematic halos impossible
+ * in a single pass — the blur radius grows to ~32 pixels via five
+ * doubling-step iterations (1, 2, 4, 8, 16 px), which would need
+ * ~65² samples single-pass.
+ *
+ *   pass 0               — extract to-highlights gated by the reveal
+ *                          mask AND a 4·p·(1-p) envelope that zeroes
+ *                          at both endpoints.
+ *   pass 1..passCount-2  — expanding-step 9-tap box blur, doubling
+ *                          radius each iteration.
+ *   final pass           — composite: base = mix(from, to, mask), then
+ *                          add the blurred bloom scaled by intensity.
+ *
+ * Endpoints: the bloom envelope is zero at progress 0 and 1, so all
+ * intermediate passes carry zeros and the composite is pure from/to.
+ * Noise is remapped to [softness+safety, 1-softness-safety] so the
+ * reveal-mask smoothstep saturates cleanly at progress 0 and 1.
+ */
+export const bloomReveal = defineTransition({
+  name: "bloom-reveal",
+  passes: 7,
+  defaults: {
+    scale: 5,
+    softness: 0.08,
+    threshold: 0.55,
+    intensity: 3.0,
+  },
+  glsl: `
+uniform float uScale;
+uniform float uSoftness;
+uniform float uThreshold;
+uniform float uIntensity;
+
+float hash21(vec2 p) {
+  return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
+}
+
+float valNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float a = hash21(i);
+  float b = hash21(i + vec2(1.0, 0.0));
+  float c = hash21(i + vec2(0.0, 1.0));
+  float d = hash21(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+float fbm(vec2 p) {
+  return valNoise(p) * 0.55 +
+         valNoise(p * 2.1) * 0.28 +
+         valNoise(p * 4.3) * 0.17;
+}
+
+float revealMask(vec2 uv) {
+  // Safe noise bounds guarantee the mask smoothstep saturates to 0 at
+  // progress=0 and 1 at progress=1 regardless of where the noise lands.
+  float safeLow = uSoftness + 0.005;
+  float safeHigh = 1.0 - uSoftness - 0.005;
+  float n = mix(safeLow, safeHigh, clamp(fbm(uv * uScale), 0.0, 1.0));
+  return smoothstep(n - uSoftness, n + uSoftness, uProgress);
+}
+
+vec4 transition(vec2 uv) {
+  // Final pass: composite bloom on top of the from→to reveal.
+  if (uPass == uPassCount - 1) {
+    vec3 bloom = getPrevious(uv).rgb;
+    float mask = revealMask(uv);
+    vec3 base = mix(getFromColor(uv).rgb, getToColor(uv).rgb, mask);
+    return vec4(base + bloom * uIntensity, 1.0);
+  }
+
+  // Seed: bloom contribution = to_color * (brightness_mask) * reveal
+  // * envelope. Envelope vanishes at progress 0/1 → clean endpoints.
+  if (uPass == 0) {
+    float mask = revealMask(uv);
+    vec3 toColor = getToColor(uv).rgb;
+    float lum = dot(toColor, vec3(0.299, 0.587, 0.114));
+    float brightness = smoothstep(uThreshold - 0.1, uThreshold + 0.1, lum);
+    float envelope = 4.0 * uProgress * (1.0 - uProgress);
+    vec3 bloom = toColor * brightness * mask * envelope;
+    return vec4(bloom, 1.0);
+  }
+
+  // Blur: 9-tap box blur with an expanding step so the effective
+  // radius doubles each pass. After 5 blur passes, reach is ~32 px.
+  float step = pow(2.0, float(uPass - 1));
+  vec2 px = vec2(step) / uResolution;
+  vec3 sum = vec3(0.0);
+  sum += getPrevious(uv + vec2(-px.x, -px.y)).rgb;
+  sum += getPrevious(uv + vec2(0.0, -px.y)).rgb;
+  sum += getPrevious(uv + vec2(px.x, -px.y)).rgb;
+  sum += getPrevious(uv + vec2(-px.x, 0.0)).rgb;
+  sum += getPrevious(uv).rgb;
+  sum += getPrevious(uv + vec2(px.x, 0.0)).rgb;
+  sum += getPrevious(uv + vec2(-px.x, px.y)).rgb;
+  sum += getPrevious(uv + vec2(0.0, px.y)).rgb;
+  sum += getPrevious(uv + vec2(px.x, px.y)).rgb;
+  return vec4(sum / 9.0, 1.0);
+}
+`,
+});

package/src/transitions/chromatic-pulse.ts

@@ -0,0 +1,40 @@
+import { defineTransition } from "./define.js";
+
+export const chromaticPulse = defineTransition({
+  name: "chromatic-pulse",
+  defaults: {
+    intensity: 0.6,
+  },
+  glsl: `
+uniform float uIntensity;
+
+vec4 transition(vec2 uv) {
+  // Envelope peaks at midpoint, zero at endpoints.
+  float env = 4.0 * uProgress * (1.0 - uProgress);
+  float aberration = env * uIntensity * 0.03;
+
+  // Radial direction from center → outward chromatic shift feels lens-like.
+  vec2 toCenter = uv - 0.5;
+  float r = length(toCenter);
+  vec2 dir = r > 0.0001 ? toCenter / r : vec2(1.0, 0.0);
+
+  vec2 offR = clamp(uv + dir * aberration, 0.0, 1.0);
+  vec2 offG = uv;
+  vec2 offB = clamp(uv - dir * aberration, 0.0, 1.0);
+
+  vec3 fromRGB = vec3(
+    getFromColor(offR).r,
+    getFromColor(offG).g,
+    getFromColor(offB).b
+  );
+  vec3 toRGB = vec3(
+    getToColor(offR).r,
+    getToColor(offG).g,
+    getToColor(offB).b
+  );
+
+  float mixW = smoothstep(0.3, 0.7, uProgress);
+  return vec4(mix(fromRGB, toRGB, mixW), 1.0);
+}
+`,
+});

package/src/transitions/clock-wipe.ts

@@ -0,0 +1,33 @@
+import { defineTransition } from "./define.js";
+
+export const clockWipe = defineTransition({
+  name: "clock-wipe",
+  defaults: {
+    startAngle: -1.5707963, // -π/2 (12 o'clock)
+    direction: 1, // +1 clockwise, -1 counter-clockwise
+    softness: 0.02,
+  },
+  glsl: `
+uniform float uStartAngle;
+uniform float uDirection;
+uniform float uSoftness;
+
+const float TWO_PI = 6.2831853;
+
+vec4 transition(vec2 uv) {
+  vec2 delta = uv - vec2(0.5);
+  // Aspect-correct so the sweep stays angularly uniform on non-square canvases.
+  vec2 aspectDelta = delta * vec2(uResolution.x / uResolution.y, 1.0);
+
+  float angle = atan(aspectDelta.y, aspectDelta.x);
+  float sweep = mod(uDirection * (angle - uStartAngle), TWO_PI);
+
+  // Threshold extends beyond [0, 2π] by the softness on each side so the
+  // feather zone is outside the visible sweep range at the endpoints.
+  float threshold = uProgress * (TWO_PI + 2.0 * uSoftness) - uSoftness;
+  float w = smoothstep(threshold - uSoftness, threshold + uSoftness, sweep);
+
+  return mix(getToColor(uv), getFromColor(uv), w);
+}
+`,
+});

package/src/transitions/color-phase.ts

@@ -0,0 +1,24 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Port of gl-transitions' ColorPhase. Each color channel transitions on its
+ * own sub-range of progress via smoothstep, giving a phased spectrum-shift
+ * reveal (red fades early, green middle, blue late, for the defaults).
+ */
+export const colorPhase = defineTransition({
+  name: "color-phase",
+  defaults: {
+    fromStep: [0.0, 0.2, 0.4, 0.0],
+    toStep: [0.6, 0.8, 1.0, 1.0],
+  },
+  glsl: `
+uniform vec4 uFromStep;
+uniform vec4 uToStep;
+
+vec4 transition(vec2 uv) {
+  vec4 a = getFromColor(uv);
+  vec4 b = getToColor(uv);
+  return mix(a, b, smoothstep(uFromStep, uToStep, vec4(uProgress)));
+}
+`,
+});

package/src/transitions/cross-zoom.ts

@@ -0,0 +1,59 @@
+import { defineTransition } from "./define.js";
+
+export const crossZoom = defineTransition({
+  name: "cross-zoom",
+  defaults: {
+    strength: 1.2,
+    blur: 0.04,
+  },
+  glsl: `
+uniform float uStrength;
+uniform float uBlur;
+
+vec2 zoomUv(vec2 uv, float scale) {
+  return (uv - 0.5) / scale + 0.5;
+}
+
+vec4 sampleFromBlurred(vec2 uv, float amount) {
+  if (amount < 0.001) return getFromColor(uv);
+  const int N = 5;
+  vec4 sum = vec4(0.0);
+  for (int i = 0; i < N; i++) {
+    float t = (float(i) - 2.0) / 4.0;
+    vec2 offset = (uv - 0.5) * amount * t;
+    sum += getFromColor(uv + offset);
+  }
+  return sum / float(N);
+}
+
+vec4 sampleToBlurred(vec2 uv, float amount) {
+  if (amount < 0.001) return getToColor(uv);
+  const int N = 5;
+  vec4 sum = vec4(0.0);
+  for (int i = 0; i < N; i++) {
+    float t = (float(i) - 2.0) / 4.0;
+    vec2 offset = (uv - 0.5) * amount * t;
+    sum += getToColor(uv + offset);
+  }
+  return sum / float(N);
+}
+
+vec4 transition(vec2 uv) {
+  float fromScale = 1.0 + uProgress * uStrength;
+  float toScale = 1.0 + (1.0 - uProgress) * uStrength;
+
+  vec2 fromUv = zoomUv(uv, fromScale);
+  vec2 toUv = zoomUv(uv, toScale);
+
+  // Velocity-scaled radial blur (peak at midpoint, zero at endpoints).
+  float motion = 4.0 * uProgress * (1.0 - uProgress) * uBlur;
+
+  vec4 fromColor = sampleFromBlurred(fromUv, motion);
+  vec4 toColor = sampleToBlurred(toUv, motion);
+
+  // Crossfade concentrated in the middle 40% of the transition.
+  float mixW = smoothstep(0.3, 0.7, uProgress);
+  return mix(fromColor, toColor, mixW);
+}
+`,
+});

package/src/transitions/crosshatch.ts

@@ -0,0 +1,49 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Port of gl-transitions' CrossHatch. Pixels reveal based on an outer
+ * radial wave from `center` combined with per-row and per-column random
+ * thresholds, producing a sketchy hand-drawn crosshatch reveal. Outer
+ * smoothstep envelopes guarantee pixel-pure endpoints.
+ */
+export const crosshatch = defineTransition({
+  name: "crosshatch",
+  defaults: {
+    center: [0.5, 0.5],
+    threshold: 3,
+    fadeEdge: 0.1,
+  },
+  glsl: `
+uniform vec2 uCenter;
+uniform float uThreshold;
+uniform float uFadeEdge;
+
+float rand(vec2 co) {
+  return fract(sin(dot(co.xy, vec2(12.9898, 78.233))) * 43758.5453);
+}
+
+vec4 transition(vec2 uv) {
+  // Below threshold=3 the radial wave doesn't have enough range to cover
+  // the full canvas before the outer fade-edge envelope kicks in, leaving
+  // patchy unrevealed pixels mid-transition that snap to revealed at the
+  // end. Clamp here so the transition is reliable regardless of caller input.
+  float threshold = max(uThreshold, 3.0);
+  float dist = distance(uCenter, uv) / threshold;
+  float r = uProgress - min(rand(vec2(uv.y, 0.0)), rand(vec2(0.0, uv.x)));
+
+  float feather = 0.02;
+  float inner = smoothstep(dist - feather, dist + feather, r);
+
+  // Outer mix structure (from gl-transitions): no reveal until uFadeEdge,
+  // forced full reveal in last uFadeEdge of progress — guarantees clean
+  // endpoints regardless of the random threshold's noisiness.
+  float w = mix(
+    0.0,
+    mix(inner, 1.0, smoothstep(1.0 - uFadeEdge, 1.0, uProgress)),
+    smoothstep(0.0, uFadeEdge, uProgress)
+  );
+
+  return mix(getFromColor(uv), getToColor(uv), w);
+}
+`,
+});

package/src/transitions/define.ts

@@ -0,0 +1,56 @@
+import type {
+  MeshGeometry,
+  Transition,
+  TransitionShader,
+  UniformParams,
+  Widen,
+} from "../types.js";
+
+export interface DefineTransitionSpec<P extends UniformParams> {
+  name: string;
+  glsl: string;
+  /**
+   * Full vertex-shader main(). Required when `mesh` is set. See
+   * TransitionShader.vertex for shell details.
+   */
+  vertex?: string;
+  wgsl?: string;
+  defaults: P;
+  passes?: number;
+  mesh?: MeshGeometry;
+}
+
+/**
+ * Build a `Transition` from a plain spec. Authors write a fragment-shader
+ * `vec4 transition(vec2 uv) { … }` body and a `defaults` object of named
+ * uniforms; the Runner wraps it with the standard headers (`#version
+ * 300 es`, precision, `uFrom` / `uTo` / `uProgress` / `uResolution`,
+ * sampler helpers `getFromColor` / `getToColor`) and maps each key in
+ * `defaults` to a `u<PascalCase>` uniform via the runner's binding rule.
+ *
+ * Mesh transitions add a `vertex` shader body and a `mesh` geometry
+ * descriptor; multi-pass transitions add `passes`.
+ *
+ * The returned object is a plain `Transition<Widen<P>>` — the `Widen`
+ * step lifts literal default tuples (e.g. `readonly [-1, 0]`) back to
+ * the general uniform tuple types so callers can override freely.
+ *
+ * Per the project's engineering invariants, every defined transition
+ * must clear the endpoint-correctness, polish-degrades-at-endpoints,
+ * no-hard-cuts, full-frame, and continuous-motion rules.
+ */
+export function defineTransition<const P extends UniformParams>(
+  spec: DefineTransitionSpec<P>,
+): Transition<Widen<P>> {
+  const shader: TransitionShader = { glsl: spec.glsl };
+  if (spec.vertex !== undefined) shader.vertex = spec.vertex;
+  if (spec.wgsl !== undefined) shader.wgsl = spec.wgsl;
+  const t: Transition<Widen<P>> = {
+    name: spec.name,
+    shader,
+    defaults: spec.defaults as unknown as Widen<P>,
+  };
+  if (spec.passes !== undefined) t.passes = spec.passes;
+  if (spec.mesh !== undefined) t.mesh = spec.mesh;
+  return t;
+}

package/src/transitions/directional-burn.ts

@@ -0,0 +1,67 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Linear film-burn sibling: a warm-glowing fire line advances across the
+ * frame from one edge, like a sparkler running along a fuse. Distinct
+ * from light-leak (smooth colored band passing through) — this is a
+ * state-change front: unburned ahead, reveal behind, hot glow ON the
+ * line.
+ */
+export const directionalBurn = defineTransition({
+  name: "directional-burn",
+  defaults: {
+    direction: [1, 0],
+    scale: 10,
+    edgeWidth: 0.035,
+    flameColor: [1.6, 0.7, 0.15],
+  },
+  glsl: `
+uniform vec2 uDirection;
+uniform float uScale;
+uniform float uEdgeWidth;
+uniform vec3 uFlameColor;
+
+float hash21(vec2 p) {
+  return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
+}
+
+float valueNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  f = f * f * (3.0 - 2.0 * f);
+  float a = hash21(i);
+  float b = hash21(i + vec2(1.0, 0.0));
+  float c = hash21(i + vec2(0.0, 1.0));
+  float d = hash21(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+vec4 transition(vec2 uv) {
+  vec2 d = normalize(uDirection);
+  float projected = dot(uv - 0.5, -d);
+  // Max projection magnitude for any uv in [0,1]^2 given this direction;
+  // L1 formula that works for axis-aligned and diagonal directions alike.
+  float maxProj = 0.5 * (abs(d.x) + abs(d.y));
+
+  float noiseStrength = 0.06;
+  float n = valueNoise(uv * uScale);
+  float perturbed = projected - (n - 0.5) * noiseStrength;
+
+  float totalEdge = uEdgeWidth + noiseStrength * 0.5;
+  float boundary = (maxProj + totalEdge) * (1.0 - 2.0 * uProgress);
+  float signedDist = perturbed - boundary;
+
+  // Behind the front: reveal "to". Ahead: still "from".
+  float w = smoothstep(-uEdgeWidth, uEdgeWidth, signedDist);
+  vec4 base = mix(getFromColor(uv), getToColor(uv), w);
+
+  // Tight flame band centered on the front, env-gated to zero at endpoints.
+  float bandX = signedDist / max(uEdgeWidth * 1.3, 0.0001);
+  float flameBand = exp(-bandX * bandX * 3.5);
+  float env = 4.0 * uProgress * (1.0 - uProgress);
+  vec3 flame = uFlameColor * flameBand * env;
+
+  return vec4(base.rgb + flame, base.a);
+}
+`,
+});

package/src/transitions/directional-warp.ts

@@ -0,0 +1,46 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Ported from gl-transitions' directionalwarp. Uses L1-normalized direction
+ * so the wavefront covers the full image regardless of direction, and a
+ * shrink-to-center sampling that never needs to clamp outside [0,1] — so
+ * there are no stretched edge artifacts (the "bars" a naive displacement
+ * approach produces).
+ */
+export const directionalWarp = defineTransition({
+  name: "directional-warp",
+  defaults: {
+    direction: [-1, 1],
+    smoothness: 0.5,
+  },
+  glsl: `
+uniform vec2 uDirection;
+uniform float uSmoothness;
+
+vec4 transition(vec2 uv) {
+  // L1 normalization: ensures the projection v.x*uv.x + v.y*uv.y covers a
+  // range of length 1 regardless of direction.
+  vec2 v = uDirection;
+  float l = abs(v.x) + abs(v.y);
+  if (l < 0.0001) v = vec2(1.0, 0.0);
+  else v = v / l;
+
+  vec2 center = vec2(0.5);
+  float d = v.x * center.x + v.y * center.y;
+
+  float m = 1.0 - smoothstep(
+    -uSmoothness,
+    0.0,
+    v.x * uv.x + v.y * uv.y - (d - 0.5 + uProgress * (1.0 + uSmoothness))
+  );
+
+  // Shrink-to-center sampling: fromUv shrinks toward center as m grows,
+  // toUv grows out from center. UVs stay in [0,1] — no clamping needed.
+  return mix(
+    getFromColor((uv - 0.5) * (1.0 - m) + 0.5),
+    getToColor((uv - 0.5) * m + 0.5),
+    m
+  );
+}
+`,
+});

package/src/transitions/dissolve.ts

@@ -0,0 +1,16 @@
+import { defineTransition } from "./define.js";
+
+export const dissolve = defineTransition({
+  name: "dissolve",
+  defaults: {},
+  glsl: `
+vec4 transition(vec2 uv) {
+  vec4 a = getFromColor(uv);
+  vec4 b = getToColor(uv);
+  vec3 aLin = pow(a.rgb, vec3(2.2));
+  vec3 bLin = pow(b.rgb, vec3(2.2));
+  vec3 mixed = mix(aLin, bLin, uProgress);
+  return vec4(pow(mixed, vec3(1.0 / 2.2)), mix(a.a, b.a, uProgress));
+}
+`,
+});

package/src/transitions/dreamy-zoom.ts

@@ -0,0 +1,66 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Port of gl-transitions' DreamyZoom (Zeh Fernando, MIT). Phase 1 (p<0.5):
+ * from-image zooms in + rotates, fading toward white. Phase 2 (p>0.5):
+ * white fades back to to-image starting pre-rotated and unwinding to
+ * identity while zooming out. The white flash at p=0.5 masks the from→to
+ * image swap.
+ *
+ * Note: the original gl-transitions source has a bug (`* vec4(0)`) that
+ * disables the flash — fixed here to use white, matching the actual
+ * preview on gl-transitions.com.
+ *
+ * Single `intensity` param drives both rotation and scale internally.
+ * Rotation alone would push corners outside the canvas (visible edge-clamp
+ * streaks); scale must compensate. Splitting them as separate params lets
+ * the caller pick mismatched values that produce streaks. We map intensity
+ * to (rotation, scale) along a curve where scale always covers rotation,
+ * so any value in [0, 1] is visually safe.
+ *
+ * Default `intensity: 0.5` reproduces gl-transitions' defaults exactly
+ * (rotation ≈ 0.105 rad / 6°, scale ≈ 1.2).
+ */
+export const dreamyZoom = defineTransition({
+  name: "dreamy-zoom",
+  defaults: {
+    intensity: 0.5,
+  },
+  glsl: `
+uniform float uIntensity;
+
+vec4 transition(vec2 uv) {
+  float ratio = uResolution.x / max(uResolution.y, 1.0);
+
+  // Single knob, mapped to rotation + scale together. Coefficients chosen
+  // so intensity=0.5 reproduces gl-transitions' (0.105 rad, 1.2) defaults.
+  float intensity = clamp(uIntensity, 0.0, 1.0);
+  float rotation = intensity * 0.21;
+  float scale = 1.0 + intensity * 0.4;
+
+  float phase = uProgress < 0.5 ? uProgress * 2.0 : (uProgress - 0.5) * 2.0;
+  float angleOffset = uProgress < 0.5
+    ? mix(0.0, rotation, phase)
+    : mix(-rotation, 0.0, phase);
+  float newScale = uProgress < 0.5
+    ? mix(1.0, scale, phase)
+    : mix(scale, 1.0, phase);
+
+  vec2 p = (uv - vec2(0.5)) / newScale * vec2(ratio, 1.0);
+  float angle = atan(p.y, p.x) + angleOffset;
+  float dist = length(p);
+  vec2 sampledP = vec2(
+    cos(angle) * dist / ratio + 0.5,
+    sin(angle) * dist + 0.5
+  );
+
+  vec4 c = uProgress < 0.5
+    ? getFromColor(sampledP)
+    : getToColor(sampledP);
+
+  // White flash: zero at endpoints, peaks at midpoint to mask the swap.
+  float flash = uProgress < 0.5 ? phase : 1.0 - phase;
+  return vec4(c.rgb + flash, c.a);
+}
+`,
+});

package/src/transitions/dreamy.ts

@@ -0,0 +1,26 @@
+import { defineTransition } from "./define.js";
+
+/**
+ * Ported from gl-transitions' Dreamy. A gentle vertical wobble displaces
+ * both images with opposing phases; combined with the linear crossfade this
+ * gives a soft, hypnotic "dream" feel. Procedural, no displacement texture
+ * required.
+ */
+export const dreamy = defineTransition({
+  name: "dreamy",
+  defaults: {},
+  glsl: `
+vec2 dreamyOffset(float progress, float x, float theta) {
+  float shifty = 0.03 * progress * cos(10.0 * (progress + x) + theta);
+  return vec2(0.0, shifty);
+}
+
+vec4 transition(vec2 uv) {
+  return mix(
+    getFromColor(uv + dreamyOffset(uProgress, uv.x, 0.0)),
+    getToColor(uv + dreamyOffset(1.0 - uProgress, uv.x, 3.14159)),
+    uProgress
+  );
+}
+`,
+});