@wave3d/core 0.6.0 → 0.8.0

package/dist/renderer/shaders.js

@@ -157,57 +157,7 @@ vec3 applyColorGrade(vec3 c){
   return hueShift(c, radians(uHueShift));
 }
 `;
-const vertexShader = `
-${simplex2d}
-
-uniform float uTime, uSpeed, uSeed;
-uniform float uDispFreqX, uDispFreqZ, uDispAmount;
-uniform float uDetailFreq, uDetailAmount; // 2nd displacement octave (only read under DETAIL_OCTAVE)
-uniform float uTwFreqX, uTwFreqY, uTwFreqZ, uTwPowX, uTwPowY, uTwPowZ;
-uniform float uLoopSeconds; // seamless-loop period (only read under LOOP_MOTION)
-
-// Helix (optional). Behind HELIX so a wave without one compiles the exact same program — same
-// byte-identity contract as the pointer block below.
-#ifdef HELIX
-uniform float uHelixTurns;  // full turns from one end of the ribbon to the other
-uniform float uHelixRadius; // orbit radius: carries the whole ribbon around the axis
-uniform float uHelixRoll;   // cross-section roll, as a fraction of the turns (1 = rigid ladder)
-uniform float uHelixPhase;  // degrees
-#endif
-
-varying vec2 vUv;
-varying vec3 vWorldPos;
-varying vec3 vViewDir;
-varying vec4 vClipPosition; // = gl_Position, for the wireframe theme's depth fade
-
-// Pointer field (optional, additive). ALL declarations here sit behind POINTER_FX so a wave with
-// no interaction config compiles the exact same program (JS-side uniform entries are always present
-// — see makeUniforms — but three only uploads uniforms the compiled program actually declares).
-#ifdef POINTER_FX
-uniform vec2  uPointer;        // smoothed pointer, NDC (-1..1)
-uniform float uPointerActive;  // presence ramp 0..1 × per-wave influence
-uniform float uPointerRadius;  // falloff radius in NDC-y units (config radius × 2)
-uniform float uPointerAspect;  // drawing-buffer dw/dh (circular screen falloff)
-uniform float uPointerAgitate;
-uniform float uPointerPush;    // signed membrane dome at the cursor (+ repel / − attract)
-uniform float uPointerWake;    // drag-wake trough amplitude (behind the moving cursor)
-uniform vec2  uPointerVel;     // smoothed pointer velocity, NDC/s (drag-wake direction)
-// Ribbon flow: stretch the falloff along the strip's length axis so the field reaches ALONG the
-// ribbon rather than as a screen disc. 0 = the plain circular smoothstep (byte-identical when off).
-uniform float uShapeFlow;
-varying float vPointerFall;    // falloff × presence — consumed by both fragment themes
-#ifdef POINTER_RIPPLES
-uniform vec2  uRippleOrigin[4]; // NDC
-uniform float uRippleAge[4];    // seconds since spawn (CPU-computed)
-uniform float uRippleAmp[4];    // shared 0..1 decay envelope per slot (CPU-computed; 0 = slot free)
-uniform float uPointerRipple;   // THIS wave's ripple amplitude (scales the shared envelope)
-const float RIPPLE_WAVE_SPEED = 0.85; // NDC/s the ring crest travels outward
-const float RIPPLE_SIGMA = 0.14;      // gaussian half-width of the travelling packet (NDC)
-const float RIPPLE_FREQ = 11.0;       // oscillation within the packet (one crest + faint troughs)
-const float RIPPLE_MAX_R = 1.2;       // reach where the crest has fully left the frame
-#endif
-#endif
-
+const waveShapeChunk = `
 // expStep: a falloff from 1 (at x=0) toward 0, sharpness set by n. The
 // max() guards pow(0, n) (= Infinity → NaN) so negative n is safe — negative n
 // just concentrates the twist toward the OTHER end instead.
@@ -225,27 +175,15 @@ mat4 rotationMatrix(vec3 axis, float angle){
   );
 }
 
-void main(){
-  vUv = uv;
-#ifndef LOOP_MOTION
-  float t = uTime * uSpeed + uSeed;
-#endif
-
-#ifdef LOOP_MOTION
-  // Seamless loop: rather than scrolling the noise field linearly by t (which never repeats),
-  // sample it on a circle of radius loopR at angle loopTheta — exactly periodic with period
-  // uLoopSeconds. The tangential speed loopR·dθ/dt equals uSpeed, so the looped motion advances
-  // at the same rate as the linear drift, just curved into a closed orbit (it orbits rather than
-  // drifts — the trade-off for a seamless loop, hence opt-in). uSeed offsets the phase so stacked
-  // waves keep their relative motion while sharing the single period.
-  float loopTheta = uTime * (6.28318530718 / uLoopSeconds) + uSeed;
-  float loopR = uSpeed * uLoopSeconds * 0.159154943092; // = uSpeed·uLoopSeconds / (2π)
-  vec2 loopOff = loopR * vec2(cos(loopTheta), sin(loopTheta));
-#endif
-
-  // The base geometry is already a baked hairpin fold. On top of it we deform the
-  // vertices: a displacement lifts Y by simplex noise of the (x,z) position, then
-  // three axis-rotations twist the strip.
+// The wave SHAPE deform, shared by the wave vertex shader (below) and the particle SHED emitter
+// (particleVertexShader): a base hairpin position + its uv → the displaced / helixed / twisted /
+// fanned LOCAL position, plus the three twist matrices (the pointer field reads them). Every branch
+// sits behind the SAME #ifdef gates as the code it replaces, so a given compiled program is
+// byte-identical to the former inline version. t / loopOff are the linear / orbit time the
+// caller computed; only the one selected by LOOP_MOTION is read (the other is a dead argument).
+struct WaveShape { vec3 pos; mat4 rotA; mat4 rotB; mat4 rotC; };
+WaveShape waveShape(vec3 position, vec2 uv, float t, vec2 loopOff){
+  // Displacement lifts Y by simplex noise of the (x,z) position.
   vec3 pos = position;
 #ifdef LOOP_MOTION
   pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX, pos.z * uDispFreqZ) + loopOff);
@@ -253,9 +191,7 @@ void main(){
   pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX + t, pos.z * uDispFreqZ + t));
 #endif
 #ifdef DETAIL_OCTAVE
-  // A second, finer octave riding on the broad swell — fine ripples on top of the big shape, a
-  // shape vocabulary single-octave displacement can't reach. Shares the loop orbit so it stays
-  // periodic when looping.
+  // A second, finer octave riding on the broad swell (loop-orbit shared so it stays periodic).
 #ifdef LOOP_MOTION
   pos.y += uDetailAmount * simplexNoise(vec2(pos.x * uDetailFreq, pos.z * uDetailFreq) + loopOff);
 #else
@@ -264,16 +200,8 @@ void main(){
 #endif
 
 #ifdef HELIX
-  // Helix — the one shape the three twists below cannot reach. Their angle is freq * expStep(uv),
-  // a MONOTONE falloff, so it can only ramp once; this one is periodic in uv.y (the length), so
-  // uHelixTurns full turns land evenly from end to end. Runs AFTER the displacement so the noise
-  // above still samples the undeformed pos.x/pos.z (byte-identical sampling), and BEFORE the twist
-  // so the two compose.
-  //   roll   rolls the ribbon's own cross-section about the axis in step with the sweep, swinging
-  //          its two long edges onto opposite sides — one wave becomes a ladder whose edges are
-  //          both strands (pair with the wireframe theme's rungs for the rungs between them).
-  //   radius carries the whole ribbon around the axis instead, orientation intact — a narrow ribbon
-  //          then reads as ONE strand, and a second wave at phase+180 is the other.
+  // Helix — the periodic sweep the three twists (monotone falloffs) can't reach. Runs AFTER the
+  // displacement (so the noise still samples undeformed pos) and BEFORE the twist (so they compose).
   float hAng = 6.28318530718 * uHelixTurns * uv.y + radians(uHelixPhase);
   // Roll about the ribbon's width centre, not the origin — see RIBBON_Z_CENTER in WaveGeometry.
   float rollA = hAng * uHelixRoll;
@@ -285,23 +213,19 @@ void main(){
   pos.z += uHelixRadius * sin(hAng);
 #endif
 
-  // The X-twist frequency feeding rotB. Two modes: by default uTwFreqX is used
-  // directly; the variant (used by the Wave 4 preset) modulates it with
-  // simplex noise indexed along the ribbon (uv.y) so the twist breathes over time.
-  // We gate the wobble with a #define so the compiled program is unchanged when off.
+  // The X-twist frequency feeding rotB; the TWIST_MOTION variant modulates it with simplex noise
+  // indexed along the ribbon (uv.y) so the twist breathes over time.
   float twistXFreq = uTwFreqX;
 #ifdef TWIST_MOTION
 #ifdef LOOP_MOTION
-  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, 0.0) + loopOff);
+  float twistXNoise = simplexNoise(vec2(uv.y * 2.0, 0.0) + loopOff);
 #else
-  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, t));
+  float twistXNoise = simplexNoise(vec2(uv.y * 2.0, t));
 #endif
   twistXFreq = uTwFreqX - twistXNoise * 0.1;
 #endif
 
-  // Three-axis twist: expStep falloff sets how
-  // sharply each rotation concentrates toward an edge. rotA keys off uv.x, rotB/rotC
-  // off uv.y; axes (0.5,0,0.5) and (0,0.5,0.5) are normalised inside rotationMatrix.
+  // Three-axis twist (see the falloff-axis note: rotA keys off uv.x/WIDTH, rotB/rotC off uv.y/LENGTH).
   mat4 rotA = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqY * expStep(uv.x, uTwPowY));
   mat4 rotB = rotationMatrix(vec3(0.0, 0.5, 0.5), twistXFreq * expStep(uv.y, uTwPowX));
   mat4 rotC = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqZ * expStep(uv.y, uTwPowZ));
@@ -309,19 +233,66 @@ void main(){
   pos = (vec4(pos, 1.0) * rotB).xyz;
   pos = (vec4(pos, 1.0) * rotC).xyz;
 
-#ifdef POINTER_FX
-  // Pointer field: displace along the wave's own (post-twist) up-axis, weighted by a screen-space
-  // falloff around the smoothed cursor — a circle at uShapeFlow 0, stretched along the ribbon as it
-  // rises. Everything here is ADDITIVE and fenced, so the shared path above/below is untouched and
-  // byte-identical when POINTER_FX is off.
-  // Shared clip-space transform, computed once and reused for the cursor metric and the ribbon
-  // tangent (the compiler is not guaranteed to CSE the triple product otherwise). Associativity is
-  // unchanged, so preClip is bit-for-bit what the plain P*V*M*v product produced.
-  mat4 mvp = projectionMatrix * viewMatrix * modelMatrix;
-  vec4 preClip = mvp * vec4(pos, 1.0);
+#ifdef RADIAL
+  // Radial fan: remap the ribbon to polar around the LOCAL origin so its LENGTH fans into a plume.
+  // uv.x (folded WIDTH) → fan ANGLE across uRadialArc; uv.y (LENGTH) → RADIUS, so a constant-uv.x
+  // combed fiber becomes a constant-angle radial spoke. mix(pos, fanned, 0) is identity → off is
+  // byte-identical. (Placement is the wave's position transform — the fan has no separate pivot.)
+  {
+    float rAng = radians(uRadialCenter) + (clamp(uv.x, 0.0, 1.0) - 0.5) * radians(uRadialArc);
+    float rRho = uRadialRadius + uv.y * 400.0 * uRadialSpread; // 400 = native ribbon length
+    vec3 rEr = vec3(cos(rAng), sin(rAng), 0.0);                // radial dir, in local X–Y (screen plane)
+    vec3 rEt = vec3(-sin(rAng), cos(rAng), 0.0);               // tangential
+    vec3 fanned = rEr * rRho
+                + rEt * (pos.z - ${(-8).toFixed(1)}) * 0.5
+                + vec3(0.0, 0.0, pos.y);
+    pos = mix(pos, fanned, clamp(uRadialAmount, 0.0, 1.0));
+  }
+#endif
+
+  WaveShape s;
+  s.pos = pos;
+  s.rotA = rotA;
+  s.rotB = rotB;
+  s.rotC = rotC;
+  return s;
+}
+`;
+const pointerFieldChunk = `
+uniform vec2  uPointer;        // smoothed pointer, NDC (-1..1)
+uniform float uPointerActive;  // presence ramp 0..1 × per-wave influence
+uniform float uPointerRadius;  // falloff radius in NDC-y units (config radius × 2)
+uniform float uPointerAspect;  // drawing-buffer dw/dh (circular screen falloff)
+uniform float uPointerAgitate;
+uniform float uPointerPush;    // signed membrane dome at the cursor (+ repel / − attract)
+uniform float uPointerWake;    // drag-wake trough amplitude (behind the moving cursor)
+uniform vec2  uPointerVel;     // smoothed pointer velocity, NDC/s (drag-wake direction)
+// Ribbon flow: stretch the falloff along the strip's length axis so the field reaches ALONG the
+// ribbon rather than as a screen disc. 0 = the plain circular smoothstep (byte-identical when off).
+uniform float uShapeFlow;
+#ifdef POINTER_RIPPLES
+uniform vec2  uRippleOrigin[4]; // NDC
+uniform float uRippleAge[4];    // seconds since spawn (CPU-computed)
+uniform float uRippleAmp[4];    // shared 0..1 decay envelope per slot (CPU-computed; 0 = slot free)
+uniform float uPointerRipple;   // THIS wave's ripple amplitude (scales the shared envelope)
+const float RIPPLE_WAVE_SPEED = 0.85; // NDC/s the ring crest travels outward
+const float RIPPLE_SIGMA = 0.14;      // gaussian half-width of the travelling packet (NDC)
+const float RIPPLE_FREQ = 11.0;       // oscillation within the packet (one crest + faint troughs)
+const float RIPPLE_MAX_R = 1.2;       // reach where the crest has fully left the frame
+#endif
+
+// fall = screen falloff × presence (the wave's vPointerFall, which both fragment themes consume);
+// disp = the signed displacement along the surface's own up-axis, which the CALLER applies (the wave
+// in its local space, the dust through the wave's world matrix).
+struct PointerHit { float fall; float disp; };
+
+// Sample the field for ONE point. ndc is that point's screen position; mvp the clip transform of the
+// space rotA/rotB/rotC and churnPos live in (the owning wave's local space); t / loopOff the caller's
+// linear / orbit time — only the one selected by LOOP_MOTION is read.
+PointerHit pointerField(vec2 ndc, mat4 mvp, mat4 rotA, mat4 rotB, mat4 rotC, vec3 churnPos,
+                        float t, vec2 loopOff){
   // Screen-space offset from the cursor (aspect-corrected → round in pixels). The DEFAULT metric.
-  vec2 ndcHere = preClip.xy / max(preClip.w, 1.0e-6);
-  vec2 dp = (ndcHere - uPointer) * vec2(uPointerAspect, 1.0);
+  vec2 dp = (ndc - uPointer) * vec2(uPointerAspect, 1.0);
   // Ribbon flow: stretch the metric along the strip's own LENGTH axis so the field reaches ALONG the
   // ribbon and stays tight across it — the "flows with the material" feel, per-vertex (so it follows
   // the strip's curve) with no CPU surface pick. The length axis is local +X (uv.x runs with x)
@@ -339,23 +310,19 @@ void main(){
       dp = vec2(dot(dp, tang) / (1.0 + uShapeFlow * 2.5), dot(dp, nrm)); // up to 3.5× reach along length
     }
   }
-  float fall = smoothstep(uPointerRadius, 0.0, length(dp));
-  vPointerFall = fall * uPointerActive;
-  // Displacement axis = local +Y carried through the SAME three twist rotations as pos (row-vector
-  // convention). Rotations are linear, so post-twist axis displacement equals pre-twist Y displacement.
-  vec3 dispAxis = (((vec4(0.0, 1.0, 0.0, 0.0) * rotA) * rotB) * rotC).xyz;
+  float fall = smoothstep(uPointerRadius, 0.0, length(dp)) * uPointerActive;
   // Agitation: a fast churn octave near the cursor (additive — never rewrites base noise t, which
   // would force restructuring the shared path). Loop-safe under both time variants.
 #ifdef LOOP_MOTION
-  float disp = uPointerAgitate * vPointerFall
-        * simplexNoise(vec2(pos.x * uDispFreqX * 3.0, pos.z * uDispFreqZ * 3.0) + loopOff * 4.0);
+  float disp = uPointerAgitate * fall
+        * simplexNoise(vec2(churnPos.x * uDispFreqX * 3.0, churnPos.z * uDispFreqZ * 3.0) + loopOff * 4.0);
 #else
-  float disp = uPointerAgitate * vPointerFall
-        * simplexNoise(vec2(pos.x * uDispFreqX * 3.0 + t * 4.0, pos.z * uDispFreqZ * 3.0));
+  float disp = uPointerAgitate * fall
+        * simplexNoise(vec2(churnPos.x * uDispFreqX * 3.0 + t * 4.0, churnPos.z * uDispFreqZ * 3.0));
 #endif
-  // Membrane push/pull: a smooth dome (vPointerFall is the falloff) that swells toward you (+ repel)
-  // or dents away (− attract) at the cursor, riding along with the sprung field.
-  disp += uPointerPush * vPointerFall;
+  // Membrane push/pull: a smooth dome (fall is the falloff) that swells toward you (+ repel) or dents
+  // away (− attract) at the cursor, riding along with the sprung field.
+  disp += uPointerPush * fall;
   // Drag-wake: pull the surface just BEHIND the moving cursor into a trailing trough. dp points
   // from cursor to vertex; "behind" is how far the vertex sits opposite the velocity (0 ahead → 1 a
   // radius behind), gated by speed so it only forms while dragging and heals when the cursor stops.
@@ -363,12 +330,12 @@ void main(){
   float wakeSpeed = length(velC);
   if (uPointerWake != 0.0 && wakeSpeed > 1.0e-4) {
     float behind = clamp(dot(-dp, velC) / (wakeSpeed * uPointerRadius), 0.0, 1.0);
-    disp -= uPointerWake * vPointerFall * behind * smoothstep(0.05, 0.6, wakeSpeed);
+    disp -= uPointerWake * fall * behind * smoothstep(0.05, 0.6, wakeSpeed);
   }
 #ifdef POINTER_RIPPLES
   for (int i = 0; i < 4; i++) {
     if (uRippleAmp[i] > 0.0) {
-      float rd = length((preClip.xy / max(preClip.w, 1.0e-6) - uRippleOrigin[i]) * vec2(uPointerAspect, 1.0));
+      float rd = length((ndc - uRippleOrigin[i]) * vec2(uPointerAspect, 1.0));
       // A wave PACKET whose crest travels outward at RIPPLE_WAVE_SPEED: a gaussian window centred on
       // the moving front carrying a short oscillation (a raised ring with faint trailing troughs),
       // so the energy radiates instead of throbbing at the click point. The shared uRippleAmp
@@ -381,7 +348,99 @@ void main(){
     }
   }
 #endif
-  pos += dispAxis * disp;
+  PointerHit hit;
+  hit.fall = fall;
+  hit.disp = disp;
+  return hit;
+}
+`;
+const vertexShader = `
+${simplex2d}
+
+uniform float uTime, uSpeed, uSeed;
+uniform float uDispFreqX, uDispFreqZ, uDispAmount;
+uniform float uDetailFreq, uDetailAmount; // 2nd displacement octave (only read under DETAIL_OCTAVE)
+uniform float uTwFreqX, uTwFreqY, uTwFreqZ, uTwPowX, uTwPowY, uTwPowZ;
+uniform float uLoopSeconds; // seamless-loop period (only read under LOOP_MOTION)
+
+// Helix (optional). Behind HELIX so a wave without one compiles the exact same program — same
+// byte-identity contract as the pointer block below.
+#ifdef HELIX
+uniform float uHelixTurns;  // full turns from one end of the ribbon to the other
+uniform float uHelixRadius; // orbit radius: carries the whole ribbon around the axis
+uniform float uHelixRoll;   // cross-section roll, as a fraction of the turns (1 = rigid ladder)
+uniform float uHelixPhase;  // degrees
+#endif
+
+// Radial fan (optional). Behind RADIAL so a wave without one compiles the exact same program (same
+// byte-identity contract as HELIX / POINTER_FX above).
+#ifdef RADIAL
+uniform float uRadialAmount; // 0..1 blend (0 = identity)
+uniform float uRadialArc;    // fan spread, degrees
+uniform float uRadialSpread; // length → radius scale
+uniform float uRadialRadius; // source / inner radius
+uniform float uRadialCenter; // base angle, degrees
+#endif
+
+varying vec2 vUv;
+varying vec3 vWorldPos;
+varying vec3 vViewDir;
+varying vec4 vClipPosition; // = gl_Position, for the wireframe theme's depth fade
+
+// Pointer field (optional, additive) — the shared chunk, gated so a wave with no interaction config
+// compiles the exact same program. The particle emitter interpolates the SAME chunk, so dust reacts
+// through one implementation of the footprint / falloff / displacement.
+#ifdef POINTER_FX
+${pointerFieldChunk}
+varying float vPointerFall;    // falloff × presence — consumed by both fragment themes
+#endif
+
+${waveShapeChunk}
+
+void main(){
+  vUv = uv;
+#ifndef LOOP_MOTION
+  float t = uTime * uSpeed + uSeed;
+  vec2 loopOff = vec2(0.0); // unused under linear time; kept so waveShape's signature is uniform
+#endif
+
+#ifdef LOOP_MOTION
+  // Seamless loop: rather than scrolling the noise field linearly by t (which never repeats),
+  // sample it on a circle of radius loopR at angle loopTheta — exactly periodic with period
+  // uLoopSeconds. The tangential speed loopR·dθ/dt equals uSpeed, so the looped motion advances
+  // at the same rate as the linear drift, just curved into a closed orbit (it orbits rather than
+  // drifts — the trade-off for a seamless loop, hence opt-in). uSeed offsets the phase so stacked
+  // waves keep their relative motion while sharing the single period.
+  float loopTheta = uTime * (6.28318530718 / uLoopSeconds) + uSeed;
+  float loopR = uSpeed * uLoopSeconds * 0.159154943092; // = uSpeed·uLoopSeconds / (2π)
+  vec2 loopOff = loopR * vec2(cos(loopTheta), sin(loopTheta));
+  float t = 0.0; // unused under loop time
+#endif
+
+  // Deform the baked hairpin via the shared waveShape chunk (displacement + helix + twist + radial),
+  // which also drives the particle shed emitter. It returns the deformed local pos + the twist
+  // matrices the pointer field reads below.
+  WaveShape ws = waveShape(position, uv, t, loopOff);
+  vec3 pos = ws.pos;
+
+#ifdef POINTER_FX
+  // Pointer field: displace along the wave's own (post-twist) up-axis, weighted by a screen-space
+  // falloff around the smoothed cursor — a circle at uShapeFlow 0, stretched along the ribbon as it
+  // rises. Everything here is ADDITIVE and fenced, so the shared path above/below is untouched and
+  // byte-identical when POINTER_FX is off. The field itself lives in pointerFieldChunk, which the
+  // particle emitter also calls — so dust reacts through this exact footprint and falloff.
+  // Shared clip-space transform, computed once and reused for the cursor metric and the ribbon
+  // tangent (the compiler is not guaranteed to CSE the triple product otherwise). Associativity is
+  // unchanged, so preClip is bit-for-bit what the plain P*V*M*v product produced.
+  mat4 mvp = projectionMatrix * viewMatrix * modelMatrix;
+  vec4 preClip = mvp * vec4(pos, 1.0);
+  PointerHit hit = pointerField(preClip.xy / max(preClip.w, 1.0e-6), mvp,
+                                ws.rotA, ws.rotB, ws.rotC, pos, t, loopOff);
+  vPointerFall = hit.fall;
+  // Displacement axis = local +Y carried through the SAME three twist rotations as pos (row-vector
+  // convention). Rotations are linear, so post-twist axis displacement equals pre-twist Y displacement.
+  vec3 dispAxis = (((vec4(0.0, 1.0, 0.0, 0.0) * ws.rotA) * ws.rotB) * ws.rotC).xyz;
+  pos += dispAxis * hit.disp;
 #endif
 
   // The scale / rotation / position transform lives on the mesh (modelMatrix), so the
@@ -434,7 +493,7 @@ uniform vec3 uDepthTintColor;
 varying vec4 vClipPosition; // clip-space depth (written by the vertex shader for both programs)
 #endif
 #ifdef EDGE_FEATHER
-uniform float uEdgeFeather; // ribbon long-edge softness (only when it differs from the 0.1 default)
+uniform float uEdgeFeather; // softness of the ribbon's two ENDS (only when it differs from 0.1)
 #endif
 #ifdef POINTER_FX
 uniform float uPointerThin;    // 0..1 local translucency near the cursor
@@ -474,8 +533,10 @@ vec3 surfaceStreaks(vec2 uv, vec3 color, float crease){
     colorAtten = mix(colorAtten, prm.w, blend);
     paraPow = mix(paraPow, uNoiseBandParaPow[i], blend);
   }
-  // The high frequency runs along uv.x (the ribbon's length) so the streaks read as
-  // fine lengthwise fibers; end-weighted by 1 - parabola(uv.x).
+  // The high frequency runs along uv.x (the folded WIDTH — see WaveGeometry's UV AXES note),
+  // packing many thin stripes across the cross-section while uv.y is barely scaled, so each
+  // one stretches out into a fine LENGTHWISE fiber. 1 - parabola(uv.x) then weights them
+  // toward the two long edges and away from the width centreline.
   float p = 1.0 - parabola(uv.x, paraPow);
   float n0 = simplexNoise(vec2(uv.x * 0.1, uv.y * 0.5));
   float n1 = simplexNoise(vec2(uv.x * (freq + freq * 0.5 * n0), uv.y * 4.0 * n0));
@@ -564,7 +625,8 @@ void main(){
 
   if (uTexture > 0.001) col *= 1.0 + (grainHash(vUv * 850.0) - 0.5) * uTexture * 0.25;
 
-  // Soft long edges + optional viewport-edge fade. The edge softness is the hardcoded 0.1 by
+  // Soft ribbon ENDS (it fades on vUv.y, the length) + optional viewport-edge fade. The edge
+  // softness is the hardcoded 0.1 by
   // default (literal branch → byte-identical); EDGE_FEATHER swaps in the uEdgeFeather knob only
   // when it differs, so razor-crisp or vapor-soft edges are both reachable.
 #ifdef EDGE_FEATHER
@@ -638,7 +700,7 @@ void main(){
   color *= 1.0 + uPointerLighten * vPointerFall;
 #endif
 
-  // Carve into fine vertical lines; thickness from the screen-space uv derivative.
+  // Carve into fine lengthwise strands; thickness from the screen-space uv derivative.
   vec2 dy = dFdy(vUv);
   float lineThickness = uLineThickness * pow(abs(dy.x * uMaxWidth), uLineDerivativePower);
 #ifdef POINTER_FX
@@ -897,7 +959,195 @@ void main(){
   gl_FragColor = vec4(mix(src.rgb, outc, clamp(uHalftoneCmyk, 0.0, 1.0)), src.a);
 }
 `;
+const particleVertexShader = `
+attribute float aSeed;
+attribute vec4 aRnd;
+attribute vec2 aUv; // where this particle spawns on the ribbon (x = flank, y = along length; edge-biased at build)
+
+uniform float uTime, uLoopSeconds, uLife, uSize, uSizeJitter, uTwinkle, uPixelRatio;
+uniform float uPartSpeed;
+uniform vec3 uColor, uColor2, uCenter, uRight, uUp;
+uniform float uDrift, uRise, uSwirl, uWander;
+
+// The owning wave's shape, mirrored in configure() so the dust rides the SAME deform as the ribbon.
+// The HELIX/RADIAL uniform blocks are declared only when the matching #define is set.
+${simplex2d}
+uniform float uDispFreqX, uDispFreqZ, uDispAmount;
+uniform float uDetailFreq, uDetailAmount;
+uniform float uTwFreqX, uTwFreqY, uTwFreqZ, uTwPowX, uTwPowY, uTwPowZ;
+#ifdef HELIX
+uniform float uHelixTurns, uHelixRadius, uHelixRoll, uHelixPhase;
+#endif
+#ifdef RADIAL
+uniform float uRadialAmount, uRadialArc, uRadialSpread, uRadialRadius, uRadialCenter;
+#endif
+uniform mat4 uShedModel;              // the wave's matrixWorld (deformed LOCAL → world)
+uniform float uShedSpeed, uShedSeed;
+${waveShapeChunk}
+
+// The cursor. Same chunk the ribbon uses, mirrored onto this material in ParticleField.configure(),
+// and behind the same POINTER_FX gate — a wave with no hover field compiles the point program it
+// always did. uPartShove is the one particle-only knob (see the two samples in main).
+#ifdef POINTER_FX
+${pointerFieldChunk}
+uniform float uPartShove; // how hard the cursor shoves dust that has already drifted free (0 = off)
+#endif
+
+varying float vAlpha;
+varying vec3 vColor;
+varying vec2 vDir; // screen-space motion direction (for the streak sprite)
+
+const float TAU = 6.28318530718;
+
+void main(){
+  // Deterministic life: age 0..1 from uTime + a per-particle seed. Advances once per loop period when
+  // looping (so the whole field repeats seamlessly), else once per uLife seconds. uPartSpeed scales the
+  // cadence (motion speed); under a loop it snaps to a whole number of cycles so the seam stays seamless.
+  float cyc = max(1.0, floor(uPartSpeed + 0.5));
+  float rate = (uLoopSeconds > 0.0) ? (uTime / uLoopSeconds * cyc) : (uTime * uPartSpeed / max(uLife, 0.001));
+  float age = fract(rate + aSeed);
+  float fade = sin(3.14159265 * age); // 0 at birth/death, 1 mid-life
+
+  // Spawn on the owning wave's DEFORMED surface / edge at aUv (via the shared waveShape), then peel
+  // outward from the wave centre as the particle ages — silk dissolving into glitter.
+  float ts = uTime * uShedSpeed + uShedSeed;
+  vec2 loopOff = vec2(0.0);
+#ifdef LOOP_MOTION
+  float loopTheta = uTime * (TAU / uLoopSeconds) + uShedSeed;
+  float loopR = uShedSpeed * uLoopSeconds * 0.159154943092;
+  loopOff = loopR * vec2(cos(loopTheta), sin(loopTheta));
+  ts = 0.0;
+#endif
+  // Approximate the base hairpin point for this uv (length from uv.y; width centre), then deform it
+  // exactly as the wave does. Good enough for dust — the fan / displacement dominate.
+  vec3 base = vec3((aUv.y - 0.5) * 400.0, 0.0, ${(-8).toFixed(1)});
+  WaveShape ws = waveShape(base, aUv, ts, loopOff);
+  vec3 origin = (uShedModel * vec4(ws.pos, 1.0)).xyz;
+  vec3 outward = normalize(origin - uCenter + vec3(1e-4));
+
+#ifdef POINTER_FX
+  // WELD (applied below, once the mote's own motion is known). The ribbon displaces its surface by
+  // pointerField() along its own post-twist up-axis; a mote sitting ON that surface has to take the
+  // same ride, or the cursor's dome lifts the silk out from under its own glitter. Sampled at the
+  // SPAWN point and carried through the local→world matrix exactly as the ribbon's own
+  // pos += dispAxis * disp is, so the two land on the same place. Sampling at the spawn point also
+  // leaves outward derived from the UNDISPLACED origin, so a poke never bends the drift direction.
+  mat4 pMvp = projectionMatrix * viewMatrix * uShedModel;
+  vec4 originClip = pMvp * vec4(ws.pos, 1.0);
+  vec3 dispAxis = mat3(uShedModel) * (((vec4(0.0, 1.0, 0.0, 0.0) * ws.rotA) * ws.rotB) * ws.rotC).xyz;
+  PointerHit weld = pointerField(originClip.xy / max(originClip.w, 1.0e-6), pMvp,
+                                 ws.rotA, ws.rotB, ws.rotC, ws.pos, ts, loopOff);
+#endif
+
+  vec3 p = origin + outward * age * uDrift + (aRnd.xyz - 0.5) * age * uDrift * 0.35;
+
+  // Motion styles, each 0 = off, all riding age so they stay loop-safe (the age wrap is hidden by
+  // fade→0 at birth/death). rise = screen-vertical buoyancy (embers up / snow down); swirl = orbit
+  // around the wave centre in the screen plane; wander = curl-noise turbulence (fireflies / motes).
+  p += uUp * age * uRise;
+  // How far this mote travels away from its birth patch over a WHOLE life — the straight-line terms
+  // plus, under swirl, the arc it sweeps at its own orbit radius. Only the pointer weld reads it
+  // (0 for dust that merely clings to the surface, which is exactly the case age would get wrong),
+  // so it is fenced like everything else the cursor drives.
+#ifdef POINTER_FX
+  float span = abs(uDrift) * 1.35 + abs(uRise) + uWander;
+#endif
+  if (uSwirl != 0.0) {
+    vec3 nrm = cross(uRight, uUp);
+    vec3 rel = p - uCenter;
+#ifdef POINTER_FX
+    span += abs(uSwirl) * TAU * length(rel);
+#endif
+    float rx = dot(rel, uRight), ry = dot(rel, uUp), rz = dot(rel, nrm);
+    float a = age * uSwirl * TAU;
+    float ca = cos(a), sa = sin(a);
+    p = uCenter + uRight * (rx * ca - ry * sa) + uUp * (rx * sa + ry * ca) + nrm * rz;
+  }
+  if (uWander != 0.0) {
+    vec2 wan = vec2(simplexNoise(vec2(aSeed * 17.0, age * 3.0)),
+                    simplexNoise(vec2(age * 3.0, aSeed * 23.0)));
+    p += (uRight * wan.x + uUp * wan.y) * uWander;
+  }
+
+#ifdef POINTER_FX
+  // How attached to its birth patch this mote still is: 1 while it sits on the surface, 0 once it
+  // has travelled a full life's worth away. Measured from the DISTANCE it actually moved rather than
+  // from age, because dust with no drift / rise / swirl / wander never leaves the surface at all —
+  // an age fade would quietly stop that dust from following the ribbon halfway through its life.
+  float attach = span > 1.0e-4 ? 1.0 - clamp(length(p - origin) / span, 0.0, 1.0) : 1.0;
+  p += dispAxis * (weld.disp * attach);
+  // SHOVE: the exact complement. The same field sampled at the mote's OWN screen position, so the
+  // cursor also pushes dust that has already left the surface — and a click ripple visibly blows
+  // through the cloud instead of stopping dead at the ribbon. Uniform branch (warp-coherent), so
+  // uPartShove 0 costs nothing.
+  if (uPartShove != 0.0) {
+    vec4 pClip = projectionMatrix * viewMatrix * vec4(p, 1.0);
+    PointerHit shove = pointerField(pClip.xy / max(pClip.w, 1.0e-6), pMvp,
+                                    ws.rotA, ws.rotB, ws.rotC, ws.pos, ts, loopOff);
+    p += dispAxis * (shove.disp * (1.0 - attach) * uPartShove);
+  }
+#endif
+
+  float tw = 0.5 + 0.5 * sin((age * 9.0 + aSeed) * TAU); // loop-safe flicker (rides age)
+  vAlpha = fade * mix(1.0, tw, clamp(uTwinkle, 0.0, 1.0));
+  vColor = mix(uColor, uColor2, aRnd.w); // two-tone dust: per-particle blend of the two colours
+  vDir = normalize(vec2(dot(outward, uRight), dot(outward, uUp)) + vec2(1e-4)); // outward, in screen space
+  gl_Position = projectionMatrix * viewMatrix * vec4(p, 1.0);
+  // Orthographic camera → point size is constant in device pixels (no perspective depth divide).
+  float jitter = 1.0 + uSizeJitter * (aSeed - 0.5) * 2.0;
+  gl_PointSize = max(uSize * uPixelRatio * jitter * fade, 0.0);
+}
+`;
+const particleFragmentShader = `
+precision highp float;
+uniform float uShape; // 0 glitter · 1 soft · 2 ring · 3 star · 4 streak
+varying float vAlpha;
+varying vec3 vColor;
+varying vec2 vDir;
+// User artwork (shape "sprite"), behind a define so a field without one compiles the exact same
+// program — and so the sampler only exists once a texture is actually bound to it. ONE texture is
+// shared by every particle in the field; see ParticleField.loadSprite for the rasterization.
+#ifdef PARTICLE_SPRITE
+uniform sampler2D uSprite;
+#endif
+void main(){
+#ifdef PARTICLE_SPRITE
+  // gl_PointCoord's origin is the sprite's TOP-left with y running DOWN, so it has to be flipped or
+  // every sprite draws upside down. The procedural shapes below never needed this — they are all
+  // symmetric about y, which is exactly why the bug would have gone unnoticed.
+  vec4 tex = texture2D(uSprite, vec2(gl_PointCoord.x, 1.0 - gl_PointCoord.y));
+  float a = tex.a * vAlpha;
+  if (a <= 0.0) discard;
+  // Tinted by the dust colour so color / color2 keep working: white artwork takes the tint
+  // exactly, coloured artwork multiplies it.
+  gl_FragColor = vec4(vColor * tex.rgb, a);
+#else
+  vec2 pc = gl_PointCoord - 0.5;
+  float d = length(pc);
+  int s = int(uShape + 0.5);
+  float a;
+  if (s == 1) {                    // soft: a diffuse gaussian blob (motes / pollen)
+    a = exp(-d * d * 7.0);
+  } else if (s == 2) {             // ring: a hollow band (bubbles)
+    a = smoothstep(0.09, 0.0, abs(d - 0.34));
+  } else if (s == 3) {             // star: a 4-point sparkle
+    float ang = atan(pc.y, pc.x);
+    float spike = pow(abs(cos(ang * 2.0)), 6.0);
+    a = smoothstep(1.0, 0.0, d / (0.14 + 0.5 * spike));
+  } else if (s == 4) {             // streak: an elongated comet along the motion direction
+    float along = dot(pc, vDir);
+    float perp = dot(pc, vec2(-vDir.y, vDir.x));
+    a = smoothstep(0.5, 0.0, length(vec2(along * 0.42, perp * 2.2)));
+  } else {                         // glitter (0): the soft round additive disc
+    a = smoothstep(0.5, 0.0, d);
+  }
+  a *= vAlpha;
+  if (a <= 0.0) discard;
+  gl_FragColor = vec4(vColor, a); // AdditiveBlending (src = SrcAlpha) → adds vColor·a
+#endif
+}
+`;
 //#endregion
-export { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader };
+export { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, particleFragmentShader, particleVertexShader, postFragmentShader, postVertexShader, vertexShader };
 
 //# sourceMappingURL=shaders.js.map