@wave3d/core 0.4.1 → 0.6.0

package/dist/renderer/WaveRenderer.d.ts

@@ -1,18 +1,30 @@
-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;
@@ -51,7 +63,8 @@ declare class WavePalette {
 type Wave = {
   mesh: THREE.Mesh;
   material: THREE.ShaderMaterial;
-  geometry: WaveGeometry; /** This wave's own 2D palette texture + optional video. */
+  geometry: WaveGeometry;
+  /** This wave's own 2D palette texture + optional video. */
   palette: WavePalette;
 };
 /** Convert an sRGB hex string to a linear-space RGB vector (three's ColorManagement does the
@@ -120,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. */
@@ -197,7 +215,35 @@ declare class WaveRenderer {
   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;
@@ -253,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).
    *
@@ -287,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,6 +1,6 @@
 import { ensureStudioConfig } from "../config/model.js";
-import { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.js";
 import { WaveGeometry } from "./WaveGeometry.js";
+import { ditherFragmentShader, fragmentShader, halftoneCmykFragmentShader, halftoneFragmentShader, heatmapFragmentShader, innerLightFragmentShader, lineFragmentShader, paperTextureFragmentShader, postFragmentShader, postVertexShader, vertexShader } from "./shaders.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";
 import { buildHeroPaletteCanvas, buildHeroPaletteTexture } from "./heroPalette.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).
@@ -201,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. */
@@ -256,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();
@@ -355,7 +392,7 @@ var WaveRenderer = class {
 			uEdgeFeather: { value: .1 },
 			uOpacity: { value: 1 },
 			uSquared: { value: 1 },
-			uResolution: { value: new THREE.Vector2(1, 1) },
+			uResolution: { value: this.renderer.getDrawingBufferSize(new THREE.Vector2()) },
 			uAmbient: { value: .45 },
 			uNumLights: { value: 1 },
 			uLightPos: { value: lightPos },
@@ -370,6 +407,12 @@ var WaveRenderer = class {
 			uLineDerivativePower: { value: .95 },
 			uMaxWidth: { value: 1232 },
 			uClearColor: { value: new THREE.Vector3(1, 1, 1) },
+			uHelixTurns: { value: 0 },
+			uHelixRadius: { value: 0 },
+			uHelixRoll: { value: 0 },
+			uHelixPhase: { value: 0 },
+			uRungAmount: { value: 0 },
+			uRungThickness: { value: 1 },
 			uPointer: { value: new THREE.Vector2(0, 0) },
 			uPointerActive: { value: 0 },
 			uPointerRadius: { value: .6 },
@@ -399,6 +442,9 @@ var WaveRenderer = class {
 		if ((sc?.detailAmount ?? 0) !== 0 || bindsDetail) defines.DETAIL_OCTAVE = "";
 		if ((sc?.depthTint ?? 0) > 0) defines.DEPTH_TINT = "";
 		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?.theme === "wireframe" && (sc.rungAmount ?? 0) > 0) defines.RUNGS = "";
 		if (sc && wavePointerFxActive(this.config, sc)) {
 			defines.POINTER_FX = "";
 			if (waveRipplesActive(this.config, sc)) defines.POINTER_RIPPLES = "";
@@ -550,6 +596,8 @@ var WaveRenderer = class {
 			u.uLineAmount.value = sc.lineAmount ?? 425;
 			u.uLineThickness.value = sc.lineThickness ?? 1;
 			u.uLineDerivativePower.value = sc.lineDerivativePower ?? .95;
+			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);
 			u.uFiberCount.value = sc.fiberCount;
@@ -606,6 +654,10 @@ var WaveRenderer = class {
 			u.uTwPowX.value = sc.twistPower.x;
 			u.uTwPowY.value = sc.twistPower.y;
 			u.uTwPowZ.value = sc.twistPower.z;
+			u.uHelixTurns.value = sc.helixTurns ?? 0;
+			u.uHelixRadius.value = sc.helixRadius ?? 0;
+			u.uHelixRoll.value = sc.helixRoll ?? 0;
+			u.uHelixPhase.value = sc.helixPhase ?? 0;
 			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);
@@ -1093,9 +1145,57 @@ var WaveRenderer = class {
 			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);
@@ -1111,9 +1211,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) {
@@ -1387,16 +1490,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).
 	*
@@ -1509,12 +1616,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);
@@ -1538,6 +1647,6 @@ var WaveRenderer = class {
 	}
 };
 //#endregion
-export { FRAME_H, FRAME_W, WaveRenderer, hexToLinearVec3 };
+export { FRAME_H, FRAME_W, WaveRenderer, frameZoom, hexToLinearVec3 };
 
 //# sourceMappingURL=WaveRenderer.js.map