rayzee 7.20.3 → 7.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.20.3",
+  "version": "7.21.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -21,7 +21,6 @@ export const ENGINE_DEFAULTS = {
 	enableEnvironment: true,
 	showBackground: true,
 	transparentBackground: false,
-	useImportanceSampledEnvironment: true,
 	environmentIntensity: 1,
 	backgroundIntensity: 1,
 	// Solid backdrop color shown on camera-ray misses in 'color' background mode
@@ -164,7 +163,9 @@ export const ENGINE_DEFAULTS = {
 	asvgfPhiDepth: 1.0,
 	asvgfVarianceBoost: 1.0,
 	asvgfMaxAccumFrames: 32,
-	asvgfGradientStrength: 0.0,
+	// Must be > 0: the gradient also rejects fireflies before the EMA smears them across
+	// ~1/alpha frames. At 0 the denoiser measures ~3x worse than no denoiser at 1 spp.
+	asvgfGradientStrength: 1.0,
 	asvgfGradientSigmaScale: 2.0,
 	asvgfGradientNoiseFloor: 0.0,
 	asvgfDebugMode: 0,

package/src/PathTracerApp.js

@@ -1562,6 +1562,11 @@ export class PathTracerApp extends EventDispatcher {
 			this.cameraManager?.setAutoFocusMode( 'manual' );
 			if ( this.stages.autoExposure ) this.stages.autoExposure.enabled = false;
 
+			// The seed axis free-runs across accumulation resets so a camera drag gets fresh
+			// sequences; offline rendering needs the opposite. Pinning it makes seedFrame track
+			// frameCount, so N samples reproduce bit-for-bit. reset() below zeroes the tick.
+			stage._pinSeedToFrame = true;
+
 			this._deterministic = true;
 			this._dispatchPinned = pinDispatch;
 
@@ -1580,6 +1585,8 @@ export class PathTracerApp extends EventDispatcher {
 
 			}
 
+			stage._pinSeedToFrame = false;
+
 			this._deterministicRestore = null;
 			this._deterministic = false;
 			this._dispatchPinned = false;

package/src/Pipeline/BindingAudit.js

@@ -0,0 +1,178 @@
+/**
+ * Dev-only guard against texture-binding aliasing.
+ *
+ * Two TextureNodes still holding the default EmptyTexture when a stage's kernel is first
+ * compiled can share one GPU binding, which then resolves to whichever is assigned last.
+ * Nothing throws — the aliased node reads a real texture, just not its own. BilateralFilter
+ * shipped this way, reading ASVGF's history counter as its variance.
+ *
+ * Rule enforced: every TextureNode a kernel reads must hold its real texture before that
+ * kernel is first dispatched. StorageTexture-typed nodes are exempt — `textureLoad` codegen
+ * only emits the required `level` parameter while the node still holds EmptyTexture, so those
+ * are deliberately bound after compile (see ASVGF.render).
+ *
+ * Off by default; the bench harness turns it on.
+ */
+
+let enabled = false;
+const findings = [];
+
+/** Per-stage audit state. WeakMap so a disposed stage does not pin its entry. */
+const stageState = new WeakMap();
+
+/**
+ * @param {boolean} on
+ */
+export function setBindingAudit( on ) {
+
+	enabled = !! on;
+
+}
+
+export function isBindingAuditEnabled() {
+
+	return enabled;
+
+}
+
+/** @returns {Array<{stage: string, nodes: string[], unboundAtCompile: string[], message: string}>} */
+export function getBindingAuditFindings() {
+
+	return findings.slice();
+
+}
+
+export function clearBindingAuditFindings() {
+
+	findings.length = 0;
+
+}
+
+/** Own enumerable properties holding a TSL TextureNode. */
+function textureNodeKeys( stage ) {
+
+	const keys = [];
+
+	for ( const key of Object.keys( stage ) ) {
+
+		if ( stage[ key ]?.isTextureNode === true ) keys.push( key );
+
+	}
+
+	return keys;
+
+}
+
+// EmptyTexture (the TextureNode default) is a bare `new Texture()`, so its image is null.
+// Every real texture the stages bind — RenderTarget textures and StorageTextures alike —
+// carries an image with a nonzero width.
+const isUnbound = ( texture ) => ! texture || ! texture.image || ! ( texture.image.width > 0 );
+
+/**
+ * Runs a stage's render with the audit wrapped around it.
+ *
+ * The snapshot must be taken when the stage first calls `renderer.compute`, not before or
+ * after render() — the binding assignments and the compile are interleaved inside that one
+ * call, so by the time it returns everything is bound. Sampling after render() was the first
+ * version of this guard and it silently caught nothing.
+ *
+ * A later frame then resolves: a candidate now holding a StorageTexture is the sanctioned
+ * pattern; anything else was bound too late.
+ *
+ * @param {Object} stage
+ * @param {Object} renderer
+ * @param {function(): void} renderFn
+ */
+export function auditStageRender( stage, renderer, renderFn ) {
+
+	if ( ! enabled ) {
+
+		renderFn();
+		return;
+
+	}
+
+	let state = stageState.get( stage );
+
+	if ( ! state ) {
+
+		state = { phase: 'pending', unboundAtCompile: [] };
+		stageState.set( stage, state );
+
+	}
+
+	if ( state.phase !== 'pending' ) {
+
+		renderFn();
+		if ( state.phase === 'watch' ) resolve( stage, state );
+		return;
+
+	}
+
+	// Shadow the prototype method for the duration of this stage's render only.
+	const hadOwn = Object.prototype.hasOwnProperty.call( renderer, 'compute' );
+	const original = renderer.compute;
+
+	renderer.compute = function ( ...args ) {
+
+		if ( state.phase === 'pending' ) {
+
+			state.unboundAtCompile = textureNodeKeys( stage )
+				.filter( ( key ) => isUnbound( stage[ key ].value ) );
+
+			// A single unbound node has nothing to alias with, so it cannot produce this bug.
+			state.phase = state.unboundAtCompile.length < 2 ? 'done' : 'watch';
+
+		}
+
+		return original.apply( this, args );
+
+	};
+
+	try {
+
+		renderFn();
+
+	} finally {
+
+		if ( hadOwn ) renderer.compute = original;
+		else delete renderer.compute;
+
+	}
+
+}
+
+function resolve( stage, state ) {
+
+	const lateBound = [];
+
+	for ( const key of state.unboundAtCompile ) {
+
+		const texture = stage[ key ]?.value;
+
+		// Still unassigned — the stage may bind it on a later frame (or never, which is also
+		// not this bug). Leave the audit open rather than guessing.
+		if ( isUnbound( texture ) ) return;
+
+		if ( texture.isStorageTexture !== true ) lateBound.push( key );
+
+	}
+
+	state.phase = 'done';
+
+	if ( lateBound.length === 0 ) return;
+
+	findings.push( {
+		stage: stage.name,
+		nodes: lateBound,
+		unboundAtCompile: state.unboundAtCompile.slice(),
+		message:
+			`${stage.name}: ${lateBound.join( ', ' )} ` +
+			`${lateBound.length === 1 ? 'was' : 'were'} still holding EmptyTexture when the stage ` +
+			`first dispatched, alongside ${state.unboundAtCompile.length - lateBound.length} ` +
+			'other unbound node(s), and later received a non-storage texture. Two nodes unbound at ' +
+			'compile time can share one GPU binding and then both resolve to whichever is assigned ' +
+			'last. Assign these before the first dispatch.',
+	} );
+
+}

package/src/Pipeline/RenderPipeline.js

@@ -1,5 +1,6 @@
 import { PipelineContext } from './PipelineContext.js';
 import { EventDispatcher } from './EventDispatcher.js';
+import { auditStageRender } from './BindingAudit.js';
 
 /**
  * RenderPipeline - Orchestrates execution of pipeline stages
@@ -183,8 +184,10 @@ export class RenderPipeline {
 
 				const stageStartTime = this.stats.enabled ? performance.now() : 0;
 
-				// Execute stage
-				stage.render( this.context, writeBuffer );
+				// Pass-through unless setBindingAudit(true) — see BindingAudit.js.
+				auditStageRender(
+					stage, this.renderer, () => stage.render( this.context, writeBuffer )
+				);
 
 				// Track timing
 				if ( this.stats.enabled ) {

package/src/Processor/CameraOptimizer.js

@@ -24,7 +24,6 @@ export class CameraOptimizer {
 		// Enhanced interaction mode settings for reduced quality during interaction
 		this.interactionQualitySettings = {
 			maxBounceCount: 1,
-			useEnvMapIS: false,
 			// pixelRatio: 0.25,
 			enableAccumulation: false,
 			...settings.qualitySettings
@@ -303,25 +302,21 @@ export class CameraOptimizer {
 		const presets = {
 			'ultra-low': {
 				maxBounceCount: 1,
-				useEnvMapIS: false,
 				pixelRatio: 0.125,
 				enableAccumulation: false
 			},
 			'low': {
 				maxBounceCount: 1,
-				useEnvMapIS: false,
 				pixelRatio: 0.25,
 				enableAccumulation: false
 			},
 			'medium': {
 				maxBounceCount: 2,
-				useEnvMapIS: true,
 				pixelRatio: 0.5,
 				enableAccumulation: false
 			},
 			'high': {
 				maxBounceCount: 3,
-				useEnvMapIS: true,
 				pixelRatio: 0.75,
 				enableAccumulation: true
 			}

package/src/Processor/PackedRayBuffer.js

@@ -5,7 +5,7 @@
 
 import {
 	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int, float, clamp,
-	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16,
+	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16, select, floor, log2, exp2, max,
 } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { createLogger, fmt } from '../utils/Logger.js';
@@ -186,13 +186,38 @@ export const gbDecodeAlbedo = ( packed ) =>
 // .w packs per-ray bounce state: perRayBounces (bits 0-7) | sssSteps (bits 8-15) | transparentCount
 // (bits 16-21), each masked so an overrun can't bleed into its neighbour. pixelIndex is NOT stored —
 // it equals rayID (one ray per pixel).
-export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps, transparentCount = uint( 0 ) ) =>
-	buf.element( soa( id, RAY.ORIGIN_META ) )
-		.assign( vec4( origin, uintBitsToFloat(
-			uint( bounces ).bitAnd( uint( 0xFF ) )
-				.bitOr( uint( sssSteps ).bitAnd( uint( 0xFF ) ).shiftLeft( 8 ) )
-				.bitOr( uint( transparentCount ).bitAnd( uint( 0x3F ) ).shiftLeft( 16 ) )
-		) ) );
+// Bits 22-31 of ORIGIN_META.w: alpha-passthrough distance since the last real scatter (Cycles'
+// mis_ray_t), as a 10-bit float (4e6m, bias 8, ~0.004-500 range, ≤1.6% rel err). The emissive-hit
+// MIS partner pdf must be evaluated at the scatter point that produced prevBouncePdf, not at the
+// last skip surface — feeding it the skip origin collapses dist² and lets full-Le BSDF hits
+// through nearly unweighted (fireflies on emitters inside alpha-blend shades).
+const encodeMisRayT = ( t ) => {
+
+	const e = clamp( floor( log2( max( t, 1e-6 ) ) ), - 8.0, 7.0 );
+	const m = clamp( float( t ).mul( exp2( e.negate() ) ).sub( 1.0 ).mul( 64.0 ), 0.0, 63.0 );
+	return select( float( t ).lessThan( 0.004 ), uint( 0 ), uint( e.add( 8.0 ) ).shiftLeft( 6 ).bitOr( uint( m ) ) );
+
+};
+
+export const readMisRayT = ( buf, id ) => {
+
+	const bits = floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).shiftRight( 22 );
+	const e = float( bits.shiftRight( 6 ).bitAnd( uint( 15 ) ) ).sub( 8.0 );
+	const m = float( bits.bitAnd( uint( 63 ) ) ).div( 64.0 ).add( 1.0 );
+	return select( bits.equal( uint( 0 ) ), float( 0.0 ), m.mul( exp2( e ) ) );
+
+};
+
+export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps, transparentCount = uint( 0 ), misRayT = null ) => {
+
+	let packed = uint( bounces ).bitAnd( uint( 0xFF ) )
+		.bitOr( uint( sssSteps ).bitAnd( uint( 0xFF ) ).shiftLeft( 8 ) )
+		.bitOr( uint( transparentCount ).bitAnd( uint( 0x3F ) ).shiftLeft( 16 ) );
+	if ( misRayT !== null ) packed = packed.bitOr( encodeMisRayT( misRayT ).shiftLeft( 22 ) );
+	return buf.element( soa( id, RAY.ORIGIN_META ) )
+		.assign( vec4( origin, uintBitsToFloat( packed ) ) );
+
+};
 
 export const writeRayDirFlags = ( buf, id, direction, bounceFlags ) =>
 	buf.element( soa( id, RAY.DIR_FLAGS ) )

package/src/Stages/ASVGF.js

@@ -40,7 +40,8 @@ export class ASVGF extends RenderStage {
 		this.renderer = renderer;
 
 		this.temporalAlpha = uniform( options.temporalAlpha ?? 0.0 );
-		this.gradientStrength = uniform( options.gradientStrength ?? 0.0 );
+		// > 0 is required for firefly rejection, not just anti-lag — see ENGINE_DEFAULTS.
+		this.gradientStrength = uniform( options.gradientStrength ?? 1.0 );
 		// σ multiplier for the per-pixel noise floor (NRD luminanceSigmaScale ≈ 2).
 		this.gradientSigmaScale = uniform( options.gradientSigmaScale ?? 2.0 );
 		// Secondary relative floor on the normalised gradient (0 = rely on σ alone).
@@ -380,7 +381,12 @@ export class ASVGF extends RenderStage {
 			If( gx.lessThan( int( resW ) ).and( gy.lessThan( int( resH ) ) ), () => {
 
 				const coord = ivec2( gx, gy );
-				const currentColor = textureLoad( colorTex, coord ).xyz;
+				const currentSample = textureLoad( colorTex, coord );
+				const currentColor = currentSample.xyz;
+				// Coverage from the path tracer — 0 on background rays when
+				// transparentBackground is on. Forcing 1.0 here made the whole frame opaque,
+				// so a transparent render composited as black.
+				const currentAlpha = currentSample.w;
 				const currentAlbedo = textureLoad( albedoTex, coord ).xyz;
 
 				// Same safeAlbedo on both demod and re-mod sides → exact
@@ -390,7 +396,7 @@ export class ASVGF extends RenderStage {
 
 				// Defaults = fresh sample (no temporal blend).
 				const demodResult = vec4( currentLighting, 1.0 ).toVar();
-				const modulatedResult = vec4( currentColor, 1.0 ).toVar();
+				const modulatedResult = vec4( currentColor, currentAlpha ).toVar();
 
 				// forceResetU skips the blend for one frame after asvgf:reset → re-anchors
 				// history to the current (post-reset) scene instead of the stale ping-pong.
@@ -491,7 +497,7 @@ export class ASVGF extends RenderStage {
 							const newHistory = min( prevHistory.add( 1.0 ), maxAccumFrames );
 
 							demodResult.assign( vec4( blendedLighting, newHistory ) );
-							modulatedResult.assign( vec4( blendedLighting.mul( safeAlbedo ), 1.0 ) );
+							modulatedResult.assign( vec4( blendedLighting.mul( safeAlbedo ), currentAlpha ) );
 
 						} );
 
@@ -643,12 +649,6 @@ export class ASVGF extends RenderStage {
 
 		this.on( 'asvgf:reset', () => this.resetTemporalData() );
 
-		this.on( 'asvgf:setTemporal', ( data ) => {
-
-			if ( data && data.enabled !== undefined ) this.setTemporalEnabled( data.enabled );
-
-		} );
-
 		this.on( 'asvgf:updateParameters', ( data ) => this.updateParameters( data ) );
 
 	}

package/src/Stages/BilateralFilter.js

@@ -24,7 +24,9 @@ const bilateralWeight = /*@__PURE__*/ wgslFn( `
 		let lumW = exp( -abs( centerLum - sLum ) / sigmaL );
 		// clamp dot to [0,1]: miss-ray normals decode to (-1,-1,-1) with
 		// dot=3 → pow saturates to +inf → inf*0 = NaN. See project_tsl_pitfalls.
-		let normW = pow( clamp( dot( centerNormal, sNormal ), 0.0, 1.0 ), phiNorm );
+		// max(phiNorm, 1e-6): pow(0.0, 0.0) is undefined in WGSL and returned NaN on ~12%
+		// of pixels when phiNormal was set to 0.
+		let normW = pow( clamp( dot( centerNormal, sNormal ), 0.0, 1.0 ), max( phiNorm, 1e-6 ) );
 		let depW = exp( -abs( centerDepth - sDepth ) / max( centerDepth * phiDep, 0.001 ) );
 		let maxDiff = max( max( abs( centerColor.x - sColor.x ),
 			abs( centerColor.y - sColor.y ) ),
@@ -79,6 +81,8 @@ export class BilateralFilter extends RenderStage {
 		this.stepSizeU = uniform( 1, 'int' );
 		// 1 on the final iteration → multiply by albedo to remodulate.
 		this.isLastIterationU = uniform( 0, 'int' );
+		// 1 on pass 0 → seed variance from variance:output; later passes read the carried value.
+		this.isFirstIterationU = uniform( 1, 'int' );
 		this.resW = uniform( options.width || 1 );
 		this.resH = uniform( options.height || 1 );
 
@@ -87,6 +91,8 @@ export class BilateralFilter extends RenderStage {
 		this._shadingNormalTexNode = new TextureNode();
 		this._albedoTexNode = new TextureNode();
 		this._varianceTexNode = new TextureNode();
+		// pathtracer:color, read only for its alpha (coverage) on the final pass.
+		this._srcAlphaTexNode = new TextureNode();
 
 		const w = options.width || 1;
 		const h = options.height || 1;
@@ -144,6 +150,7 @@ export class BilateralFilter extends RenderStage {
 		const snTexNode = this._shadingNormalTexNode;
 		const albedoTexNode = this._albedoTexNode;
 		const varTexNode = this._varianceTexNode;
+		const srcAlphaTexNode = this._srcAlphaTexNode;
 		const phiColor = this.phiColor;
 		const phiNormal = this.phiNormal;
 		const phiDepth = this.phiDepth;
@@ -151,6 +158,7 @@ export class BilateralFilter extends RenderStage {
 		const spatialVarianceWeight = this.spatialVarianceWeight;
 		const stepSize = this.stepSizeU;
 		const isLastIterationU = this.isLastIterationU;
+		const isFirstIterationU = this.isFirstIterationU;
 		const resW = this.resW;
 		const resH = this.resH;
 
@@ -173,7 +181,8 @@ export class BilateralFilter extends RenderStage {
 			If( gx.lessThan( int( resW ) ).and( gy.lessThan( int( resH ) ) ), () => {
 
 				const coord = ivec2( gx, gy );
-				const centerColor = textureLoad( readTexNode, coord ).xyz;
+				const centerSample = textureLoad( readTexNode, coord );
+				const centerColor = centerSample.xyz;
 				const centerND = textureLoad( ndTexNode, coord );
 				// Normal edge-stop reads the mapped (shading) normal; depth gate stays geometric.
 				const centerNormal = textureLoad( snTexNode, coord ).xyz.mul( 2.0 ).sub( 1.0 );
@@ -182,22 +191,43 @@ export class BilateralFilter extends RenderStage {
 				const centerSafeAlbedo = max( textureLoad( albedoTexNode, coord ).xyz, vec3( ALBEDO_EPS ) );
 				const centerAlbedoLum = max( luminance( centerSafeAlbedo ), float( ALBEDO_EPS ) ).toVar();
 
+				// Variance is filtered alongside colour and carried between passes in the
+				// ping-pong's spare alpha, so sigma_l tightens as the signal smooths. Without
+				// it every pass re-read the unfiltered variance:output and filter strength
+				// never backed off as the render converged.
+				//
+				// Stored as the ROOT: converged variance reaches ~1e-6, a half-float subnormal
+				// that flushes to zero on some drivers. select() rather than If() — an If
+				// around a texture read lets the inactive branch contaminate the result.
+				// .z = temporal, .w = spatial 3×3; blending toward max widens sigma_l where
+				// history is thin.
+				const isFirst = isFirstIterationU.equal( int( 1 ) );
+				const seedVariance = ( at ) => {
+
+					const v = textureLoad( varTexNode, at );
+					return mix( v.z, max( v.z, v.w ), spatialVarianceWeight );
+
+				};
+
+				const centerVariance = isFirst.select(
+					seedVariance( coord ),
+					centerSample.w.mul( centerSample.w )
+				).toVar();
+
 				// sigma_l = phiLum * √variance / albedoLum + ε. Dividing by
 				// albedoLum compensates for the 1/albedo noise amplification
 				// from demodulation — otherwise dark materials get an
 				// under-estimated sigma → over-strict luminance gate → no
 				// blending → silhouette dark-outline artifact.
-				// .z = temporal variance, .w = spatial (3×3) variance. Blend toward
-				// max(temporal, spatial) so disoccluded/low-history pixels widen sigma_l.
-				const vSample = textureLoad( varTexNode, coord );
-				const variance = mix( vSample.z, max( vSample.z, vSample.w ), spatialVarianceWeight );
 				const sigmaL = phiLuminance
-					.mul( sqrt( max( variance, float( 0.0 ) ) ) )
+					.mul( sqrt( max( centerVariance, float( 0.0 ) ) ) )
 					.div( centerAlbedoLum )
 					.add( float( 0.0001 ) );
 
 				const colorSum = vec3( 0.0 ).toVar();
 				const weightSum = float( 0.0 ).toVar();
+				// Squared weights, normalised by weightSum² — the variance of a weighted mean.
+				const varianceSum = float( 0.0 ).toVar();
 
 				// 5×5 à-trous kernel (Gaussian-approx, Σ=1)
 				for ( let iy = 0; iy < 5; iy ++ ) {
@@ -213,7 +243,8 @@ export class BilateralFilter extends RenderStage {
 						const sy = gy.add( stepSize.mul( dy ) )
 							.clamp( int( 0 ), int( resH ).sub( 1 ) );
 
-						const sColor = textureLoad( readTexNode, ivec2( sx, sy ) ).xyz;
+						const sSample = textureLoad( readTexNode, ivec2( sx, sy ) );
+						const sColor = sSample.xyz;
 						const sND = textureLoad( ndTexNode, ivec2( sx, sy ) );
 						const sNormal = textureLoad( snTexNode, ivec2( sx, sy ) ).xyz.mul( 2.0 ).sub( 1.0 );
 						const sDepth = sND.w;
@@ -228,24 +259,39 @@ export class BilateralFilter extends RenderStage {
 							sigmaL, phiNormal, phiDepth, phiColor
 						);
 
+						const sVariance = isFirst.select(
+							seedVariance( ivec2( sx, sy ) ),
+							sSample.w.mul( sSample.w )
+						);
+
 						colorSum.addAssign( sColor.mul( w ) );
 						weightSum.addAssign( w );
+						varianceSum.addAssign( w.mul( w ).mul( max( sVariance, float( 0.0 ) ) ) );
 
 					}
 
 				}
 
 				const filtered = colorSum.div( max( weightSum, float( 0.0001 ) ) );
+				const filteredVariance = varianceSum
+					.div( max( weightSum.mul( weightSum ), float( 1e-8 ) ) );
 
 				// Remodulate by albedo only on the final iteration so the
 				// inner ping-pong stays in demodulated space.
 				const isLast = isLastIterationU.equal( int( 1 ) );
 				const output = isLast.select( filtered.mul( centerSafeAlbedo ), filtered );
 
+				// The last pass restores the path tracer's coverage — Compositor reads .w as
+				// image alpha when transparentBackground is on.
+				const carriedAlpha = isLast.select(
+					textureLoad( srcAlphaTexNode, coord ).w,
+					sqrt( max( filteredVariance, float( 0.0 ) ) )
+				);
+
 				textureStore(
 					writeStorageTex,
 					uvec2( uint( gx ), uint( gy ) ),
-					vec4( output, 1.0 )
+					vec4( output, carriedAlpha )
 				).toWriteOnly();
 
 			} );
@@ -271,6 +317,7 @@ export class BilateralFilter extends RenderStage {
 		const snTex = context.getTexture( this.shadingNormalTextureName ) || ndTex;
 		const albedoTex = context.getTexture( this.albedoTextureName );
 		const varTex = context.getTexture( this.varianceTextureName );
+		const srcAlphaTex = context.getTexture( 'pathtracer:color' );
 
 		if ( ! inputTex ) return;
 
@@ -291,6 +338,18 @@ export class BilateralFilter extends RenderStage {
 		if ( ndTex ) this._normalDepthTexNode.value = ndTex;
 		if ( snTex ) this._shadingNormalTexNode.value = snTex;
 		if ( albedoTex ) this._albedoTexNode.value = albedoTex;
+		// Bind these BEFORE compile too: two TextureNodes still holding the default empty
+		// texture when the node builder runs share one GPU binding, which then resolves to
+		// whichever is assigned last. That aliased varTexNode onto the colour input.
+		//
+		// Safe only because inputTex is a RenderTarget texture, which produces the same
+		// `textureLoad(t, coord, level)` codegen as EmptyTexture — the form the StorageTexture
+		// ping-pong needs on passes 1+. Binding an actual StorageTexture here would emit the
+		// no-level form and later reads would return zero. EdgeFilter must NOT do this: its
+		// pass-0 input IS a StorageTexture.
+		this._readTexNode.value = inputTex;
+		if ( varTex ) this._varianceTexNode.value = varTex;
+		if ( srcAlphaTex ) this._srcAlphaTexNode.value = srcAlphaTex;
 
 		// First-frame compile while StorageTexture-typed nodes still hold
 		// EmptyTexture — codegen then emits textureLoad with the level
@@ -303,8 +362,6 @@ export class BilateralFilter extends RenderStage {
 
 		}
 
-		if ( varTex ) this._varianceTexNode.value = varTex;
-
 		// À-trous iterations: step size 2^i, ping-pong write direction.
 		// Last iteration multiplies by albedo to remodulate.
 		let readTex = inputTex;
@@ -316,6 +373,7 @@ export class BilateralFilter extends RenderStage {
 			this.stepSizeU.value = 1 << i;
 			this._readTexNode.value = readTex;
 			this.isLastIterationU.value = ( i === this.iterations - 1 ) ? 1 : 0;
+			this.isFirstIterationU.value = i === 0 ? 1 : 0;
 
 			this.renderer.compute( writeNode );
 
@@ -420,6 +478,7 @@ export class BilateralFilter extends RenderStage {
 		this._shadingNormalTexNode?.dispose();
 		this._albedoTexNode?.dispose();
 		this._varianceTexNode?.dispose();
+		this._srcAlphaTexNode?.dispose();
 
 	}