@wave3d/core 0.8.0 → 0.10.0

package/dist/renderer/WaveRenderer.js

@@ -1,7 +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 { InteractionController, SCENE_APPLIERS, WAVE_APPLIERS, anyPointerFxActive, interactionActive, wavePointerFxActive, waveRipplesActive } from "./interaction.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";
 import { buildHeroPaletteCanvas, buildHeroPaletteTexture } from "./heroPalette.js";
@@ -174,6 +174,12 @@ function hexToLinearVec3(hex, target) {
 */
 var WaveRenderer = class {
 	renderer;
+	/**
+	* Whether this renderer can draw yet. The WebGL backend is ready the moment it is constructed;
+	* the WebGPU subclass has to `await renderer.init()` first, and `renderOnce()` throws before that.
+	* The base class is always ready, so the WebGL path is unaffected.
+	*/
+	ready = true;
 	scene = new THREE.Scene();
 	camera;
 	group = new THREE.Group();
@@ -211,8 +217,17 @@ var WaveRenderer = class {
 	clipSphere = new THREE.Sphere();
 	clipTmpA = new THREE.Vector3();
 	clipTmpB = new THREE.Vector3();
-	/** Created by syncInteraction() when interaction turns on, disposed when it turns off. */
+	/** Created by loadInteraction() once the runtime chunk lands, disposed when interaction turns off.
+	*  Stays undefined for the frames between the config turning it on and the chunk arriving. */
 	interaction;
+	/** The chunk itself, kept for the applier tables. Set and cleared with `interaction`. */
+	interactionModule;
+	/** A fetch already in flight, so a per-frame refresh can't start a second one. */
+	interactionLoading = false;
+	/** setInteractionInput() calls made while the chunk was in flight, replayed once it lands. */
+	stagedInputs;
+	/** Set by dispose(), so an in-flight chunk can't attach listeners to a dead renderer. */
+	disposed = false;
 	/** Extra ortho-zoom MULTIPLIER from a cameraZoom binding (1 = none); applied in applyZoom().
 	*  Protected so the studio's writeCameraToConfig() can divide it back out (keep it out of config). */
 	interactionZoom = 1;
@@ -250,12 +265,7 @@ var WaveRenderer = class {
 		this.config = ensureStudioConfig(config);
 		this.respectReducedMotion = options.respectReducedMotion ?? true;
 		this.skipIntroRamp = options.skipIntroRamp ?? false;
-		this.renderer = new THREE.WebGLRenderer({
-			antialias: true,
-			alpha: true,
-			preserveDrawingBuffer: true,
-			powerPreference: "high-performance"
-		});
+		this.renderer = this.createRenderer();
 		this.renderer.outputColorSpace = THREE.SRGBColorSpace;
 		this.renderer.setClearColor(0, 0);
 		container.appendChild(this.renderer.domElement);
@@ -301,6 +311,24 @@ var WaveRenderer = class {
 		this.buildWaves();
 		this.resize();
 	}
+	/**
+	* Build the backing three renderer. Overridden by the WebGPU subclass; called from the
+	* constructor, so it must not depend on subclass FIELDS (prototype methods are available during
+	* `super()`, field initialisers are not).
+	*/
+	createRenderer() {
+		return new THREE.WebGLRenderer({
+			antialias: true,
+			alpha: true,
+			preserveDrawingBuffer: true,
+			powerPreference: "high-performance"
+		});
+	}
+	/**
+	* Await any asynchronous backend startup. A no-op on WebGL; the WebGPU subclass overrides it to
+	* `await renderer.init()` and then draw the first frame. Safe to call more than once.
+	*/
+	async init() {}
 	get segments() {
 		const q = this.config.quality / Math.sqrt(Math.max(1, this.config.waves.length));
 		return THREE.MathUtils.clamp(Math.round(BASE_SEGMENTS * q), 24, 360);
@@ -464,16 +492,7 @@ var WaveRenderer = class {
 	addWave() {
 		const geo = new WaveGeometry(this.segments);
 		const sc = this.config.waves[this.waves.length] ?? this.config.waves[0];
-		const material = new THREE.ShaderMaterial({
-			uniforms: this.makeUniforms(),
-			defines: this.waveDefines(sc),
-			vertexShader,
-			fragmentShader: sc?.theme === "wireframe" ? lineFragmentShader : fragmentShader,
-			transparent: true,
-			depthTest: true,
-			depthWrite: true,
-			side: THREE.DoubleSide
-		});
+		const material = this.createWaveMaterial(sc);
 		this.applyBlendMode(material, sc?.blendMode ?? "squared");
 		const mesh = new THREE.Mesh(geo.geometry, material);
 		mesh.frustumCulled = false;
@@ -491,6 +510,45 @@ var WaveRenderer = class {
 		});
 	}
 	/**
+	* Build the material for one wave. The GLSL backend compiles a ShaderMaterial with `#define`
+	* variants; the WebGPU subclass builds a TSL node graph instead. Both expose the same `uniforms`
+	* surface, so everything downstream in `refresh()` is shared.
+	*/
+	createWaveMaterial(sc) {
+		return new THREE.ShaderMaterial({
+			uniforms: this.makeUniforms(),
+			defines: this.waveDefines(sc),
+			vertexShader,
+			fragmentShader: sc?.theme === "wireframe" ? lineFragmentShader : fragmentShader,
+			transparent: true,
+			depthTest: true,
+			depthWrite: true,
+			side: THREE.DoubleSide
+		});
+	}
+	/**
+	* 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
+	* different graph rather than a different define set.
+	*/
+	applyWaveVariant(wave, sc) {
+		const material = wave.material;
+		let changed = false;
+		const wantDefines = this.waveDefines(sc);
+		const curDefines = material.defines ?? {};
+		if (Object.keys(wantDefines).sort().join(",") !== Object.keys(curDefines).sort().join(",")) {
+			material.defines = wantDefines;
+			changed = true;
+		}
+		const wantFrag = sc.theme === "wireframe" ? lineFragmentShader : fragmentShader;
+		if (material.fragmentShader !== wantFrag) {
+			material.fragmentShader = wantFrag;
+			changed = true;
+		}
+		return changed;
+	}
+	/**
 	* Apply config.blendMode to a material. "squared" (the default) is the hero blend:
 	* CustomBlending with AddEquation, src = SrcColorFactor, dst = ZeroFactor, so the
 	* framebuffer result is fragColor² — the squaring deepens the colours into the vivid
@@ -516,7 +574,7 @@ var WaveRenderer = class {
 			s.geometry.dispose();
 			s.palette.dispose();
 			if (s.particleField) {
-				this.scene.remove(s.particleField.points);
+				this.scene.remove(s.particleField.object);
 				s.particleField.dispose();
 			}
 		}
@@ -538,7 +596,7 @@ var WaveRenderer = class {
 			s.geometry.dispose();
 			s.palette.dispose();
 			if (s.particleField) {
-				this.scene.remove(s.particleField.points);
+				this.scene.remove(s.particleField.object);
 				s.particleField.dispose();
 			}
 		}
@@ -566,17 +624,7 @@ var WaveRenderer = class {
 			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
 			const u = wave.material.uniforms;
 			if (this.applyBlendMode(wave.material, sc.blendMode)) wave.material.needsUpdate = true;
-			const wantDefines = this.waveDefines(sc);
-			const curDefines = wave.material.defines ?? {};
-			if (Object.keys(wantDefines).sort().join(",") !== Object.keys(curDefines).sort().join(",")) {
-				wave.material.defines = wantDefines;
-				wave.material.needsUpdate = true;
-			}
-			const wantFrag = sc.theme === "wireframe" ? lineFragmentShader : fragmentShader;
-			if (wave.material.fragmentShader !== wantFrag) {
-				wave.material.fragmentShader = wantFrag;
-				wave.material.needsUpdate = true;
-			}
+			if (this.applyWaveVariant(wave, sc)) wave.material.needsUpdate = true;
 			const stops = [...sc.palette].sort((a, b) => a.pos - b.pos);
 			const colorCount = Math.max(1, Math.min(stops.length, 8));
 			const colors = u.uColors.value;
@@ -731,18 +779,41 @@ var WaveRenderer = class {
 		if (this.config.transparentBackground) {
 			this.scene.background = null;
 			this.renderer.setClearColor(0, 0);
+			this.onBackgroundChanged();
 			return;
 		}
 		const matte = new THREE.Color(this.config.background);
 		this.renderer.setClearColor(matte, 1);
 		if (this.config.backgroundMode === "color") {
 			this.applyColorBackground(matte);
+			this.onBackgroundChanged();
 			return;
 		}
 		const { width, height } = this.backgroundCanvasSize(this.config.backgroundVideoUrl ? 2048 : 4096);
 		if (this.config.backgroundMode === "gradient") this.applyGradientBackground(width, height);
 		else this.applyImageBackground(matte, width, height);
+		this.onBackgroundChanged();
+	}
+	/**
+	* Build a wave's particle field. The GLSL backend returns a `THREE.Points` field; the TSL backend
+	* returns an instanced-sprite one wired to this wave's own uniform registry.
+	*/
+	createParticleField(_wave, _sc, onReady) {
+		return new ParticleField(onReady);
+	}
+	/**
+	* Largest texture edge the backend will accept, used to cap the background canvas. WebGL reports
+	* it on `capabilities`; WebGPU has no such object, so the subclass reads the device limit.
+	*/
+	maxTextureSize() {
+		return this.renderer.capabilities.maxTextureSize;
 	}
+	/**
+	* Called whenever the scene background changes. A no-op on WebGL, where `EffectComposer`'s
+	* RenderPass reads the scene afresh each frame; the WebGPU subclass rebuilds its post chain,
+	* because a `pass()` node captures the background state at the point its render context is built.
+	*/
+	onBackgroundChanged() {}
 	applyColorBackground(matte) {
 		this.clearBackgroundVideo();
 		this.backgroundTexture?.dispose();
@@ -872,7 +943,7 @@ var WaveRenderer = class {
 	backgroundCanvasSize(maxRequestedEdge = 4096) {
 		const rawWidth = this.outputSize?.width ?? Math.max(1, this.container.clientWidth);
 		const rawHeight = this.outputSize?.height ?? Math.max(1, this.container.clientHeight);
-		const maxEdge = Math.min(maxRequestedEdge, this.renderer.capabilities.maxTextureSize);
+		const maxEdge = Math.min(maxRequestedEdge, this.maxTextureSize());
 		const scale = Math.min(1, maxEdge / Math.max(rawWidth, rawHeight));
 		return {
 			width: Math.max(1, Math.round(rawWidth * scale)),
@@ -1247,8 +1318,7 @@ var WaveRenderer = class {
 			this.renderer.domElement.style.width = "100%";
 			this.renderer.domElement.style.height = "100%";
 		}
-		this.composer.setPixelRatio(dpr);
-		this.composer.setSize(w, h);
+		this.resizePost(w, h, dpr);
 		const dw = w * dpr;
 		const dh = h * dpr;
 		this.postPass.uniforms.uResolution.value.set(dw, dh);
@@ -1334,14 +1404,28 @@ var WaveRenderer = class {
 		this.postPass.uniforms.uTime.value = t;
 		for (const w of this.waves) w.particleField?.setTime(t);
 	}
+	/** Draw the composed frame. WebGL runs the EffectComposer; WebGPU runs a node post chain. */
+	renderComposed() {
+		this.composer.render();
+	}
+	/** Resize the post chain's render targets. */
+	resizePost(w, h, dpr) {
+		this.composer.setPixelRatio(dpr);
+		this.composer.setSize(w, h);
+	}
+	/** Release the post chain's GPU resources. */
+	disposePost() {
+		this.composer.dispose();
+	}
 	/** Render exactly one frame at the current time. */
 	renderOnce() {
+		if (!this.ready) return;
 		this.updateBackgroundVideoFrame();
 		this.updateTime();
 		this.applyInteraction();
 		this.updateSceneFx();
 		this.updateClipPlanes();
-		this.composer.render();
+		this.renderComposed();
 		this.onAfterRenderFrame();
 	}
 	/** Insert / sync / remove EACH wave's particle field — mirrors applyBloom's lazy lifecycle, per wave.
@@ -1351,17 +1435,18 @@ var WaveRenderer = class {
 	applyParticles() {
 		const loop = this.config.loopSeconds ?? 0;
 		this.waves.forEach((wave, i) => {
-			const cfg = (this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1])?.particles;
+			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
+			const cfg = sc?.particles;
 			if (cfg && cfg.count > 0) {
 				if (!wave.particleField) {
-					wave.particleField = new ParticleField(() => {
+					wave.particleField = this.createParticleField(wave, sc, () => {
 						if (!this.running) this.renderOnce();
 					});
-					this.scene.add(wave.particleField.points);
+					this.scene.add(wave.particleField.object);
 				}
 				wave.particleField.sync(cfg, loop);
 			} else if (wave.particleField) {
-				this.scene.remove(wave.particleField.points);
+				this.scene.remove(wave.particleField.object);
 				wave.particleField.dispose();
 				wave.particleField = void 0;
 			}
@@ -1425,10 +1510,11 @@ var WaveRenderer = class {
 	*  refresh(); the compiled define set (POINTER_FX etc.) is handled separately by waveDefines(). */
 	syncInteraction() {
 		const active = interactionActive(this.config);
-		if (active && !this.interaction) this.interaction = new InteractionController(this.container, () => this.config);
+		if (active && !this.interaction) this.loadInteraction();
 		else if (!active && this.interaction) {
 			this.interaction.dispose();
 			this.interaction = void 0;
+			this.interactionModule = void 0;
 			this.interactionTimeOffset = 0;
 			if (this.interactionZoom !== 1) {
 				this.interactionZoom = 1;
@@ -1436,18 +1522,50 @@ var WaveRenderer = class {
 			}
 		}
 	}
+	/**
+	* Fetch the interactivity runtime and attach it. Deliberately a DYNAMIC import: the controller,
+	* its listeners, the applier tables and the tilt sensor are ~3.8 KB gzipped that a scene with no
+	* `interaction` block never runs, and a static import would put all of it in every bundle. The
+	* cost is that interaction goes live a chunk-fetch after the first frame instead of on it —
+	* invisible in practice, since there is nothing to react to until a reader moves.
+	*
+	* A failed fetch is not fatal: the wave renders exactly as an inert one does, which is the same
+	* thing that happens on a config with no interaction at all.
+	*/
+	async loadInteraction() {
+		if (this.interactionLoading) return;
+		this.interactionLoading = true;
+		try {
+			const mod = await import("./interaction.js");
+			if (this.disposed || this.interaction || !interactionActive(this.config)) return;
+			this.interactionModule = mod;
+			this.interaction = new mod.InteractionController(this.container, () => this.config);
+			if (this.stagedInputs) {
+				for (const [name, value] of this.stagedInputs) this.interaction.setInput(name, value);
+				this.stagedInputs = void 0;
+			}
+			this.onInteractionReady();
+		} catch {} finally {
+			this.interactionLoading = false;
+		}
+	}
+	/** Hook for subclasses that hold state the controller must be told about once it exists (the
+	*  studio's scroll preview). No-op in the base renderer. */
+	onInteractionReady() {}
 	/** Per-frame interaction write: dynamic pointer-field uniforms + bindings. No-op without a
 	*  controller. While capturing it writes the REST state instead (pointer field zeroed, every bound
 	*  param at its authored base) — merely skipping the write would freeze whatever live hover/scroll
 	*  state the previous frame left in the uniforms, so exports wouldn't be deterministic. */
 	applyInteraction() {
-		if (!this.interaction) return;
+		const ic = this.interaction;
+		const mod = this.interactionModule;
+		if (!ic || !mod) return;
 		if (this.capturing) {
-			this.applyInteractionRest();
+			this.applyInteractionRest(mod);
 			return;
 		}
-		if (anyPointerFxActive(this.config)) this.applyPointerField(this.interaction);
-		this.applyBindings(this.interaction);
+		if (anyPointerFxActive(this.config)) this.applyPointerField(ic);
+		this.applyBindings(ic, mod);
 	}
 	/** Write the capture-frame interaction state: exactly what this config renders with no input —
 	*  pointer presence + ripple envelopes zeroed (vPointerFall gates every hover effect to 0) and each
@@ -1455,7 +1573,7 @@ var WaveRenderer = class {
 	*  the capture resumes mid-gesture; the trailing renderOnce() in captureImage restores the preview.
 	*  interactionZoom is deliberately NOT reset — captureImage strips it from camera.zoom itself, and
 	*  the post-capture restore depends on it being unchanged. */
-	applyInteractionRest() {
+	applyInteractionRest(mod) {
 		for (let i = 0; i < this.waves.length; i++) {
 			const sc = this.config.waves[i] ?? this.config.waves[this.config.waves.length - 1];
 			if (!wavePointerFxActive(this.config, sc)) continue;
@@ -1473,7 +1591,7 @@ var WaveRenderer = class {
 				out: this.interactionSceneOut
 			};
 			for (const b of sceneBindings) {
-				const applier = SCENE_APPLIERS[b.target];
+				const applier = mod.SCENE_APPLIERS[b.target];
 				applier.apply(applier.base(this.config), sceneArgs);
 			}
 		}
@@ -1487,7 +1605,7 @@ var WaveRenderer = class {
 			if (!sc || !bindings || bindings.length === 0) continue;
 			const wave = this.waves[i];
 			for (const b of bindings) {
-				const applier = WAVE_APPLIERS[b.target];
+				const applier = mod.WAVE_APPLIERS[b.target];
 				applier.apply(applier.base(sc), {
 					u: wave.material.uniforms,
 					mesh: wave.mesh
@@ -1529,7 +1647,7 @@ var WaveRenderer = class {
 	}
 	/** Evaluate bindings via the applier tables: value = mix(from ?? base, to, smoothedSource). Scene
 	*  bindings drive scene params; each wave's bindings drive that wave's uniforms. */
-	applyBindings(ic) {
+	applyBindings(ic, mod) {
 		this.interactionSceneOut.timeOffset = this.config.timeOffset ?? 0;
 		this.interactionSceneOut.zoom = this.config.cameraZoom ?? 1;
 		const sceneArgs = {
@@ -1537,7 +1655,7 @@ var WaveRenderer = class {
 			out: this.interactionSceneOut
 		};
 		for (const b of this.config.interaction?.bindings ?? []) {
-			const applier = SCENE_APPLIERS[b.target];
+			const applier = mod.SCENE_APPLIERS[b.target];
 			const value = THREE.MathUtils.lerp(b.from ?? applier.base(this.config), b.to, ic.bindingValue(b));
 			applier.apply(value, sceneArgs);
 		}
@@ -1547,7 +1665,7 @@ var WaveRenderer = class {
 			if (!sc || !bindings || bindings.length === 0) continue;
 			const wave = this.waves[i];
 			for (const b of bindings) {
-				const applier = WAVE_APPLIERS[b.target];
+				const applier = mod.WAVE_APPLIERS[b.target];
 				const value = THREE.MathUtils.lerp(b.from ?? applier.base(sc), b.to, ic.bindingValue(b));
 				applier.apply(value, {
 					u: wave.material.uniforms,
@@ -1562,9 +1680,45 @@ var WaveRenderer = class {
 			this.applyZoom();
 		}
 	}
-	/** Feed a `custom:<name>` interaction input (developer API). No-op when interaction is off. */
+	/** Feed a `custom:<name>` interaction input (developer API). No-op when interaction is off.
+	*  Values fed before the interaction chunk lands are STAGED (last one per name wins) and replayed
+	*  when it does — otherwise a one-shot input sent right after `onReady` would vanish into the
+	*  fetch window. */
 	setInteractionInput(name, value) {
-		this.interaction?.setInput(name, value);
+		if (this.interaction) {
+			this.interaction.setInput(name, value);
+			return;
+		}
+		if (typeof name !== "string" || !Number.isFinite(value)) return;
+		if (!interactionActive(this.config)) return;
+		(this.stagedInputs ??= /* @__PURE__ */ new Map()).set(name, value);
+	}
+	/**
+	* Explicitly ask for the device-orientation sensor. OPTIONAL, and on iOS it opens a modal
+	* permission dialog — so this belongs to a page where tilt is the point, not to a decorative
+	* background, which should simply go without tilt there. Nothing calls this for you.
+	*
+	* CALL IT FROM A USER GESTURE: iOS 13+ only grants the sensor from inside a tap handler, and
+	* awaiting anything before it (a fetch, a timeout) spends the gesture. Resolves true once
+	* readings can flow — false when
+	* the platform has no sensor, the scene declares no `interaction.tilt`, or the reader refused.
+	* Where no permission is required the sensor is already live and this resolves true.
+	*/
+	enableTilt() {
+		if (!this.interaction) {
+			if (interactionActive(this.config)) this.loadInteraction();
+			return Promise.resolve(false);
+		}
+		return this.interaction.enableTilt();
+	}
+	/** Where the tilt sensor stands. `"prompt"` is exactly when a tap-to-enable affordance helps. */
+	tiltStatus() {
+		if (this.interaction) return this.interaction.tiltStatus();
+		return typeof window !== "undefined" && typeof window.DeviceOrientationEvent !== "undefined" ? "prompt" : "unsupported";
+	}
+	/** Take the next orientation reading as the neutral pose — for when the reader has changed grip. */
+	recenterTilt() {
+		this.interaction?.recenterTilt();
 	}
 	/** Re-evaluate play/pause after `config.paused` changes. */
 	refreshPlayback() {
@@ -1720,11 +1874,13 @@ var WaveRenderer = class {
 		this.applyCameraFromConfig();
 	}
 	dispose() {
+		this.disposed = true;
 		cancelAnimationFrame(this.rafId);
 		cancelAnimationFrame(this.resizeRaf);
 		this.running = false;
 		this.interaction?.dispose();
 		this.interaction = void 0;
+		this.interactionModule = void 0;
 		this.resizeObserver.disconnect();
 		this.intersectionObserver.disconnect();
 		this.motionQuery.removeEventListener("change", this.onMotionChange);
@@ -1747,7 +1903,7 @@ var WaveRenderer = class {
 		this.heatmapPass?.dispose();
 		this.paperTexturePass?.dispose();
 		this.halftoneCmykPass?.dispose();
-		this.composer.dispose();
+		this.disposePost();
 		this.renderer.dispose();
 		this.renderer.domElement.remove();
 	}