@wave3d/core 0.9.0 → 0.11.0

package/dist/renderer/WaveRenderer.d.ts

@@ -108,6 +108,14 @@ type Wave = {
   /** This wave's own particle / dust field — created when its `particles.count` first goes >0,
    *  disposed at 0 / absent (the WavePalette lifecycle pattern). Undefined = no dust for this wave. */
   particleField?: WaveParticleField;
+  /** The baked centreline LUT for this wave's `path` (absent when it has none). */
+  pathTexture?: THREE.DataTexture;
+  /** Signature of the points the LUT was baked from, so a drag only rewrites it when it changed. */
+  pathSig?: string;
+  /** Glass only: the layer-count companion (this wave's vertex stage + a coverage-only fragment),
+   *  built lazily by renderGlassPasses() and rebuilt when `layerKey` no longer matches. */
+  layerMaterial?: THREE.Material;
+  layerKey?: string;
 };
 /** Convert an sRGB hex string to a linear-space RGB vector (three's ColorManagement does the
  *  sRGB→linear conversion on parse). Exported for the studio subclass's live light-uniform push. */
@@ -147,6 +155,12 @@ declare class WaveRenderer {
   protected config: StudioConfig;
   protected waves: Wave[];
   private backgroundTexture?;
+  /** The frame behind the glass waves — allocated only once a wave asks for the glass theme. */
+  private backdropTarget?;
+  /** How many glass layers cover each pixel. A sheet that folds over itself is thicker there, and
+   *  thickness is the cue that reads as VOLUME rather than as a tinted film — but glass draws
+   *  opaque, so the nearest layer wins and the fold behind it is invisible without counting. */
+  private layerTarget?;
   private backgroundSig;
   private backgroundImage?;
   private backgroundImageUrl;
@@ -186,6 +200,11 @@ declare class WaveRenderer {
   protected running: boolean;
   private started;
   private visible;
+  /** Read from the document, NOT assumed: the shell builds the renderer whenever the engine chunk
+   *  lands, which can be after the reader has left the tab. Assumed visible, that renderer marked
+   *  itself running with no frame to run on, and the `visibilitychange` that brought the reader back
+   *  found nothing to restart — so the delta baseline was never reset and the first frame was handed
+   *  the whole absence at once (see MAX_FRAME_SECONDS for the same stall without the event). */
   private pageVisible;
   private reducedMotion;
   /** Intro ramp: eases animation time 0→1 over ~1s on load (when config.introRamp). */
@@ -216,6 +235,10 @@ declare class WaveRenderer {
   init(): Promise<void>;
   private get segments();
   private makeUniforms;
+  /** Reconcile a wave's baked path LUT with its config. The texture is rewritten in place when the
+   *  points change — which is what makes dragging a control point cheap, since the alternative is
+   *  rebuilding 80k vertices per frame — and disposed when a wave loses its path. */
+  private syncPathTexture;
   /** Vertex-shader #defines for a wave: TWIST_MOTION (per-wave animated twist wobble) and
    *  LOOP_MOTION (scene-level seamless loop). Both select #ifdef-gated code paths; an empty
    *  object compiles the default (linear-time) program. */
@@ -227,6 +250,20 @@ declare class WaveRenderer {
    * surface, so everything downstream in `refresh()` is shared.
    */
   protected createWaveMaterial(sc: WaveConfig | undefined): WaveMaterial;
+  /**
+   * The glass LAYER-COUNT companion for one wave: the same vertex program on the same uniforms
+   * object (shared by reference, so every per-frame write reaches it), with a fragment that only
+   * marks coverage. Drawn additively with depth off, so every fold over a pixel adds up.
+   *
+   * A stock override material could not stand in for this: its vertex stage knows nothing of the
+   * deformation and it culls back faces, so the count came out for the rest-pose plane — measured
+   * at a tenth of the real silhouette on the Liquid Glass preset. The WebGPU subclass builds the
+   * node twin from the same flags.
+   */
+  protected createLayerMaterial(sc: WaveConfig, material: WaveMaterial): THREE.Material;
+  /** What the layer companion was built against; when this changes, it is rebuilt. */
+  protected layerVariantKey(material: WaveMaterial): string;
+  private dropLayerMaterial;
   /**
    * Re-select this wave's shader variant when its config changes shape (theme, twist motion, helix,
    * …). Returns true if the material needs recompiling. The GLSL backend swaps `defines` and the
@@ -360,6 +397,31 @@ declare class WaveRenderer {
   private updateTime;
   /** Draw the composed frame. WebGL runs the EffectComposer; WebGPU runs a node post chain. */
   protected renderComposed(): void;
+  /** Capture what sits BEHIND the glass waves, so they have something to bend.
+   *
+   *  Glass is drawn opaque and fakes its see-through by sampling this texture, which is why
+   *  overlapping sheets need no sorting. The pass is skipped entirely when no wave asks for it, so
+   *  a scene without glass renders exactly as before.
+   *
+   *  The texture MUST be unbound while we render into it: binding a target as a texture while it is
+   *  the render target is a framebuffer feedback loop, and the frame is undefined. */
+  /** The world axis from a surface toward the camera. Constant under an orthographic projection,
+   *  which is exactly why it is a uniform rather than something the shader derives per fragment. */
+  private pushViewAxis;
+  private viewAxisTmp;
+  private empty?;
+  private backdropClear;
+  private prevClear;
+  private depthTmp;
+  private sizeTmp;
+  /** Pin a capture's sampling so both backends read it the same way. Left to their defaults the
+   *  two disagree about filtering and edge behaviour, and a glass sheet samples FAR from the
+   *  fragment — one offset per channel — so the disagreement shows up as a red/blue bias with green
+   *  untouched, which looks like a dispersion bug and is not one. */
+  private pinSampling;
+  /** A 1x1 transparent texture, used wherever a sampler must be BOUND but must contribute nothing. */
+  private emptyTexture;
+  protected renderGlassPasses(): void;
   /** Resize the post chain's render targets. */
   protected resizePost(w: number, h: number, dpr: number): void;
   /** Release the post chain's GPU resources. */

package/dist/renderer/WaveRenderer.js

@@ -1,6 +1,7 @@
 import { ensureStudioConfig } from "../config/model.js";
 import { WaveGeometry } from "./WaveGeometry.js";
-import { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
+import { bakePathTexture, writePathTexture } from "./wavePath.js";
+import { ditherFragmentShader, fragmentShader, glassFragmentShader, glassLayerFragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
 import { anyPointerFxActive, interactionActive, wavePointerFxActive, waveRipplesActive } from "./interactionGates.js";
 import { ParticleField } from "./particleField.js";
 import { PALETTE_MAPS, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, loadPaletteImage, paletteMapCanvas, paletteSignature } from "./palette.js";
@@ -12,7 +13,40 @@ import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
 import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js";
 import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
 //#region src/renderer/WaveRenderer.ts
+/** Which fragment program a wave's theme wants. */
+function fragmentFor(sc) {
+	if (sc?.theme === "wireframe") return lineFragmentShader;
+	if (sc?.theme === "glass") return glassFragmentShader;
+	return fragmentShader;
+}
+/** How opaque a wave's between-strand colour is. Absent is the page background at full strength (the
+*  theme as it always drew); `"transparent"` or an 8-digit hex carries its own alpha. */
+function gapAlpha(color) {
+	if (!color) return 1;
+	if (color === "transparent") return 0;
+	if (/^#[0-9a-f]{8}$/i.test(color)) return parseInt(color.slice(7, 9), 16) / 255;
+	return 1;
+}
+/** The colour half of the same field — the alpha is stripped, and `"transparent"` has no colour of
+*  its own, so it falls back to the page background it is standing in for. */
+function gapColorHex(color) {
+	if (!color || color === "transparent") return void 0;
+	return /^#[0-9a-f]{8}$/i.test(color) ? color.slice(0, 7) : color;
+}
+/** Dissolve axis name → the float the shaders branch on (see dissolveChunk's dissolveCoord). */
+const DISSOLVE_AXIS_INDEX = {
+	length: 0,
+	width: 1,
+	screenX: 2,
+	screenY: 3
+};
 const BASE_SEGMENTS = 220;
+/** The longest frame the clock will believe, in seconds. Anything past it is a STALL — frames
+*  suspended with no `visibilitychange` to say so (an embedding webview that parks rAF, a debugger
+*  pause, the machine asleep) — and replaying a stall is a fast-forward, not motion. A ceiling, not
+*  a jitter clamp: recordings run on this same wall-clock loop, so a merely slow frame (a 4K export
+*  at 10fps) must still advance by its real length or a `loopSeconds` export stops closing. */
+const MAX_FRAME_SECONDS = 1;
 /** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
 *  framed by mapping this FRAME_W × FRAME_H rectangle (centred on cameraTarget) onto the canvas,
 *  so a given cameraZoom / cameraTarget frames the wave the SAME at any canvas size or aspect
@@ -202,6 +236,12 @@ var WaveRenderer = class {
 	config;
 	waves = [];
 	backgroundTexture;
+	/** The frame behind the glass waves — allocated only once a wave asks for the glass theme. */
+	backdropTarget;
+	/** How many glass layers cover each pixel. A sheet that folds over itself is thicker there, and
+	*  thickness is the cue that reads as VOLUME rather than as a tinted film — but glass draws
+	*  opaque, so the nearest layer wins and the fold behind it is invisible without counting. */
+	layerTarget;
 	backgroundSig = "";
 	backgroundImage;
 	backgroundImageUrl = "";
@@ -244,7 +284,12 @@ var WaveRenderer = class {
 	running = false;
 	started = false;
 	visible = true;
-	pageVisible = true;
+	/** Read from the document, NOT assumed: the shell builds the renderer whenever the engine chunk
+	*  lands, which can be after the reader has left the tab. Assumed visible, that renderer marked
+	*  itself running with no frame to run on, and the `visibilitychange` that brought the reader back
+	*  found nothing to restart — so the delta baseline was never reset and the first frame was handed
+	*  the whole absence at once (see MAX_FRAME_SECONDS for the same stall without the event). */
+	pageVisible = document.visibilityState === "visible";
 	reducedMotion = false;
 	/** Intro ramp: eases animation time 0→1 over ~1s on load (when config.introRamp). */
 	introTimeRamp = 0;
@@ -422,6 +467,28 @@ var WaveRenderer = class {
 			uCreaseSoftness: { value: 1 },
 			uEdgeFade: { value: .06 },
 			uEdgeFeather: { value: .1 },
+			uBackdrop: { value: null },
+			uGlassStrength: { value: 90 },
+			uGlassChroma: { value: .7 },
+			uGlassFrost: { value: .08 },
+			uGlassSpec: { value: 1.2 },
+			uGlassVibrancy: { value: .05 },
+			uGlassTint: { value: .12 },
+			uGlassRimPower: { value: 1.2 },
+			uGlassRipple: { value: 0 },
+			uGlassRippleScale: { value: .012 },
+			uGlassFlow: { value: .9 },
+			uGlassPath: { value: .45 },
+			uGlassDensity: { value: 1.2 },
+			uGlassRim: { value: .5 },
+			uGlassIrid: { value: 0 },
+			uGlassFilmNm: { value: 380 },
+			uGlassIor: { value: 1.45 },
+			uLayers: { value: null },
+			uGlassLayerGain: { value: .6 },
+			uGlassFusion: { value: 0 },
+			uGlassCaustic: { value: .4 },
+			uViewAxis: { value: new THREE.Vector3(0, 0, 1) },
 			uOpacity: { value: 1 },
 			uSquared: { value: 1 },
 			uResolution: { value: this.renderer.getDrawingBufferSize(new THREE.Vector2()) },
@@ -437,19 +504,32 @@ var WaveRenderer = class {
 			uLineAmount: { value: 425 },
 			uLineThickness: { value: 1 },
 			uLineDerivativePower: { value: .95 },
-			uMaxWidth: { value: 1232 },
+			uLineDepthFade: { value: 1 },
+			uLineSharpness: { value: 0 },
+			uLineGapOpacity: { value: 1 },
+			uLineLight: { value: 0 },
 			uClearColor: { value: new THREE.Vector3(1, 1, 1) },
 			uHelixTurns: { value: 0 },
 			uHelixRadius: { value: 0 },
 			uHelixRoll: { value: 0 },
 			uHelixPhase: { value: 0 },
+			uPathTex: { value: null },
 			uRadialAmount: { value: 0 },
 			uRadialArc: { value: 160 },
 			uRadialSpread: { value: 1 },
 			uRadialRadius: { value: 40 },
 			uRadialCenter: { value: 0 },
+			uRadialCone: { value: 0 },
+			uRadialSwirl: { value: 0 },
 			uRungAmount: { value: 0 },
 			uRungThickness: { value: 1 },
+			uDissolveAmount: { value: 0 },
+			uDissolveBand: { value: .35 },
+			uDissolveScale: { value: 90 },
+			uDissolveBlocky: { value: .6 },
+			uDissolveAxis: { value: 0 },
+			uDissolveReverse: { value: 0 },
+			uDissolveDust: { value: 1 },
 			uPointer: { value: new THREE.Vector2(0, 0) },
 			uPointerActive: { value: 0 },
 			uPointerRadius: { value: .6 },
@@ -468,6 +548,30 @@ var WaveRenderer = class {
 			uRippleAmp: { value: rippleAmp }
 		};
 	}
+	/** Reconcile a wave's baked path LUT with its config. The texture is rewritten in place when the
+	*  points change — which is what makes dragging a control point cheap, since the alternative is
+	*  rebuilding 80k vertices per frame — and disposed when a wave loses its path. */
+	syncPathTexture(wave, sc) {
+		const pts = sc.path;
+		if (!pts || pts.length < 2) {
+			if (wave.pathTexture) {
+				wave.pathTexture.dispose();
+				wave.pathTexture = void 0;
+				wave.pathSig = void 0;
+			}
+			return;
+		}
+		const sig = JSON.stringify(pts);
+		if (!wave.pathTexture) {
+			wave.pathTexture = bakePathTexture(pts);
+			wave.pathSig = sig;
+		} else if (sig !== wave.pathSig) {
+			writePathTexture(wave.pathTexture.image.data, pts);
+			wave.pathTexture.needsUpdate = true;
+			wave.pathSig = sig;
+		}
+		wave.material.uniforms.uPathTex.value = wave.pathTexture;
+	}
 	/** Vertex-shader #defines for a wave: TWIST_MOTION (per-wave animated twist wobble) and
 	*  LOOP_MOTION (scene-level seamless loop). Both select #ifdef-gated code paths; an empty
 	*  object compiles the default (linear-time) program. */
@@ -481,8 +585,15 @@ var WaveRenderer = class {
 		if ((sc?.edgeFeather ?? .1) !== .1) defines.EDGE_FEATHER = "";
 		const bindsHelix = sc?.interaction?.bindings?.some((b) => b.target.startsWith("helix")) ?? false;
 		if ((sc?.helixRadius ?? 0) !== 0 || (sc?.helixRoll ?? 0) !== 0 || bindsHelix) defines.HELIX = "";
+		if (sc?.path && sc.path.length >= 2) defines.PATH = "";
+		if (sc?.theme === "glass") defines.VERTEX_NORMAL = "";
 		if ((sc?.radialAmount ?? 0) !== 0) defines.RADIAL = "";
 		if (sc?.theme === "wireframe" && (sc.rungAmount ?? 0) > 0) defines.RUNGS = "";
+		if (sc?.theme === "wireframe" && (sc.lineSharpness ?? 0) > 0) defines.LINE_SHARP = "";
+		if (sc?.theme === "wireframe" && gapAlpha(sc.lineGapColor) < 1) defines.LINE_CLEAR_GAPS = "";
+		if (sc?.theme === "wireframe" && (sc.lineLight ?? 0) > 0) defines.LINE_LIGHT = "";
+		const bindsDissolve = sc?.interaction?.bindings?.some((b) => b.target === "dissolveAmount") ?? false;
+		if (sc?.dissolve && ((sc.dissolve.amount ?? 0) > 0 || bindsDissolve)) defines.DISSOLVE = "";
 		if (sc && wavePointerFxActive(this.config, sc)) {
 			defines.POINTER_FX = "";
 			if (waveRipplesActive(this.config, sc)) defines.POINTER_RIPPLES = "";
@@ -519,14 +630,51 @@ var WaveRenderer = class {
 			uniforms: this.makeUniforms(),
 			defines: this.waveDefines(sc),
 			vertexShader,
-			fragmentShader: sc?.theme === "wireframe" ? lineFragmentShader : fragmentShader,
-			transparent: true,
+			fragmentShader: fragmentFor(sc),
+			transparent: sc?.theme !== "glass",
 			depthTest: true,
 			depthWrite: true,
 			side: THREE.DoubleSide
 		});
 	}
 	/**
+	* The glass LAYER-COUNT companion for one wave: the same vertex program on the same uniforms
+	* object (shared by reference, so every per-frame write reaches it), with a fragment that only
+	* marks coverage. Drawn additively with depth off, so every fold over a pixel adds up.
+	*
+	* A stock override material could not stand in for this: its vertex stage knows nothing of the
+	* deformation and it culls back faces, so the count came out for the rest-pose plane — measured
+	* at a tenth of the real silhouette on the Liquid Glass preset. The WebGPU subclass builds the
+	* node twin from the same flags.
+	*/
+	createLayerMaterial(sc, material) {
+		const main = material;
+		const defines = { ...main.defines ?? this.waveDefines(sc) };
+		delete defines.VERTEX_NORMAL;
+		return new THREE.ShaderMaterial({
+			uniforms: main.uniforms,
+			defines,
+			vertexShader,
+			fragmentShader: glassLayerFragmentShader,
+			transparent: true,
+			blending: THREE.AdditiveBlending,
+			depthTest: false,
+			depthWrite: false,
+			side: THREE.DoubleSide
+		});
+	}
+	/** What the layer companion was built against; when this changes, it is rebuilt. */
+	layerVariantKey(material) {
+		const defines = material.defines ?? {};
+		return Object.keys(defines).sort().join(",");
+	}
+	dropLayerMaterial(wave) {
+		if (!wave.layerMaterial) return;
+		wave.layerMaterial.dispose();
+		wave.layerMaterial = void 0;
+		wave.layerKey = void 0;
+	}
+	/**
 	* Re-select this wave's shader variant when its config changes shape (theme, twist motion, helix,
 	* …). Returns true if the material needs recompiling. The GLSL backend swaps `defines` and the
 	* fragment source; the WebGPU subclass rebuilds the node graph, since a TSL variant is a
@@ -541,11 +689,12 @@ var WaveRenderer = class {
 			material.defines = wantDefines;
 			changed = true;
 		}
-		const wantFrag = sc.theme === "wireframe" ? lineFragmentShader : fragmentShader;
+		const wantFrag = fragmentFor(sc);
 		if (material.fragmentShader !== wantFrag) {
 			material.fragmentShader = wantFrag;
 			changed = true;
 		}
+		material.transparent = sc.theme !== "glass";
 		return changed;
 	}
 	/**
@@ -571,6 +720,7 @@ var WaveRenderer = class {
 		for (const s of this.waves) {
 			this.group.remove(s.mesh);
 			s.material.dispose();
+			s.layerMaterial?.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
 			if (s.particleField) {
@@ -593,6 +743,7 @@ var WaveRenderer = class {
 			if (!s) break;
 			this.group.remove(s.mesh);
 			s.material.dispose();
+			s.layerMaterial?.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
 			if (s.particleField) {
@@ -663,10 +814,15 @@ var WaveRenderer = class {
 			u.uLineAmount.value = sc.lineAmount ?? 425;
 			u.uLineThickness.value = sc.lineThickness ?? 1;
 			u.uLineDerivativePower.value = sc.lineDerivativePower ?? .95;
+			u.uLineDepthFade.value = sc.lineDepthFade ?? 1;
+			u.uLineSharpness.value = sc.lineSharpness ?? 0;
+			u.uLineGapOpacity.value = gapAlpha(sc.lineGapColor);
+			u.uLineLight.value = sc.lineLight ?? 0;
+			const wantDepthWrite = !(sc.theme === "wireframe" && gapAlpha(sc.lineGapColor) < 1);
+			if (wave.material.depthWrite !== wantDepthWrite) wave.material.depthWrite = wantDepthWrite;
 			u.uRungAmount.value = sc.rungAmount ?? 0;
 			u.uRungThickness.value = sc.rungThickness ?? 1;
-			u.uMaxWidth.value = sc.maxWidth ?? 1232;
-			hexToLinearVec3(this.config.background, u.uClearColor.value);
+			hexToLinearVec3(gapColorHex(sc.lineGapColor) ?? this.config.background, u.uClearColor.value);
 			u.uFiberCount.value = sc.fiberCount;
 			u.uFiberStrength.value = sc.fiberStrength;
 			u.uTexture.value = sc.texture;
@@ -680,6 +836,32 @@ var WaveRenderer = class {
 			hexToLinearVec3(sc.depthTintColor ?? "#0a2540", u.uDepthTintColor.value);
 			u.uEdgeFade.value = sc.edgeFade;
 			u.uEdgeFeather.value = sc.edgeFeather ?? .1;
+			if (sc.theme === "glass") {
+				hexToLinearVec3(this.config.background, u.uClearColor.value);
+				u.uGlassStrength.value = sc.glassStrength ?? 90;
+				u.uGlassChroma.value = sc.glassChroma ?? .7;
+				u.uGlassFrost.value = sc.glassFrost ?? .08;
+				u.uGlassSpec.value = sc.glassSpec ?? 1.2;
+				u.uGlassVibrancy.value = sc.glassVibrancy ?? .05;
+				u.uGlassTint.value = sc.glassTint ?? .12;
+				u.uGlassRimPower.value = sc.glassRimPower ?? 1.2;
+				u.uGlassRipple.value = sc.glassRipple ?? 0;
+				u.uGlassRippleScale.value = sc.glassRippleScale ?? .012;
+				{
+					const flow = sc.glassFlow ?? .9;
+					const loop = this.config.loopSeconds ?? 0;
+					u.uGlassFlow.value = loop > 0 && flow !== 0 ? Math.max(1, Math.round(Math.abs(flow) * loop / (Math.PI * 2))) * (Math.PI * 2) / loop / (flow < 0 ? -1 : 1) : flow;
+				}
+				u.uGlassPath.value = sc.glassPath ?? .45;
+				u.uGlassDensity.value = sc.glassDensity ?? 1.2;
+				u.uGlassRim.value = sc.glassRim ?? .5;
+				u.uGlassIrid.value = sc.glassIrid ?? 0;
+				u.uGlassFilmNm.value = sc.glassFilmNm ?? 380;
+				u.uGlassIor.value = sc.glassIor ?? 1.45;
+				u.uGlassLayerGain.value = sc.glassLayerGain ?? .6;
+				u.uGlassFusion.value = sc.glassFusion ?? 0;
+				u.uGlassCaustic.value = sc.glassCaustic ?? .4;
+			}
 			const lights = this.config.lights ?? [];
 			u.uAmbient.value = this.config.ambient ?? .45;
 			u.uNumLights.value = Math.min(lights.length, 8);
@@ -724,12 +906,23 @@ var WaveRenderer = class {
 			u.uHelixTurns.value = sc.helixTurns ?? 0;
 			u.uHelixRadius.value = sc.helixRadius ?? 0;
 			u.uHelixRoll.value = sc.helixRoll ?? 0;
+			this.syncPathTexture(wave, sc);
 			u.uHelixPhase.value = sc.helixPhase ?? 0;
 			u.uRadialAmount.value = sc.radialAmount ?? 0;
 			u.uRadialArc.value = sc.radialArc ?? 160;
 			u.uRadialSpread.value = sc.radialSpread ?? 1;
 			u.uRadialRadius.value = sc.radialRadius ?? 40;
 			u.uRadialCenter.value = sc.radialCenter ?? 0;
+			u.uRadialCone.value = sc.radialCone ?? 0;
+			u.uRadialSwirl.value = sc.radialSwirl ?? 0;
+			const dis = sc.dissolve;
+			u.uDissolveAmount.value = dis?.amount ?? 0;
+			u.uDissolveBand.value = dis?.band ?? .35;
+			u.uDissolveScale.value = dis?.scale ?? 90;
+			u.uDissolveBlocky.value = dis?.blocky ?? .6;
+			u.uDissolveAxis.value = DISSOLVE_AXIS_INDEX[dis?.axis ?? "length"] ?? 0;
+			u.uDissolveReverse.value = dis?.reverse ? 1 : 0;
+			u.uDissolveDust.value = dis?.dust ?? 1;
 			wave.mesh.scale.set(sc.scale.x, sc.scale.y, sc.scale.z);
 			wave.mesh.rotation.set(THREE.MathUtils.degToRad(sc.rotation.x), THREE.MathUtils.degToRad(sc.rotation.y), THREE.MathUtils.degToRad(sc.rotation.z));
 			wave.mesh.position.set(sc.position.x, sc.position.y, sc.position.z);
@@ -1378,7 +1571,7 @@ var WaveRenderer = class {
 	loop = () => {
 		if (!this.running) return;
 		this.timer.update();
-		const dt = this.timer.getDelta();
+		const dt = Math.min(this.timer.getDelta(), MAX_FRAME_SECONDS);
 		this.time += dt;
 		this.interaction?.update(dt);
 		if (this.introTimeRamp < 1) this.introTimeRamp = Math.min(1, this.introTimeRamp + .016);
@@ -1406,8 +1599,144 @@ var WaveRenderer = class {
 	}
 	/** Draw the composed frame. WebGL runs the EffectComposer; WebGPU runs a node post chain. */
 	renderComposed() {
+		this.renderGlassPasses();
 		this.composer.render();
 	}
+	/** Capture what sits BEHIND the glass waves, so they have something to bend.
+	*
+	*  Glass is drawn opaque and fakes its see-through by sampling this texture, which is why
+	*  overlapping sheets need no sorting. The pass is skipped entirely when no wave asks for it, so
+	*  a scene without glass renders exactly as before.
+	*
+	*  The texture MUST be unbound while we render into it: binding a target as a texture while it is
+	*  the render target is a framebuffer feedback loop, and the frame is undefined. */
+	/** The world axis from a surface toward the camera. Constant under an orthographic projection,
+	*  which is exactly why it is a uniform rather than something the shader derives per fragment. */
+	pushViewAxis() {
+		const fwd = this.camera.getWorldDirection(this.viewAxisTmp).multiplyScalar(-1);
+		for (const w of this.waves) w.material.uniforms.uViewAxis.value.copy(fwd);
+	}
+	viewAxisTmp = new THREE.Vector3();
+	empty;
+	backdropClear = new THREE.Color();
+	prevClear = new THREE.Color();
+	depthTmp = new THREE.Vector3();
+	sizeTmp = new THREE.Vector2();
+	/** Pin a capture's sampling so both backends read it the same way. Left to their defaults the
+	*  two disagree about filtering and edge behaviour, and a glass sheet samples FAR from the
+	*  fragment — one offset per channel — so the disagreement shows up as a red/blue bias with green
+	*  untouched, which looks like a dispersion bug and is not one. */
+	pinSampling(t) {
+		t.texture.minFilter = THREE.LinearFilter;
+		t.texture.magFilter = THREE.LinearFilter;
+		t.texture.wrapS = THREE.ClampToEdgeWrapping;
+		t.texture.wrapT = THREE.ClampToEdgeWrapping;
+		t.texture.generateMipmaps = false;
+		return t;
+	}
+	/** A 1x1 transparent texture, used wherever a sampler must be BOUND but must contribute nothing. */
+	emptyTexture() {
+		if (!this.empty) {
+			this.empty = new THREE.DataTexture(new Uint8Array([
+				0,
+				0,
+				0,
+				0
+			]), 1, 1);
+			this.empty.needsUpdate = true;
+		}
+		return this.empty;
+	}
+	renderGlassPasses() {
+		this.pushViewAxis();
+		const glassIdx = [];
+		for (let i = 0; i < this.waves.length; i++) if ((this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1])?.theme === "glass") glassIdx.push(i);
+		if (glassIdx.length === 0) {
+			if (this.backdropTarget) for (const w of this.waves) w.material.uniforms.uBackdrop.value = null;
+			for (const w of this.waves) this.dropLayerMaterial(w);
+			return;
+		}
+		this.scene.updateMatrixWorld();
+		const axis = this.viewAxisTmp;
+		const depthOf = (i) => this.waves[i].mesh.getWorldPosition(this.depthTmp).dot(axis);
+		const glassDepth = glassIdx.map(depthOf);
+		const excluded = [];
+		for (let i = 0; i < this.waves.length; i++) {
+			const d = depthOf(i);
+			const inFront = glassIdx.some((g, k) => {
+				const dd = d - glassDepth[k];
+				return dd > .001 || Math.abs(dd) <= .001 && i > g;
+			});
+			if (glassIdx.includes(i) || inFront) excluded.push(this.waves[i].mesh);
+		}
+		const size = this.renderer.getDrawingBufferSize(this.sizeTmp);
+		if (!this.backdropTarget) this.backdropTarget = this.pinSampling(new THREE.WebGLRenderTarget(size.x, size.y, {
+			depthBuffer: true,
+			stencilBuffer: false
+		}));
+		else if (this.backdropTarget.width !== size.x || this.backdropTarget.height !== size.y) this.backdropTarget.setSize(size.x, size.y);
+		const prevTarget = this.renderer.getRenderTarget();
+		const prevClearAlpha = this.renderer.getClearAlpha();
+		this.renderer.getClearColor(this.prevClear);
+		const prevBg = this.scene.background;
+		const restore = () => {
+			this.renderer.setRenderTarget(prevTarget);
+			this.renderer.setClearColor(this.prevClear, prevClearAlpha);
+			this.scene.background = prevBg;
+		};
+		for (const w of this.waves) w.material.uniforms.uBackdrop.value = this.emptyTexture();
+		for (const m of excluded) m.visible = false;
+		this.renderer.setRenderTarget(this.backdropTarget);
+		this.backdropClear.set(this.config.background || "#ffffff");
+		this.renderer.setClearColor(this.backdropClear, 1);
+		this.renderer.clear(true, true, false);
+		this.renderer.render(this.scene, this.camera);
+		for (const m of excluded) m.visible = true;
+		for (const w of this.waves) w.material.uniforms.uBackdrop.value = this.backdropTarget.texture;
+		const hidden = [];
+		const hide = (o) => {
+			if (o && o.visible) {
+				o.visible = false;
+				hidden.push(o);
+			}
+		};
+		for (let i = 0; i < this.waves.length; i++) {
+			if (!glassIdx.includes(i)) hide(this.waves[i].mesh);
+			hide(this.waves[i].particleField?.object);
+		}
+		this.scene.background = null;
+		if (!this.layerTarget) this.layerTarget = this.pinSampling(new THREE.WebGLRenderTarget(size.x, size.y, {
+			depthBuffer: false,
+			stencilBuffer: false
+		}));
+		else if (this.layerTarget.width !== size.x || this.layerTarget.height !== size.y) this.layerTarget.setSize(size.x, size.y);
+		for (const w of this.waves) w.material.uniforms.uLayers.value = this.emptyTexture();
+		const swapped = [];
+		for (let i = 0; i < this.waves.length; i++) {
+			const w = this.waves[i];
+			if (!glassIdx.includes(i)) {
+				this.dropLayerMaterial(w);
+				continue;
+			}
+			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
+			const key = this.layerVariantKey(w.material);
+			if (w.layerMaterial && w.layerKey !== key) this.dropLayerMaterial(w);
+			if (!w.layerMaterial) {
+				w.layerMaterial = this.createLayerMaterial(sc, w.material);
+				w.layerKey = key;
+			}
+			w.mesh.material = w.layerMaterial;
+			swapped.push(w);
+		}
+		this.renderer.setRenderTarget(this.layerTarget);
+		this.renderer.setClearColor(0, 0);
+		this.renderer.clear(true, false, false);
+		this.renderer.render(this.scene, this.camera);
+		for (const w of swapped) w.mesh.material = w.material;
+		for (const w of this.waves) w.material.uniforms.uLayers.value = this.layerTarget.texture;
+		for (const o of hidden) o.visible = true;
+		restore();
+	}
 	/** Resize the post chain's render targets. */
 	resizePost(w, h, dpr) {
 		this.composer.setPixelRatio(dpr);
@@ -1416,6 +1745,12 @@ var WaveRenderer = class {
 	/** Release the post chain's GPU resources. */
 	disposePost() {
 		this.composer.dispose();
+		this.backdropTarget?.dispose();
+		this.backdropTarget = void 0;
+		this.layerTarget?.dispose();
+		this.layerTarget = void 0;
+		this.empty?.dispose();
+		this.empty = void 0;
 	}
 	/** Render exactly one frame at the current time. */
 	renderOnce() {
@@ -1501,8 +1836,10 @@ var WaveRenderer = class {
 			"HELIX",
 			"TWIST_MOTION",
 			"RADIAL",
+			"PATH",
 			"POINTER_FX",
-			"POINTER_RIPPLES"
+			"POINTER_RIPPLES",
+			"DISSOLVE"
 		]) if (k in all) out[k] = "";
 		return out;
 	}
@@ -1892,9 +2229,11 @@ var WaveRenderer = class {
 		this.backgroundTexture?.dispose();
 		for (const s of this.waves) {
 			s.material.dispose();
+			s.layerMaterial?.dispose();
 			s.geometry.dispose();
 			s.palette.dispose();
 			s.particleField?.dispose();
+			s.pathTexture?.dispose();
 		}
 		this.bloomPass?.dispose();
 		this.ditherPass?.dispose();