@wave3d/core 0.3.0 → 0.5.0

package/dist/renderer/WaveRenderer.d.ts

@@ -1,18 +1,31 @@
-import { StudioConfig, WaveConfig } from "../config/model.js";
+import { CameraFit, StudioConfig, WaveConfig } from "../config/model.js";
 import { WaveGeometry } from "./WaveGeometry.js";
 import { InteractionController } from "./interaction.js";
 import * as THREE from "three";
 
 //#region src/renderer/WaveRenderer.d.ts
 /** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
- *  framed by COVERING this FRAME_W × FRAME_H rectangle (centred on cameraTarget) into the canvas
- *  — scaled to fill both dimensions, cropping the aspect overflow — so a given cameraZoom /
- *  cameraTarget frames the wave the SAME at any canvas size or aspect (only the cropped margin
- *  differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle; for canvases wider
- *  than that the width binds, narrower ones zoom in to fill instead of
- *  showing empty bands. This is what makes a saved preset reproduce on anyone's screen. */
+ *  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
+ *  (only the margin differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle.
+ *  This is what makes a saved preset reproduce on anyone's screen. See {@link frameZoom} for how
+ *  a canvas of a different aspect is reconciled against it. */
 declare const FRAME_W = 1333;
 declare const FRAME_H = 750;
+/**
+ * The responsive base zoom: how many device pixels one world unit occupies so the FRAME_W × FRAME_H
+ * reference lands on a `dw × dh` (device px) canvas under `fit`, then clamped so at least
+ * `minVisibleWidth` of the frame's width survives.
+ *
+ * Shared by the renderer (which applies it) and the studio (which inverts it to persist a
+ * scroll-zoom back into config.cameraZoom) — one implementation, so the two cannot drift.
+ *
+ * The clamp is a pure zoom CEILING layered on top of the fit, which is what lets both knobs
+ * coexist: it can only widen the view, never tighten it, so it is inert for `contain`/`width`
+ * (already at or below that zoom) and bites exactly where the crop hurts — `cover`/`height` on a
+ * canvas narrower than 16:9. `minVisibleWidth` 0 disables it and restores pure-fit behaviour.
+ */
+declare function frameZoom(dw: number, dh: number, fit: CameraFit, minVisibleWidth?: number): number;
 interface WaveRendererOptions {
   /** Honor prefers-reduced-motion by freezing animation. Default true. */
   respectReducedMotion?: boolean;
@@ -71,6 +84,12 @@ declare class WaveRenderer {
   private readonly postPass;
   /** Optional bloom pass — created lazily when bloomStrength first goes >0, removed at 0. */
   private bloomPass?;
+  private ditherPass?;
+  private innerLightPass?;
+  private halftonePass?;
+  private heatmapPass?;
+  private paperTexturePass?;
+  private halftoneCmykPass?;
   protected readonly container: HTMLElement;
   private readonly respectReducedMotion;
   private readonly skipIntroRamp;
@@ -114,6 +133,11 @@ declare class WaveRenderer {
   private readonly resizeObserver;
   private readonly intersectionObserver;
   private readonly motionQuery;
+  /** Re-armed at the live devicePixelRatio on every change — see watchDpr(). */
+  private dprQuery?;
+  /** Pending coalesced resize (0 = none), and the metrics the last resize() actually applied. */
+  private resizeRaf;
+  private lastResize?;
   protected capturing: boolean;
   /** Fixed backing-buffer dimensions used by the studio's visible export frame. Embeds leave
    *  this unset and continue to resize responsively with their container and device DPR. */
@@ -172,7 +196,54 @@ declare class WaveRenderer {
    *  created lazily the first time bloom is enabled and disposed when turned back off. It sits
    *  right after the scene RenderPass so it blooms the wave before the grain/blur pass. */
   private applyBloom;
+  /** Insert / tune / remove the dithering pass — a self-contained "layered" post shader (an ordered
+   *  Bayer dither, in the spirit of paper-design/shaders). Like bloom, dither 0 removes the pass
+   *  entirely so cost and pixels match dither-off, and it's created lazily on first enable. It is
+   *  appended AFTER OutputPass so it runs last and quantizes display-space colour (tone-mapped +
+   *  sRGB) — dithering the linear composer buffer would crush the steps in the shadows. */
+  private applyDither;
+  /** Insert / tune / remove the innerLight pass — volumetric light streaks scattered from the bright
+   *  wave toward a light point (innerLightX/Y in UV). Scene zone (index 1) so it scatters the raw wave
+   *  like bloom. innerLight 0 removes the pass entirely; created lazily on first enable. */
+  private applyInnerLight;
+  /** Insert / tune / remove the halftone pass — a rotated dot screen (dot size scales with local
+   *  brightness) over the finished image. halftone 0 removes the pass; created lazily on enable. */
+  private applyHalftone;
+  /** Heatmap: recolour the final image by luminance → thermal palette. Finish zone. */
+  private applyHeatmap;
+  /** Paper texture: fibrous substrate shading multiplied over the image. Finish zone. */
+  private applyPaperTexture;
+  /** CMYK halftone: four rotated dot screens (cyan/magenta/yellow/black). Finish zone. */
+  private applyHalftoneCmyk;
+  /** Coalesce observer-driven resizes to one per frame, and drop any that don't move a device pixel.
+   *
+   *  resize() is expensive — composer.setSize reallocates every pass's render target, and
+   *  applyBackground() rebuilds a container-sized canvas + texture for gradient/image backgrounds.
+   *  The old 1:1 `observe → resize()` paid that for observations that changed nothing: the observer
+   *  reports fractional content-box sizes, so sub-pixel layout shifts (and anything that rounds to
+   *  the same backing buffer) triggered a full reallocation, as did every observation while an
+   *  export frame is pinned and the container is not what drives the buffer at all.
+   *
+   *  Genuine per-frame changes — a mobile URL bar collapsing animates the container height — still
+   *  resize every frame. That work is necessary; the canvas would otherwise stretch. What is
+   *  removed is the redundant work, not the real work.
+   *
+   *  Only this path is throttled. `resize()` itself stays synchronous and unconditional — context
+   *  restore and setOutputSize must re-apply immediately, and on a fresh GPU context the metrics
+   *  are unchanged but the resources are not. */
   private onResize;
+  /** Re-arm the DPR watch and re-render at the new device-pixel ratio.
+   *
+   *  ResizeObserver watches the CSS box only, so browser zoom or dragging the window to a monitor
+   *  with a different DPR changes devicePixelRatio without changing the box — the backing buffer
+   *  stayed at the old resolution and the wave went soft until something else forced a resize. */
+  private onDprChange;
+  /** A `(resolution: Xdppx)` query only fires when we LEAVE the current ratio, so it is re-armed at
+   *  the new one on every change. */
+  private watchDpr;
+  /** The backing-buffer metrics resize() will apply: the export frame when one is pinned, else the
+   *  container box at the (clamped) device-pixel ratio. */
+  private viewportMetrics;
   private onContextLost;
   private onContextRestored;
   resize(): void;
@@ -228,11 +299,13 @@ declare class WaveRenderer {
   protected onAfterRenderFrame(): void;
   /** Hook ④: called at the end of resize(), before the trailing renderOnce(). */
   protected onAfterResize(): void;
-  /** Responsive ortho zoom: COVER the FRAME_W × FRAME_H reference frame onto the canvas so the
-   *  wave frames the same at any size/aspect/dpr (only the cropped margin differs), times the
-   *  user's cameraZoom. `max(...)` = cover (fill both axes, crop overflow); `min(...)` would be
-   *  contain (fit with letterbox bands). Cover keeps the wave filling the frame on every screen. */
+  /** Responsive ortho zoom: map the FRAME_W × FRAME_H reference frame onto the canvas (per
+   *  config.cameraFit / cameraMinVisibleWidth — see {@link frameZoom}) so the wave frames the same
+   *  at any size/aspect/dpr, times the user's cameraZoom. */
   protected applyZoom(): void;
+  /** The responsive base zoom for the current config's framing policy, before the cameraZoom
+   *  multiplier. Subclasses invert this to recover cameraZoom from a live camera. */
+  protected baseFrameZoom(dw: number, dh: number): number;
   /** Fit the orthographic near/far planes to the scene before every render, so no part of a wave
    *  is ever clipped as the camera orbits / dollies / pans (or when waves are added or scaled).
    *
@@ -262,5 +335,5 @@ declare class WaveRenderer {
   dispose(): void;
 }
 //#endregion
-export { FRAME_H, FRAME_W, WaveRenderer, WaveRendererOptions, hexToLinearVec3 };
+export { FRAME_H, FRAME_W, WaveRenderer, WaveRendererOptions, frameZoom, hexToLinearVec3 };
 //# sourceMappingURL=WaveRenderer.d.ts.map

package/dist/renderer/WaveRenderer.js

@@ -1,5 +1,5 @@
 import { ensureStudioConfig } from "../config/model.js";
-import { fragmentShader, lineFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
+import { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
 import { WaveGeometry } from "./WaveGeometry.js";
 import { InteractionController, SCENE_APPLIERS, WAVE_APPLIERS, anyPointerFxActive, interactionActive, wavePointerFxActive, waveRipplesActive } from "./interaction.js";
 import { PALETTE_MAPS, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, loadPaletteImage, paletteMapCanvas, paletteSignature } from "./palette.js";
@@ -13,15 +13,46 @@ import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"
 //#region src/renderer/WaveRenderer.ts
 const BASE_SEGMENTS = 220;
 /** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
-*  framed by COVERING this FRAME_W × FRAME_H rectangle (centred on cameraTarget) into the canvas
-*  — scaled to fill both dimensions, cropping the aspect overflow — so a given cameraZoom /
-*  cameraTarget frames the wave the SAME at any canvas size or aspect (only the cropped margin
-*  differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle; for canvases wider
-*  than that the width binds, narrower ones zoom in to fill instead of
-*  showing empty bands. This is what makes a saved preset reproduce on anyone's screen. */
+*  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
+*  (only the margin differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle.
+*  This is what makes a saved preset reproduce on anyone's screen. See {@link frameZoom} for how
+*  a canvas of a different aspect is reconciled against it. */
 const FRAME_W = 1333;
 const FRAME_H = 750;
 /**
+* The responsive base zoom: how many device pixels one world unit occupies so the FRAME_W × FRAME_H
+* reference lands on a `dw × dh` (device px) canvas under `fit`, then clamped so at least
+* `minVisibleWidth` of the frame's width survives.
+*
+* Shared by the renderer (which applies it) and the studio (which inverts it to persist a
+* scroll-zoom back into config.cameraZoom) — one implementation, so the two cannot drift.
+*
+* The clamp is a pure zoom CEILING layered on top of the fit, which is what lets both knobs
+* coexist: it can only widen the view, never tighten it, so it is inert for `contain`/`width`
+* (already at or below that zoom) and bites exactly where the crop hurts — `cover`/`height` on a
+* canvas narrower than 16:9. `minVisibleWidth` 0 disables it and restores pure-fit behaviour.
+*/
+function frameZoom(dw, dh, fit, minVisibleWidth = 0) {
+	const byWidth = dw / FRAME_W;
+	const byHeight = dh / 750;
+	let zoom;
+	switch (fit) {
+		case "contain":
+			zoom = Math.min(byWidth, byHeight);
+			break;
+		case "width":
+			zoom = byWidth;
+			break;
+		case "height":
+			zoom = byHeight;
+			break;
+		default: zoom = Math.max(byWidth, byHeight);
+	}
+	if (minVisibleWidth > 0) zoom = Math.min(zoom, dw / (FRAME_W * minVisibleWidth));
+	return zoom;
+}
+/**
 * Per-wave 2D palette texture (+ optional looping video). One instance per wave, so each
 * wave carries its own palette. Guarded by a signature so it only rebuilds when that wave's
 * palette actually changes (not every refresh).
@@ -149,6 +180,12 @@ var WaveRenderer = class {
 	postPass;
 	/** Optional bloom pass — created lazily when bloomStrength first goes >0, removed at 0. */
 	bloomPass;
+	ditherPass;
+	innerLightPass;
+	halftonePass;
+	heatmapPass;
+	paperTexturePass;
+	halftoneCmykPass;
 	container;
 	respectReducedMotion;
 	skipIntroRamp;
@@ -195,6 +232,11 @@ var WaveRenderer = class {
 	resizeObserver;
 	intersectionObserver;
 	motionQuery;
+	/** Re-armed at the live devicePixelRatio on every change — see watchDpr(). */
+	dprQuery;
+	/** Pending coalesced resize (0 = none), and the metrics the last resize() actually applied. */
+	resizeRaf = 0;
+	lastResize;
 	capturing = false;
 	/** Fixed backing-buffer dimensions used by the studio's visible export frame. Embeds leave
 	*  this unset and continue to resize responsively with their container and device DPR. */
@@ -250,6 +292,7 @@ var WaveRenderer = class {
 		this.intersectionObserver.observe(container);
 		this.resizeObserver = new ResizeObserver(this.onResize);
 		this.resizeObserver.observe(container);
+		this.watchDpr();
 		this.applyBackground();
 		this.buildWaves();
 		this.resize();
@@ -372,6 +415,7 @@ var WaveRenderer = class {
 			uPointerPush: { value: 0 },
 			uPointerWake: { value: 0 },
 			uPointerVel: { value: new THREE.Vector2(0, 0) },
+			uShapeFlow: { value: 0 },
 			uPointerThin: { value: 0 },
 			uPointerHue: { value: 0 },
 			uPointerLighten: { value: 0 },
@@ -605,6 +649,7 @@ var WaveRenderer = class {
 			u.uOpacity.value = sc.opacity;
 		});
 		const sharedRadius = (this.config.interaction?.radius ?? .3) * 2;
+		const sharedFlow = this.config.interaction?.ribbonFlow ?? .8;
 		this.waves.forEach((wave, i) => {
 			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
 			if (!wavePointerFxActive(this.config, sc)) return;
@@ -618,6 +663,7 @@ var WaveRenderer = class {
 			u.uPointerHue.value = h?.hueShift ?? 0;
 			u.uPointerLighten.value = h?.lighten ?? 0;
 			u.uPointerRipple.value = sc.interaction?.press?.ripple ?? 0;
+			u.uShapeFlow.value = sharedFlow;
 		});
 		this.updatePaletteTextures();
 		this.syncVideoPlayback();
@@ -890,6 +936,12 @@ var WaveRenderer = class {
 		u.uGrainAmount.value = this.config.grain;
 		u.uBlurSamples.value = Math.round(this.config.blurSamples ?? 6);
 		this.applyBloom();
+		this.applyInnerLight();
+		this.applyHalftone();
+		this.applyHeatmap();
+		this.applyHalftoneCmyk();
+		this.applyPaperTexture();
+		this.applyDither();
 	}
 	/** Insert / tune / remove the bloom pass. strength 0 removes it from the composer entirely, so
 	*  cost and pixels are identical to bloom-off; the pass (and its mip-chain render targets) is
@@ -912,9 +964,223 @@ var WaveRenderer = class {
 			this.bloomPass = void 0;
 		}
 	}
+	/** Insert / tune / remove the dithering pass — a self-contained "layered" post shader (an ordered
+	*  Bayer dither, in the spirit of paper-design/shaders). Like bloom, dither 0 removes the pass
+	*  entirely so cost and pixels match dither-off, and it's created lazily on first enable. It is
+	*  appended AFTER OutputPass so it runs last and quantizes display-space colour (tone-mapped +
+	*  sRGB) — dithering the linear composer buffer would crush the steps in the shadows. */
+	applyDither() {
+		const strength = this.config.dither ?? 0;
+		if (strength > 0) {
+			if (!this.ditherPass) {
+				this.ditherPass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uResolution: { value: this.renderer.getDrawingBufferSize(new THREE.Vector2()) },
+						uDitherStrength: { value: strength },
+						uDitherScale: { value: this.config.ditherScale ?? 2 },
+						uDitherSteps: { value: this.config.ditherSteps ?? 4 }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: ditherFragmentShader
+				});
+				this.composer.addPass(this.ditherPass);
+			}
+			const u = this.ditherPass.uniforms;
+			u.uDitherStrength.value = strength;
+			u.uDitherScale.value = Math.max(1, this.config.ditherScale ?? 2);
+			u.uDitherSteps.value = Math.max(2, Math.round(this.config.ditherSteps ?? 4));
+		} else if (this.ditherPass) {
+			this.composer.removePass(this.ditherPass);
+			this.ditherPass.dispose();
+			this.ditherPass = void 0;
+		}
+	}
+	/** Insert / tune / remove the innerLight pass — volumetric light streaks scattered from the bright
+	*  wave toward a light point (innerLightX/Y in UV). Scene zone (index 1) so it scatters the raw wave
+	*  like bloom. innerLight 0 removes the pass entirely; created lazily on first enable. */
+	applyInnerLight() {
+		const strength = this.config.innerLight ?? 0;
+		if (strength > 0) {
+			const cx = this.config.innerLightX ?? .5;
+			const cy = this.config.innerLightY ?? .15;
+			if (!this.innerLightPass) {
+				this.innerLightPass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uInnerLight: { value: strength },
+						uInnerLightDensity: { value: this.config.innerLightDensity ?? .5 },
+						uInnerLightDecay: { value: this.config.innerLightDecay ?? .95 },
+						uInnerLightCenter: { value: new THREE.Vector2(cx, cy) }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: innerLightFragmentShader
+				});
+				this.composer.insertPass(this.innerLightPass, 1);
+			}
+			const u = this.innerLightPass.uniforms;
+			u.uInnerLight.value = strength;
+			u.uInnerLightDensity.value = this.config.innerLightDensity ?? .5;
+			u.uInnerLightDecay.value = this.config.innerLightDecay ?? .95;
+			u.uInnerLightCenter.value.set(cx, cy);
+		} else if (this.innerLightPass) {
+			this.composer.removePass(this.innerLightPass);
+			this.innerLightPass.dispose();
+			this.innerLightPass = void 0;
+		}
+	}
+	/** Insert / tune / remove the halftone pass — a rotated dot screen (dot size scales with local
+	*  brightness) over the finished image. halftone 0 removes the pass; created lazily on enable. */
+	applyHalftone() {
+		const strength = this.config.halftone ?? 0;
+		if (strength > 0) {
+			if (!this.halftonePass) {
+				this.halftonePass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uResolution: { value: this.renderer.getDrawingBufferSize(new THREE.Vector2()) },
+						uHalftone: { value: strength },
+						uHalftoneCell: { value: this.config.halftoneCell ?? 6 },
+						uHalftoneAngle: { value: this.config.halftoneAngle ?? .4 }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: halftoneFragmentShader
+				});
+				this.composer.addPass(this.halftonePass);
+			}
+			const u = this.halftonePass.uniforms;
+			u.uHalftone.value = strength;
+			u.uHalftoneCell.value = Math.max(2, this.config.halftoneCell ?? 6);
+			u.uHalftoneAngle.value = this.config.halftoneAngle ?? .4;
+		} else if (this.halftonePass) {
+			this.composer.removePass(this.halftonePass);
+			this.halftonePass.dispose();
+			this.halftonePass = void 0;
+		}
+	}
+	/** Heatmap: recolour the final image by luminance → thermal palette. Finish zone. */
+	applyHeatmap() {
+		const strength = this.config.heatmap ?? 0;
+		if (strength > 0) {
+			if (!this.heatmapPass) {
+				this.heatmapPass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uHeatmap: { value: strength }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: heatmapFragmentShader
+				});
+				this.composer.addPass(this.heatmapPass);
+			}
+			this.heatmapPass.uniforms.uHeatmap.value = strength;
+		} else if (this.heatmapPass) {
+			this.composer.removePass(this.heatmapPass);
+			this.heatmapPass.dispose();
+			this.heatmapPass = void 0;
+		}
+	}
+	/** Paper texture: fibrous substrate shading multiplied over the image. Finish zone. */
+	applyPaperTexture() {
+		const strength = this.config.paperTexture ?? 0;
+		if (strength > 0) {
+			if (!this.paperTexturePass) {
+				this.paperTexturePass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uPaper: { value: strength },
+						uPaperScale: { value: this.config.paperTextureScale ?? 2 }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: paperTextureFragmentShader
+				});
+				this.composer.addPass(this.paperTexturePass);
+			}
+			const u = this.paperTexturePass.uniforms;
+			u.uPaper.value = strength;
+			u.uPaperScale.value = Math.max(.5, this.config.paperTextureScale ?? 2);
+		} else if (this.paperTexturePass) {
+			this.composer.removePass(this.paperTexturePass);
+			this.paperTexturePass.dispose();
+			this.paperTexturePass = void 0;
+		}
+	}
+	/** CMYK halftone: four rotated dot screens (cyan/magenta/yellow/black). Finish zone. */
+	applyHalftoneCmyk() {
+		const strength = this.config.halftoneCmyk ?? 0;
+		if (strength > 0) {
+			if (!this.halftoneCmykPass) {
+				this.halftoneCmykPass = new ShaderPass({
+					uniforms: {
+						tDiffuse: { value: null },
+						uHalftoneCmyk: { value: strength },
+						uHalftoneCmykCell: { value: this.config.halftoneCmykCell ?? 6 }
+					},
+					vertexShader: postVertexShader,
+					fragmentShader: halftoneCmykFragmentShader
+				});
+				this.composer.addPass(this.halftoneCmykPass);
+			}
+			const u = this.halftoneCmykPass.uniforms;
+			u.uHalftoneCmyk.value = strength;
+			u.uHalftoneCmykCell.value = Math.max(2, this.config.halftoneCmykCell ?? 6);
+		} else if (this.halftoneCmykPass) {
+			this.composer.removePass(this.halftoneCmykPass);
+			this.halftoneCmykPass.dispose();
+			this.halftoneCmykPass = void 0;
+		}
+	}
+	/** Coalesce observer-driven resizes to one per frame, and drop any that don't move a device pixel.
+	*
+	*  resize() is expensive — composer.setSize reallocates every pass's render target, and
+	*  applyBackground() rebuilds a container-sized canvas + texture for gradient/image backgrounds.
+	*  The old 1:1 `observe → resize()` paid that for observations that changed nothing: the observer
+	*  reports fractional content-box sizes, so sub-pixel layout shifts (and anything that rounds to
+	*  the same backing buffer) triggered a full reallocation, as did every observation while an
+	*  export frame is pinned and the container is not what drives the buffer at all.
+	*
+	*  Genuine per-frame changes — a mobile URL bar collapsing animates the container height — still
+	*  resize every frame. That work is necessary; the canvas would otherwise stretch. What is
+	*  removed is the redundant work, not the real work.
+	*
+	*  Only this path is throttled. `resize()` itself stays synchronous and unconditional — context
+	*  restore and setOutputSize must re-apply immediately, and on a fresh GPU context the metrics
+	*  are unchanged but the resources are not. */
 	onResize = () => {
+		if (this.resizeRaf) return;
+		this.resizeRaf = requestAnimationFrame(() => {
+			this.resizeRaf = 0;
+			const next = this.viewportMetrics();
+			const last = this.lastResize;
+			if (last && next.w === last.w && next.h === last.h && next.dpr === last.dpr) return;
+			this.resize();
+		});
+	};
+	/** Re-arm the DPR watch and re-render at the new device-pixel ratio.
+	*
+	*  ResizeObserver watches the CSS box only, so browser zoom or dragging the window to a monitor
+	*  with a different DPR changes devicePixelRatio without changing the box — the backing buffer
+	*  stayed at the old resolution and the wave went soft until something else forced a resize. */
+	onDprChange = () => {
+		this.watchDpr();
 		this.resize();
 	};
+	/** A `(resolution: Xdppx)` query only fires when we LEAVE the current ratio, so it is re-armed at
+	*  the new one on every change. */
+	watchDpr() {
+		this.dprQuery?.removeEventListener("change", this.onDprChange);
+		this.dprQuery = window.matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`);
+		this.dprQuery.addEventListener("change", this.onDprChange);
+	}
+	/** The backing-buffer metrics resize() will apply: the export frame when one is pinned, else the
+	*  container box at the (clamped) device-pixel ratio. */
+	viewportMetrics() {
+		return {
+			w: this.outputSize?.width ?? Math.max(1, this.container.clientWidth),
+			h: this.outputSize?.height ?? Math.max(1, this.container.clientHeight),
+			dpr: this.outputSize ? 1 : Math.min(window.devicePixelRatio || 1, this.config.dprMax)
+		};
+	}
 	onContextLost = (e) => {
 		e.preventDefault();
 		cancelAnimationFrame(this.rafId);
@@ -930,9 +1196,12 @@ var WaveRenderer = class {
 		this.updateRunning();
 	};
 	resize() {
-		const w = this.outputSize?.width ?? Math.max(1, this.container.clientWidth);
-		const h = this.outputSize?.height ?? Math.max(1, this.container.clientHeight);
-		const dpr = this.outputSize ? 1 : Math.min(window.devicePixelRatio || 1, this.config.dprMax);
+		const { w, h, dpr } = this.viewportMetrics();
+		this.lastResize = {
+			w,
+			h,
+			dpr
+		};
 		this.renderer.setPixelRatio(dpr);
 		this.renderer.setSize(w, h, !this.outputSize);
 		if (this.outputSize) {
@@ -944,6 +1213,8 @@ var WaveRenderer = class {
 		const dw = w * dpr;
 		const dh = h * dpr;
 		this.postPass.uniforms.uResolution.value.set(dw, dh);
+		if (this.ditherPass) this.ditherPass.uniforms.uResolution.value.set(dw, dh);
+		if (this.halftonePass) this.halftonePass.uniforms.uResolution.value.set(dw, dh);
 		for (const s of this.waves) s.material.uniforms.uResolution.value.set(dw, dh);
 		this.camera.left = -dw / 2;
 		this.camera.right = dw / 2;
@@ -1204,16 +1475,20 @@ var WaveRenderer = class {
 	onAfterRenderFrame() {}
 	/** Hook ④: called at the end of resize(), before the trailing renderOnce(). */
 	onAfterResize() {}
-	/** Responsive ortho zoom: COVER the FRAME_W × FRAME_H reference frame onto the canvas so the
-	*  wave frames the same at any size/aspect/dpr (only the cropped margin differs), times the
-	*  user's cameraZoom. `max(...)` = cover (fill both axes, crop overflow); `min(...)` would be
-	*  contain (fit with letterbox bands). Cover keeps the wave filling the frame on every screen. */
+	/** Responsive ortho zoom: map the FRAME_W × FRAME_H reference frame onto the canvas (per
+	*  config.cameraFit / cameraMinVisibleWidth — see {@link frameZoom}) so the wave frames the same
+	*  at any size/aspect/dpr, times the user's cameraZoom. */
 	applyZoom() {
 		const dw = this.camera.right - this.camera.left;
 		const dh = this.camera.top - this.camera.bottom;
-		this.camera.zoom = Math.max(dw / FRAME_W, dh / 750) * (this.config.cameraZoom ?? 1) * this.interactionZoom;
+		this.camera.zoom = this.baseFrameZoom(dw, dh) * (this.config.cameraZoom ?? 1) * this.interactionZoom;
 		this.camera.updateProjectionMatrix();
 	}
+	/** The responsive base zoom for the current config's framing policy, before the cameraZoom
+	*  multiplier. Subclasses invert this to recover cameraZoom from a live camera. */
+	baseFrameZoom(dw, dh) {
+		return frameZoom(dw, dh, this.config.cameraFit ?? "cover", this.config.cameraMinVisibleWidth ?? 0);
+	}
 	/** Fit the orthographic near/far planes to the scene before every render, so no part of a wave
 	*  is ever clipped as the camera orbits / dollies / pans (or when waves are added or scaled).
 	*
@@ -1326,12 +1601,14 @@ var WaveRenderer = class {
 	}
 	dispose() {
 		cancelAnimationFrame(this.rafId);
+		cancelAnimationFrame(this.resizeRaf);
 		this.running = false;
 		this.interaction?.dispose();
 		this.interaction = void 0;
 		this.resizeObserver.disconnect();
 		this.intersectionObserver.disconnect();
 		this.motionQuery.removeEventListener("change", this.onMotionChange);
+		this.dprQuery?.removeEventListener("change", this.onDprChange);
 		document.removeEventListener("visibilitychange", this.onVisibilityChange);
 		this.renderer.domElement.removeEventListener("webglcontextlost", this.onContextLost);
 		this.renderer.domElement.removeEventListener("webglcontextrestored", this.onContextRestored);
@@ -1343,12 +1620,18 @@ var WaveRenderer = class {
 			s.palette.dispose();
 		}
 		this.bloomPass?.dispose();
+		this.ditherPass?.dispose();
+		this.innerLightPass?.dispose();
+		this.halftonePass?.dispose();
+		this.heatmapPass?.dispose();
+		this.paperTexturePass?.dispose();
+		this.halftoneCmykPass?.dispose();
 		this.composer.dispose();
 		this.renderer.dispose();
 		this.renderer.domElement.remove();
 	}
 };
 //#endregion
-export { FRAME_H, FRAME_W, WaveRenderer, hexToLinearVec3 };
+export { FRAME_H, FRAME_W, WaveRenderer, frameZoom, hexToLinearVec3 };
 
 //# sourceMappingURL=WaveRenderer.js.map