@dopaminefx/effect-ripple 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ripple (the tactile "droplet in a still pool" acknowledge effect) as an
+ * `EffectFactory` on the Dopamine backbone.
+ *
+ * FULLY DATA-DRIVEN (P2): everything that isn't the GLSL lives in
+ * ripple.dope.json — the mood→params mapping + OKLCH palette (the loader), AND
+ * the per-frame logic: `tempo.frame` (the held-breath envelope amp),
+ * `render.shadowHeightFrac` (the wave field's outward reach), `render.consts`
+ * (MAX_RINGS/MIN_RINGS), `render.config` and the uniform `binding` contract.
+ * `registerDopeEffect` interprets that data through the generic
+ * `createPassInstance` fullscreen-pass runner; this module is just the water
+ * SHADER + the registration call.
+ *
+ * Anchored at `uOrigin` (usesOrigin: true): concentric wavefronts expand from
+ * the action point. Distinct from Solarbloom's soft radial CORE — Ripple's light
+ * lives only on thin, moving ring crests + the caustics they refract.
+ */
+import { type EffectFactory, type PassParams } from "@dopaminefx/core";
+/** The resolved render params Ripple's shader consumes. */
+export interface RippleParams extends PassParams {
+    exposure: number;
+    amplitude: number;
+    rings: number;
+    wavelength: number;
+    speed: number;
+    caustic: number;
+    overshoot: number;
+    rippleSeed: number;
+}
+export declare const ripple: EffectFactory<RippleParams>;
+export default ripple;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKtG,2DAA2D;AAC3D,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,eAAO,MAAM,MAAM,EAGgB,aAAa,CAAC,YAAY,CAAC,CAAC;AAE/D,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * Ripple (the tactile "droplet in a still pool" acknowledge effect) as an
+ * `EffectFactory` on the Dopamine backbone.
+ *
+ * FULLY DATA-DRIVEN (P2): everything that isn't the GLSL lives in
+ * ripple.dope.json — the mood→params mapping + OKLCH palette (the loader), AND
+ * the per-frame logic: `tempo.frame` (the held-breath envelope amp),
+ * `render.shadowHeightFrac` (the wave field's outward reach), `render.consts`
+ * (MAX_RINGS/MIN_RINGS), `render.config` and the uniform `binding` contract.
+ * `registerDopeEffect` interprets that data through the generic
+ * `createPassInstance` fullscreen-pass runner; this module is just the water
+ * SHADER + the registration call.
+ *
+ * Anchored at `uOrigin` (usesOrigin: true): concentric wavefronts expand from
+ * the action point. Distinct from Solarbloom's soft radial CORE — Ripple's light
+ * lives only on thin, moving ring crests + the caustics they refract.
+ */
+import { RIPPLE_FRAGMENT_SRC, RIPPLE_VERTEX_SRC } from "./ripple-shader.js";
+import { parseDope, registerDopeEffect } from "@dopaminefx/core";
+import doc from "./ripple.dope.json";
+const DOPE = parseDope(doc);
+// The whole factory (resolve / create / reducedMotion / program registration)
+// is data: ripple.dope.json interpreted by the core backbone.
+export const ripple = registerDopeEffect(DOPE, {
+    vertex: RIPPLE_VERTEX_SRC,
+    fragment: RIPPLE_FRAGMENT_SRC,
+});
+export default ripple;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAuC,MAAM,kBAAkB,CAAC;AACtG,OAAO,GAAG,MAAM,oBAAoB,CAAC;AAErC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAa,CAAC,CAAC;AActC,8EAA8E;AAC9E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,iBAAiB;IACzB,QAAQ,EAAE,mBAAmB;CAC9B,CAA6D,CAAC;AAE/D,eAAe,MAAM,CAAC"}

package/dist/ripple-shader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * GLSL ES 3.00 source for **Ripple** — Dopamine's tactile "droplet in a still
+ * pool" acknowledge effect.
+ *
+ * Governing metaphor: a single drop strikes a calm water surface at the action
+ * point (`uOrigin`). Concentric WAVES expand outward, and each travelling
+ * wavefront REFRACTS bright caustic light that dances across the UI as the ring
+ * passes; behind the front, the surface settles back to still. It reads as
+ * water + light: physical, tactile, anchored.
+ *
+ * This is a deliberate DIVERGENCE from Solarbloom's volumetric radial bloom.
+ * Solarbloom is a soft glowing CORE that fills outward and lingers; Ripple has
+ * NO bright core — its light lives entirely on thin, moving RING crests and the
+ * caustic sparkle they refract. The motion is a set of discrete expanding
+ * annuli, not a swelling blob.
+ *
+ * Layers, summed as light (canvas is black, `mix-blend-mode: screen`, so black
+ * == no change, bright == cast light onto the page beneath):
+ *   1. WAVEFIELD — a sum of `uRings` radially-travelling cosine waves whose
+ *      phase = k*r - w*t, launched in a quick stagger from the origin. The
+ *      surface height + its radial gradient (slope) drive everything else.
+ *   2. CAUSTICS — the wave SLOPE bends light: bright filaments form where the
+ *      curved surface focuses light (|slope| high, near crests), animated as the
+ *      rings travel. This is the dancing light the brief describes.
+ *   3. CREST GLINT — a thin specular highlight riding the leading crest of each
+ *      ring (the wet "shine" of the moving wavefront).
+ *   4. SETTLE — the whole field is gated by a radial wavefront envelope so light
+ *      only appears where a ring currently is, then the pool goes still.
+ *
+ * Reward timing: uAmp (held-breath envelope) gates global brightness — a quick
+ * expanding swell then a gentle settle. Pure function of uTimeS (frame-perfect,
+ * cheap under SwiftShader: analytic waves + noise, single pass).
+ *
+ * whimsy == uStyle:
+ *   0 = photoreal smooth refraction — soft caustics, continuous crests, smooth
+ *       OKLCH colour drift across the rings.
+ *   1 = stylized: hard concentric CEL rings (posterized crest bands), posterized
+ *       caustics (chunky light cells), and the motion snaps "on twos" (the
+ *       pass-runner already steps the clock; we also quantize the wave phase so
+ *       the rings advance in discrete, posed jumps).
+ */
+/**
+ * Max concurrent expanding rings. Single source of truth for the loop cap: it is
+ * BOTH the GLSL `#define MAX_RINGS` (interpolated below) and the integer-clamp
+ * const the `.dope` mapping references (passed to the loader as `MAX_RINGS`).
+ */
+export declare const MAX_RINGS = 7;
+export declare const RIPPLE_VERTEX_SRC = "#version 300 es\nvoid main() {\n  // Single full-screen triangle from gl_VertexID \u2014 no vertex buffers needed.\n  vec2 pos = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));\n  gl_Position = vec4(pos * 2.0 - 1.0, 0.0, 1.0);\n}";
+export declare const RIPPLE_FRAGMENT_SRC = "#version 300 es\nprecision highp float;\nout vec4 fragColor;\n\nuniform vec2  uResolution;    // device pixels\nuniform vec2  uOrigin;        // drop point, gl coords (y up)\nuniform float uAmp;           // envelope amplitude (peaks > 1)\nuniform float uLife;          // whole-effect progress 0..1\nuniform float uTimeS;         // elapsed seconds (snapped \"on twos\" by style)\nuniform float uExposure;\nuniform float uAmplitude;     // wave height (intensity)\nuniform float uRings;         // number of concentric wavefronts launched\nuniform float uWavelength;    // crest spacing as a fraction of min viewport dim\nuniform float uSpeed;         // wave propagation speed (fraction of minDim / s)\nuniform float uCaustic;       // 0..1 caustic-light brightness (intensity)\nuniform float uSeed;          // per-fire hash offset\nuniform float uStyle;         // 0..1 photoreal smooth refraction -> cel rings (whimsy)\nuniform float uShadow;        // 0 = light pass (screen), 1 = shadow pass (multiply)\nuniform vec2  uShadowOffset;  // device-px offset of the cast silhouette (away from light)\nuniform float uShadowSoft;    // penumbra softness in device px (blur tap radius)\nuniform float uShadowStrength;// 0..1 max darkening of the multiply layer\nuniform vec3  uC0;            // crest core color\nuniform vec3  uC1;            // mid\nuniform vec3  uC2;            // caustic accent\n\n#define MAX_RINGS 7\n\n#define TAU 6.28318530718\n\n\nfloat hash11(float p){ p = fract(p * 0.1031); p *= p + 33.33; p *= p + p; return fract(p); }\nvec2 hash21(float p){\n  vec3 p3 = fract(vec3(p) * vec3(0.1031, 0.1030, 0.0973));\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.xx + p3.yz) * p3.zy);\n}\n\n\nfloat vnoise(vec2 p){\n  vec2 i = floor(p), f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float a = hash11(dot(i, vec2(1.0, 57.0)));\n  float b = hash11(dot(i + vec2(1.0, 0.0), vec2(1.0, 57.0)));\n  float c = hash11(dot(i + vec2(0.0, 1.0), vec2(1.0, 57.0)));\n  float d = hash11(dot(i + vec2(1.0, 1.0), vec2(1.0, 57.0)));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\nfloat fbm(vec2 p){\n  float s = 0.0, a = 0.5;\n  mat2 rot = mat2(0.80, -0.60, 0.60, 0.80);\n  for (int i = 0; i < 4; i++) { s += a * vnoise(p); p = rot * p * 2.03; a *= 0.5; }\n  return s;\n}\n\n\nvec3 paletteMix(float t){\n  t = clamp(t, 0.0, 1.0);\n  return t < 0.5 ? mix(uC0, uC1, t * 2.0) : mix(uC1, uC2, (t - 0.5) * 2.0);\n}\n\n\nvec3 tonemapACES(vec3 x){\n  const float a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;\n  return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);\n}\n\n\nvec3 ditherAdd(vec3 col, vec2 frag, float t, float fade){\n  float dz = hash11(dot(frag, vec2(12.989, 78.233)) + t) - 0.5;\n  return col + (dz / 255.0) * fade;\n}\n\n\n// A travelling ring's launch time as a fraction of life. The drop strikes at\n// t=0 and successive rings (the secondary swells of a real impact) follow in a\n// stagger wide enough that, at any instant, the rings sit at clearly DIFFERENT\n// radii \u2014 a family of distinct sizes rippling out, not bunched near-duplicates.\nfloat ringLaunch(int i){\n  return float(i) * 0.12;\n}\n\n// The wave surface as a function of normalized radius rn (= r / minDim) and the\n// life clock. Returns height in h; the radial SLOPE (dHeight/dr) in slope;\n// and a 0..1 wavefront ENVELOPE in front (1 where a ring currently is, 0 in\n// the still water ahead/behind). Shared by the light pass and the shadow so the\n// cast occlusion tracks exactly the troughs that are drawn.\n//\n// Each ring is a radially-expanding wave packet: a cosine carrier (phase =\n// k*r - w*t) under a gaussian envelope that travels outward at uSpeed and\n// spreads/decays as 1/sqrt(r) (energy conservation on an expanding circle).\nvoid waveField(float rn, out float h, out float slope, out float front){\n  h = 0.0; slope = 0.0; front = 0.0;\n  float k = TAU / max(uWavelength, 0.001);        // angular wavenumber (per rn)\n  float w = k * uSpeed;                            // angular frequency\n  int rings = int(clamp(uRings, 0.0, float(MAX_RINGS)) + 0.5);\n  for (int i = 0; i < MAX_RINGS; i++) {\n    if (i >= rings) break;\n    float t0 = ringLaunch(i);\n    float age = uLife - t0;                         // 0..(1-t0)\n    if (age <= 0.0) continue;\n    // Front radius travels outward; the packet starts tight and SWELLS markedly as\n    // the ring expands, so each ring visibly changes size as it travels out (and an\n    // older ring is both farther AND fatter than a younger one).\n    float front_r = uSpeed * age;                   // expected crest of this ring\n    float width = uWavelength * (1.0 + 2.6 * age);  // packet half-extent (grows as it expands)\n    float d = rn - front_r;                         // signed distance to the front\n    float pkt = exp(-(d * d) / (2.0 * width * width));\n    if (pkt < 0.002) continue;\n    // Amplitude fades CONTINUOUSLY as the ring ages/expands (not just a late cutoff),\n    // so each crest dims steadily as it grows \u2014 on top of the 1/sqrt(r) spreading.\n    float decay = pow(max(1.0 - age, 0.0), 1.3);\n    // 1/sqrt(r) spreading (clamped near the origin so the drop isn't a spike).\n    float spread = 1.0 / sqrt(max(rn, uWavelength * 0.5));\n    // On the cel end, quantize the carrier phase so the rings advance \"on twos\"\n    // (discrete posed crests) instead of sliding smoothly.\n    float phase = k * rn - w * uLife;\n    float qstep = TAU * 0.5;\n    float qphase = floor(phase / qstep) * qstep;\n    phase = mix(phase, qphase, uStyle * 0.85);\n    float amp = uAmplitude * pkt * decay * spread;\n    h += amp * cos(phase);\n    // d(h)/d(rn): carrier derivative dominates (the steep part that bends light).\n    slope += -amp * k * sin(phase);\n    front = max(front, pkt * decay);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// SHADOW silhouette \u2014 the wave TROUGHS cast a faint soft occlusion (a real\n// rippled surface dimples the light it sits in). We sample the wave height at\n// the offset shadow point and darken where the surface dips below rest (h < 0),\n// gated by the wavefront envelope so still water casts nothing. Kept subtle.\nfloat rippleOcclusion(vec2 frag){\n  float minDim = min(uResolution.x, uResolution.y);\n  float rn = length(frag - uOrigin) / minDim;\n  float h, slope, front;\n  waveField(rn, h, slope, front);\n  float trough = max(-h, 0.0);                      // depth below rest\n  return clamp(trough * 2.2 * front * uAmp, 0.0, 1.0);\n}\n\nvec4 rippleShadowColor(vec2 frag){\n  vec2 sp = frag - uShadowOffset;\n  float soft = uShadowSoft;\n  float occ = rippleOcclusion(sp);\n  occ += rippleOcclusion(sp + vec2( soft, 0.0));\n  occ += rippleOcclusion(sp + vec2(-soft, 0.0));\n  occ += rippleOcclusion(sp + vec2(0.0,  soft));\n  occ += rippleOcclusion(sp + vec2(0.0, -soft));\n  occ /= 5.0;\n  // Troughs are a faint dimple, so cap the darkening well below full strength.\n  float dark = clamp(occ, 0.0, 1.0) * uShadowStrength * 0.5;\n  vec3 tint = mix(vec3(1.0), 0.6 + 0.4 * normalize(uC0 + 1e-3), 0.2);\n  vec3 mul = mix(vec3(1.0), tint, dark);\n  return vec4(mul, 1.0);\n}\n\nvoid main(){\n  vec2 frag = gl_FragCoord.xy;\n  vec2 res = uResolution;\n  float minDim = min(res.x, res.y);\n\n  if (uShadow > 0.5) {\n    fragColor = rippleShadowColor(frag);\n    return;\n  }\n\n  vec3 col = vec3(0.0);\n  vec2 rel = frag - uOrigin;\n  float r = length(rel);\n  float rn = r / minDim;                            // normalized radius\n  vec2 rdir = rel / max(r, 1e-3);                   // outward unit (toward rim)\n\n  // ---- The wave surface at this fragment. ----\n  float h, slope, front;\n  waveField(rn, h, slope, front);\n\n  float gain = uAmp * uExposure;\n\n  // Colour register: hue drifts gently OUTWARD across the rings (OKLCH palette\n  // C0->C1->C2), so each expanding crest reads as a slightly different light \u2014\n  // unique per fire (the palette is seeded). A touch of slow temporal drift +\n  // tiny fbm break keeps it alive without going rainbow.\n  float tcol = clamp(rn / (uWavelength * float(MAX_RINGS) * 0.9), 0.0, 1.0);\n  tcol = fract(tcol + uTimeS * 0.04 + fbm(rel / minDim * 5.0 + uSeed) * 0.06);\n  vec3 ringCol = paletteMix(tcol);\n\n  // ---- 1. CRESTS: the bright wet ridge of each travelling wavefront. ----\n  // Light lives on the positive crests (h > 0), masked to where a ring is.\n  float crest = smoothstep(0.0, uAmplitude * 0.5, h) * front;\n  col += ringCol * crest * gain * 0.9;\n\n  // ---- 2. CAUSTICS: the wave SLOPE refracts/focuses light. A curved surface\n  // bends parallel light into bright filaments; |slope| peaks on the steep\n  // flanks between crest and trough, so the caustic web sits BETWEEN the rings\n  // and dances as they travel. Sharpened to thin, bright lines. ----\n  float foc = abs(slope);\n  float caustic = pow(clamp(foc / (uAmplitude * 1.2 + 1e-3), 0.0, 1.0), 1.8);\n  // A little noise breaks the caustic into a living, glittering web.\n  float glit = 0.6 + 0.6 * fbm(rel / minDim * 22.0 - uTimeS * 0.5 + uSeed);\n  caustic *= glit * front;\n  // The accent hue carries the caustic light (a brighter, whiter highlight on top).\n  col += mix(uC2, vec3(1.0), 0.35) * caustic * uCaustic * gain * 1.3;\n\n  // ---- 3. CREST GLINT: a thin specular line riding each leading crest. ----\n  float glint = smoothstep(0.85, 1.0, front) * smoothstep(uAmplitude * 0.55, uAmplitude * 0.9, h);\n  col += vec3(1.0) * glint * gain * 0.5 * (0.5 + 0.5 * uCaustic);\n\n  // ---- Tone + finishing ----\n  col = tonemapACES(col * 0.95);\n\n  // ---- Non-photoreal pass: cel rings + posterized caustics (whimsy). ----\n  // Toward the cel end the smooth refraction becomes hard concentric BANDS: the\n  // crest mask is thresholded into a flat ring, and the caustic web is posterized\n  // into chunky light cells. The phase quantization in waveField already steps\n  // the rings \"on twos\"; here we flatten their tone.\n  if (uStyle > 0.001) {\n    // Hard ring: a flat band where the crest is strong, with a brighter inner core.\n    float band = smoothstep(0.18, 0.30, crest);\n    float core = smoothstep(0.45, 0.60, crest);\n    vec3 celRing = clamp(ringCol * 1.3, 0.0, 1.2) * band\n                 + clamp(uC0 * 1.6 + 0.1, 0.0, 1.3) * core;\n    // Posterize the caustic light into 2 chunky levels (Ben-Day-ish cells),\n    // and keep only the BRIGHT cells (drop the dim wash so the cel read stays\n    // clean white-on-dark rings instead of a muddy mid-tone field).\n    float caus = clamp(caustic * uCaustic, 0.0, 1.0);\n    float causQ = step(0.5, caus) * 0.6 + step(0.8, caus) * 0.4;\n    vec3 celCaustic = mix(uC2, vec3(1.0), 0.5) * causQ;\n    vec3 cel = (celRing + celCaustic) * gain;\n    col = mix(col, cel, uStyle);\n  }\n\n  // Ordered dither (~1/255) to kill banding the screen blend reveals; faded out\n  // toward the cel end where hard bands are intended.\n  col = ditherAdd(col, frag, uTimeS, 1.0 - uStyle);\n\n  fragColor = vec4(max(col, 0.0), 1.0);\n}";
+//# sourceMappingURL=ripple-shader.d.ts.map

package/dist/ripple-shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple-shader.d.ts","sourceRoot":"","sources":["../src/ripple-shader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAWH;;;;GAIG;AACH,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,eAAO,MAAM,iBAAiB,uPAK5B,CAAC;AAEH,eAAO,MAAM,mBAAmB,izVAqM9B,CAAC"}

package/dist/ripple-shader.js

@@ -0,0 +1,253 @@
+/**
+ * GLSL ES 3.00 source for **Ripple** — Dopamine's tactile "droplet in a still
+ * pool" acknowledge effect.
+ *
+ * Governing metaphor: a single drop strikes a calm water surface at the action
+ * point (`uOrigin`). Concentric WAVES expand outward, and each travelling
+ * wavefront REFRACTS bright caustic light that dances across the UI as the ring
+ * passes; behind the front, the surface settles back to still. It reads as
+ * water + light: physical, tactile, anchored.
+ *
+ * This is a deliberate DIVERGENCE from Solarbloom's volumetric radial bloom.
+ * Solarbloom is a soft glowing CORE that fills outward and lingers; Ripple has
+ * NO bright core — its light lives entirely on thin, moving RING crests and the
+ * caustic sparkle they refract. The motion is a set of discrete expanding
+ * annuli, not a swelling blob.
+ *
+ * Layers, summed as light (canvas is black, `mix-blend-mode: screen`, so black
+ * == no change, bright == cast light onto the page beneath):
+ *   1. WAVEFIELD — a sum of `uRings` radially-travelling cosine waves whose
+ *      phase = k*r - w*t, launched in a quick stagger from the origin. The
+ *      surface height + its radial gradient (slope) drive everything else.
+ *   2. CAUSTICS — the wave SLOPE bends light: bright filaments form where the
+ *      curved surface focuses light (|slope| high, near crests), animated as the
+ *      rings travel. This is the dancing light the brief describes.
+ *   3. CREST GLINT — a thin specular highlight riding the leading crest of each
+ *      ring (the wet "shine" of the moving wavefront).
+ *   4. SETTLE — the whole field is gated by a radial wavefront envelope so light
+ *      only appears where a ring currently is, then the pool goes still.
+ *
+ * Reward timing: uAmp (held-breath envelope) gates global brightness — a quick
+ * expanding swell then a gentle settle. Pure function of uTimeS (frame-perfect,
+ * cheap under SwiftShader: analytic waves + noise, single pass).
+ *
+ * whimsy == uStyle:
+ *   0 = photoreal smooth refraction — soft caustics, continuous crests, smooth
+ *       OKLCH colour drift across the rings.
+ *   1 = stylized: hard concentric CEL rings (posterized crest bands), posterized
+ *       caustics (chunky light cells), and the motion snaps "on twos" (the
+ *       pass-runner already steps the clock; we also quantize the wave phase so
+ *       the rings advance in discrete, posed jumps).
+ */
+import { GLSL_CONSTANTS, GLSL_DITHER, GLSL_FBM, GLSL_HASH, GLSL_PALETTE_MIX, GLSL_TONEMAP_ACES, } from "@dopaminefx/core";
+/**
+ * Max concurrent expanding rings. Single source of truth for the loop cap: it is
+ * BOTH the GLSL `#define MAX_RINGS` (interpolated below) and the integer-clamp
+ * const the `.dope` mapping references (passed to the loader as `MAX_RINGS`).
+ */
+export const MAX_RINGS = 7;
+export const RIPPLE_VERTEX_SRC = /* glsl */ `#version 300 es
+void main() {
+  // Single full-screen triangle from gl_VertexID — no vertex buffers needed.
+  vec2 pos = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  gl_Position = vec4(pos * 2.0 - 1.0, 0.0, 1.0);
+}`;
+export const RIPPLE_FRAGMENT_SRC = /* glsl */ `#version 300 es
+precision highp float;
+out vec4 fragColor;
+
+uniform vec2  uResolution;    // device pixels
+uniform vec2  uOrigin;        // drop point, gl coords (y up)
+uniform float uAmp;           // envelope amplitude (peaks > 1)
+uniform float uLife;          // whole-effect progress 0..1
+uniform float uTimeS;         // elapsed seconds (snapped "on twos" by style)
+uniform float uExposure;
+uniform float uAmplitude;     // wave height (intensity)
+uniform float uRings;         // number of concentric wavefronts launched
+uniform float uWavelength;    // crest spacing as a fraction of min viewport dim
+uniform float uSpeed;         // wave propagation speed (fraction of minDim / s)
+uniform float uCaustic;       // 0..1 caustic-light brightness (intensity)
+uniform float uSeed;          // per-fire hash offset
+uniform float uStyle;         // 0..1 photoreal smooth refraction -> cel rings (whimsy)
+uniform float uShadow;        // 0 = light pass (screen), 1 = shadow pass (multiply)
+uniform vec2  uShadowOffset;  // device-px offset of the cast silhouette (away from light)
+uniform float uShadowSoft;    // penumbra softness in device px (blur tap radius)
+uniform float uShadowStrength;// 0..1 max darkening of the multiply layer
+uniform vec3  uC0;            // crest core color
+uniform vec3  uC1;            // mid
+uniform vec3  uC2;            // caustic accent
+
+#define MAX_RINGS ${MAX_RINGS}
+${GLSL_CONSTANTS}
+${GLSL_HASH}
+${GLSL_FBM}
+${GLSL_PALETTE_MIX}
+${GLSL_TONEMAP_ACES}
+${GLSL_DITHER}
+
+// A travelling ring's launch time as a fraction of life. The drop strikes at
+// t=0 and successive rings (the secondary swells of a real impact) follow in a
+// stagger wide enough that, at any instant, the rings sit at clearly DIFFERENT
+// radii — a family of distinct sizes rippling out, not bunched near-duplicates.
+float ringLaunch(int i){
+  return float(i) * 0.12;
+}
+
+// The wave surface as a function of normalized radius rn (= r / minDim) and the
+// life clock. Returns height in h; the radial SLOPE (dHeight/dr) in slope;
+// and a 0..1 wavefront ENVELOPE in front (1 where a ring currently is, 0 in
+// the still water ahead/behind). Shared by the light pass and the shadow so the
+// cast occlusion tracks exactly the troughs that are drawn.
+//
+// Each ring is a radially-expanding wave packet: a cosine carrier (phase =
+// k*r - w*t) under a gaussian envelope that travels outward at uSpeed and
+// spreads/decays as 1/sqrt(r) (energy conservation on an expanding circle).
+void waveField(float rn, out float h, out float slope, out float front){
+  h = 0.0; slope = 0.0; front = 0.0;
+  float k = TAU / max(uWavelength, 0.001);        // angular wavenumber (per rn)
+  float w = k * uSpeed;                            // angular frequency
+  int rings = int(clamp(uRings, 0.0, float(MAX_RINGS)) + 0.5);
+  for (int i = 0; i < MAX_RINGS; i++) {
+    if (i >= rings) break;
+    float t0 = ringLaunch(i);
+    float age = uLife - t0;                         // 0..(1-t0)
+    if (age <= 0.0) continue;
+    // Front radius travels outward; the packet starts tight and SWELLS markedly as
+    // the ring expands, so each ring visibly changes size as it travels out (and an
+    // older ring is both farther AND fatter than a younger one).
+    float front_r = uSpeed * age;                   // expected crest of this ring
+    float width = uWavelength * (1.0 + 2.6 * age);  // packet half-extent (grows as it expands)
+    float d = rn - front_r;                         // signed distance to the front
+    float pkt = exp(-(d * d) / (2.0 * width * width));
+    if (pkt < 0.002) continue;
+    // Amplitude fades CONTINUOUSLY as the ring ages/expands (not just a late cutoff),
+    // so each crest dims steadily as it grows — on top of the 1/sqrt(r) spreading.
+    float decay = pow(max(1.0 - age, 0.0), 1.3);
+    // 1/sqrt(r) spreading (clamped near the origin so the drop isn't a spike).
+    float spread = 1.0 / sqrt(max(rn, uWavelength * 0.5));
+    // On the cel end, quantize the carrier phase so the rings advance "on twos"
+    // (discrete posed crests) instead of sliding smoothly.
+    float phase = k * rn - w * uLife;
+    float qstep = TAU * 0.5;
+    float qphase = floor(phase / qstep) * qstep;
+    phase = mix(phase, qphase, uStyle * 0.85);
+    float amp = uAmplitude * pkt * decay * spread;
+    h += amp * cos(phase);
+    // d(h)/d(rn): carrier derivative dominates (the steep part that bends light).
+    slope += -amp * k * sin(phase);
+    front = max(front, pkt * decay);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SHADOW silhouette — the wave TROUGHS cast a faint soft occlusion (a real
+// rippled surface dimples the light it sits in). We sample the wave height at
+// the offset shadow point and darken where the surface dips below rest (h < 0),
+// gated by the wavefront envelope so still water casts nothing. Kept subtle.
+float rippleOcclusion(vec2 frag){
+  float minDim = min(uResolution.x, uResolution.y);
+  float rn = length(frag - uOrigin) / minDim;
+  float h, slope, front;
+  waveField(rn, h, slope, front);
+  float trough = max(-h, 0.0);                      // depth below rest
+  return clamp(trough * 2.2 * front * uAmp, 0.0, 1.0);
+}
+
+vec4 rippleShadowColor(vec2 frag){
+  vec2 sp = frag - uShadowOffset;
+  float soft = uShadowSoft;
+  float occ = rippleOcclusion(sp);
+  occ += rippleOcclusion(sp + vec2( soft, 0.0));
+  occ += rippleOcclusion(sp + vec2(-soft, 0.0));
+  occ += rippleOcclusion(sp + vec2(0.0,  soft));
+  occ += rippleOcclusion(sp + vec2(0.0, -soft));
+  occ /= 5.0;
+  // Troughs are a faint dimple, so cap the darkening well below full strength.
+  float dark = clamp(occ, 0.0, 1.0) * uShadowStrength * 0.5;
+  vec3 tint = mix(vec3(1.0), 0.6 + 0.4 * normalize(uC0 + 1e-3), 0.2);
+  vec3 mul = mix(vec3(1.0), tint, dark);
+  return vec4(mul, 1.0);
+}
+
+void main(){
+  vec2 frag = gl_FragCoord.xy;
+  vec2 res = uResolution;
+  float minDim = min(res.x, res.y);
+
+  if (uShadow > 0.5) {
+    fragColor = rippleShadowColor(frag);
+    return;
+  }
+
+  vec3 col = vec3(0.0);
+  vec2 rel = frag - uOrigin;
+  float r = length(rel);
+  float rn = r / minDim;                            // normalized radius
+  vec2 rdir = rel / max(r, 1e-3);                   // outward unit (toward rim)
+
+  // ---- The wave surface at this fragment. ----
+  float h, slope, front;
+  waveField(rn, h, slope, front);
+
+  float gain = uAmp * uExposure;
+
+  // Colour register: hue drifts gently OUTWARD across the rings (OKLCH palette
+  // C0->C1->C2), so each expanding crest reads as a slightly different light —
+  // unique per fire (the palette is seeded). A touch of slow temporal drift +
+  // tiny fbm break keeps it alive without going rainbow.
+  float tcol = clamp(rn / (uWavelength * float(MAX_RINGS) * 0.9), 0.0, 1.0);
+  tcol = fract(tcol + uTimeS * 0.04 + fbm(rel / minDim * 5.0 + uSeed) * 0.06);
+  vec3 ringCol = paletteMix(tcol);
+
+  // ---- 1. CRESTS: the bright wet ridge of each travelling wavefront. ----
+  // Light lives on the positive crests (h > 0), masked to where a ring is.
+  float crest = smoothstep(0.0, uAmplitude * 0.5, h) * front;
+  col += ringCol * crest * gain * 0.9;
+
+  // ---- 2. CAUSTICS: the wave SLOPE refracts/focuses light. A curved surface
+  // bends parallel light into bright filaments; |slope| peaks on the steep
+  // flanks between crest and trough, so the caustic web sits BETWEEN the rings
+  // and dances as they travel. Sharpened to thin, bright lines. ----
+  float foc = abs(slope);
+  float caustic = pow(clamp(foc / (uAmplitude * 1.2 + 1e-3), 0.0, 1.0), 1.8);
+  // A little noise breaks the caustic into a living, glittering web.
+  float glit = 0.6 + 0.6 * fbm(rel / minDim * 22.0 - uTimeS * 0.5 + uSeed);
+  caustic *= glit * front;
+  // The accent hue carries the caustic light (a brighter, whiter highlight on top).
+  col += mix(uC2, vec3(1.0), 0.35) * caustic * uCaustic * gain * 1.3;
+
+  // ---- 3. CREST GLINT: a thin specular line riding each leading crest. ----
+  float glint = smoothstep(0.85, 1.0, front) * smoothstep(uAmplitude * 0.55, uAmplitude * 0.9, h);
+  col += vec3(1.0) * glint * gain * 0.5 * (0.5 + 0.5 * uCaustic);
+
+  // ---- Tone + finishing ----
+  col = tonemapACES(col * 0.95);
+
+  // ---- Non-photoreal pass: cel rings + posterized caustics (whimsy). ----
+  // Toward the cel end the smooth refraction becomes hard concentric BANDS: the
+  // crest mask is thresholded into a flat ring, and the caustic web is posterized
+  // into chunky light cells. The phase quantization in waveField already steps
+  // the rings "on twos"; here we flatten their tone.
+  if (uStyle > 0.001) {
+    // Hard ring: a flat band where the crest is strong, with a brighter inner core.
+    float band = smoothstep(0.18, 0.30, crest);
+    float core = smoothstep(0.45, 0.60, crest);
+    vec3 celRing = clamp(ringCol * 1.3, 0.0, 1.2) * band
+                 + clamp(uC0 * 1.6 + 0.1, 0.0, 1.3) * core;
+    // Posterize the caustic light into 2 chunky levels (Ben-Day-ish cells),
+    // and keep only the BRIGHT cells (drop the dim wash so the cel read stays
+    // clean white-on-dark rings instead of a muddy mid-tone field).
+    float caus = clamp(caustic * uCaustic, 0.0, 1.0);
+    float causQ = step(0.5, caus) * 0.6 + step(0.8, caus) * 0.4;
+    vec3 celCaustic = mix(uC2, vec3(1.0), 0.5) * causQ;
+    vec3 cel = (celRing + celCaustic) * gain;
+    col = mix(col, cel, uStyle);
+  }
+
+  // Ordered dither (~1/255) to kill banding the screen blend reveals; faded out
+  // toward the cel end where hard bands are intended.
+  col = ditherAdd(col, frag, uTimeS, 1.0 - uStyle);
+
+  fragColor = vec4(max(col, 0.0), 1.0);
+}`;
+//# sourceMappingURL=ripple-shader.js.map

package/dist/ripple-shader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple-shader.js","sourceRoot":"","sources":["../src/ripple-shader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAE3B,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;;;;;EAK1C,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;oBAyB1B,SAAS;EAC3B,cAAc;EACd,SAAS;EACT,QAAQ;EACR,gBAAgB;EAChB,iBAAiB;EACjB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsKX,CAAC"}