@wave3d/core 0.2.2 → 0.4.1

package/dist/renderer/shaders.js

@@ -171,6 +171,34 @@ 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
+
 // 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.
@@ -250,6 +278,81 @@ 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);
+  // 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);
+  // 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)
+  // carried through the SAME twist as the surface. The camera is orthographic (affine, w=1), so the
+  // axis's screen image is the linear map of the DIRECTION (w=0): one mat·dir, no second
+  // point-projection and no perspective divide. (A true per-pixel uv would need GPU picking — the
+  // visible surface is shader-displaced, so a CPU raycast of the base geometry misses.)
+  if (uShapeFlow > 0.0) {
+    vec3 tangentLocal = (((vec4(1.0, 0.0, 0.0, 0.0) * rotA) * rotB) * rotC).xyz;
+    vec2 tang = (mvp * vec4(tangentLocal, 0.0)).xy * vec2(uPointerAspect, 1.0);
+    float tl = length(tang);
+    if (tl > 1.0e-6) {
+      tang /= tl;
+      vec2 nrm = vec2(-tang.y, tang.x);
+      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;
+  // 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);
+#else
+  float disp = uPointerAgitate * vPointerFall
+        * simplexNoise(vec2(pos.x * uDispFreqX * 3.0 + t * 4.0, pos.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;
+  // 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.
+  vec2 velC = uPointerVel * vec2(uPointerAspect, 1.0);
+  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);
+  }
+#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));
+      // 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
+      // envelope fades the whole packet over its lifetime; reach fades it as the crest leaves frame.
+      float front = uRippleAge[i] * RIPPLE_WAVE_SPEED;
+      float band  = rd - front;
+      float packet = exp(-band * band / (2.0 * RIPPLE_SIGMA * RIPPLE_SIGMA)) * cos(band * RIPPLE_FREQ);
+      float reach = 1.0 - smoothstep(RIPPLE_MAX_R * 0.7, RIPPLE_MAX_R, front);
+      disp += uPointerRipple * uRippleAmp[i] * packet * reach;
+    }
+  }
+#endif
+  pos += dispAxis * disp;
+#endif
+
   // The scale / rotation / position transform lives on the mesh (modelMatrix), so the
   // orientation matches THREE's Euler-XYZ rather than an in-shader rotation order.
   vec4 world = modelMatrix * vec4(pos, 1.0);
@@ -302,6 +405,12 @@ varying vec4 vClipPosition; // clip-space depth (written by the vertex shader fo
 #ifdef EDGE_FEATHER
 uniform float uEdgeFeather; // ribbon long-edge softness (only when it differs from the 0.1 default)
 #endif
+#ifdef POINTER_FX
+uniform float uPointerThin;    // 0..1 local translucency near the cursor
+uniform float uPointerHue;     // degrees, local hue rotation near the cursor
+uniform float uPointerLighten; // -1..1 local brightness lift near the cursor
+varying float vPointerFall;    // falloff × presence, written by the vertex shader
+#endif
 
 // Cheap value hash for the optional grain overlay (distinct from the simplex hash).
 float grainHash(vec2 p){ return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }
@@ -366,6 +475,12 @@ void main(){
   col = surfaceStreaks(vUv, col, crease);
   col = applyColorGrade(col);
 
+#ifdef POINTER_FX
+  // Local hue rotation + brightness lift near the cursor (both fade out with vPointerFall).
+  col = hueShift(col, radians(uPointerHue) * vPointerFall);
+  col *= 1.0 + uPointerLighten * vPointerFall;
+#endif
+
   // Iridescence: a thin-film / holographic hue that shifts with view angle. Reuses the same
   // camera-facing ratio as roundness (recomputed here, since roundness may be off): grazing parts
   // of the ribbon (low facing) shift hue most, so the colour flows as the ribbon curves. Skipped
@@ -428,6 +543,9 @@ void main(){
   float ribEdge = smoothstep(0.0, 0.1, vUv.y) * (1.0 - smoothstep(0.9, 1.0, vUv.y));
 #endif
   float alpha = uOpacity * ribEdge;
+#ifdef POINTER_FX
+  alpha *= clamp(1.0 - uPointerThin * vPointerFall, 0.0, 1.0); // solid: local translucency
+#endif
   if (uEdgeFade > 0.001) {
     vec2 sc = gl_FragCoord.xy / max(uResolution, vec2(1.0));
     float vig =
@@ -466,6 +584,12 @@ uniform vec3 uClearColor;           // = page background colour (shown between t
 
 varying vec2 vUv;
 varying vec4 vClipPosition;
+#ifdef POINTER_FX
+uniform float uPointerThin;    // 0..1 — strands taper to hairlines near the cursor
+uniform float uPointerHue;     // degrees, local hue rotation near the cursor
+uniform float uPointerLighten; // -1..1 local brightness lift near the cursor
+varying float vPointerFall;    // falloff × presence, written by the vertex shader
+#endif
 
 ${colorFns}
 
@@ -473,9 +597,17 @@ void main(){
   // Same 2D palette sample + colour ops as the solid theme.
   vec3 color = applyColorGrade(waveBaseColor(vUv));
 
+#ifdef POINTER_FX
+  color = hueShift(color, radians(uPointerHue) * vPointerFall);
+  color *= 1.0 + uPointerLighten * vPointerFall;
+#endif
+
   // Carve into fine vertical lines; thickness from the screen-space uv derivative.
   vec2 dy = dFdy(vUv);
   float lineThickness = uLineThickness * pow(abs(dy.x * uMaxWidth), uLineDerivativePower);
+#ifdef POINTER_FX
+  lineThickness *= clamp(1.0 - uPointerThin * vPointerFall, 0.0, 1.0); // wireframe: taper strands
+#endif
   float a = abs(sin(vUv.x * uLineAmount));
   a = smoothstep(lineThickness, 0.0, a);
 
@@ -539,7 +671,187 @@ void main(){
   gl_FragColor = color;   // preserve alpha → transparent background works
 }
 `;
+const ditherFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform vec2 uResolution;
+uniform float uDitherStrength;  // 0..1 mix back toward the original
+uniform float uDitherScale;     // pixel-block size in device px (paper: u_pxSize)
+uniform float uDitherSteps;     // quantization levels (paper: u_colorSteps)
+varying vec2 vUv;
+
+const int bayer2x2[4] = int[4](0, 2, 3, 1);
+const int bayer4x4[16] = int[16](0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5);
+const int bayer8x8[64] = int[64](
+  0, 32, 8, 40, 2, 34, 10, 42, 48, 16, 56, 24, 50, 18, 58, 26,
+  12, 44, 4, 36, 14, 46, 6, 38, 60, 28, 52, 20, 62, 30, 54, 22,
+  3, 35, 11, 43, 1, 33, 9, 41, 51, 19, 59, 27, 49, 17, 57, 25,
+  15, 47, 7, 39, 13, 45, 5, 37, 63, 31, 55, 23, 61, 29, 53, 21
+);
+float getBayerValue(vec2 uv, int size){
+  ivec2 pos = ivec2(fract(uv / float(size)) * float(size));
+  int index = pos.y * size + pos.x;
+  if (size == 2) return float(bayer2x2[index]) / 4.0;
+  else if (size == 4) return float(bayer4x4[index]) / 16.0;
+  else if (size == 8) return float(bayer8x8[index]) / 64.0;
+  return 0.0;
+}
+
+void main(){
+  float pxSize = max(uDitherScale, 1.0);
+  vec2 pxSizeUV = gl_FragCoord.xy / pxSize;
+  vec2 sampleUV = (floor(gl_FragCoord.xy / pxSize) + 0.5) * pxSize / max(uResolution, vec2(1.0));
+  vec4 image = texture2D(tDiffuse, sampleUV);
+
+  float lum = dot(vec3(0.2126, 0.7152, 0.0722), image.rgb);
+  float colorSteps = max(floor(uDitherSteps), 1.0);
+
+  float dithering = getBayerValue(pxSizeUV, 8) - 0.5;   // paper's default 8x8 ordered screen
+  float brightness = clamp(lum + dithering / colorSteps, 0.0, 1.0);
+  brightness = mix(0.0, brightness, image.a);
+  float quantLum = floor(brightness * colorSteps + 0.5) / colorSteps;
+
+  // paper's "original colours" path: keep the source hue, quantize luminance.
+  vec3 color = image.rgb / max(lum, 0.001) * quantLum;
+  float quantAlpha = floor(image.a * colorSteps + 0.5) / colorSteps;
+  float opacity = mix(quantLum, 1.0, quantAlpha);
+
+  gl_FragColor = mix(image, vec4(color, opacity), clamp(uDitherStrength, 0.0, 1.0));
+}
+`;
+const innerLightFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform float uInnerLight;        // 0..1 strength of the added light
+uniform float uInnerLightDensity; // ray length / spread
+uniform float uInnerLightDecay;   // per-sample falloff (<1)
+uniform vec2  uInnerLightCenter;  // light source, UV (0..1)
+varying vec2 vUv;
+
+const int LIGHT_SAMPLES = 24;
+
+float luma(vec3 c){ return dot(c, vec3(0.2126, 0.7152, 0.0722)); }
+
+void main(){
+  vec4 src = texture2D(tDiffuse, vUv);
+  vec2 delta = (vUv - uInnerLightCenter) * (uInnerLightDensity / float(LIGHT_SAMPLES));
+  vec2 coord = vUv;
+  float decay = 1.0;
+  vec3 rays = vec3(0.0);
+  for (int i = 0; i < LIGHT_SAMPLES; i++){
+    coord -= delta;
+    vec4 s = texture2D(tDiffuse, coord);
+    rays += s.rgb * s.a * decay;   // only opaque (wave) pixels emit light
+    decay *= uInnerLightDecay;
+  }
+  rays /= float(LIGHT_SAMPLES);
+  vec3 outc = src.rgb + rays * uInnerLight;
+  float outA = max(src.a, luma(rays) * uInnerLight); // shafts stay visible over the transparent bg
+  gl_FragColor = vec4(outc, clamp(outA, 0.0, 1.0));
+}
+`;
+const halftoneFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform vec2 uResolution;
+uniform float uHalftone;      // 0..1 mix
+uniform float uHalftoneCell;  // dot cell size in device px (paper: u_size)
+uniform float uHalftoneAngle; // screen rotation (radians, paper: u_rotation)
+varying vec2 vUv;
+
+float sigmoid(float x, float k){ return 1.0 / (1.0 + exp(-k * (x - 0.5))); }
+// paper's classic dot: radius grows as the sampled cell darkens (1 - lum), soft edge via fwidth.
+float getCircle(vec2 uv, float lum, float baseR){
+  float r = mix(0.25 * baseR, 0.0, lum);
+  float d = length(uv - 0.5);
+  float aa = fwidth(d);
+  return 1.0 - smoothstep(r - aa, r + aa, d);
+}
+
+void main(){
+  float ca = cos(uHalftoneAngle);
+  float sa = sin(uHalftoneAngle);
+  mat2 rot = mat2(ca, sa, -sa, ca);
+  float cell = max(uHalftoneCell, 2.0);
+  vec2 gridPx = rot * gl_FragCoord.xy;                      // rotate the screen into the dot grid
+  vec2 cellId = floor(gridPx / cell);
+  vec2 inCell = fract(gridPx / cell);                       // position within the cell (0..1)
+  vec2 centrePx = transpose(rot) * ((cellId + 0.5) * cell); // cell centre, back in screen px
+  vec4 tex = texture2D(tDiffuse, centrePx / max(uResolution, vec2(1.0)));
+
+  float k = 2.0;                                            // sigmoid contrast (paper default)
+  vec3 c = vec3(sigmoid(tex.r, k), sigmoid(tex.g, k), sigmoid(tex.b, k));
+  float lum = dot(vec3(0.2126, 0.7152, 0.0722), c);
+  lum = mix(1.0, lum, tex.a);
+  float dot = getCircle(inCell, lum, 1.3);                 // baseR 1.3 ≈ paper original-colours default
+  vec4 dots = vec4(tex.rgb, tex.a * dot);                  // wave-coloured dots, transparent between
+  gl_FragColor = mix(texture2D(tDiffuse, vUv), dots, clamp(uHalftone, 0.0, 1.0));
+}
+`;
+const heatmapFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform float uHeatmap;   // 0..1 mix
+varying vec2 vUv;
+vec3 heat(float t){
+  t = clamp(t, 0.0, 1.0);
+  vec3 c = mix(vec3(0.0, 0.0, 0.4), vec3(0.0, 0.6, 1.0), smoothstep(0.0, 0.25, t));
+  c = mix(c, vec3(0.0, 1.0, 0.4), smoothstep(0.25, 0.5, t));
+  c = mix(c, vec3(1.0, 1.0, 0.0), smoothstep(0.5, 0.75, t));
+  c = mix(c, vec3(1.0, 0.1, 0.0), smoothstep(0.75, 1.0, t));
+  return c;
+}
+void main(){
+  vec4 src = texture2D(tDiffuse, vUv);
+  float l = dot(src.rgb, vec3(0.299, 0.587, 0.114));
+  gl_FragColor = vec4(mix(src.rgb, heat(l), clamp(uHeatmap, 0.0, 1.0)), src.a);
+}
+`;
+const paperTextureFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform float uPaper;      // 0..1 strength
+uniform float uPaperScale; // grain scale
+varying vec2 vUv;
+float h21(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+void main(){
+  vec4 src = texture2D(tDiffuse, vUv);
+  vec2 p = gl_FragCoord.xy / max(uPaperScale, 0.5);
+  float fiber = h21(floor(p)) * 0.5 + h21(floor(p * vec2(0.3, 3.0))) * 0.5; // directional fibers
+  float tex = mix(fiber, h21(gl_FragCoord.xy), 0.3);                        // + fine speckle
+  float shade = 1.0 - (tex - 0.5) * 0.35;
+  gl_FragColor = vec4(src.rgb * mix(1.0, shade, clamp(uPaper, 0.0, 1.0)), src.a);
+}
+`;
+const halftoneCmykFragmentShader = `
+uniform sampler2D tDiffuse;
+uniform float uHalftoneCmyk;     // 0..1 mix
+uniform float uHalftoneCmykCell; // dot cell size in device px
+varying vec2 vUv;
+// One rotated halftone dot screen for a channel value.
+float dotScreen(vec2 coord, float value, float angle, float cell){
+  float ca = cos(angle);
+  float sa = sin(angle);
+  vec2 r = mat2(ca, sa, -sa, ca) * coord;
+  vec2 c = fract(r / max(cell, 2.0)) - 0.5;
+  float radius = sqrt(clamp(value, 0.0, 1.0)) * 0.5;
+  return smoothstep(radius, radius - 0.06, length(c));
+}
+void main(){
+  vec4 src = texture2D(tDiffuse, vUv);
+  float k = 1.0 - max(max(src.r, src.g), src.b);   // RGB → CMYK
+  float invK = max(1.0 - k, 1e-3);
+  float cyan = (1.0 - src.r - k) / invK;
+  float mag = (1.0 - src.g - k) / invK;
+  float yel = (1.0 - src.b - k) / invK;
+  vec2 coord = gl_FragCoord.xy;
+  float cell = uHalftoneCmykCell;
+  float dc = dotScreen(coord, cyan, 1.309, cell); // 75°
+  float dm = dotScreen(coord, mag, 0.262, cell);  // 15°
+  float dy = dotScreen(coord, yel, 0.0, cell);    // 0°
+  float dk = dotScreen(coord, k, 0.785, cell);    // 45°
+  // Subtractive: cyan ink absorbs red, magenta absorbs green, yellow absorbs blue, black absorbs all.
+  vec3 outc = vec3(1.0) - vec3(dc, 0.0, 0.0) - vec3(0.0, dm, 0.0) - vec3(0.0, 0.0, dy) - vec3(dk);
+  outc = clamp(outc, 0.0, 1.0);
+  gl_FragColor = vec4(mix(src.rgb, outc, clamp(uHalftoneCmyk, 0.0, 1.0)), src.a);
+}
+`;
 //#endregion
-export { fragmentShader, lineFragmentShader, postFragmentShader, postVertexShader, vertexShader };
+export { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader };
 
 //# sourceMappingURL=shaders.js.map

package/dist/renderer/shaders.js.map

@@ -1 +1 @@
-{"version":3,"file":"shaders.js","names":[],"sources":["../../src/renderer/shaders.ts"],"sourcesContent":["import { MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS } from \"../config/model\";\n\n/**\n * The wave shaders. Vertex: a flat plane is Y-displaced by simplex noise, then\n * twisted by three axis-rotations `freq * expStep(uv, power)` where\n * `expStep(x,n) = exp2(-exp2(n)*pow(x,n))` is a falloff (rotation concentrated at\n * the uv=0 edge), with diagonal axes + an animated X wobble. Fragment: uses NO\n * normal-based lighting — \"thickness\" comes from `crease`, a foreshorten/fold\n * detector built from `dFdy(uv)`, used to lift flat areas toward white\n * (`col += (1-crease)*0.25`) and to localise the striations. Striations are subtle\n * high-frequency simplex noise ADDED to the colour, colour-matched via (1-blue)\n * and end-weighted via a parabola — so they blend rather than form hard lines.\n * Our additions: gradient stops/types for colour, and an optional additive light\n * layer (kept gentle so the default look is preserved).\n */\n\n// Noise function: xxHash-seeded unit-vector gradients + a Gustavson simplex. It uses\n// GLSL ES 3.00 integer ops (floatBitsToUint, unsigned bit-shifts) — available with no\n// glslVersion change because three compiles non-raw ShaderMaterials as \"#version 300 es\"\n// already. `hash` returns a vec2 here — the cheap grain hash in the fragment is named\n// `grainHash` to avoid clashing with it.\nconst simplex2d = /* glsl */ `\nfloat xxhash(vec2 x){\n  uvec2 t = floatBitsToUint(x);\n  uint h = 0xc2b2ae3du * t.x + 0x165667b9u;\n  h = (h << 17u | h >> 15u) * 0x27d4eb2fu;\n  h += 0xc2b2ae3du * t.y;\n  h = (h << 17u | h >> 15u) * 0x27d4eb2fu;\n  h ^= h >> 15u;\n  h *= 0x85ebca77u;\n  h ^= h >> 13u;\n  h *= 0xc2b2ae3du;\n  h ^= h >> 16u;\n  return uintBitsToFloat(h >> 9u | 0x3f800000u) - 1.0;\n}\nvec2 hash(vec2 x){\n  float k = 6.283185307 * xxhash(x);\n  return vec2(cos(k), sin(k));\n}\nfloat simplexNoise(in vec2 p){\n  const float K1 = 0.366025404; // (sqrt(3)-1)/2\n  const float K2 = 0.211324865; // (3-sqrt(3))/6\n  vec2 i = floor(p + (p.x + p.y) * K1);\n  vec2 a = p - i + (i.x + i.y) * K2;\n  float m = step(a.y, a.x);\n  vec2 o = vec2(m, 1.0 - m);\n  vec2 b = a - o + K2;\n  vec2 c = a - 1.0 + 2.0 * K2;\n  vec3 h = max(0.5 - vec3(dot(a, a), dot(b, b), dot(c, c)), 0.0);\n  vec3 n = h * h * h * vec3(dot(a, hash(i + 0.0)), dot(b, hash(i + o)), dot(c, hash(i + 1.0)));\n  return dot(n, vec3(32.99)); // analytic factor (= 2916*sqrt(2)/125)\n}\n`;\n\n// Uniforms shared by BOTH fragment shaders (solid + wireframe line): the palette/gradient\n// inputs and the colour-grade knobs. Each shader declares its theme-specific uniforms beside\n// this block. Requires MAX_COLORS / MAX_MESH_POINTS #defines.\nconst colorUniforms = /* glsl */ `\nuniform vec3 uColors[MAX_COLORS];\nuniform float uColorPos[MAX_COLORS];\nuniform int uColorCount;\nuniform int uGradType;\nuniform float uGradAngle;\nuniform float uGradShift;\nuniform vec2 uMeshPointPos[MAX_MESH_POINTS];\nuniform vec3 uMeshPointColor[MAX_MESH_POINTS];\nuniform float uMeshPointInfluence[MAX_MESH_POINTS];\nuniform int uMeshPointCount;\nuniform float uMeshSoftness;\nuniform sampler2D uPalette;   // baked 2D palette texture\nuniform float uUsePalette;    // >0.5 = sample the texture; else procedural grad()\nuniform float uPaletteRaw;    // >0.5 = sample palette by raw (uv.x,uv.y), not gradCoord\nuniform vec2 uPaletteScale;\nuniform vec2 uPaletteOffset;\nuniform float uPaletteRotation;\nuniform float uHueShift;\nuniform float uContrast;\nuniform float uSaturation;\nuniform float uOpacity;\nuniform float uSquared;   // 1 = square the output colour (the deep \"squared\" hero look)\n`;\n\n// Colour helpers + the palette/gradient sampler shared by both fragment shaders.\n// Interpolate AFTER ${\"simplex2d\"} and ${\"colorUniforms\"} (gradCoord needs both) and a PI define.\nconst colorFns = /* glsl */ `\nvec3 contrastFn(vec3 v, float a){ return (v - 0.5) * a + 0.5; }\nvec3 desaturate(vec3 color, float factor){\n  vec3 gray = vec3(dot(vec3(0.299, 0.587, 0.114), color));\n  return mix(color, gray, factor);\n}\nvec3 hueShift(vec3 color, float shift){\n  vec3 g = vec3(0.57735);\n  vec3 proj = g * dot(g, color);\n  vec3 U = color - proj;\n  vec3 W = cross(g, U);\n  return U * cos(shift) + W * sin(shift) + proj;\n}\n\n// Our gradient: interpolate stops by their positions (uColorPos sorted ascending).\nvec3 grad(float u){\n  u = clamp(u, 0.0, 1.0);\n  vec3 col = uColors[0];\n  for (int i = 0; i < MAX_COLORS - 1; i++){\n    if (i >= uColorCount - 1) break;\n    float p0 = uColorPos[i];\n    float p1 = uColorPos[i + 1];\n    if (u >= p0){\n      float t = clamp((u - p0) / max(p1 - p0, 1e-5), 0.0, 1.0);\n      col = mix(uColors[i], uColors[i + 1], t);\n    }\n  }\n  return col;\n}\n\n// iOS-style 2D colour field. Each control point contributes an inverse-distance\n// weight; normalising the sum fills the whole surface without dark seams.\nvec3 meshGradient(vec2 uv){\n  vec3 colorSum = vec3(0.0);\n  float weightSum = 0.0;\n  float exponent = mix(4.8, 1.35, clamp(uMeshSoftness, 0.0, 1.0));\n  for (int i = 0; i < MAX_MESH_POINTS; i++){\n    if (i >= uMeshPointCount) break;\n    float influence = max(uMeshPointInfluence[i], 0.05);\n    float distanceFromPoint = length(uv - uMeshPointPos[i]) / influence;\n    float weight = 1.0 / (pow(max(distanceFromPoint, 0.012), exponent) + 0.002);\n    colorSum += uMeshPointColor[i] * weight;\n    weightSum += weight;\n  }\n  return colorSum / max(weightSum, 0.0001);\n}\n\n// Map a surface uv to the 0–1 gradient coordinate per gradient type. uGradShift\n// adds a low-frequency simplex warp so the colour varies in 2D (along the length\n// as well as across the width) — a 2D palette feel instead\n// of flat 1-D bands.\nfloat gradCoord(vec2 uv){\n  float warp = uGradShift * simplexNoise(uv * 1.6 + 4.0);\n  if (uGradType == 1){ return clamp(length(uv - 0.5) * 2.0 + warp, 0.0, 1.0); }    // radial\n  if (uGradType == 2){ return fract(atan(uv.y - 0.5, uv.x - 0.5) / (2.0 * PI) + 0.5 + warp); } // conic\n  vec2 dir = vec2(sin(uGradAngle), cos(uGradAngle));                              // linear, angled\n  return clamp(dot(uv - 0.5, dir) + 0.5 + warp, 0.0, 1.0);\n}\n\n// One base-colour sample for the whole surface: rotate/scale/offset the raw-palette uv,\n// then pick the mesh field / baked 2D texture / procedural stops by mode. The raw palette\n// is sampled by (uv.x, uv.y) directly; the stops-generated texture is sampled via\n// gradCoord so its angle/type/warp still apply.\nvec3 waveBaseColor(vec2 uv){\n  float gc = gradCoord(uv);\n  vec2 mediaUv = uv - 0.5;\n  float mediaCos = cos(uPaletteRotation);\n  float mediaSin = sin(uPaletteRotation);\n  mediaUv = vec2(\n    mediaCos * mediaUv.x + mediaSin * mediaUv.y,\n    -mediaSin * mediaUv.x + mediaCos * mediaUv.y\n  );\n  mediaUv = mediaUv * uPaletteScale + 0.5 + uPaletteOffset;\n  vec2 puv = uPaletteRaw > 0.5\n    ? clamp(mediaUv, 0.0, 1.0)\n    : vec2(gc, clamp(uv.y, 0.0, 1.0));\n  return uGradType == 3\n    ? meshGradient(uv)\n    : (uUsePalette > 0.5 ? texture2D(uPalette, puv).rgb : grad(gc));\n}\n\n// The shared colour grade: contrast → desaturate → hue rotate (degrees).\nvec3 applyColorGrade(vec3 c){\n  c = contrastFn(c, uContrast);\n  c = desaturate(c, 1.0 - uSaturation);\n  return hueShift(c, radians(uHueShift));\n}\n`;\n\nexport const vertexShader = /* glsl */ `\n${simplex2d}\n\nuniform float uTime, uSpeed, uSeed;\nuniform float uDispFreqX, uDispFreqZ, uDispAmount;\nuniform float uDetailFreq, uDetailAmount; // 2nd displacement octave (only read under DETAIL_OCTAVE)\nuniform float uTwFreqX, uTwFreqY, uTwFreqZ, uTwPowX, uTwPowY, uTwPowZ;\nuniform float uLoopSeconds; // seamless-loop period (only read under LOOP_MOTION)\n\nvarying vec2 vUv;\nvarying vec3 vWorldPos;\nvarying vec3 vViewDir;\nvarying vec4 vClipPosition; // = gl_Position, for the wireframe theme's depth fade\n\n// expStep: a falloff from 1 (at x=0) toward 0, sharpness set by n. The\n// max() guards pow(0, n) (= Infinity → NaN) so negative n is safe — negative n\n// just concentrates the twist toward the OTHER end instead.\nfloat expStep(float x, float n){ return exp2(-exp2(n) * pow(max(x, 1.0e-3), n)); }\n\n// rotationMatrix (mat4), used row-vector style: pos = (vec4(pos,1) * R).xyz\nmat4 rotationMatrix(vec3 axis, float angle){\n  axis = normalize(axis);\n  float s = sin(angle), c = cos(angle), oc = 1.0 - c;\n  return mat4(\n    oc*axis.x*axis.x + c,        oc*axis.x*axis.y - axis.z*s, oc*axis.z*axis.x + axis.y*s, 0.0,\n    oc*axis.x*axis.y + axis.z*s, oc*axis.y*axis.y + c,        oc*axis.y*axis.z - axis.x*s, 0.0,\n    oc*axis.z*axis.x - axis.y*s, oc*axis.y*axis.z + axis.x*s, oc*axis.z*axis.z + c,        0.0,\n    0.0, 0.0, 0.0, 1.0\n  );\n}\n\nvoid main(){\n  vUv = uv;\n#ifndef LOOP_MOTION\n  float t = uTime * uSpeed + uSeed;\n#endif\n\n#ifdef LOOP_MOTION\n  // Seamless loop: rather than scrolling the noise field linearly by t (which never repeats),\n  // sample it on a circle of radius loopR at angle loopTheta — exactly periodic with period\n  // uLoopSeconds. The tangential speed loopR·dθ/dt equals uSpeed, so the looped motion advances\n  // at the same rate as the linear drift, just curved into a closed orbit (it orbits rather than\n  // drifts — the trade-off for a seamless loop, hence opt-in). uSeed offsets the phase so stacked\n  // waves keep their relative motion while sharing the single period.\n  float loopTheta = uTime * (6.28318530718 / uLoopSeconds) + uSeed;\n  float loopR = uSpeed * uLoopSeconds * 0.159154943092; // = uSpeed·uLoopSeconds / (2π)\n  vec2 loopOff = loopR * vec2(cos(loopTheta), sin(loopTheta));\n#endif\n\n  // The base geometry is already a baked hairpin fold. On top of it we deform the\n  // vertices: a displacement lifts Y by simplex noise of the (x,z) position, then\n  // three axis-rotations twist the strip.\n  vec3 pos = position;\n#ifdef LOOP_MOTION\n  pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX, pos.z * uDispFreqZ) + loopOff);\n#else\n  pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX + t, pos.z * uDispFreqZ + t));\n#endif\n#ifdef DETAIL_OCTAVE\n  // A second, finer octave riding on the broad swell — fine ripples on top of the big shape, a\n  // shape vocabulary single-octave displacement can't reach. Shares the loop orbit so it stays\n  // periodic when looping.\n#ifdef LOOP_MOTION\n  pos.y += uDetailAmount * simplexNoise(vec2(pos.x * uDetailFreq, pos.z * uDetailFreq) + loopOff);\n#else\n  pos.y += uDetailAmount * simplexNoise(vec2(pos.x * uDetailFreq + t, pos.z * uDetailFreq + t));\n#endif\n#endif\n\n  // The X-twist frequency feeding rotB. Two modes: by default uTwFreqX is used\n  // directly; the variant (used by the Wave 4 preset) modulates it with\n  // simplex noise indexed along the ribbon (uv.y) so the twist breathes over time.\n  // We gate the wobble with a #define so the compiled program is unchanged when off.\n  float twistXFreq = uTwFreqX;\n#ifdef TWIST_MOTION\n#ifdef LOOP_MOTION\n  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, 0.0) + loopOff);\n#else\n  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, t));\n#endif\n  twistXFreq = uTwFreqX - twistXNoise * 0.1;\n#endif\n\n  // Three-axis twist: expStep falloff sets how\n  // sharply each rotation concentrates toward an edge. rotA keys off uv.x, rotB/rotC\n  // off uv.y; axes (0.5,0,0.5) and (0,0.5,0.5) are normalised inside rotationMatrix.\n  mat4 rotA = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqY * expStep(uv.x, uTwPowY));\n  mat4 rotB = rotationMatrix(vec3(0.0, 0.5, 0.5), twistXFreq * expStep(uv.y, uTwPowX));\n  mat4 rotC = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqZ * expStep(uv.y, uTwPowZ));\n  pos = (vec4(pos, 1.0) * rotA).xyz;\n  pos = (vec4(pos, 1.0) * rotB).xyz;\n  pos = (vec4(pos, 1.0) * rotC).xyz;\n\n  // The scale / rotation / position transform lives on the mesh (modelMatrix), so the\n  // orientation matches THREE's Euler-XYZ rather than an in-shader rotation order.\n  vec4 world = modelMatrix * vec4(pos, 1.0);\n  vWorldPos = world.xyz;\n  vViewDir = cameraPosition - world.xyz;\n  gl_Position = projectionMatrix * viewMatrix * world;\n  vClipPosition = gl_Position;\n}\n`;\n\nexport const fragmentShader = /* glsl */ `\n#define MAX_COLORS ${MAX_COLORS}\n#define MAX_MESH_POINTS ${MAX_MESH_POINTS}\n#define MAX_LIGHTS ${MAX_LIGHTS}\n#define MAX_NOISE_BANDS ${MAX_NOISE_BANDS}\n#define PI 3.14159265359\n\n${simplex2d}\n\n${colorUniforms}\nuniform float uDebug;         // dev: 1 = show crease, 2 = show derivative normal\nuniform float uSheen;       // white-lift on the flat (low-crease) areas (1 = full)\nuniform float uRoundness;        // pose-robust normal-based roundness/thickness strength\nuniform float uIridescence;      // thin-film hue shift with view angle (0 = off)\nuniform float uFiberCount;\nuniform float uFiberStrength;\nuniform float uTexture;\nuniform float uCreaseLight;\nuniform float uCreaseSharpness;\nuniform float uCreaseSoftness;\nuniform float uEdgeFade;\nuniform vec2 uResolution;\nuniform float uAmbient;\nuniform int uNumLights;\nuniform vec3 uLightPos[MAX_LIGHTS];\nuniform vec3 uLightColor[MAX_LIGHTS];\nuniform float uLightIntensity[MAX_LIGHTS];\nuniform int uNumNoiseBands;\nuniform vec4 uNoiseBandBounds[MAX_NOISE_BANDS];  // (startX, endX, startY, endY)\nuniform vec4 uNoiseBandParams[MAX_NOISE_BANDS];  // (feather, strength, frequency, colorAttenuation)\nuniform float uNoiseBandParaPow[MAX_NOISE_BANDS];\n\nvarying vec2 vUv;\nvarying vec3 vWorldPos;\nvarying vec3 vViewDir;\n#ifdef DEPTH_TINT\nuniform float uDepthTint;\nuniform vec3 uDepthTintColor;\nvarying vec4 vClipPosition; // clip-space depth (written by the vertex shader for both programs)\n#endif\n#ifdef EDGE_FEATHER\nuniform float uEdgeFeather; // ribbon long-edge softness (only when it differs from the 0.1 default)\n#endif\n\n// Cheap value hash for the optional grain overlay (distinct from the simplex hash).\nfloat grainHash(vec2 p){ return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }\n\nfloat parabola(float x, float k){ return pow(4.0 * x * (1.0 - x), k); }\nfloat mapLinear(float v, float a, float b, float c, float d){ return c + (v - a) * (d - c) / (b - a); }\n\n${colorFns}\n\n// Striations: a subtle high-frequency simplex-noise grain ADDED to the\n// colour — colour-matched (weaker where blue is high), only near folds (crease), and\n// concentrated toward the ends (parabola). Blends in rather than reading as hard lines.\nvec3 surfaceStreaks(vec2 uv, vec3 color, float crease){\n  float strength = uFiberStrength;          // default 0.2\n  float freq = uFiberCount;                   // default 600\n  float colorAtten = 0.9;\n  float paraPow = 3.0;\n  // Noise bands: inside each rectangular uv region the\n  // fiber params are overridden, so the streaks vary per region instead of uniform.\n  for (int i = 0; i < MAX_NOISE_BANDS; i++) {\n    if (i >= uNumNoiseBands) break;\n    vec4 b = uNoiseBandBounds[i];\n    vec4 prm = uNoiseBandParams[i];\n    float feather = max(prm.x, 1.0e-4);\n    float blend =\n      smoothstep(b.x - feather, b.x, uv.x) * (1.0 - smoothstep(b.y, b.y + feather, uv.x)) *\n      smoothstep(b.z - feather, b.z, uv.y) * (1.0 - smoothstep(b.w, b.w + feather, uv.y));\n    strength = mix(strength, prm.y, blend);\n    freq = mix(freq, prm.z, blend);\n    colorAtten = mix(colorAtten, prm.w, blend);\n    paraPow = mix(paraPow, uNoiseBandParaPow[i], blend);\n  }\n  // The high frequency runs along uv.x (the ribbon's length) so the streaks read as\n  // fine lengthwise fibers; end-weighted by 1 - parabola(uv.x).\n  float p = 1.0 - parabola(uv.x, paraPow);\n  float n0 = simplexNoise(vec2(uv.x * 0.1, uv.y * 0.5));\n  float n1 = simplexNoise(vec2(uv.x * (freq + freq * 0.5 * n0), uv.y * 4.0 * n0));\n  n1 = mapLinear(n1, -1.0, 1.0, 0.0, 1.0);\n  color += n1 * strength * (1.0 - color.b * colorAtten) * crease * p;\n  return color;\n}\n\nvoid main(){\n  // crease: a foreshortening / fold detector from the screen-space uv derivative.\n  // It drives BOTH the roundness shading and where the streaks appear — this is what\n  // gives the wave its thickness without any normal-based lighting.\n  float crease = dFdy(vUv).y * uResolution.y * uCreaseLight;\n  crease = clamp(mapLinear(crease, -1.0, 1.0, 0.0, 1.0), 0.0, 1.0);\n  crease = pow(crease, uCreaseSharpness);\n  crease = clamp(smoothstep(0.0, uCreaseSoftness, crease), 0.0, 1.0);\n\n  // Debug visualisations (dev): 1 = crease value, 2 = derivative surface normal.\n  if (uDebug > 0.5) {\n    if (uDebug < 1.5) { gl_FragColor = vec4(vec3(crease), 1.0); return; }\n    vec3 dn = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    gl_FragColor = vec4(dn * 0.5 + 0.5, 1.0); return;\n  }\n\n  // Colour: sample the baked 2D palette texture, or fall back to the procedural 1-D\n  // gradient (see waveBaseColor).\n  vec3 col = waveBaseColor(vUv);\n  col = surfaceStreaks(vUv, col, crease);\n  col = applyColorGrade(col);\n\n  // Iridescence: a thin-film / holographic hue that shifts with view angle. Reuses the same\n  // camera-facing ratio as roundness (recomputed here, since roundness may be off): grazing parts\n  // of the ribbon (low facing) shift hue most, so the colour flows as the ribbon curves. Skipped\n  // at 0, so the compiled result is unchanged when off.\n  if (uIridescence > 0.001) {\n    vec3 iridN = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    float iridFacing = abs(dot(iridN, normalize(vViewDir)));\n    col = hueShift(col, (1.0 - iridFacing) * uIridescence * PI);\n  }\n\n  // Sheen: lift the flat (low-crease) areas toward white. This is\n  // pose-dependent (it keys off dFdy(uv.y)), so we keep it gentle and add a robust term.\n  col += (1.0 - crease) * 0.25 * uSheen;\n\n  // Pose-robust roundness: shade by the camera-facing ratio of the derivative surface\n  // normal so the ribbon reads as a rounded, grabbable solid from any angle. Grazing\n  // edges darken into shadow (defining the rounded form), the body keeps its full colour,\n  // and the most face-on sliver catches a soft highlight. uRoundness = strength.\n  if (uRoundness > 0.001) {\n    vec3 volN = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    float facing = abs(dot(volN, normalize(vViewDir)));   // 1 = facing camera, 0 = edge-on\n    col *= mix(1.0 - 0.6 * uRoundness, 1.0, facing);          // deepen grazing edges → solid form\n    col += smoothstep(0.65, 1.0, facing) * uRoundness * 0.18; // soft highlight on the facing body\n  }\n\n  // Optional positionable lights (our feature) — additive & gentle, on top of the\n  // base shading so the default look is preserved. A finely-subdivided mesh\n  // keeps this derivative normal smooth.\n  if (uNumLights > 0) {\n    vec3 N = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    vec3 Vd = normalize(vViewDir);\n    if (dot(N, Vd) < 0.0) N = -N;\n    for (int i = 0; i < MAX_LIGHTS; i++) {\n      if (i >= uNumLights) break;\n      vec3 L = normalize(uLightPos[i] - vWorldPos);\n      vec3 lc = uLightColor[i] * uLightIntensity[i];\n      float diff = max(dot(N, L), 0.0);\n      float spec = pow(max(dot(N, normalize(L + Vd)), 0.0), 28.0);\n      col += col * diff * lc * 0.16 + spec * lc * 0.10;\n    }\n  }\n  col *= 0.55 + clamp(uAmbient, 0.0, 1.0);   // overall level; default 0.45 => x1.0 (neutral)\n\n#ifdef DEPTH_TINT\n  // Depth tint: fade far fragments toward a colour so a multi-wave stack gains atmospheric\n  // separation — near strands keep their colour, far ones recede. Reuses the clip-space depth the\n  // wireframe theme fades with (clamp(z*6), where 1 = far).\n  col = mix(col, uDepthTintColor, clamp(vClipPosition.z * 6.0, 0.0, 1.0) * uDepthTint);\n#endif\n\n  if (uTexture > 0.001) col *= 1.0 + (grainHash(vUv * 850.0) - 0.5) * uTexture * 0.25;\n\n  // Soft long edges + optional viewport-edge fade. The edge softness is the hardcoded 0.1 by\n  // default (literal branch → byte-identical); EDGE_FEATHER swaps in the uEdgeFeather knob only\n  // when it differs, so razor-crisp or vapor-soft edges are both reachable.\n#ifdef EDGE_FEATHER\n  float ribEdge =\n    smoothstep(0.0, uEdgeFeather, vUv.y) * (1.0 - smoothstep(1.0 - uEdgeFeather, 1.0, vUv.y));\n#else\n  float ribEdge = smoothstep(0.0, 0.1, vUv.y) * (1.0 - smoothstep(0.9, 1.0, vUv.y));\n#endif\n  float alpha = uOpacity * ribEdge;\n  if (uEdgeFade > 0.001) {\n    vec2 sc = gl_FragCoord.xy / max(uResolution, vec2(1.0));\n    float vig =\n      smoothstep(0.0, uEdgeFade, sc.x) * (1.0 - smoothstep(1.0 - uEdgeFade, 1.0, sc.x)) *\n      smoothstep(0.0, uEdgeFade, sc.y) * (1.0 - smoothstep(1.0 - uEdgeFade, 1.0, sc.y));\n    alpha *= vig;\n  }\n\n  // Deep \"squared\" hero colour: formerly done by a framebuffer-squaring blend that REPLACED the\n  // destination (punching holes at soft edges / where waves overlap). Squaring here + normal\n  // premultiplied compositing (see applyBlendMode) keeps the deep colour and blends correctly.\n  col = clamp(col, 0.0, 1.0);\n  // Square colour AND alpha so the soft ribbon edges keep the crisp, thin feather of the original\n  // squared-blend look — but now composited (premultiplied) rather than replace-blended, so they\n  // no longer punch holes. Over an opaque background alpha² still resolves to fully opaque.\n  if (uSquared > 0.5) { col *= col; alpha *= alpha; }\n  gl_FragColor = vec4(col, alpha);\n#ifdef PREMULTIPLIED_ALPHA\n  gl_FragColor.rgb *= gl_FragColor.a;\n#endif\n}\n`;\n\n// ---- Wireframe \"thin-line\" theme ----\n// The same wave geometry, but instead of a solid surface the colour is carved into fine\n// vertical lines (abs(sin(uv.x * lineAmount))) whose thickness scales with the screen-\n// space uv derivative, then mixed line<->background with a depth fade. Used by the dark\n// hero preset. hueShift takes degrees (radians() here) to match the light shader.\nexport const lineFragmentShader = /* glsl */ `\n#define MAX_COLORS ${MAX_COLORS}\n#define MAX_MESH_POINTS ${MAX_MESH_POINTS}\n#define PI 3.14159265359\n\n${simplex2d}\n\n${colorUniforms}\nuniform float uLineAmount;          // default 425\nuniform float uLineThickness;       // default 1\nuniform float uLineDerivativePower; // default 0.95\nuniform float uMaxWidth;            // default 1232\nuniform vec3 uClearColor;           // = page background colour (shown between the lines)\n\nvarying vec2 vUv;\nvarying vec4 vClipPosition;\n\n${colorFns}\n\nvoid main(){\n  // Same 2D palette sample + colour ops as the solid theme.\n  vec3 color = applyColorGrade(waveBaseColor(vUv));\n\n  // Carve into fine vertical lines; thickness from the screen-space uv derivative.\n  vec2 dy = dFdy(vUv);\n  float lineThickness = uLineThickness * pow(abs(dy.x * uMaxWidth), uLineDerivativePower);\n  float a = abs(sin(vUv.x * uLineAmount));\n  a = smoothstep(lineThickness, 0.0, a);\n\n  // Depth fade: the wave recedes into the background colour with depth. Watch the\n  // argument order: clamp(0.0, 1.0, z*6) is a swapped-args trap — it clamps the\n  // constant 0.0 into [1.0, z*6], i.e. min(1.0, z*6), which (with our ortho clip.z\n  // range) collapses the whole wave to the background. The correct clamp(z*6, 0, 1)\n  // gives the proper subtle far-end fade and thin-line look.\n  float depthFade = clamp(vClipPosition.z * 6.0, 0.0, 1.0);\n  color = mix(uClearColor, color, a * (1.0 - depthFade));\n  if (uSquared > 0.5) color *= color; // deep \"squared\" look, now composited not replace-blended\n  gl_FragColor = vec4(color, uOpacity);\n#ifdef PREMULTIPLIED_ALPHA\n  gl_FragColor.rgb *= gl_FragColor.a;\n#endif\n}\n`;\n\n// ---- Post pass: viewport-edge soft-focus blur + dither grain ----\n\nexport const postVertexShader = /* glsl */ `\nvarying vec2 vUv;\nvoid main(){\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}\n`;\n\nexport const postFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform vec2 uResolution;\nuniform float uBlurAmount;\nuniform int uBlurSamples;\nuniform float uGrainAmount;\nuniform float uTime;\nvarying vec2 vUv;\n\nfloat random2(vec2 st){ return fract(sin(dot(st.xy, vec2(12.9898, 78.233))) * 43758.5453); }\n\n// Angular (spin) blur: rotate the sample coord around the centre and\n// accumulate — a tangential smear that grows toward the edges. Carries alpha so a\n// transparent background survives the post pass.\nvec4 blurAngular(sampler2D tex, vec2 uv, float angle, int samples){\n  vec4 total = vec4(0.0);\n  vec2 coord = uv - 0.5;\n  float dist = 1.0 / float(samples);\n  vec2 dir = vec2(cos(angle * dist), sin(angle * dist));\n  mat2 rot = mat2(dir.x, dir.y, -dir.y, dir.x);\n  for (int i = 0; i < 64; i++){\n    if (i >= samples) break;\n    total += texture2D(tex, coord + 0.5);\n    coord = coord * rot; // row-vector order (coord * rot) sets the spin direction\n  }\n  return total * dist;\n}\n\nvoid main(){\n  vec4 sceneColor = texture2D(tDiffuse, vUv);\n  vec4 blurColor = blurAngular(tDiffuse, vUv, uBlurAmount, uBlurSamples);\n  // blurPower: keep a sharp band weighted to the middle, blurring toward top & bottom.\n  float blurPower = smoothstep(0.0, 0.7, vUv.y) - smoothstep(0.2, 1.0, vUv.y);\n  vec4 color = mix(blurColor, sceneColor, blurPower);\n  // Static film grain: keyed off gl_FragCoord only (no uTime), so it doesn't flicker.\n  color.rgb += mix(uGrainAmount, -uGrainAmount, random2(gl_FragCoord.xy * 0.01)) * (4.0 / 255.0);\n  gl_FragColor = color;   // preserve alpha → transparent background works\n}\n`;\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,MAAM,YAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC7B,MAAM,gBAA2B;;;;;;;;;;;;;;;;;;;;;;;;AA2BjC,MAAM,WAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyF5B,MAAa,eAA0B;EACrC,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGZ,MAAa,iBAA4B;;;;;;;EAOvC,UAAU;;EAEV,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCd,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmJX,MAAa,qBAAgC;;;;;EAK3C,UAAU;;EAEV,cAAc;;;;;;;;;;EAUd,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BX,MAAa,mBAA8B;;;;;;;AAQ3C,MAAa,qBAAgC"}
+{"version":3,"file":"shaders.js","names":[],"sources":["../../src/renderer/shaders.ts"],"sourcesContent":["import { MAX_COLORS, MAX_LIGHTS, MAX_MESH_POINTS, MAX_NOISE_BANDS } from \"../config/model\";\n\n/**\n * The wave shaders. Vertex: a flat plane is Y-displaced by simplex noise, then\n * twisted by three axis-rotations `freq * expStep(uv, power)` where\n * `expStep(x,n) = exp2(-exp2(n)*pow(x,n))` is a falloff (rotation concentrated at\n * the uv=0 edge), with diagonal axes + an animated X wobble. Fragment: uses NO\n * normal-based lighting — \"thickness\" comes from `crease`, a foreshorten/fold\n * detector built from `dFdy(uv)`, used to lift flat areas toward white\n * (`col += (1-crease)*0.25`) and to localise the striations. Striations are subtle\n * high-frequency simplex noise ADDED to the colour, colour-matched via (1-blue)\n * and end-weighted via a parabola — so they blend rather than form hard lines.\n * Our additions: gradient stops/types for colour, and an optional additive light\n * layer (kept gentle so the default look is preserved).\n */\n\n// Noise function: xxHash-seeded unit-vector gradients + a Gustavson simplex. It uses\n// GLSL ES 3.00 integer ops (floatBitsToUint, unsigned bit-shifts) — available with no\n// glslVersion change because three compiles non-raw ShaderMaterials as \"#version 300 es\"\n// already. `hash` returns a vec2 here — the cheap grain hash in the fragment is named\n// `grainHash` to avoid clashing with it.\nconst simplex2d = /* glsl */ `\nfloat xxhash(vec2 x){\n  uvec2 t = floatBitsToUint(x);\n  uint h = 0xc2b2ae3du * t.x + 0x165667b9u;\n  h = (h << 17u | h >> 15u) * 0x27d4eb2fu;\n  h += 0xc2b2ae3du * t.y;\n  h = (h << 17u | h >> 15u) * 0x27d4eb2fu;\n  h ^= h >> 15u;\n  h *= 0x85ebca77u;\n  h ^= h >> 13u;\n  h *= 0xc2b2ae3du;\n  h ^= h >> 16u;\n  return uintBitsToFloat(h >> 9u | 0x3f800000u) - 1.0;\n}\nvec2 hash(vec2 x){\n  float k = 6.283185307 * xxhash(x);\n  return vec2(cos(k), sin(k));\n}\nfloat simplexNoise(in vec2 p){\n  const float K1 = 0.366025404; // (sqrt(3)-1)/2\n  const float K2 = 0.211324865; // (3-sqrt(3))/6\n  vec2 i = floor(p + (p.x + p.y) * K1);\n  vec2 a = p - i + (i.x + i.y) * K2;\n  float m = step(a.y, a.x);\n  vec2 o = vec2(m, 1.0 - m);\n  vec2 b = a - o + K2;\n  vec2 c = a - 1.0 + 2.0 * K2;\n  vec3 h = max(0.5 - vec3(dot(a, a), dot(b, b), dot(c, c)), 0.0);\n  vec3 n = h * h * h * vec3(dot(a, hash(i + 0.0)), dot(b, hash(i + o)), dot(c, hash(i + 1.0)));\n  return dot(n, vec3(32.99)); // analytic factor (= 2916*sqrt(2)/125)\n}\n`;\n\n// Uniforms shared by BOTH fragment shaders (solid + wireframe line): the palette/gradient\n// inputs and the colour-grade knobs. Each shader declares its theme-specific uniforms beside\n// this block. Requires MAX_COLORS / MAX_MESH_POINTS #defines.\nconst colorUniforms = /* glsl */ `\nuniform vec3 uColors[MAX_COLORS];\nuniform float uColorPos[MAX_COLORS];\nuniform int uColorCount;\nuniform int uGradType;\nuniform float uGradAngle;\nuniform float uGradShift;\nuniform vec2 uMeshPointPos[MAX_MESH_POINTS];\nuniform vec3 uMeshPointColor[MAX_MESH_POINTS];\nuniform float uMeshPointInfluence[MAX_MESH_POINTS];\nuniform int uMeshPointCount;\nuniform float uMeshSoftness;\nuniform sampler2D uPalette;   // baked 2D palette texture\nuniform float uUsePalette;    // >0.5 = sample the texture; else procedural grad()\nuniform float uPaletteRaw;    // >0.5 = sample palette by raw (uv.x,uv.y), not gradCoord\nuniform vec2 uPaletteScale;\nuniform vec2 uPaletteOffset;\nuniform float uPaletteRotation;\nuniform float uHueShift;\nuniform float uContrast;\nuniform float uSaturation;\nuniform float uOpacity;\nuniform float uSquared;   // 1 = square the output colour (the deep \"squared\" hero look)\n`;\n\n// Colour helpers + the palette/gradient sampler shared by both fragment shaders.\n// Interpolate AFTER ${\"simplex2d\"} and ${\"colorUniforms\"} (gradCoord needs both) and a PI define.\nconst colorFns = /* glsl */ `\nvec3 contrastFn(vec3 v, float a){ return (v - 0.5) * a + 0.5; }\nvec3 desaturate(vec3 color, float factor){\n  vec3 gray = vec3(dot(vec3(0.299, 0.587, 0.114), color));\n  return mix(color, gray, factor);\n}\nvec3 hueShift(vec3 color, float shift){\n  vec3 g = vec3(0.57735);\n  vec3 proj = g * dot(g, color);\n  vec3 U = color - proj;\n  vec3 W = cross(g, U);\n  return U * cos(shift) + W * sin(shift) + proj;\n}\n\n// Our gradient: interpolate stops by their positions (uColorPos sorted ascending).\nvec3 grad(float u){\n  u = clamp(u, 0.0, 1.0);\n  vec3 col = uColors[0];\n  for (int i = 0; i < MAX_COLORS - 1; i++){\n    if (i >= uColorCount - 1) break;\n    float p0 = uColorPos[i];\n    float p1 = uColorPos[i + 1];\n    if (u >= p0){\n      float t = clamp((u - p0) / max(p1 - p0, 1e-5), 0.0, 1.0);\n      col = mix(uColors[i], uColors[i + 1], t);\n    }\n  }\n  return col;\n}\n\n// iOS-style 2D colour field. Each control point contributes an inverse-distance\n// weight; normalising the sum fills the whole surface without dark seams.\nvec3 meshGradient(vec2 uv){\n  vec3 colorSum = vec3(0.0);\n  float weightSum = 0.0;\n  float exponent = mix(4.8, 1.35, clamp(uMeshSoftness, 0.0, 1.0));\n  for (int i = 0; i < MAX_MESH_POINTS; i++){\n    if (i >= uMeshPointCount) break;\n    float influence = max(uMeshPointInfluence[i], 0.05);\n    float distanceFromPoint = length(uv - uMeshPointPos[i]) / influence;\n    float weight = 1.0 / (pow(max(distanceFromPoint, 0.012), exponent) + 0.002);\n    colorSum += uMeshPointColor[i] * weight;\n    weightSum += weight;\n  }\n  return colorSum / max(weightSum, 0.0001);\n}\n\n// Map a surface uv to the 0–1 gradient coordinate per gradient type. uGradShift\n// adds a low-frequency simplex warp so the colour varies in 2D (along the length\n// as well as across the width) — a 2D palette feel instead\n// of flat 1-D bands.\nfloat gradCoord(vec2 uv){\n  float warp = uGradShift * simplexNoise(uv * 1.6 + 4.0);\n  if (uGradType == 1){ return clamp(length(uv - 0.5) * 2.0 + warp, 0.0, 1.0); }    // radial\n  if (uGradType == 2){ return fract(atan(uv.y - 0.5, uv.x - 0.5) / (2.0 * PI) + 0.5 + warp); } // conic\n  vec2 dir = vec2(sin(uGradAngle), cos(uGradAngle));                              // linear, angled\n  return clamp(dot(uv - 0.5, dir) + 0.5 + warp, 0.0, 1.0);\n}\n\n// One base-colour sample for the whole surface: rotate/scale/offset the raw-palette uv,\n// then pick the mesh field / baked 2D texture / procedural stops by mode. The raw palette\n// is sampled by (uv.x, uv.y) directly; the stops-generated texture is sampled via\n// gradCoord so its angle/type/warp still apply.\nvec3 waveBaseColor(vec2 uv){\n  float gc = gradCoord(uv);\n  vec2 mediaUv = uv - 0.5;\n  float mediaCos = cos(uPaletteRotation);\n  float mediaSin = sin(uPaletteRotation);\n  mediaUv = vec2(\n    mediaCos * mediaUv.x + mediaSin * mediaUv.y,\n    -mediaSin * mediaUv.x + mediaCos * mediaUv.y\n  );\n  mediaUv = mediaUv * uPaletteScale + 0.5 + uPaletteOffset;\n  vec2 puv = uPaletteRaw > 0.5\n    ? clamp(mediaUv, 0.0, 1.0)\n    : vec2(gc, clamp(uv.y, 0.0, 1.0));\n  return uGradType == 3\n    ? meshGradient(uv)\n    : (uUsePalette > 0.5 ? texture2D(uPalette, puv).rgb : grad(gc));\n}\n\n// The shared colour grade: contrast → desaturate → hue rotate (degrees).\nvec3 applyColorGrade(vec3 c){\n  c = contrastFn(c, uContrast);\n  c = desaturate(c, 1.0 - uSaturation);\n  return hueShift(c, radians(uHueShift));\n}\n`;\n\nexport const vertexShader = /* glsl */ `\n${simplex2d}\n\nuniform float uTime, uSpeed, uSeed;\nuniform float uDispFreqX, uDispFreqZ, uDispAmount;\nuniform float uDetailFreq, uDetailAmount; // 2nd displacement octave (only read under DETAIL_OCTAVE)\nuniform float uTwFreqX, uTwFreqY, uTwFreqZ, uTwPowX, uTwPowY, uTwPowZ;\nuniform float uLoopSeconds; // seamless-loop period (only read under LOOP_MOTION)\n\nvarying vec2 vUv;\nvarying vec3 vWorldPos;\nvarying vec3 vViewDir;\nvarying vec4 vClipPosition; // = gl_Position, for the wireframe theme's depth fade\n\n// Pointer field (optional, additive). ALL declarations here sit behind POINTER_FX so a wave with\n// no interaction config compiles the exact same program (JS-side uniform entries are always present\n// — see makeUniforms — but three only uploads uniforms the compiled program actually declares).\n#ifdef POINTER_FX\nuniform vec2  uPointer;        // smoothed pointer, NDC (-1..1)\nuniform float uPointerActive;  // presence ramp 0..1 × per-wave influence\nuniform float uPointerRadius;  // falloff radius in NDC-y units (config radius × 2)\nuniform float uPointerAspect;  // drawing-buffer dw/dh (circular screen falloff)\nuniform float uPointerAgitate;\nuniform float uPointerPush;    // signed membrane dome at the cursor (+ repel / − attract)\nuniform float uPointerWake;    // drag-wake trough amplitude (behind the moving cursor)\nuniform vec2  uPointerVel;     // smoothed pointer velocity, NDC/s (drag-wake direction)\n// Ribbon flow: stretch the falloff along the strip's length axis so the field reaches ALONG the\n// ribbon rather than as a screen disc. 0 = the plain circular smoothstep (byte-identical when off).\nuniform float uShapeFlow;\nvarying float vPointerFall;    // falloff × presence — consumed by both fragment themes\n#ifdef POINTER_RIPPLES\nuniform vec2  uRippleOrigin[4]; // NDC\nuniform float uRippleAge[4];    // seconds since spawn (CPU-computed)\nuniform float uRippleAmp[4];    // shared 0..1 decay envelope per slot (CPU-computed; 0 = slot free)\nuniform float uPointerRipple;   // THIS wave's ripple amplitude (scales the shared envelope)\nconst float RIPPLE_WAVE_SPEED = 0.85; // NDC/s the ring crest travels outward\nconst float RIPPLE_SIGMA = 0.14;      // gaussian half-width of the travelling packet (NDC)\nconst float RIPPLE_FREQ = 11.0;       // oscillation within the packet (one crest + faint troughs)\nconst float RIPPLE_MAX_R = 1.2;       // reach where the crest has fully left the frame\n#endif\n#endif\n\n// expStep: a falloff from 1 (at x=0) toward 0, sharpness set by n. The\n// max() guards pow(0, n) (= Infinity → NaN) so negative n is safe — negative n\n// just concentrates the twist toward the OTHER end instead.\nfloat expStep(float x, float n){ return exp2(-exp2(n) * pow(max(x, 1.0e-3), n)); }\n\n// rotationMatrix (mat4), used row-vector style: pos = (vec4(pos,1) * R).xyz\nmat4 rotationMatrix(vec3 axis, float angle){\n  axis = normalize(axis);\n  float s = sin(angle), c = cos(angle), oc = 1.0 - c;\n  return mat4(\n    oc*axis.x*axis.x + c,        oc*axis.x*axis.y - axis.z*s, oc*axis.z*axis.x + axis.y*s, 0.0,\n    oc*axis.x*axis.y + axis.z*s, oc*axis.y*axis.y + c,        oc*axis.y*axis.z - axis.x*s, 0.0,\n    oc*axis.z*axis.x - axis.y*s, oc*axis.y*axis.z + axis.x*s, oc*axis.z*axis.z + c,        0.0,\n    0.0, 0.0, 0.0, 1.0\n  );\n}\n\nvoid main(){\n  vUv = uv;\n#ifndef LOOP_MOTION\n  float t = uTime * uSpeed + uSeed;\n#endif\n\n#ifdef LOOP_MOTION\n  // Seamless loop: rather than scrolling the noise field linearly by t (which never repeats),\n  // sample it on a circle of radius loopR at angle loopTheta — exactly periodic with period\n  // uLoopSeconds. The tangential speed loopR·dθ/dt equals uSpeed, so the looped motion advances\n  // at the same rate as the linear drift, just curved into a closed orbit (it orbits rather than\n  // drifts — the trade-off for a seamless loop, hence opt-in). uSeed offsets the phase so stacked\n  // waves keep their relative motion while sharing the single period.\n  float loopTheta = uTime * (6.28318530718 / uLoopSeconds) + uSeed;\n  float loopR = uSpeed * uLoopSeconds * 0.159154943092; // = uSpeed·uLoopSeconds / (2π)\n  vec2 loopOff = loopR * vec2(cos(loopTheta), sin(loopTheta));\n#endif\n\n  // The base geometry is already a baked hairpin fold. On top of it we deform the\n  // vertices: a displacement lifts Y by simplex noise of the (x,z) position, then\n  // three axis-rotations twist the strip.\n  vec3 pos = position;\n#ifdef LOOP_MOTION\n  pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX, pos.z * uDispFreqZ) + loopOff);\n#else\n  pos.y += uDispAmount * simplexNoise(vec2(pos.x * uDispFreqX + t, pos.z * uDispFreqZ + t));\n#endif\n#ifdef DETAIL_OCTAVE\n  // A second, finer octave riding on the broad swell — fine ripples on top of the big shape, a\n  // shape vocabulary single-octave displacement can't reach. Shares the loop orbit so it stays\n  // periodic when looping.\n#ifdef LOOP_MOTION\n  pos.y += uDetailAmount * simplexNoise(vec2(pos.x * uDetailFreq, pos.z * uDetailFreq) + loopOff);\n#else\n  pos.y += uDetailAmount * simplexNoise(vec2(pos.x * uDetailFreq + t, pos.z * uDetailFreq + t));\n#endif\n#endif\n\n  // The X-twist frequency feeding rotB. Two modes: by default uTwFreqX is used\n  // directly; the variant (used by the Wave 4 preset) modulates it with\n  // simplex noise indexed along the ribbon (uv.y) so the twist breathes over time.\n  // We gate the wobble with a #define so the compiled program is unchanged when off.\n  float twistXFreq = uTwFreqX;\n#ifdef TWIST_MOTION\n#ifdef LOOP_MOTION\n  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, 0.0) + loopOff);\n#else\n  float twistXNoise = simplexNoise(vec2(vUv.y * 2.0, t));\n#endif\n  twistXFreq = uTwFreqX - twistXNoise * 0.1;\n#endif\n\n  // Three-axis twist: expStep falloff sets how\n  // sharply each rotation concentrates toward an edge. rotA keys off uv.x, rotB/rotC\n  // off uv.y; axes (0.5,0,0.5) and (0,0.5,0.5) are normalised inside rotationMatrix.\n  mat4 rotA = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqY * expStep(uv.x, uTwPowY));\n  mat4 rotB = rotationMatrix(vec3(0.0, 0.5, 0.5), twistXFreq * expStep(uv.y, uTwPowX));\n  mat4 rotC = rotationMatrix(vec3(0.5, 0.0, 0.5), uTwFreqZ * expStep(uv.y, uTwPowZ));\n  pos = (vec4(pos, 1.0) * rotA).xyz;\n  pos = (vec4(pos, 1.0) * rotB).xyz;\n  pos = (vec4(pos, 1.0) * rotC).xyz;\n\n#ifdef POINTER_FX\n  // Pointer field: displace along the wave's own (post-twist) up-axis, weighted by a screen-space\n  // falloff around the smoothed cursor — a circle at uShapeFlow 0, stretched along the ribbon as it\n  // rises. Everything here is ADDITIVE and fenced, so the shared path above/below is untouched and\n  // byte-identical when POINTER_FX is off.\n  // Shared clip-space transform, computed once and reused for the cursor metric and the ribbon\n  // tangent (the compiler is not guaranteed to CSE the triple product otherwise). Associativity is\n  // unchanged, so preClip is bit-for-bit what the plain P*V*M*v product produced.\n  mat4 mvp = projectionMatrix * viewMatrix * modelMatrix;\n  vec4 preClip = mvp * vec4(pos, 1.0);\n  // Screen-space offset from the cursor (aspect-corrected → round in pixels). The DEFAULT metric.\n  vec2 ndcHere = preClip.xy / max(preClip.w, 1.0e-6);\n  vec2 dp = (ndcHere - uPointer) * vec2(uPointerAspect, 1.0);\n  // Ribbon flow: stretch the metric along the strip's own LENGTH axis so the field reaches ALONG the\n  // ribbon and stays tight across it — the \"flows with the material\" feel, per-vertex (so it follows\n  // the strip's curve) with no CPU surface pick. The length axis is local +X (uv.x runs with x)\n  // carried through the SAME twist as the surface. The camera is orthographic (affine, w=1), so the\n  // axis's screen image is the linear map of the DIRECTION (w=0): one mat·dir, no second\n  // point-projection and no perspective divide. (A true per-pixel uv would need GPU picking — the\n  // visible surface is shader-displaced, so a CPU raycast of the base geometry misses.)\n  if (uShapeFlow > 0.0) {\n    vec3 tangentLocal = (((vec4(1.0, 0.0, 0.0, 0.0) * rotA) * rotB) * rotC).xyz;\n    vec2 tang = (mvp * vec4(tangentLocal, 0.0)).xy * vec2(uPointerAspect, 1.0);\n    float tl = length(tang);\n    if (tl > 1.0e-6) {\n      tang /= tl;\n      vec2 nrm = vec2(-tang.y, tang.x);\n      dp = vec2(dot(dp, tang) / (1.0 + uShapeFlow * 2.5), dot(dp, nrm)); // up to 3.5× reach along length\n    }\n  }\n  float fall = smoothstep(uPointerRadius, 0.0, length(dp));\n  vPointerFall = fall * uPointerActive;\n  // Displacement axis = local +Y carried through the SAME three twist rotations as pos (row-vector\n  // convention). Rotations are linear, so post-twist axis displacement equals pre-twist Y displacement.\n  vec3 dispAxis = (((vec4(0.0, 1.0, 0.0, 0.0) * rotA) * rotB) * rotC).xyz;\n  // Agitation: a fast churn octave near the cursor (additive — never rewrites base noise t, which\n  // would force restructuring the shared path). Loop-safe under both time variants.\n#ifdef LOOP_MOTION\n  float disp = uPointerAgitate * vPointerFall\n        * simplexNoise(vec2(pos.x * uDispFreqX * 3.0, pos.z * uDispFreqZ * 3.0) + loopOff * 4.0);\n#else\n  float disp = uPointerAgitate * vPointerFall\n        * simplexNoise(vec2(pos.x * uDispFreqX * 3.0 + t * 4.0, pos.z * uDispFreqZ * 3.0));\n#endif\n  // Membrane push/pull: a smooth dome (vPointerFall is the falloff) that swells toward you (+ repel)\n  // or dents away (− attract) at the cursor, riding along with the sprung field.\n  disp += uPointerPush * vPointerFall;\n  // Drag-wake: pull the surface just BEHIND the moving cursor into a trailing trough. dp points\n  // from cursor to vertex; \"behind\" is how far the vertex sits opposite the velocity (0 ahead → 1 a\n  // radius behind), gated by speed so it only forms while dragging and heals when the cursor stops.\n  vec2 velC = uPointerVel * vec2(uPointerAspect, 1.0);\n  float wakeSpeed = length(velC);\n  if (uPointerWake != 0.0 && wakeSpeed > 1.0e-4) {\n    float behind = clamp(dot(-dp, velC) / (wakeSpeed * uPointerRadius), 0.0, 1.0);\n    disp -= uPointerWake * vPointerFall * behind * smoothstep(0.05, 0.6, wakeSpeed);\n  }\n#ifdef POINTER_RIPPLES\n  for (int i = 0; i < 4; i++) {\n    if (uRippleAmp[i] > 0.0) {\n      float rd = length((preClip.xy / max(preClip.w, 1.0e-6) - uRippleOrigin[i]) * vec2(uPointerAspect, 1.0));\n      // A wave PACKET whose crest travels outward at RIPPLE_WAVE_SPEED: a gaussian window centred on\n      // the moving front carrying a short oscillation (a raised ring with faint trailing troughs),\n      // so the energy radiates instead of throbbing at the click point. The shared uRippleAmp\n      // envelope fades the whole packet over its lifetime; reach fades it as the crest leaves frame.\n      float front = uRippleAge[i] * RIPPLE_WAVE_SPEED;\n      float band  = rd - front;\n      float packet = exp(-band * band / (2.0 * RIPPLE_SIGMA * RIPPLE_SIGMA)) * cos(band * RIPPLE_FREQ);\n      float reach = 1.0 - smoothstep(RIPPLE_MAX_R * 0.7, RIPPLE_MAX_R, front);\n      disp += uPointerRipple * uRippleAmp[i] * packet * reach;\n    }\n  }\n#endif\n  pos += dispAxis * disp;\n#endif\n\n  // The scale / rotation / position transform lives on the mesh (modelMatrix), so the\n  // orientation matches THREE's Euler-XYZ rather than an in-shader rotation order.\n  vec4 world = modelMatrix * vec4(pos, 1.0);\n  vWorldPos = world.xyz;\n  vViewDir = cameraPosition - world.xyz;\n  gl_Position = projectionMatrix * viewMatrix * world;\n  vClipPosition = gl_Position;\n}\n`;\n\nexport const fragmentShader = /* glsl */ `\n#define MAX_COLORS ${MAX_COLORS}\n#define MAX_MESH_POINTS ${MAX_MESH_POINTS}\n#define MAX_LIGHTS ${MAX_LIGHTS}\n#define MAX_NOISE_BANDS ${MAX_NOISE_BANDS}\n#define PI 3.14159265359\n\n${simplex2d}\n\n${colorUniforms}\nuniform float uDebug;         // dev: 1 = show crease, 2 = show derivative normal\nuniform float uSheen;       // white-lift on the flat (low-crease) areas (1 = full)\nuniform float uRoundness;        // pose-robust normal-based roundness/thickness strength\nuniform float uIridescence;      // thin-film hue shift with view angle (0 = off)\nuniform float uFiberCount;\nuniform float uFiberStrength;\nuniform float uTexture;\nuniform float uCreaseLight;\nuniform float uCreaseSharpness;\nuniform float uCreaseSoftness;\nuniform float uEdgeFade;\nuniform vec2 uResolution;\nuniform float uAmbient;\nuniform int uNumLights;\nuniform vec3 uLightPos[MAX_LIGHTS];\nuniform vec3 uLightColor[MAX_LIGHTS];\nuniform float uLightIntensity[MAX_LIGHTS];\nuniform int uNumNoiseBands;\nuniform vec4 uNoiseBandBounds[MAX_NOISE_BANDS];  // (startX, endX, startY, endY)\nuniform vec4 uNoiseBandParams[MAX_NOISE_BANDS];  // (feather, strength, frequency, colorAttenuation)\nuniform float uNoiseBandParaPow[MAX_NOISE_BANDS];\n\nvarying vec2 vUv;\nvarying vec3 vWorldPos;\nvarying vec3 vViewDir;\n#ifdef DEPTH_TINT\nuniform float uDepthTint;\nuniform vec3 uDepthTintColor;\nvarying vec4 vClipPosition; // clip-space depth (written by the vertex shader for both programs)\n#endif\n#ifdef EDGE_FEATHER\nuniform float uEdgeFeather; // ribbon long-edge softness (only when it differs from the 0.1 default)\n#endif\n#ifdef POINTER_FX\nuniform float uPointerThin;    // 0..1 local translucency near the cursor\nuniform float uPointerHue;     // degrees, local hue rotation near the cursor\nuniform float uPointerLighten; // -1..1 local brightness lift near the cursor\nvarying float vPointerFall;    // falloff × presence, written by the vertex shader\n#endif\n\n// Cheap value hash for the optional grain overlay (distinct from the simplex hash).\nfloat grainHash(vec2 p){ return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }\n\nfloat parabola(float x, float k){ return pow(4.0 * x * (1.0 - x), k); }\nfloat mapLinear(float v, float a, float b, float c, float d){ return c + (v - a) * (d - c) / (b - a); }\n\n${colorFns}\n\n// Striations: a subtle high-frequency simplex-noise grain ADDED to the\n// colour — colour-matched (weaker where blue is high), only near folds (crease), and\n// concentrated toward the ends (parabola). Blends in rather than reading as hard lines.\nvec3 surfaceStreaks(vec2 uv, vec3 color, float crease){\n  float strength = uFiberStrength;          // default 0.2\n  float freq = uFiberCount;                   // default 600\n  float colorAtten = 0.9;\n  float paraPow = 3.0;\n  // Noise bands: inside each rectangular uv region the\n  // fiber params are overridden, so the streaks vary per region instead of uniform.\n  for (int i = 0; i < MAX_NOISE_BANDS; i++) {\n    if (i >= uNumNoiseBands) break;\n    vec4 b = uNoiseBandBounds[i];\n    vec4 prm = uNoiseBandParams[i];\n    float feather = max(prm.x, 1.0e-4);\n    float blend =\n      smoothstep(b.x - feather, b.x, uv.x) * (1.0 - smoothstep(b.y, b.y + feather, uv.x)) *\n      smoothstep(b.z - feather, b.z, uv.y) * (1.0 - smoothstep(b.w, b.w + feather, uv.y));\n    strength = mix(strength, prm.y, blend);\n    freq = mix(freq, prm.z, blend);\n    colorAtten = mix(colorAtten, prm.w, blend);\n    paraPow = mix(paraPow, uNoiseBandParaPow[i], blend);\n  }\n  // The high frequency runs along uv.x (the ribbon's length) so the streaks read as\n  // fine lengthwise fibers; end-weighted by 1 - parabola(uv.x).\n  float p = 1.0 - parabola(uv.x, paraPow);\n  float n0 = simplexNoise(vec2(uv.x * 0.1, uv.y * 0.5));\n  float n1 = simplexNoise(vec2(uv.x * (freq + freq * 0.5 * n0), uv.y * 4.0 * n0));\n  n1 = mapLinear(n1, -1.0, 1.0, 0.0, 1.0);\n  color += n1 * strength * (1.0 - color.b * colorAtten) * crease * p;\n  return color;\n}\n\nvoid main(){\n  // crease: a foreshortening / fold detector from the screen-space uv derivative.\n  // It drives BOTH the roundness shading and where the streaks appear — this is what\n  // gives the wave its thickness without any normal-based lighting.\n  float crease = dFdy(vUv).y * uResolution.y * uCreaseLight;\n  crease = clamp(mapLinear(crease, -1.0, 1.0, 0.0, 1.0), 0.0, 1.0);\n  crease = pow(crease, uCreaseSharpness);\n  crease = clamp(smoothstep(0.0, uCreaseSoftness, crease), 0.0, 1.0);\n\n  // Debug visualisations (dev): 1 = crease value, 2 = derivative surface normal.\n  if (uDebug > 0.5) {\n    if (uDebug < 1.5) { gl_FragColor = vec4(vec3(crease), 1.0); return; }\n    vec3 dn = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    gl_FragColor = vec4(dn * 0.5 + 0.5, 1.0); return;\n  }\n\n  // Colour: sample the baked 2D palette texture, or fall back to the procedural 1-D\n  // gradient (see waveBaseColor).\n  vec3 col = waveBaseColor(vUv);\n  col = surfaceStreaks(vUv, col, crease);\n  col = applyColorGrade(col);\n\n#ifdef POINTER_FX\n  // Local hue rotation + brightness lift near the cursor (both fade out with vPointerFall).\n  col = hueShift(col, radians(uPointerHue) * vPointerFall);\n  col *= 1.0 + uPointerLighten * vPointerFall;\n#endif\n\n  // Iridescence: a thin-film / holographic hue that shifts with view angle. Reuses the same\n  // camera-facing ratio as roundness (recomputed here, since roundness may be off): grazing parts\n  // of the ribbon (low facing) shift hue most, so the colour flows as the ribbon curves. Skipped\n  // at 0, so the compiled result is unchanged when off.\n  if (uIridescence > 0.001) {\n    vec3 iridN = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    float iridFacing = abs(dot(iridN, normalize(vViewDir)));\n    col = hueShift(col, (1.0 - iridFacing) * uIridescence * PI);\n  }\n\n  // Sheen: lift the flat (low-crease) areas toward white. This is\n  // pose-dependent (it keys off dFdy(uv.y)), so we keep it gentle and add a robust term.\n  col += (1.0 - crease) * 0.25 * uSheen;\n\n  // Pose-robust roundness: shade by the camera-facing ratio of the derivative surface\n  // normal so the ribbon reads as a rounded, grabbable solid from any angle. Grazing\n  // edges darken into shadow (defining the rounded form), the body keeps its full colour,\n  // and the most face-on sliver catches a soft highlight. uRoundness = strength.\n  if (uRoundness > 0.001) {\n    vec3 volN = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    float facing = abs(dot(volN, normalize(vViewDir)));   // 1 = facing camera, 0 = edge-on\n    col *= mix(1.0 - 0.6 * uRoundness, 1.0, facing);          // deepen grazing edges → solid form\n    col += smoothstep(0.65, 1.0, facing) * uRoundness * 0.18; // soft highlight on the facing body\n  }\n\n  // Optional positionable lights (our feature) — additive & gentle, on top of the\n  // base shading so the default look is preserved. A finely-subdivided mesh\n  // keeps this derivative normal smooth.\n  if (uNumLights > 0) {\n    vec3 N = normalize(cross(dFdx(vWorldPos), dFdy(vWorldPos)));\n    vec3 Vd = normalize(vViewDir);\n    if (dot(N, Vd) < 0.0) N = -N;\n    for (int i = 0; i < MAX_LIGHTS; i++) {\n      if (i >= uNumLights) break;\n      vec3 L = normalize(uLightPos[i] - vWorldPos);\n      vec3 lc = uLightColor[i] * uLightIntensity[i];\n      float diff = max(dot(N, L), 0.0);\n      float spec = pow(max(dot(N, normalize(L + Vd)), 0.0), 28.0);\n      col += col * diff * lc * 0.16 + spec * lc * 0.10;\n    }\n  }\n  col *= 0.55 + clamp(uAmbient, 0.0, 1.0);   // overall level; default 0.45 => x1.0 (neutral)\n\n#ifdef DEPTH_TINT\n  // Depth tint: fade far fragments toward a colour so a multi-wave stack gains atmospheric\n  // separation — near strands keep their colour, far ones recede. Reuses the clip-space depth the\n  // wireframe theme fades with (clamp(z*6), where 1 = far).\n  col = mix(col, uDepthTintColor, clamp(vClipPosition.z * 6.0, 0.0, 1.0) * uDepthTint);\n#endif\n\n  if (uTexture > 0.001) col *= 1.0 + (grainHash(vUv * 850.0) - 0.5) * uTexture * 0.25;\n\n  // Soft long edges + optional viewport-edge fade. The edge softness is the hardcoded 0.1 by\n  // default (literal branch → byte-identical); EDGE_FEATHER swaps in the uEdgeFeather knob only\n  // when it differs, so razor-crisp or vapor-soft edges are both reachable.\n#ifdef EDGE_FEATHER\n  float ribEdge =\n    smoothstep(0.0, uEdgeFeather, vUv.y) * (1.0 - smoothstep(1.0 - uEdgeFeather, 1.0, vUv.y));\n#else\n  float ribEdge = smoothstep(0.0, 0.1, vUv.y) * (1.0 - smoothstep(0.9, 1.0, vUv.y));\n#endif\n  float alpha = uOpacity * ribEdge;\n#ifdef POINTER_FX\n  alpha *= clamp(1.0 - uPointerThin * vPointerFall, 0.0, 1.0); // solid: local translucency\n#endif\n  if (uEdgeFade > 0.001) {\n    vec2 sc = gl_FragCoord.xy / max(uResolution, vec2(1.0));\n    float vig =\n      smoothstep(0.0, uEdgeFade, sc.x) * (1.0 - smoothstep(1.0 - uEdgeFade, 1.0, sc.x)) *\n      smoothstep(0.0, uEdgeFade, sc.y) * (1.0 - smoothstep(1.0 - uEdgeFade, 1.0, sc.y));\n    alpha *= vig;\n  }\n\n  // Deep \"squared\" hero colour: formerly done by a framebuffer-squaring blend that REPLACED the\n  // destination (punching holes at soft edges / where waves overlap). Squaring here + normal\n  // premultiplied compositing (see applyBlendMode) keeps the deep colour and blends correctly.\n  col = clamp(col, 0.0, 1.0);\n  // Square colour AND alpha so the soft ribbon edges keep the crisp, thin feather of the original\n  // squared-blend look — but now composited (premultiplied) rather than replace-blended, so they\n  // no longer punch holes. Over an opaque background alpha² still resolves to fully opaque.\n  if (uSquared > 0.5) { col *= col; alpha *= alpha; }\n  gl_FragColor = vec4(col, alpha);\n#ifdef PREMULTIPLIED_ALPHA\n  gl_FragColor.rgb *= gl_FragColor.a;\n#endif\n}\n`;\n\n// ---- Wireframe \"thin-line\" theme ----\n// The same wave geometry, but instead of a solid surface the colour is carved into fine\n// vertical lines (abs(sin(uv.x * lineAmount))) whose thickness scales with the screen-\n// space uv derivative, then mixed line<->background with a depth fade. Used by the dark\n// hero preset. hueShift takes degrees (radians() here) to match the light shader.\nexport const lineFragmentShader = /* glsl */ `\n#define MAX_COLORS ${MAX_COLORS}\n#define MAX_MESH_POINTS ${MAX_MESH_POINTS}\n#define PI 3.14159265359\n\n${simplex2d}\n\n${colorUniforms}\nuniform float uLineAmount;          // default 425\nuniform float uLineThickness;       // default 1\nuniform float uLineDerivativePower; // default 0.95\nuniform float uMaxWidth;            // default 1232\nuniform vec3 uClearColor;           // = page background colour (shown between the lines)\n\nvarying vec2 vUv;\nvarying vec4 vClipPosition;\n#ifdef POINTER_FX\nuniform float uPointerThin;    // 0..1 — strands taper to hairlines near the cursor\nuniform float uPointerHue;     // degrees, local hue rotation near the cursor\nuniform float uPointerLighten; // -1..1 local brightness lift near the cursor\nvarying float vPointerFall;    // falloff × presence, written by the vertex shader\n#endif\n\n${colorFns}\n\nvoid main(){\n  // Same 2D palette sample + colour ops as the solid theme.\n  vec3 color = applyColorGrade(waveBaseColor(vUv));\n\n#ifdef POINTER_FX\n  color = hueShift(color, radians(uPointerHue) * vPointerFall);\n  color *= 1.0 + uPointerLighten * vPointerFall;\n#endif\n\n  // Carve into fine vertical lines; thickness from the screen-space uv derivative.\n  vec2 dy = dFdy(vUv);\n  float lineThickness = uLineThickness * pow(abs(dy.x * uMaxWidth), uLineDerivativePower);\n#ifdef POINTER_FX\n  lineThickness *= clamp(1.0 - uPointerThin * vPointerFall, 0.0, 1.0); // wireframe: taper strands\n#endif\n  float a = abs(sin(vUv.x * uLineAmount));\n  a = smoothstep(lineThickness, 0.0, a);\n\n  // Depth fade: the wave recedes into the background colour with depth. Watch the\n  // argument order: clamp(0.0, 1.0, z*6) is a swapped-args trap — it clamps the\n  // constant 0.0 into [1.0, z*6], i.e. min(1.0, z*6), which (with our ortho clip.z\n  // range) collapses the whole wave to the background. The correct clamp(z*6, 0, 1)\n  // gives the proper subtle far-end fade and thin-line look.\n  float depthFade = clamp(vClipPosition.z * 6.0, 0.0, 1.0);\n  color = mix(uClearColor, color, a * (1.0 - depthFade));\n  if (uSquared > 0.5) color *= color; // deep \"squared\" look, now composited not replace-blended\n  gl_FragColor = vec4(color, uOpacity);\n#ifdef PREMULTIPLIED_ALPHA\n  gl_FragColor.rgb *= gl_FragColor.a;\n#endif\n}\n`;\n\n// ---- Post pass: viewport-edge soft-focus blur + dither grain ----\n\nexport const postVertexShader = /* glsl */ `\nvarying vec2 vUv;\nvoid main(){\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}\n`;\n\nexport const postFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform vec2 uResolution;\nuniform float uBlurAmount;\nuniform int uBlurSamples;\nuniform float uGrainAmount;\nuniform float uTime;\nvarying vec2 vUv;\n\nfloat random2(vec2 st){ return fract(sin(dot(st.xy, vec2(12.9898, 78.233))) * 43758.5453); }\n\n// Angular (spin) blur: rotate the sample coord around the centre and\n// accumulate — a tangential smear that grows toward the edges. Carries alpha so a\n// transparent background survives the post pass.\nvec4 blurAngular(sampler2D tex, vec2 uv, float angle, int samples){\n  vec4 total = vec4(0.0);\n  vec2 coord = uv - 0.5;\n  float dist = 1.0 / float(samples);\n  vec2 dir = vec2(cos(angle * dist), sin(angle * dist));\n  mat2 rot = mat2(dir.x, dir.y, -dir.y, dir.x);\n  for (int i = 0; i < 64; i++){\n    if (i >= samples) break;\n    total += texture2D(tex, coord + 0.5);\n    coord = coord * rot; // row-vector order (coord * rot) sets the spin direction\n  }\n  return total * dist;\n}\n\nvoid main(){\n  vec4 sceneColor = texture2D(tDiffuse, vUv);\n  vec4 blurColor = blurAngular(tDiffuse, vUv, uBlurAmount, uBlurSamples);\n  // blurPower: keep a sharp band weighted to the middle, blurring toward top & bottom.\n  float blurPower = smoothstep(0.0, 0.7, vUv.y) - smoothstep(0.2, 1.0, vUv.y);\n  vec4 color = mix(blurColor, sceneColor, blurPower);\n  // Static film grain: keyed off gl_FragCoord only (no uTime), so it doesn't flicker.\n  color.rgb += mix(uGrainAmount, -uGrainAmount, random2(gl_FragCoord.xy * 0.01)) * (4.0 / 255.0);\n  gl_FragColor = color;   // preserve alpha → transparent background works\n}\n`;\n\n// ---- Post pass: ordered (Bayer) dithering ----\n//\n// DERIVED FROM @paper-design/shaders `image-dithering` (https://github.com/paper-design/shaders,\n// Apache-2.0 — see THIRD-PARTY-NOTICES.md). The Bayer matrices, getBayerValue, and the brightness /\n// luminance-quantization / hue-preserving \"original colours\" recolour are paper's. Adapted to a\n// post pass: samples the composited scene (tDiffuse) at full-frame vUv instead of paper's sized/fit\n// u_image UV, drops the frame/aspect machinery, fixes the 8x8 matrix (paper's default), and gates\n// via uDitherStrength. The int[] arrays + dynamic indexing compile because three builds\n// ShaderMaterials as \"#version 300 es\". Runs AFTER OutputPass, so it dithers display-space colour;\n// keyed off gl_FragCoord/tDiffuse only (no uTime) → deterministic, friendly to pixel-digest checks.\nexport const ditherFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform vec2 uResolution;\nuniform float uDitherStrength;  // 0..1 mix back toward the original\nuniform float uDitherScale;     // pixel-block size in device px (paper: u_pxSize)\nuniform float uDitherSteps;     // quantization levels (paper: u_colorSteps)\nvarying vec2 vUv;\n\nconst int bayer2x2[4] = int[4](0, 2, 3, 1);\nconst int bayer4x4[16] = int[16](0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5);\nconst int bayer8x8[64] = int[64](\n  0, 32, 8, 40, 2, 34, 10, 42, 48, 16, 56, 24, 50, 18, 58, 26,\n  12, 44, 4, 36, 14, 46, 6, 38, 60, 28, 52, 20, 62, 30, 54, 22,\n  3, 35, 11, 43, 1, 33, 9, 41, 51, 19, 59, 27, 49, 17, 57, 25,\n  15, 47, 7, 39, 13, 45, 5, 37, 63, 31, 55, 23, 61, 29, 53, 21\n);\nfloat getBayerValue(vec2 uv, int size){\n  ivec2 pos = ivec2(fract(uv / float(size)) * float(size));\n  int index = pos.y * size + pos.x;\n  if (size == 2) return float(bayer2x2[index]) / 4.0;\n  else if (size == 4) return float(bayer4x4[index]) / 16.0;\n  else if (size == 8) return float(bayer8x8[index]) / 64.0;\n  return 0.0;\n}\n\nvoid main(){\n  float pxSize = max(uDitherScale, 1.0);\n  vec2 pxSizeUV = gl_FragCoord.xy / pxSize;\n  vec2 sampleUV = (floor(gl_FragCoord.xy / pxSize) + 0.5) * pxSize / max(uResolution, vec2(1.0));\n  vec4 image = texture2D(tDiffuse, sampleUV);\n\n  float lum = dot(vec3(0.2126, 0.7152, 0.0722), image.rgb);\n  float colorSteps = max(floor(uDitherSteps), 1.0);\n\n  float dithering = getBayerValue(pxSizeUV, 8) - 0.5;   // paper's default 8x8 ordered screen\n  float brightness = clamp(lum + dithering / colorSteps, 0.0, 1.0);\n  brightness = mix(0.0, brightness, image.a);\n  float quantLum = floor(brightness * colorSteps + 0.5) / colorSteps;\n\n  // paper's \"original colours\" path: keep the source hue, quantize luminance.\n  vec3 color = image.rgb / max(lum, 0.001) * quantLum;\n  float quantAlpha = floor(image.a * colorSteps + 0.5) / colorSteps;\n  float opacity = mix(quantLum, 1.0, quantAlpha);\n\n  gl_FragColor = mix(image, vec4(color, opacity), clamp(uDitherStrength, 0.0, 1.0));\n}\n`;\n\n// ---- Post pass: innerLight (volumetric light streaks) — another \"layered\" post shader ----\n//\n// Radial light-scattering (à la GPU Gems 3): from each pixel, march toward a light point and\n// accumulate the wave's own brightness (weighted by alpha, so only opaque pixels emit), then add\n// the streaks back. Runs in the scene zone so it scatters the raw, pre-tone-map wave like bloom.\nexport const innerLightFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform float uInnerLight;        // 0..1 strength of the added light\nuniform float uInnerLightDensity; // ray length / spread\nuniform float uInnerLightDecay;   // per-sample falloff (<1)\nuniform vec2  uInnerLightCenter;  // light source, UV (0..1)\nvarying vec2 vUv;\n\nconst int LIGHT_SAMPLES = 24;\n\nfloat luma(vec3 c){ return dot(c, vec3(0.2126, 0.7152, 0.0722)); }\n\nvoid main(){\n  vec4 src = texture2D(tDiffuse, vUv);\n  vec2 delta = (vUv - uInnerLightCenter) * (uInnerLightDensity / float(LIGHT_SAMPLES));\n  vec2 coord = vUv;\n  float decay = 1.0;\n  vec3 rays = vec3(0.0);\n  for (int i = 0; i < LIGHT_SAMPLES; i++){\n    coord -= delta;\n    vec4 s = texture2D(tDiffuse, coord);\n    rays += s.rgb * s.a * decay;   // only opaque (wave) pixels emit light\n    decay *= uInnerLightDecay;\n  }\n  rays /= float(LIGHT_SAMPLES);\n  vec3 outc = src.rgb + rays * uInnerLight;\n  float outA = max(src.a, luma(rays) * uInnerLight); // shafts stay visible over the transparent bg\n  gl_FragColor = vec4(outc, clamp(outA, 0.0, 1.0));\n}\n`;\n\n// ---- Post pass: halftone (rotated dot screen) ----\n//\n// DERIVED FROM @paper-design/shaders `halftone-dots` (https://github.com/paper-design/shaders,\n// Apache-2.0 — see THIRD-PARTY-NOTICES.md). Ports the \"classic\" dot type + \"original colours\" path:\n// paper's getCircle (dot radius ← 1 − luminance, fwidth-antialiased) and sigmoid-contrast luminance,\n// sampled once per cell centre. Adapted to a post pass — samples the composited scene (tDiffuse)\n// instead of paper's sized u_image, drops the gooey/holes/soft dot types, the diagonal grid and the\n// grain layers, and composites transparent between dots. Contrast/radius fixed at paper's defaults.\nexport const halftoneFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform vec2 uResolution;\nuniform float uHalftone;      // 0..1 mix\nuniform float uHalftoneCell;  // dot cell size in device px (paper: u_size)\nuniform float uHalftoneAngle; // screen rotation (radians, paper: u_rotation)\nvarying vec2 vUv;\n\nfloat sigmoid(float x, float k){ return 1.0 / (1.0 + exp(-k * (x - 0.5))); }\n// paper's classic dot: radius grows as the sampled cell darkens (1 - lum), soft edge via fwidth.\nfloat getCircle(vec2 uv, float lum, float baseR){\n  float r = mix(0.25 * baseR, 0.0, lum);\n  float d = length(uv - 0.5);\n  float aa = fwidth(d);\n  return 1.0 - smoothstep(r - aa, r + aa, d);\n}\n\nvoid main(){\n  float ca = cos(uHalftoneAngle);\n  float sa = sin(uHalftoneAngle);\n  mat2 rot = mat2(ca, sa, -sa, ca);\n  float cell = max(uHalftoneCell, 2.0);\n  vec2 gridPx = rot * gl_FragCoord.xy;                      // rotate the screen into the dot grid\n  vec2 cellId = floor(gridPx / cell);\n  vec2 inCell = fract(gridPx / cell);                       // position within the cell (0..1)\n  vec2 centrePx = transpose(rot) * ((cellId + 0.5) * cell); // cell centre, back in screen px\n  vec4 tex = texture2D(tDiffuse, centrePx / max(uResolution, vec2(1.0)));\n\n  float k = 2.0;                                            // sigmoid contrast (paper default)\n  vec3 c = vec3(sigmoid(tex.r, k), sigmoid(tex.g, k), sigmoid(tex.b, k));\n  float lum = dot(vec3(0.2126, 0.7152, 0.0722), c);\n  lum = mix(1.0, lum, tex.a);\n  float dot = getCircle(inCell, lum, 1.3);                 // baseR 1.3 ≈ paper original-colours default\n  vec4 dots = vec4(tex.rgb, tex.a * dot);                  // wave-coloured dots, transparent between\n  gl_FragColor = mix(texture2D(tDiffuse, vUv), dots, clamp(uHalftone, 0.0, 1.0));\n}\n`;\n\n// ---- Post pass: heatmap (map luminance → thermal palette) — a finish-zone filter ----\nexport const heatmapFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform float uHeatmap;   // 0..1 mix\nvarying vec2 vUv;\nvec3 heat(float t){\n  t = clamp(t, 0.0, 1.0);\n  vec3 c = mix(vec3(0.0, 0.0, 0.4), vec3(0.0, 0.6, 1.0), smoothstep(0.0, 0.25, t));\n  c = mix(c, vec3(0.0, 1.0, 0.4), smoothstep(0.25, 0.5, t));\n  c = mix(c, vec3(1.0, 1.0, 0.0), smoothstep(0.5, 0.75, t));\n  c = mix(c, vec3(1.0, 0.1, 0.0), smoothstep(0.75, 1.0, t));\n  return c;\n}\nvoid main(){\n  vec4 src = texture2D(tDiffuse, vUv);\n  float l = dot(src.rgb, vec3(0.299, 0.587, 0.114));\n  gl_FragColor = vec4(mix(src.rgb, heat(l), clamp(uHeatmap, 0.0, 1.0)), src.a);\n}\n`;\n\n// ---- Post pass: paper texture (fibrous substrate shading) — a finish-zone overlay ----\nexport const paperTextureFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform float uPaper;      // 0..1 strength\nuniform float uPaperScale; // grain scale\nvarying vec2 vUv;\nfloat h21(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }\nvoid main(){\n  vec4 src = texture2D(tDiffuse, vUv);\n  vec2 p = gl_FragCoord.xy / max(uPaperScale, 0.5);\n  float fiber = h21(floor(p)) * 0.5 + h21(floor(p * vec2(0.3, 3.0))) * 0.5; // directional fibers\n  float tex = mix(fiber, h21(gl_FragCoord.xy), 0.3);                        // + fine speckle\n  float shade = 1.0 - (tex - 0.5) * 0.35;\n  gl_FragColor = vec4(src.rgb * mix(1.0, shade, clamp(uPaper, 0.0, 1.0)), src.a);\n}\n`;\n\n// ---- Post pass: CMYK halftone (four rotated dot screens) — a finish-zone filter ----\nexport const halftoneCmykFragmentShader = /* glsl */ `\nuniform sampler2D tDiffuse;\nuniform float uHalftoneCmyk;     // 0..1 mix\nuniform float uHalftoneCmykCell; // dot cell size in device px\nvarying vec2 vUv;\n// One rotated halftone dot screen for a channel value.\nfloat dotScreen(vec2 coord, float value, float angle, float cell){\n  float ca = cos(angle);\n  float sa = sin(angle);\n  vec2 r = mat2(ca, sa, -sa, ca) * coord;\n  vec2 c = fract(r / max(cell, 2.0)) - 0.5;\n  float radius = sqrt(clamp(value, 0.0, 1.0)) * 0.5;\n  return smoothstep(radius, radius - 0.06, length(c));\n}\nvoid main(){\n  vec4 src = texture2D(tDiffuse, vUv);\n  float k = 1.0 - max(max(src.r, src.g), src.b);   // RGB → CMYK\n  float invK = max(1.0 - k, 1e-3);\n  float cyan = (1.0 - src.r - k) / invK;\n  float mag = (1.0 - src.g - k) / invK;\n  float yel = (1.0 - src.b - k) / invK;\n  vec2 coord = gl_FragCoord.xy;\n  float cell = uHalftoneCmykCell;\n  float dc = dotScreen(coord, cyan, 1.309, cell); // 75°\n  float dm = dotScreen(coord, mag, 0.262, cell);  // 15°\n  float dy = dotScreen(coord, yel, 0.0, cell);    // 0°\n  float dk = dotScreen(coord, k, 0.785, cell);    // 45°\n  // Subtractive: cyan ink absorbs red, magenta absorbs green, yellow absorbs blue, black absorbs all.\n  vec3 outc = vec3(1.0) - vec3(dc, 0.0, 0.0) - vec3(0.0, dm, 0.0) - vec3(0.0, 0.0, dy) - vec3(dk);\n  outc = clamp(outc, 0.0, 1.0);\n  gl_FragColor = vec4(mix(src.rgb, outc, clamp(uHalftoneCmyk, 0.0, 1.0)), src.a);\n}\n`;\n"],"mappings":";;;;;;;;;;;;;;;AAqBA,MAAM,YAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC7B,MAAM,gBAA2B;;;;;;;;;;;;;;;;;;;;;;;;AA2BjC,MAAM,WAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyF5B,MAAa,eAA0B;EACrC,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6MZ,MAAa,iBAA4B;;;;;;;EAOvC,UAAU;;EAEV,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+Cd,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4JX,MAAa,qBAAgC;;;;;EAK3C,UAAU;;EAEV,cAAc;;;;;;;;;;;;;;;;EAgBd,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCX,MAAa,mBAA8B;;;;;;;AAQ3C,MAAa,qBAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkD7C,MAAa,uBAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqD/C,MAAa,2BAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCnD,MAAa,yBAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCjD,MAAa,wBAAmC;;;;;;;;;;;;;;;;;;AAoBhD,MAAa,6BAAwC;;;;;;;;;;;;;;;AAiBrD,MAAa,6BAAwC"}

package/dist/shell/createWave.d.ts

@@ -1,6 +1,7 @@
 import { StudioConfig } from "../config/model.js";
 import { WaveRenderer } from "../renderer/WaveRenderer.js";
 import { core_loader_d_exports } from "../core-loader.js";
+import { PosterFit } from "./poster.js";
 
 //#region src/shell/createWave.d.ts
 /** Why the shell showed the poster instead of a live wave. */
@@ -12,6 +13,10 @@ type CoreModule = typeof core_loader_d_exports;
 interface WaveOptions {
   /** Poster URL / data-URI. Defaults to adopting the container's `<img data-wave3d-poster>` (SSR). */
   poster?: string;
+  /** Poster `object-fit`. Default `"fill"` — matches the canvas (which renders edge-to-edge at the
+   *  container's aspect), so a poster captured at that aspect hands off with no visible jump. Use
+   *  `"cover"` to crop a different-aspect placeholder instead of stretching it. See {@link PosterFit}. */
+  posterFit?: PosterFit;
   /** Wait until the container nears the viewport before fetching the engine. Default true. */
   lazy?: boolean;
   /** IntersectionObserver margin for the lazy trigger. Default "200px". */
@@ -54,6 +59,9 @@ interface WaveHandle {
   snapshot(options?: SnapshotOptions): Promise<Blob | null>;
   /** Merge a partial config. Staged before upgrade; after, setConfig() then refreshPlayback(). */
   set(config: Partial<StudioConfig>): void;
+  /** Feed a `custom:<name>` interaction input for `custom:*` bindings. Staged (last value per name)
+   *  before upgrade and replayed once the renderer is live; a no-op if no binding consumes it. */
+  setInteractionInput(name: string, value: number): void;
   play(): void;
   pause(): void;
   /** Safe to call in any state (aborts a pending upgrade, disposes a live renderer, removes the poster). */
@@ -69,5 +77,5 @@ declare function createWave(container: HTMLElement, config?: Partial<StudioConfi
 /** The drop-in embed contract: an alias of {@link createWave}. */
 declare const mountWave: typeof createWave;
 //#endregion
-export { FallbackReason, SnapshotOptions, WaveHandle, WaveOptions, WaveState, createWave, mountWave };
+export { FallbackReason, type PosterFit, SnapshotOptions, WaveHandle, WaveOptions, WaveState, createWave, mountWave };
 //# sourceMappingURL=createWave.d.ts.map

package/dist/shell/createWave.js

@@ -12,12 +12,13 @@ function createWaveImpl(loadCore, container, config, options) {
 	let renderer = null;
 	let staged = { ...config };
 	if (options.paused !== void 0) staged.paused = options.paused;
+	const stagedInputs = /* @__PURE__ */ new Map();
 	let aborted = false;
 	let io = null;
 	let lostTimer;
 	let lossCount = 0;
 	ensurePositioned(container);
-	const poster = setupPoster(container, options.poster);
+	const poster = setupPoster(container, options.poster, options.posterFit);
 	function setState(next) {
 		if (state === next) return;
 		state = next;
@@ -72,6 +73,7 @@ function createWaveImpl(loadCore, container, config, options) {
 		canvas.addEventListener("webglcontextlost", onContextLost, false);
 		canvas.addEventListener("webglcontextrestored", onContextRestored, false);
 		renderer.start();
+		for (const [name, value] of stagedInputs) renderer.setInteractionInput(name, value);
 		setState("running");
 		options.onReady?.(renderer);
 		if (poster) requestAnimationFrame(() => requestAnimationFrame(() => {
@@ -125,6 +127,10 @@ function createWaveImpl(loadCore, container, config, options) {
 				...next
 			};
 		},
+		setInteractionInput(name, value) {
+			if (renderer) renderer.setInteractionInput(name, value);
+			else stagedInputs.set(name, value);
+		},
 		play() {
 			if (renderer) {
 				renderer.getConfig().paused = false;