@wave3d/core 0.8.0 → 0.9.0

package/dist/renderer/WaveRendererGPU.js

@@ -0,0 +1,291 @@
+import { wavePointerFxActive, waveRipplesActive } from "./interactionGates.js";
+import { WaveRenderer } from "./WaveRenderer.js";
+import { floatUniform, vec2Uniform } from "./tsl/types.js";
+import { ParticleFieldGPU } from "./particleFieldGPU.js";
+import { makeTslUniforms } from "./tsl/uniforms.js";
+import { buildWaveMaterial } from "./tsl/waveMaterial.js";
+import { buildPostChain } from "./tsl/postChain.js";
+import * as THREE from "three";
+import { RenderPipeline, WebGPUCoordinateSystem, WebGPURenderer } from "three/webgpu";
+import { pass, screenUV, texture, vec2 } from "three/tsl";
+//#region src/renderer/WaveRendererGPU.ts
+/**
+* The WebGPU / TSL backend.
+*
+* Overrides only the four things that are actually backend-specific — the three renderer, the
+* wave material, how a shader variant is re-selected, and the post chain. Everything else (config
+* sync, camera, background, resize, interaction, capture, particles) is shared, because both
+* backends expose the same `uniforms` surface. The overrides are packaged as the
+* {@link withTslBackend} mixin so they can also layer over the studio's editor subclass;
+* {@link WaveRendererGPU} is that mixin applied to the plain {@link WaveRenderer}.
+*
+* `WebGPURenderer` falls back to a WebGL2 backend on its own when WebGPU is unavailable, so this
+* class is not "the WebGPU-only path" — it is the TSL path, which runs on either backend. What it
+* must not do is get imported from the package entry: `three/webgpu` pulls the whole node system
+* (~200 KB gzipped), so this module is only ever reached through a dynamic import.
+*/
+/** The flag set that decides a wave's node graph — the TSL twin of `waveDefines()`. */
+function variantKey(f) {
+	return [
+		f.theme,
+		f.loopMotion && "loop",
+		f.detailOctave && "detail",
+		f.helix && "helix",
+		f.twistMotion && "twist",
+		f.radial && "radial",
+		f.depthTint && "depthTint",
+		f.edgeFeather && "edgeFeather",
+		f.rungs && "rungs",
+		f.pointerFx && "pointer",
+		f.pointerRipples && "ripples",
+		f.webgpuClipZ && "gpuz"
+	].filter(Boolean).join(",");
+}
+/**
+* The TSL backend as a mixin, so the same override set can sit on either base: over
+* {@link WaveRenderer} for embeds (the {@link WaveRendererGPU} export below), or over the studio's
+* editor subclass (`studio/StudioWaveRendererGPU.ts`). That composition works because the two
+* override DISJOINT hook sets — the editor overrides the camera/overlay hooks, this backend the
+* renderer/material/post hooks — so layering order doesn't matter.
+*
+* `Base` is constrained to (and internally cast as) `typeof WaveRenderer` because TypeScript
+* forbids protected-member access from a class extending a bare type parameter. The cast is sound
+* for any WaveRenderer subclass, and returning `TBase` hands the composed class back with its real
+* base's type (the editor API survives on the studio composition).
+*/
+function withTslBackend(Base) {
+	class WithTslBackend extends Base {
+		post;
+		/**
+		* Lazily built, NOT a field initialiser. Subclass field initialisers run only after `super()`
+		* returns, and the base constructor already renders (buildWaves → resize → renderOnce), so a
+		* field here would still be `undefined` at first draw.
+		*/
+		postUniformsCache;
+		/** The effect set the current chain was built for; a change rebuilds it, as the WebGL path
+		*  inserts and removes passes. */
+		postFlagsKey = "";
+		createRenderer() {
+			this.ready = false;
+			return new WebGPURenderer({
+				antialias: false,
+				alpha: true,
+				powerPreference: "high-performance"
+			});
+		}
+		get postUniforms() {
+			this.postUniformsCache ??= {
+				uBlurAmount: floatUniform(0),
+				uBlurSamples: floatUniform(6),
+				uGrainAmount: floatUniform(0),
+				uBloomStrength: floatUniform(0),
+				uBloomRadius: floatUniform(.4),
+				uBloomThreshold: floatUniform(.85),
+				uInnerLight: floatUniform(0),
+				uInnerLightDensity: floatUniform(.5),
+				uInnerLightDecay: floatUniform(.95),
+				uInnerLightCenter: vec2Uniform(.5, .15),
+				uHalftone: floatUniform(0),
+				uHalftoneCell: floatUniform(6),
+				uHalftoneAngle: floatUniform(.4),
+				uHeatmap: floatUniform(0),
+				uHalftoneCmyk: floatUniform(0),
+				uHalftoneCmykCell: floatUniform(6),
+				uPaper: floatUniform(0),
+				uPaperScale: floatUniform(2),
+				uDitherStrength: floatUniform(0),
+				uDitherScale: floatUniform(2),
+				uDitherSteps: floatUniform(4)
+			};
+			return this.postUniformsCache;
+		}
+		/** Start the WebGPU backend, then draw the first frame. Safe to call more than once. */
+		async init() {
+			if (this.ready) return;
+			await this.renderer.init();
+			this.ready = true;
+			this.resize();
+			this.refresh();
+		}
+		/**
+		* True when the live backend uses [0,1] clip Z rather than [-1,1]. Read from the renderer rather
+		* than assumed, because WebGPURenderer silently falls back to a WebGL2 backend — in which case
+		* the clip convention is the WebGL one and the depth fade must NOT be remapped.
+		*/
+		get webgpuClipZ() {
+			return this.renderer.coordinateSystem === WebGPUCoordinateSystem;
+		}
+		flagsFor(sc) {
+			const bindsDetail = sc?.interaction?.bindings?.some((b) => b.target === "detailAmount") ?? false;
+			const bindsHelix = sc?.interaction?.bindings?.some((b) => b.target.startsWith("helix")) ?? false;
+			const pointer = !!sc && wavePointerFxActive(this.config, sc);
+			return {
+				theme: sc?.theme === "wireframe" ? "wireframe" : "solid",
+				loopMotion: (this.config.loopSeconds ?? 0) > 0,
+				detailOctave: (sc?.detailAmount ?? 0) !== 0 || bindsDetail,
+				helix: (sc?.helixRadius ?? 0) !== 0 || (sc?.helixRoll ?? 0) !== 0 || bindsHelix,
+				twistMotion: !!sc?.twistMotion,
+				radial: (sc?.radialAmount ?? 0) !== 0,
+				depthTint: (sc?.depthTint ?? 0) > 0,
+				edgeFeather: (sc?.edgeFeather ?? .1) !== .1,
+				rungs: sc?.theme === "wireframe" && (sc.rungAmount ?? 0) > 0,
+				pointerFx: pointer,
+				pointerRipples: pointer && waveRipplesActive(this.config, sc),
+				webgpuClipZ: this.webgpuClipZ
+			};
+		}
+		/**
+		* An instanced-sprite particle field wired to THIS wave's uniform registry.
+		*
+		* That wiring is the whole reason this override exists: the GLSL field has to mirror the wave's
+		* shape and pointer uniforms into its own material every frame, whereas here the dust reads the
+		* ribbon's nodes directly and cannot drift out of sync with it.
+		*/
+		createParticleField(wave, sc, onReady) {
+			const { tsl } = wave.material.userData;
+			const f = this.flagsFor(sc);
+			return new ParticleFieldGPU({
+				uniforms: tsl,
+				flags: {
+					loopMotion: f.loopMotion,
+					detailOctave: f.detailOctave,
+					helix: f.helix,
+					twistMotion: f.twistMotion,
+					radial: f.radial,
+					pointerFx: f.pointerFx,
+					pointerRipples: f.pointerRipples
+				}
+			}, onReady);
+		}
+		createWaveMaterial(sc) {
+			const u = makeTslUniforms(this.renderer.getDrawingBufferSize(new THREE.Vector2()));
+			const flags = this.flagsFor(sc);
+			const material = buildWaveMaterial(u, flags);
+			material.uniforms = u;
+			material.userData = {
+				variant: variantKey(flags),
+				tsl: u
+			};
+			return material;
+		}
+		/**
+		* A TSL variant is a different GRAPH, not a different define set, so a variant change rebuilds
+		* the material and re-points the mesh at it. The uniform registry is carried over untouched, so
+		* no config state is lost and no value has to be re-synced.
+		*/
+		applyWaveVariant(wave, sc) {
+			const current = wave.material;
+			const flags = this.flagsFor(sc);
+			const key = variantKey(flags);
+			if (current.userData.variant === key) return false;
+			const rebuilt = buildWaveMaterial(current.userData.tsl, flags);
+			rebuilt.uniforms = current.uniforms;
+			rebuilt.userData = {
+				variant: key,
+				tsl: current.userData.tsl
+			};
+			rebuilt.blending = current.blending;
+			rebuilt.premultipliedAlpha = current.premultipliedAlpha;
+			wave.mesh.material = rebuilt;
+			wave.material = rebuilt;
+			current.dispose();
+			return false;
+		}
+		/** Which effects the config currently asks for — the node twin of applyPost()'s pass juggling. */
+		postFlags() {
+			const c = this.config;
+			return {
+				bloom: (c.bloomStrength ?? 0) > 0,
+				innerLight: (c.innerLight ?? 0) > 0,
+				halftone: (c.halftone ?? 0) > 0,
+				heatmap: (c.heatmap ?? 0) > 0,
+				halftoneCmyk: (c.halftoneCmyk ?? 0) > 0,
+				paperTexture: (c.paperTexture ?? 0) > 0,
+				dither: (c.dither ?? 0) > 0
+			};
+		}
+		/** Push the config into the post uniforms. Mirrors applyPost() / the per-effect apply* methods. */
+		syncPostUniforms() {
+			const c = this.config;
+			const u = this.postUniforms;
+			u.uBlurAmount.value = c.blur;
+			u.uGrainAmount.value = c.grain;
+			u.uBlurSamples.value = Math.round(c.blurSamples ?? 6);
+			u.uBloomStrength.value = c.bloomStrength ?? 0;
+			u.uBloomRadius.value = c.bloomRadius ?? .4;
+			u.uBloomThreshold.value = c.bloomThreshold ?? .85;
+			u.uInnerLight.value = c.innerLight ?? 0;
+			u.uInnerLightDensity.value = c.innerLightDensity ?? .5;
+			u.uInnerLightDecay.value = c.innerLightDecay ?? .95;
+			u.uInnerLightCenter.value.set(c.innerLightX ?? .5, c.innerLightY ?? .15);
+			u.uHalftone.value = c.halftone ?? 0;
+			u.uHalftoneCell.value = Math.max(2, c.halftoneCell ?? 6);
+			u.uHalftoneAngle.value = c.halftoneAngle ?? .4;
+			u.uHeatmap.value = c.heatmap ?? 0;
+			u.uHalftoneCmyk.value = c.halftoneCmyk ?? 0;
+			u.uHalftoneCmykCell.value = Math.max(2, c.halftoneCmykCell ?? 6);
+			u.uPaper.value = c.paperTexture ?? 0;
+			u.uPaperScale.value = Math.max(.5, c.paperTextureScale ?? 2);
+			u.uDitherStrength.value = c.dither ?? 0;
+			u.uDitherScale.value = Math.max(1, c.ditherScale ?? 2);
+			u.uDitherSteps.value = Math.max(2, Math.round(c.ditherSteps ?? 4));
+		}
+		ensurePost() {
+			const flags = this.postFlags();
+			const key = JSON.stringify(flags);
+			if (this.post && key !== this.postFlagsKey) this.disposePost();
+			if (!this.post) {
+				this.postFlagsKey = key;
+				this.post = new RenderPipeline(this.renderer);
+				this.post.outputColorTransform = false;
+				this.post.outputNode = buildPostChain(pass(this.scene, this.camera), this.postUniforms, flags);
+			}
+			return this.post;
+		}
+		renderComposed() {
+			for (const wave of this.waves) wave.material.userData.tsl.packed.sync();
+			this.syncPostUniforms();
+			this.ensurePost().render();
+		}
+		resizePost(w, h, dpr) {
+			this.renderer.setPixelRatio(dpr);
+			this.renderer.setSize(w, h, false);
+		}
+		disposePost() {
+			this.post?.dispose();
+			this.post = void 0;
+		}
+		/**
+		* WebGPU exposes no `capabilities` object; the equivalent limit lives on the adapter's device.
+		* Falls back to 8192, the value every WebGPU implementation is required to support, for the
+		* window before `init()` resolves — the base class calls this while sizing the background.
+		*/
+		maxTextureSize() {
+			return (this.renderer.backend?.device)?.limits?.maxTextureDimension2D ?? 8192;
+		}
+		/**
+		* Rebuild the post chain when the background changes.
+		*
+		* A `pass()` node captures the scene's background at the point its render context is first built.
+		* Because the chain is created lazily on the first draw — when `scene.background` is still null —
+		* a background set afterwards would never appear, rendering every non-transparent preset on a
+		* transparent canvas. Background changes are user-driven, not per-frame, so rebuilding here is
+		* cheap; rebuilding every frame (which also works) is not.
+		*/
+		onBackgroundChanged() {
+			const bg = this.scene.background;
+			const isTexture = !!bg && bg.isTexture === true;
+			this.scene.backgroundNode = isTexture ? texture(bg).sample(vec2(screenUV.x, screenUV.y.oneMinus())) : null;
+			this.disposePost();
+		}
+	}
+	return WithTslBackend;
+}
+/** The TSL/WebGPU renderer over the plain {@link WaveRenderer} base — what embeds reach through
+*  `gpu-loader.ts`. A named class (not a bare `withTslBackend(WaveRenderer)` const) so consumers
+*  keep `new WaveRendererGPU(...)`, `instanceof`, and a stable class name. */
+var WaveRendererGPU = class extends withTslBackend(WaveRenderer) {};
+//#endregion
+export { WaveRendererGPU, withTslBackend };
+
+//# sourceMappingURL=WaveRendererGPU.js.map

package/dist/renderer/WaveRendererGPU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaveRendererGPU.js","names":[],"sources":["../../src/renderer/WaveRendererGPU.ts"],"sourcesContent":["/**\n * The WebGPU / TSL backend.\n *\n * Overrides only the four things that are actually backend-specific — the three renderer, the\n * wave material, how a shader variant is re-selected, and the post chain. Everything else (config\n * sync, camera, background, resize, interaction, capture, particles) is shared, because both\n * backends expose the same `uniforms` surface. The overrides are packaged as the\n * {@link withTslBackend} mixin so they can also layer over the studio's editor subclass;\n * {@link WaveRendererGPU} is that mixin applied to the plain {@link WaveRenderer}.\n *\n * `WebGPURenderer` falls back to a WebGL2 backend on its own when WebGPU is unavailable, so this\n * class is not \"the WebGPU-only path\" — it is the TSL path, which runs on either backend. What it\n * must not do is get imported from the package entry: `three/webgpu` pulls the whole node system\n * (~200 KB gzipped), so this module is only ever reached through a dynamic import.\n */\nimport * as THREE from \"three\";\nimport { WebGPURenderer, RenderPipeline, WebGPUCoordinateSystem } from \"three/webgpu\";\nimport { pass, texture, screenUV, vec2 } from \"three/tsl\";\nimport type { WaveConfig } from \"../config/model\";\nimport { WaveRenderer, type WaveMaterial, type WaveParticleField } from \"./WaveRenderer\";\nimport { ParticleFieldGPU } from \"./particleFieldGPU\";\nimport { makeTslUniforms, type WaveTslUniforms } from \"./tsl/uniforms\";\nimport { buildWaveMaterial, type WaveMaterialFlags } from \"./tsl/waveMaterial\";\nimport { wavePointerFxActive, waveRipplesActive } from \"./interactionGates\";\nimport { buildPostChain, type PostChainUniforms, type PostFlags } from \"./tsl/postChain\";\nimport { floatUniform, vec2Uniform } from \"./tsl/types\";\n\n/** The flag set that decides a wave's node graph — the TSL twin of `waveDefines()`. */\nfunction variantKey(f: WaveMaterialFlags): string {\n  return [\n    f.theme,\n    f.loopMotion && \"loop\",\n    f.detailOctave && \"detail\",\n    f.helix && \"helix\",\n    f.twistMotion && \"twist\",\n    f.radial && \"radial\",\n    f.depthTint && \"depthTint\",\n    f.edgeFeather && \"edgeFeather\",\n    f.rungs && \"rungs\",\n    f.pointerFx && \"pointer\",\n    f.pointerRipples && \"ripples\",\n    f.webgpuClipZ && \"gpuz\",\n  ]\n    .filter(Boolean)\n    .join(\",\");\n}\n\ntype TslMaterial = WaveMaterial & { userData: { variant: string; tsl: WaveTslUniforms } };\n\n/**\n * The TSL backend as a mixin, so the same override set can sit on either base: over\n * {@link WaveRenderer} for embeds (the {@link WaveRendererGPU} export below), or over the studio's\n * editor subclass (`studio/StudioWaveRendererGPU.ts`). That composition works because the two\n * override DISJOINT hook sets — the editor overrides the camera/overlay hooks, this backend the\n * renderer/material/post hooks — so layering order doesn't matter.\n *\n * `Base` is constrained to (and internally cast as) `typeof WaveRenderer` because TypeScript\n * forbids protected-member access from a class extending a bare type parameter. The cast is sound\n * for any WaveRenderer subclass, and returning `TBase` hands the composed class back with its real\n * base's type (the editor API survives on the studio composition).\n */\nexport function withTslBackend<TBase extends typeof WaveRenderer>(Base: TBase): TBase {\n  class WithTslBackend extends (Base as typeof WaveRenderer) {\n    declare readonly renderer: THREE.WebGLRenderer & WebGPURenderer;\n    private post?: RenderPipeline;\n    /**\n     * Lazily built, NOT a field initialiser. Subclass field initialisers run only after `super()`\n     * returns, and the base constructor already renders (buildWaves → resize → renderOnce), so a\n     * field here would still be `undefined` at first draw.\n     */\n    private postUniformsCache?: PostChainUniforms;\n    /** The effect set the current chain was built for; a change rebuilds it, as the WebGL path\n     *  inserts and removes passes. */\n    private postFlagsKey = \"\";\n\n    protected override createRenderer(): THREE.WebGLRenderer {\n      // Called from the BASE constructor, which is the only hook that runs early enough to stop the\n      // first render: `ready` cannot be cleared from this subclass's constructor body or a field\n      // initialiser, since both run after super() has already drawn a frame.\n      this.ready = false;\n      // No preserveDrawingBuffer: WebGPU has no such option and does not need one — the canvas is\n      // configured COPY_SRC, so toBlob()/toDataURL() readback works, which is what captureImage,\n      // the poster capture and the studio thumbnails rely on.\n      return new WebGPURenderer({\n        // antialias: false to MATCH the WebGL path, not because MSAA is unwanted. Everything there\n        // renders through EffectComposer, whose render target is created without `samples` — so the\n        // WebGL canvas's `antialias: true` never applies and that path is effectively unaliased.\n        // Enabling MSAA here would make WebGPU quietly render smoother edges than WebGL, which is a\n        // visual change disguised as a port. It is a real upgrade to opt into later, deliberately.\n        antialias: false,\n        alpha: true,\n        powerPreference: \"high-performance\",\n      }) as unknown as THREE.WebGLRenderer;\n    }\n\n    private get postUniforms() {\n      this.postUniformsCache ??= {\n        uBlurAmount: floatUniform(0),\n        uBlurSamples: floatUniform(6),\n        uGrainAmount: floatUniform(0),\n        uBloomStrength: floatUniform(0),\n        uBloomRadius: floatUniform(0.4),\n        uBloomThreshold: floatUniform(0.85),\n        uInnerLight: floatUniform(0),\n        uInnerLightDensity: floatUniform(0.5),\n        uInnerLightDecay: floatUniform(0.95),\n        uInnerLightCenter: vec2Uniform(0.5, 0.15),\n        uHalftone: floatUniform(0),\n        uHalftoneCell: floatUniform(6),\n        uHalftoneAngle: floatUniform(0.4),\n        uHeatmap: floatUniform(0),\n        uHalftoneCmyk: floatUniform(0),\n        uHalftoneCmykCell: floatUniform(6),\n        uPaper: floatUniform(0),\n        uPaperScale: floatUniform(2),\n        uDitherStrength: floatUniform(0),\n        uDitherScale: floatUniform(2),\n        uDitherSteps: floatUniform(4),\n      };\n      return this.postUniformsCache;\n    }\n\n    /** Start the WebGPU backend, then draw the first frame. Safe to call more than once. */\n    override async init(): Promise<void> {\n      if (this.ready) return;\n      await (this.renderer as unknown as WebGPURenderer).init();\n      this.ready = true;\n      // The constructor's buildWaves()/resize() ran against a not-yet-drawable backend, so their\n      // trailing renderOnce() was skipped. Catch up now that the backend is live.\n      this.resize();\n      this.refresh();\n    }\n\n    /**\n     * True when the live backend uses [0,1] clip Z rather than [-1,1]. Read from the renderer rather\n     * than assumed, because WebGPURenderer silently falls back to a WebGL2 backend — in which case\n     * the clip convention is the WebGL one and the depth fade must NOT be remapped.\n     */\n    private get webgpuClipZ(): boolean {\n      const cs = (this.renderer as unknown as { coordinateSystem: number }).coordinateSystem;\n      return cs === (WebGPUCoordinateSystem as number);\n    }\n\n    private flagsFor(sc: WaveConfig | undefined): WaveMaterialFlags {\n      const bindsDetail =\n        sc?.interaction?.bindings?.some((b) => b.target === \"detailAmount\") ?? false;\n      const bindsHelix =\n        sc?.interaction?.bindings?.some((b) => b.target.startsWith(\"helix\")) ?? false;\n      const pointer = !!sc && wavePointerFxActive(this.config, sc);\n      return {\n        theme: sc?.theme === \"wireframe\" ? \"wireframe\" : \"solid\",\n        loopMotion: (this.config.loopSeconds ?? 0) > 0,\n        detailOctave: (sc?.detailAmount ?? 0) !== 0 || bindsDetail,\n        helix: (sc?.helixRadius ?? 0) !== 0 || (sc?.helixRoll ?? 0) !== 0 || bindsHelix,\n        twistMotion: !!sc?.twistMotion,\n        radial: (sc?.radialAmount ?? 0) !== 0,\n        depthTint: (sc?.depthTint ?? 0) > 0,\n        edgeFeather: (sc?.edgeFeather ?? 0.1) !== 0.1,\n        rungs: sc?.theme === \"wireframe\" && (sc.rungAmount ?? 0) > 0,\n        pointerFx: pointer,\n        pointerRipples: pointer && waveRipplesActive(this.config, sc as WaveConfig),\n        webgpuClipZ: this.webgpuClipZ,\n      };\n    }\n\n    /**\n     * An instanced-sprite particle field wired to THIS wave's uniform registry.\n     *\n     * That wiring is the whole reason this override exists: the GLSL field has to mirror the wave's\n     * shape and pointer uniforms into its own material every frame, whereas here the dust reads the\n     * ribbon's nodes directly and cannot drift out of sync with it.\n     */\n    protected override createParticleField(\n      wave: { material: WaveMaterial },\n      sc: WaveConfig,\n      onReady: () => void,\n    ): WaveParticleField {\n      const { tsl } = (wave.material as TslMaterial).userData;\n      const f = this.flagsFor(sc);\n      return new ParticleFieldGPU(\n        {\n          uniforms: tsl,\n          flags: {\n            loopMotion: f.loopMotion,\n            detailOctave: f.detailOctave,\n            helix: f.helix,\n            twistMotion: f.twistMotion,\n            radial: f.radial,\n            pointerFx: f.pointerFx,\n            pointerRipples: f.pointerRipples,\n          },\n        },\n        onReady,\n      );\n    }\n\n    protected override createWaveMaterial(sc: WaveConfig | undefined): WaveMaterial {\n      const u = makeTslUniforms(this.renderer.getDrawingBufferSize(new THREE.Vector2()));\n      const flags = this.flagsFor(sc);\n      const material = buildWaveMaterial(u, flags) as unknown as TslMaterial;\n      // The shared config-sync path reaches uniforms through `material.uniforms`; the node registry\n      // is that same surface, so refresh() needs no backend branch.\n      material.uniforms = u as unknown as WaveMaterial[\"uniforms\"];\n      material.userData = { variant: variantKey(flags), tsl: u };\n      return material;\n    }\n\n    /**\n     * A TSL variant is a different GRAPH, not a different define set, so a variant change rebuilds\n     * the material and re-points the mesh at it. The uniform registry is carried over untouched, so\n     * no config state is lost and no value has to be re-synced.\n     */\n    protected override applyWaveVariant(\n      wave: { mesh: THREE.Mesh; material: WaveMaterial },\n      sc: WaveConfig,\n    ): boolean {\n      const current = wave.material as TslMaterial;\n      const flags = this.flagsFor(sc);\n      const key = variantKey(flags);\n      if (current.userData.variant === key) return false;\n\n      const rebuilt = buildWaveMaterial(current.userData.tsl, flags) as unknown as TslMaterial;\n      rebuilt.uniforms = current.uniforms;\n      rebuilt.userData = { variant: key, tsl: current.userData.tsl };\n      rebuilt.blending = current.blending;\n      rebuilt.premultipliedAlpha = current.premultipliedAlpha;\n      wave.mesh.material = rebuilt;\n      wave.material = rebuilt;\n      current.dispose();\n      return false; // the mesh already points at a fresh material; nothing to recompile in place\n    }\n\n    // ---- Post chain --------------------------------------------------------------------------\n\n    /** Which effects the config currently asks for — the node twin of applyPost()'s pass juggling. */\n    private postFlags(): PostFlags {\n      const c = this.config;\n      return {\n        bloom: (c.bloomStrength ?? 0) > 0,\n        innerLight: (c.innerLight ?? 0) > 0,\n        halftone: (c.halftone ?? 0) > 0,\n        heatmap: (c.heatmap ?? 0) > 0,\n        halftoneCmyk: (c.halftoneCmyk ?? 0) > 0,\n        paperTexture: (c.paperTexture ?? 0) > 0,\n        dither: (c.dither ?? 0) > 0,\n      };\n    }\n\n    /** Push the config into the post uniforms. Mirrors applyPost() / the per-effect apply* methods. */\n    private syncPostUniforms(): void {\n      const c = this.config;\n      const u = this.postUniforms;\n      u.uBlurAmount.value = c.blur;\n      u.uGrainAmount.value = c.grain;\n      u.uBlurSamples.value = Math.round(c.blurSamples ?? 6);\n      u.uBloomStrength.value = c.bloomStrength ?? 0;\n      u.uBloomRadius.value = c.bloomRadius ?? 0.4;\n      u.uBloomThreshold.value = c.bloomThreshold ?? 0.85;\n      u.uInnerLight.value = c.innerLight ?? 0;\n      u.uInnerLightDensity.value = c.innerLightDensity ?? 0.5;\n      u.uInnerLightDecay.value = c.innerLightDecay ?? 0.95;\n      u.uInnerLightCenter.value.set(c.innerLightX ?? 0.5, c.innerLightY ?? 0.15);\n      u.uHalftone.value = c.halftone ?? 0;\n      u.uHalftoneCell.value = Math.max(2, c.halftoneCell ?? 6);\n      u.uHalftoneAngle.value = c.halftoneAngle ?? 0.4;\n      u.uHeatmap.value = c.heatmap ?? 0;\n      u.uHalftoneCmyk.value = c.halftoneCmyk ?? 0;\n      u.uHalftoneCmykCell.value = Math.max(2, c.halftoneCmykCell ?? 6);\n      u.uPaper.value = c.paperTexture ?? 0;\n      u.uPaperScale.value = Math.max(0.5, c.paperTextureScale ?? 2);\n      u.uDitherStrength.value = c.dither ?? 0;\n      u.uDitherScale.value = Math.max(1, c.ditherScale ?? 2);\n      u.uDitherSteps.value = Math.max(2, Math.round(c.ditherSteps ?? 4));\n    }\n\n    private ensurePost(): RenderPipeline {\n      const flags = this.postFlags();\n      const key = JSON.stringify(flags);\n      if (this.post && key !== this.postFlagsKey) this.disposePost();\n      if (!this.post) {\n        this.postFlagsKey = key;\n        this.post = new RenderPipeline(this.renderer as unknown as WebGPURenderer);\n        // The chain places renderOutput() itself, so the finish-zone effects see display-space\n        // colour exactly as they do after OutputPass on the WebGL path.\n        this.post.outputColorTransform = false;\n        this.post.outputNode = buildPostChain(\n          pass(this.scene, this.camera),\n          this.postUniforms,\n          flags,\n        ) as never;\n      }\n      return this.post;\n    }\n\n    protected override renderComposed(): void {\n      // Fold each wave's array-valued uniforms into its shared packed buffer. The config sync writes\n      // the logical arrays (`u.uColors.value[i].set(...)`) exactly as on the WebGL path; this is the\n      // one extra step that layout needs. Cheap — ~52 vec4s per wave.\n      for (const wave of this.waves) {\n        (wave.material as TslMaterial).userData.tsl.packed.sync();\n      }\n      this.syncPostUniforms();\n      this.ensurePost().render();\n    }\n\n    protected override resizePost(w: number, h: number, dpr: number): void {\n      this.renderer.setPixelRatio(dpr);\n      this.renderer.setSize(w, h, false);\n    }\n\n    protected override disposePost(): void {\n      this.post?.dispose();\n      this.post = undefined;\n    }\n\n    /**\n     * WebGPU exposes no `capabilities` object; the equivalent limit lives on the adapter's device.\n     * Falls back to 8192, the value every WebGPU implementation is required to support, for the\n     * window before `init()` resolves — the base class calls this while sizing the background.\n     */\n    protected override maxTextureSize(): number {\n      const device = (this.renderer as unknown as { backend?: { device?: GPUDevice } }).backend\n        ?.device;\n      return device?.limits?.maxTextureDimension2D ?? 8192;\n    }\n\n    /**\n     * Rebuild the post chain when the background changes.\n     *\n     * A `pass()` node captures the scene's background at the point its render context is first built.\n     * Because the chain is created lazily on the first draw — when `scene.background` is still null —\n     * a background set afterwards would never appear, rendering every non-transparent preset on a\n     * transparent canvas. Background changes are user-driven, not per-frame, so rebuilding here is\n     * cheap; rebuilding every frame (which also works) is not.\n     */\n    protected override onBackgroundChanged(): void {\n      // The node renderer does NOT support a plain Texture background. Background.update() handles\n      // exactly three cases — null, `isColor`, and `isNode` — and anything else hits\n      // \"Renderer: Unsupported background configuration.\" So the gradient / image / video backgrounds,\n      // which the WebGL renderer takes as `scene.background = texture`, have to be re-expressed as a\n      // node. `getBackgroundNode(scene) || scene.background` means backgroundNode wins where set, so\n      // `scene.background` can be left alone for the WebGL path's benefit.\n      const bg = this.scene.background as THREE.Texture | THREE.Color | null;\n      const isTexture = !!bg && (bg as THREE.Texture).isTexture === true;\n      // V is flipped because these background textures are CanvasTextures, which default to\n      // flipY = true. The WebGL background path honours that flag when it draws the texture across\n      // the screen; sampling by screenUV here does not, so the gradient lands mirrored. Costs ~1.4\n      // mae on a gradient-background preset and shows up as concentric banding in a diff.\n      this.scene.backgroundNode = isTexture\n        ? (texture(bg as THREE.Texture).sample(vec2(screenUV.x, screenUV.y.oneMinus())) as never)\n        : null;\n      this.disposePost();\n    }\n  }\n  return WithTslBackend as unknown as TBase;\n}\n\n/** The TSL/WebGPU renderer over the plain {@link WaveRenderer} base — what embeds reach through\n *  `gpu-loader.ts`. A named class (not a bare `withTslBackend(WaveRenderer)` const) so consumers\n *  keep `new WaveRendererGPU(...)`, `instanceof`, and a stable class name. */\nexport class WaveRendererGPU extends withTslBackend(WaveRenderer) {}\n"],"mappings":"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"}

package/dist/renderer/gpu-loader.js

@@ -0,0 +1,2 @@
+import { WaveRendererGPU } from "./WaveRendererGPU.js";
+export { WaveRendererGPU };

package/dist/renderer/index.d.ts

@@ -1,4 +1,5 @@
-import { FRAME_H, FRAME_W, WaveRenderer, WaveRendererOptions, frameZoom, hexToLinearVec3 } from "./WaveRenderer.js";
+import { TiltStatus } from "./tilt.js";
+import { FRAME_H, FRAME_W, WaveMaterial, WaveParticleField, WaveRenderer, WaveRendererOptions, WaveUniforms, frameZoom, hexToLinearVec3 } from "./WaveRenderer.js";
 import { BackgroundGradientOptions, PALETTE_MAPS, PaletteMapDef, PaletteTextureOptions, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildPaletteCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, loadPaletteImage, paletteMapCanvas, paletteSignature, renderMeshGradient } from "./palette.js";
 import { buildHeroPaletteCanvas, buildHeroPaletteTexture } from "./heroPalette.js";
-export { BackgroundGradientOptions, FRAME_H, FRAME_W, PALETTE_MAPS, PaletteMapDef, PaletteTextureOptions, WaveRenderer, WaveRendererOptions, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildHeroPaletteCanvas, buildHeroPaletteTexture, buildPaletteCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, frameZoom, hexToLinearVec3, loadPaletteImage, paletteMapCanvas, paletteSignature, renderMeshGradient };
+export { BackgroundGradientOptions, FRAME_H, FRAME_W, PALETTE_MAPS, PaletteMapDef, PaletteTextureOptions, type TiltStatus, WaveMaterial, WaveParticleField, WaveRenderer, WaveRendererOptions, WaveUniforms, buildBackgroundGradientCanvas, buildBackgroundImageCanvas, buildBackgroundMeshCanvas, buildHeroPaletteCanvas, buildHeroPaletteTexture, buildPaletteCanvas, buildPaletteTexture, canvasToTexture, configurePaletteTexture, drawBackgroundMediaFrame, frameZoom, hexToLinearVec3, loadPaletteImage, paletteMapCanvas, paletteSignature, renderMeshGradient };

package/dist/renderer/interaction.d.ts

@@ -1,4 +1,5 @@
 import { SceneInteractionBinding, StudioConfig, WaveInteractionBinding } from "../config/model.js";
+import { TiltStatus } from "./tilt.js";
 import * as THREE from "three";
 //#region src/renderer/interaction.d.ts
 type AnyBinding = WaveInteractionBinding | SceneInteractionBinding;
@@ -42,6 +43,9 @@ declare class InteractionController {
   private readonly velNdc;
   private presence;
   private presenceTarget;
+  /** Whether a REAL pointer is on the element. Tracked apart from `presenceTarget` because tilt can
+   *  raise presence too (tilt.pointer), and it must yield the moment a finger or cursor shows up. */
+  private pointerPresent;
   private press;
   private pressTarget;
   private pointerSpeed;
@@ -49,6 +53,10 @@ declare class InteractionController {
   private scrollPrev;
   private scrollVel;
   private appearLatched;
+  /** The orientation sensor, built only for a scene that declares `interaction.tilt`. */
+  private tilt;
+  private tiltX;
+  private tiltY;
   private readonly customInputs;
   private readonly ripples;
   private readonly fields;
@@ -70,6 +78,27 @@ declare class InteractionController {
   private spawnRipple;
   /** Advance all smoothed state by `dt` seconds. Called from the render loop with the same delta. */
   update(dt: number): void;
+  /**
+   * Build or drop the tilt sensor as the config declares it, then advance the smoothed axes. The
+   * sensor is created lazily and only for a scene that asked for it, so a cursor-only scene attaches
+   * no orientation listener at all — and a studio edit that adds or removes the block is picked up
+   * on the next frame, the same way the controller itself is.
+   */
+  private updateTilt;
+  /** The sensor, built on first use. Null when the platform has none (every desktop browser). */
+  private ensureTilt;
+  /**
+   * Ask for the orientation sensor, which on iOS 13+ MUST happen inside a user gesture (a tap
+   * handler — not a `setTimeout` or a promise chain that outlives the gesture). Resolves true once
+   * readings can flow. False means the platform has no sensor, the scene declares no `tilt` block,
+   * or the reader refused. Everywhere that needs no permission, tilt is already live and this
+   * simply resolves true.
+   */
+  enableTilt(): Promise<boolean>;
+  /** Where the sensor stands — `"prompt"` is exactly when a tap-to-enable affordance would help. */
+  tiltStatus(): TiltStatus;
+  /** Take the next reading as the neutral pose (the reader has changed grip). */
+  recenterTilt(): void;
   private updateBindings;
   /** Advance one binding's smoothed source value by `dt` and mark it live in `seenBindings`. */
   private advanceBinding;

package/dist/renderer/interaction.js

@@ -1,11 +1,15 @@
 import { clamp01 } from "../util/math.js";
+import { tiltActive } from "./interactionGates.js";
+import { TiltSource } from "./tilt.js";
 import * as THREE from "three";
+//#region src/renderer/interaction.ts
 const RIPPLE_LIFETIME = 1.5;
 const VELOCITY_TAU = .08;
 const POINTER_SPEED_REF = 4;
 const SCROLL_VELOCITY_REF = 2;
 const SCROLL_VELOCITY_TAU = .15;
 const DEFAULT_POINTER_TAU = .12;
+const DEFAULT_TILT_TAU = .18;
 const DEFAULT_BINDING_TAU = .25;
 const POINTER_SPRING_ZETA = .7;
 const MIN_POINTER_TAU = .02;
@@ -132,36 +136,6 @@ const SCENE_APPLIERS = {
 		a.post.uGrainAmount.value = v;
 	})
 };
-/** The global master switch: only `scene.interaction.enabled === false` turns the whole layer off. */
-function notDisabled(cfg) {
-	return cfg.interaction?.enabled !== false;
-}
-/** Whether a wave has a pointer field (hover effects, or a click ripple). */
-function waveHasPointerField(w) {
-	const it = w.interaction;
-	return !!it && (!!it.hover || (it.press?.ripple ?? 0) > 0);
-}
-/** Whether this wave has an active pointer field → its POINTER_FX shader path compiles. */
-function wavePointerFxActive(cfg, w) {
-	return notDisabled(cfg) && waveHasPointerField(w);
-}
-/** Whether this wave has active click ripples → its nested POINTER_RIPPLES path compiles. */
-function waveRipplesActive(cfg, w) {
-	return notDisabled(cfg) && (w.interaction?.press?.ripple ?? 0) > 0;
-}
-/** Whether ANY wave has a pointer field (so the renderer bothers writing the shared pointer uniforms). */
-function anyPointerFxActive(cfg) {
-	return notDisabled(cfg) && cfg.waves.some(waveHasPointerField);
-}
-/** Whether the interaction layer should run at all (any wave interaction, or any scene binding). */
-function interactionActive(cfg) {
-	if (!notDisabled(cfg)) return false;
-	if ((cfg.interaction?.bindings?.length ?? 0) > 0) return true;
-	return cfg.waves.some((w) => {
-		const it = w.interaction;
-		return !!it && (!!it.hover || (it.press?.ripple ?? 0) > 0 || (it.bindings?.length ?? 0) > 0);
-	});
-}
 /**
 * Owns the one cursor's input + scroll + press/appear/custom and all smoothing. Constructed by the
 * renderer when {@link interactionActive} first turns true, disposed when it turns false. All
@@ -178,6 +152,9 @@ var InteractionController = class {
 	velNdc = new THREE.Vector2();
 	presence = 0;
 	presenceTarget = 0;
+	/** Whether a REAL pointer is on the element. Tracked apart from `presenceTarget` because tilt can
+	*  raise presence too (tilt.pointer), and it must yield the moment a finger or cursor shows up. */
+	pointerPresent = false;
 	press = 0;
 	pressTarget = 0;
 	pointerSpeed = 0;
@@ -185,6 +162,10 @@ var InteractionController = class {
 	scrollPrev = 0;
 	scrollVel = 0;
 	appearLatched = false;
+	/** The orientation sensor, built only for a scene that declares `interaction.tilt`. */
+	tilt = null;
+	tiltX = .5;
+	tiltY = .5;
 	customInputs = /* @__PURE__ */ new Map();
 	ripples = [];
 	fields = [];
@@ -224,28 +205,33 @@ var InteractionController = class {
 	}
 	onPointerEnter = (e) => {
 		if (this.ignore(e)) return;
+		this.pointerPresent = true;
 		this.presenceTarget = 1;
 		this.setNdcTarget(e);
 	};
 	onPointerMove = (e) => {
 		if (this.ignore(e)) return;
 		if (e.pointerType === "touch" && this.pressTarget < .5) return;
+		this.pointerPresent = true;
 		this.presenceTarget = 1;
 		this.setNdcTarget(e);
 	};
 	onPointerLeave = (e) => {
 		if (this.ignore(e)) return;
+		this.pointerPresent = false;
 		this.presenceTarget = 0;
 		this.ndcTarget.set(0, 0);
 	};
 	onPointerCancel = (e) => {
 		if (this.ignore(e)) return;
+		this.pointerPresent = false;
 		this.pressTarget = 0;
 		this.presenceTarget = 0;
 		this.ndcTarget.set(0, 0);
 	};
 	onPointerDown = (e) => {
 		if (this.ignore(e)) return;
+		this.pointerPresent = true;
 		this.pressTarget = 1;
 		this.presenceTarget = 1;
 		this.setNdcTarget(e);
@@ -256,6 +242,7 @@ var InteractionController = class {
 		if (this.ignore(e)) return;
 		this.pressTarget = 0;
 		if (e.pointerType === "touch") {
+			this.pointerPresent = false;
 			this.presenceTarget = 0;
 			this.ndcTarget.set(0, 0);
 		}
@@ -279,6 +266,7 @@ var InteractionController = class {
 		if (!cfg) return;
 		const d = Math.max(dt, 0);
 		const kPointer = alpha(DEFAULT_POINTER_TAU, d);
+		this.updateTilt(cfg, d);
 		this.ndcPrev.copy(this.ndc);
 		this.ndc.lerp(this.ndcTarget, kPointer);
 		this.presence += (this.presenceTarget - this.presence) * kPointer;
@@ -322,6 +310,58 @@ var InteractionController = class {
 		}
 		this.updateBindings(cfg, d);
 	}
+	/**
+	* Build or drop the tilt sensor as the config declares it, then advance the smoothed axes. The
+	* sensor is created lazily and only for a scene that asked for it, so a cursor-only scene attaches
+	* no orientation listener at all — and a studio edit that adds or removes the block is picked up
+	* on the next frame, the same way the controller itself is.
+	*/
+	updateTilt(cfg, dt) {
+		if (!tiltActive(cfg)) {
+			if (this.tilt) {
+				this.tilt.dispose();
+				this.tilt = null;
+				this.tiltX = this.tiltY = .5;
+			}
+			return;
+		}
+		const src = this.ensureTilt();
+		if (!src) return;
+		const tiltCfg = cfg.interaction?.tilt;
+		const k = alpha(Math.max(tiltCfg?.smoothing ?? DEFAULT_TILT_TAU, 0), dt);
+		this.tiltX += (src.x - this.tiltX) * k;
+		this.tiltY += (src.y - this.tiltY) * k;
+		if (tiltCfg?.pointer && src.live && !this.pointerPresent) {
+			this.ndcTarget.set(this.tiltX * 2 - 1, -(this.tiltY * 2 - 1));
+			this.presenceTarget = 1;
+		}
+	}
+	/** The sensor, built on first use. Null when the platform has none (every desktop browser). */
+	ensureTilt() {
+		if (!this.tilt && TiltSource.supported()) this.tilt = new TiltSource(() => this.cfg()?.interaction?.tilt);
+		return this.tilt;
+	}
+	/**
+	* Ask for the orientation sensor, which on iOS 13+ MUST happen inside a user gesture (a tap
+	* handler — not a `setTimeout` or a promise chain that outlives the gesture). Resolves true once
+	* readings can flow. False means the platform has no sensor, the scene declares no `tilt` block,
+	* or the reader refused. Everywhere that needs no permission, tilt is already live and this
+	* simply resolves true.
+	*/
+	async enableTilt() {
+		const cfg = this.cfg();
+		if (!cfg || !tiltActive(cfg)) return false;
+		return await this.ensureTilt()?.enable() ?? false;
+	}
+	/** Where the sensor stands — `"prompt"` is exactly when a tap-to-enable affordance would help. */
+	tiltStatus() {
+		if (!TiltSource.supported()) return "unsupported";
+		return this.tilt?.status ?? "prompt";
+	}
+	/** Take the next reading as the neutral pose (the reader has changed grip). */
+	recenterTilt() {
+		this.tilt?.recenter();
+	}
 	updateBindings(cfg, dt) {
 		const seen = this.seenBindings;
 		seen.clear();
@@ -365,6 +405,8 @@ var InteractionController = class {
 			case "press": return this.press;
 			case "scrollVelocity": return clamp01(this.scrollVel / SCROLL_VELOCITY_REF);
 			case "appear": return this.appearLatched ? 1 : 0;
+			case "tiltX": return this.tiltX;
+			case "tiltY": return this.tiltY;
 			default: return this.customInputs.get(source.slice(7)) ?? 0;
 		}
 	}
@@ -409,8 +451,10 @@ var InteractionController = class {
 	*/
 	settle() {
 		this.presence = this.presenceTarget = 0;
+		this.pointerPresent = false;
 		this.press = this.pressTarget = 0;
 		this.pointerSpeed = 0;
+		this.tiltX = this.tiltY = .5;
 		this.velNdc.set(0, 0);
 		this.ndc.set(0, 0);
 		this.ndcTarget.set(0, 0);
@@ -473,11 +517,13 @@ var InteractionController = class {
 		c.removeEventListener("pointercancel", this.onPointerCancel);
 		c.removeEventListener("pointerdown", this.onPointerDown);
 		c.removeEventListener("pointerup", this.onPointerUp);
+		this.tilt?.dispose();
+		this.tilt = null;
 		this.customInputs.clear();
 		this.bindingState.clear();
 	}
 };
 //#endregion
-export { InteractionController, SCENE_APPLIERS, WAVE_APPLIERS, anyPointerFxActive, interactionActive, wavePointerFxActive, waveRipplesActive };
+export { InteractionController, SCENE_APPLIERS, WAVE_APPLIERS };
 
 //# sourceMappingURL=interaction.js.map