rayzee 7.16.0 → 7.18.0

package/src/TSL/ShadeKernel.js

@@ -7,7 +7,7 @@
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
 	bool as tslBool,
-	If, Loop, normalize, max, exp, log, clamp, dot, length, select,
+	If, Loop, normalize, max, exp, log, clamp, dot, length, select, smoothstep, mix,
 	instanceIndex,
 	sampler,
 	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
@@ -27,7 +27,8 @@ import { sampleChromaticCollision, sampleHenyeyGreenstein, subsurfaceCoefficient
 import { calculateIndirectLighting } from './LightsIndirect.js';
 import { IndirectLightingResult, sampleCone } from './LightsCore.js';
 import { regularizePathContribution, generateSampledDirection, computeNDCDepth, handleRussianRoulette } from './PathTracerCore.js';
-import { getImportanceSamplingInfo } from './MaterialProperties.js';
+import { getImportanceSamplingInfo, evaluateDFG } from './MaterialProperties.js';
+import { dielectricF0 } from './Fresnel.js';
 import { sampleClearcoat, ClearcoatResult } from './Clearcoat.js';
 import { refineDisplacedIntersection, DisplacementResult } from './Displacement.js';
 import { calculateEmissiveTriangleContribution, calculateEmissiveLightPdf, EmissiveSample } from './EmissiveSampling.js';
@@ -44,6 +45,7 @@ import {
 	BRDFWeights,
 	MaterialCache,
 	DirectLightingDual,
+	DFGResult,
 } from './Struct.js';
 import { RandomValue, getRandomSample } from './Random.js';
 import { RAY_FLAG, COUNTER } from '../Processor/QueueManager.js';
@@ -51,11 +53,13 @@ import {
 	readRayOrigin, readRayDirection, readRayBounceFlags, readRayThroughput, readRayPdf,
 	readMediumStack, writeMediumStack, readMediumSigmaA, writeMediumSigmaA,
 	readPathBounces, readSssSteps, readSSSMedium, writeSSSMedium,
+	readTransparentCount,
 	readHitDistance, readHitBarycentrics, readHitNormal,
 	readHitMaterialIndex, readHitTriangleIndex,
 	writeRayOriginMeta, writeRayDirFlags, writeRayThroughputPdf, writeRayRadiance,
-	writeGBuffer, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
+	writeGBuffer, readGBuffer, gbDecodeNormalDepth,
 	readRayRadiance,
+	readFeatureThroughput, writeFeatureThroughput,
 } from '../Processor/PackedRayBuffer.js';
 
 const WG_SIZE = 256;
@@ -85,11 +89,13 @@ export function buildShadeKernel( params ) {
 		pointLightsBuffer, numPointLights,
 		spotLightsBuffer, numSpotLights,
 		maxBounceCount, maxSubsurfaceSteps,
+		maxTransparentBounces, // guard on alpha-skip depth; counter in ORIGIN_META.w
 		currentBounce, // loop iteration = path length (advances on free bounces); drives RR/firefly/giScale
 		transparentBackground, backgroundIntensity, backgroundColor, backgroundBlurriness, backgroundBlurSamples, showBackground,
 		globalIlluminationIntensity,
 		cameraProjectionMatrix, cameraViewMatrix,
 		fireflyThreshold, frame, resolution,
+		chunkRowBase, // chunked path pool: global pixel = chunkRowBase·W + localSlot (rayID). See spec.
 		emissiveTriangleCount, emissiveVec4Offset, emissiveTotalPower,
 		emissiveBoost, totalTriangleCount, enableEmissiveTriangleSampling,
 		lightBVHNodeCount, reverseMapVec4Offset,
@@ -183,6 +189,11 @@ export function buildShadeKernel( params ) {
 		const pixelIndex = rayID;
 		const rngState = rngBufferRW.element( rayID ).toVar();
 
+		// DDFA see-through aux tint carried across smooth glass/mirror; committed into the OIDN/ASVGF
+		// albedo guide at the first diffuse-enough surface (or env). Mutated locally, persisted on every
+		// deferring continue (a missed persist = stale tint). 1 = untinted (direct hit → today's albedo).
+		const featCarry = readFeatureThroughput( rayBufferRW, rayID ).toVar();
+
 		const hitDist = readHitDistance( hitBufferRO, rayID ).toVar();
 		const hitNormal = readHitNormal( hitBufferRO, rayID ).toVar();
 		// hitInfo.uv is the interpolated texture UV (not barycentrics)
@@ -195,6 +206,7 @@ export function buildShadeKernel( params ) {
 		// path length = loop iteration (advances every bounce incl. transmissive/SSS); drives RR/firefly/giScale/MIS. Megakernel: loop counter i.
 		const bounceIndex = int( currentBounce ).toVar();
 		const sssSteps = readSssSteps( rayBufferRW, rayID ).toVar();
+		const transparentCount = readTransparentCount( rayBufferRW, rayID ).toVar();
 
 		// ── Analytic ground-plane shadow catcher (primary ray only, no geometry) ──
 		// A horizontal plane at y = groundCatcherHeight. For a bounce-0 ray that crosses it
@@ -309,7 +321,8 @@ export function buildShadeKernel( params ) {
 					} );
 
 					writeRayRadiance( rayBufferRW, rayID, vec4( outRgb, outAlpha ) );
-					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
+					// DDFA: the plane's aux (written above) is a committed surface — lock it (cosmetic; ray dies here).
+					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ).bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
 					rngBufferRW.element( rayID ).assign( rngState );
 					Return();
 
@@ -333,9 +346,8 @@ export function buildShadeKernel( params ) {
 			const wantBackdrop = isBackdropView.and( showBackground ); // draw env image as backdrop
 			const wantEnvLight = isBackdropView.not().and( enableEnvironmentLight ); // env as light on redirected bounces
 
-			// Fix ①: OIDN clean-aux for a redirected ray that escapes to the environment (e.g. smooth
-			// glass over sky). Holds the clamped env colour this ray sees; written into the aux G-buffer
-			// before the miss Return below, but only when the pixel still carries the black bounce-0 default.
+			// DDFA: env colour a redirected ray escaping to the environment sees (e.g. smooth glass over
+			// sky). Committed (tinted by featCarry) into the aux G-buffer before the miss Return below.
 			const escapedAuxAlbedo = vec3( 0.0 ).toVar();
 
 			If( wantBackdrop.or( wantEnvLight ), () => {
@@ -376,8 +388,8 @@ export function buildShadeKernel( params ) {
 
 				} );
 
-				// Fix ①: remember the (clamped) env colour this escaped ray sees, so a redirected ray
-				// that never captured a surface aux can feed OIDN a meaningful albedo below.
+				// DDFA: remember the (clamped) env colour this escaped ray sees, for the redirected-escape
+				// aux commit below (tinted by the accumulated see-through throughput).
 				escapedAuxAlbedo.assign( clamp( envColor, vec3( 0.0 ), vec3( 1.0 ) ) );
 
 				// MIS weight for implicit env hit — prevents double-counting with NEE
@@ -447,22 +459,18 @@ export function buildShadeKernel( params ) {
 
 			} );
 
-			// Fix ①: fill the black bounce-0 default aux for a redirected ray that reached the
-			// environment without ever locking a surface guide (smooth glass / specular transmission
-			// over sky). Only when the stored albedo is still the black default (dot < 1e-4), so a real
-			// specular-surface aux written upstream is never clobbered. Normal = the escaped ray
-			// direction (varies per pixel → OIDN sees structure that tracks the refracted view);
-			// albedo = the clamped env colour it sees; depth kept at the primary hit.
+			// DDFA: a redirected ray (specular chain — glass/mirror) that escaped to the environment without
+			// ever committing a surface guide commits the env colour it sees, tinted by the accumulated
+			// see-through throughput (red glass over sky → sky×red). Normal = the escaped direction (varies
+			// per pixel → OIDN sees structure tracking the refracted view); depth kept at the primary hit.
+			// AUX_LOCKED-clear alone means "never committed" — the old black-probe is redundant. A direct
+			// backdrop (REDIRECTED clear) keeps Generate's black/far default (regression-safe sky guide).
 			If( auxOn
 				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
 				.and( flags.bitAnd( uint( RAY_FLAG.REDIRECTED ) ).notEqual( uint( 0 ) ) ), () => {
 
 				const gPrev = readGBuffer( gBufferRW, pixelIndex );
-				If( dot( gbDecodeAlbedo( gPrev ), vec3( 1.0 ) ).lessThan( float( 1e-4 ) ), () => {
-
-					writeGBuffer( gBufferRW, pixelIndex, normalize( direction ), gbDecodeNormalDepth( gPrev ).w, escapedAuxAlbedo );
-
-				} );
+				writeGBuffer( gBufferRW, pixelIndex, normalize( direction ), gbDecodeNormalDepth( gPrev ).w, clamp( escapedAuxAlbedo.mul( featCarry ), vec3( 0.0 ), vec3( 1.0 ) ) );
 
 			} );
 
@@ -496,7 +504,14 @@ export function buildShadeKernel( params ) {
 			If( max( max( mSigmaS.x, mSigmaS.y ), mSigmaS.z ).lessThanEqual( 0.0 ), () => {
 
 				// glass: Beer-Lambert absorption
-				throughput.mulAssign( exp( mSigmaA.mul( hitDist ).negate() ) );
+				const beer = exp( mSigmaA.mul( hitDist ).negate() ).toVar();
+				throughput.mulAssign( beer );
+				// DDFA: colored-glass volume tints the deferred aux guide by the same absorption.
+				If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+
+					featCarry.mulAssign( beer );
+
+				} );
 
 			} ).Else( () => {
 
@@ -534,7 +549,7 @@ export function buildShadeKernel( params ) {
 					// free-bounce continuation: ray stays in the same medium, so medium stack + coeffs persist
 					// SSS scatter changes direction → no longer the direct backdrop view.
 					flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
-					writeRayOriginMeta( rayBufferRW, rayID, scatterPoint, cameraDepth, sssSteps );
+					writeRayOriginMeta( rayBufferRW, rayID, scatterPoint, cameraDepth, sssSteps, transparentCount );
 					writeRayDirFlags( rayBufferRW, rayID, newDir, flags );
 					// Free bounce: preserve prevBouncePdf (megakernel leaves it untouched across SSS scatter,
 					// PathTracerCore.js:1272 sets it only after an opaque scatter). Writing 1.0 here spuriously
@@ -585,6 +600,10 @@ export function buildShadeKernel( params ) {
 			material, samplingUV, N,
 		) ).toVar();
 
+		// DDFA: snapshot the UNCLAMPED roughness (before the min-0.05 clamp below) for the specular↔diffuse
+		// classification, so a perfect mirror reads 0 (fully specular → defers).
+		const rawRough = matSamples.roughness.toVar();
+
 		// BRDF functions read material.color/metalness/roughness, so apply samples here
 		material.color.assign( matSamples.albedo );
 		material.metalness.assign( matSamples.metalness.clamp( 0.0, 1.0 ) );
@@ -635,36 +654,55 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		// first-hit MRT data (bounce 0 only)
-		If( bounceIndex.equal( 0 ).and( auxOn ), () => {
+		// ─── DDFA classification (Cycles smoothstep-by-roughness, not a hard binary) ───
+		// nonspec fraction over a 2-pseudo-closure model: a Lambert closure (weight 1-metal, fully diffuse)
+		// + a glossy/glass closure (weight metal·(1-trans)+trans, classified by roughness). Commit the aux at
+		// the first surface with a meaningful diffuse response (nonspec≥0.25); smooth glass/mirror defers.
+		// featPrefix = the tint accumulated BEFORE this surface (read-only for this bounce's commits).
+		const metal = material.metalness.toVar();
+		const trans = material.transmission.toVar();
+		const roughFrac = smoothstep( float( 0.0 ), float( 0.15 ), rawRough ).toVar();
+		const auxCommit = clamp(
+			float( 1.0 ).sub( metal ).mul( float( 1.0 ).sub( trans ) )
+				.add( roughFrac.mul( metal.mul( float( 1.0 ).sub( trans ) ).add( trans ) ) ),
+			0.0, 1.0,
+		).greaterThanEqual( float( 0.25 ) ).toVar();
+		const featPrefix = featCarry.toVar();
+
+		// DDFA terminal fallback: a ray dying while still deferring (e.g. a mirror maze) commits its last
+		// surface instead of leaving a black guide OIDN would demod-amplify.
+		// Plain JS inliner, not an Fn — it closes over albedo/featPrefix/flags .toVar()s.
+		const commitDeferredAux = ( normal ) => {
+
+			If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+
+				const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
+				writeGBuffer( gBufferRW, pixelIndex, normal, primaryDepth, clamp( albedo.mul( featPrefix ), vec3( 0.0 ), vec3( 1.0 ) ) );
 
-			const linearDepth = computeNDCDepth( {
-				worldPos: hitPoint,
-				cameraProjectionMatrix,
-				cameraViewMatrix,
 			} );
-			// G-buffer is per-pixel (rayID == pixelIndex). writeGBuffer half-packs (normal/depth/albedo).
-			// Write the primary DEPTH now with the miss-default aux; the real normal/albedo are captured below
-			// (aux-extend) and may extend through specular surfaces (gap #9). Glass rays Return at the transparency
-			// block before that capture, so a glass-then-escape pixel keeps this default aux — megakernel parity
-			// (objectNormal/objectColor stay at their init for transmissive-then-miss).
-			//
-			// Fix ③: BLEND (semi-transparent) glass instead LOCKS its OWN normal + albedo here. Its per-frame
-			// stochastic alpha-skip-vs-opaque-shade outcome (MaterialTransmission.js:522-540) otherwise writes a
-			// DIFFERENT surface into the aux each frame (wall-behind on skip vs glass on opaque); with the normal
-			// not temporally averaged that becomes the speckle OIDN smears on — the visible artefact on
-			// alpha-transparent glass. A deterministic glass-surface guide every frame removes it. MASK / opaque
-			// materials keep the default + rely on the downstream aux-extend.
-			If( material.alphaMode.equal( int( 2 ) ), () => {
 
-				writeGBuffer( gBufferRW, pixelIndex, N, linearDepth, albedo.xyz );
-				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+		};
 
-			} ).Else( () => {
+		// Deactivate the ray, keeping the radiance already gathered at this vertex.
+		const terminatePath = () => {
+
+			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
+			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
+			rngBufferRW.element( rayID ).assign( rngState );
+
+		};
 
-				writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
+		// first-hit MRT data (bounce 0 only): write the primary DEPTH now with the default normal/albedo.
+		// The real normal/albedo are committed by the DDFA decision blocks below (which re-pack this depth);
+		// they may defer through smooth glass/mirror and commit at the first diffuse-enough surface or the env.
+		If( bounceIndex.equal( 0 ).and( auxOn ), () => {
 
+			const linearDepth = computeNDCDepth( {
+				worldPos: hitPoint,
+				cameraProjectionMatrix,
+				cameraViewMatrix,
 			} );
+			writeGBuffer( gBufferRW, pixelIndex, vec3( 0.0, 0.0, 1.0 ), linearDepth, vec3( 0.0 ) );
 
 		} );
 
@@ -698,6 +736,53 @@ export function buildShadeKernel( params ) {
 		// persist any wavelength locked on a fresh dispersive transmission; identity write otherwise
 		pathWavelength.assign( interaction.pathWavelength );
 
+		// ─── DDFA aux decision at a transmissive / alpha / SSS interaction. Runs for BOTH the continuing and
+		// the BLEND fall-through paths, so it sits before If(continueRay). If/ElseIf chaining so BLEND wins
+		// over the transmission branch (fixes the BLEND-glass per-frame flicker + the BLEND+transmission case). ───
+		If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+
+			const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
+			// N here is the mapped normal — faceforward it (a ray exiting glass sees a back-facing N).
+			const Nff = select( dot( N, direction.negate() ).lessThan( 0.0 ), N.negate(), N ).toVar();
+			const auxAlbedo = clamp( albedo.mul( featPrefix ), vec3( 0.0 ), vec3( 1.0 ) ).toVar();
+
+			If( material.alphaMode.equal( int( 2 ) ), () => {
+
+				// BLEND: deterministic own-surface commit on BOTH stochastic skip + shade frames (no flicker).
+				writeGBuffer( gBufferRW, pixelIndex, Nff, primaryDepth, auxAlbedo );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} ).ElseIf( interaction.isAlphaSkip, () => {
+
+				// MASK cutout passthrough: keep deferring, tint unchanged (backdrop through the hole commits later).
+
+			} ).ElseIf( interaction.isSubsurface, () => {
+
+				// SSS boundary: force-commit the skin surface as diffuse.
+				writeGBuffer( gBufferRW, pixelIndex, Nff, primaryDepth, auxAlbedo );
+				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+			} ).ElseIf( interaction.isTransmissive, () => {
+
+				If( auxCommit.or( material.dispersion.greaterThan( 0.0 ) ), () => {
+
+					// frosted / rough / dispersive glass: commit its own surface (deterministic per frame).
+					writeGBuffer( gBufferRW, pixelIndex, Nff, primaryDepth, auxAlbedo );
+					flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
+
+				} ).Else( () => {
+
+					// smooth glass: DEFER — tint by the glass colour (matches the transmission throughput,
+					// which multiplies material.color at both reflect and refract; achromatic eta²/Fr excluded).
+					featCarry.mulAssign( clamp( albedo, vec3( 0.0 ), vec3( 1.0 ) ) );
+
+				} );
+
+			} );
+			// else (opaque non-skip): the opaque decision block below handles it (needs the viewer-facing N).
+
+		} );
+
 		If( interaction.continueRay, () => {
 
 			// update medium stack for transmission (not reflection/TIR)
@@ -801,26 +886,6 @@ export function buildShadeKernel( params ) {
 
 			throughput.mulAssign( interaction.throughput );
 
-			// Fix ②: OIDN clean-aux for STOCHASTIC glass (rough / frosted / dispersive), whose refracted
-			// ray hits a different behind-surface every frame. Extending aux through it (the aux-extend on
-			// the opaque-hit path) captures that per-frame surface — albedo then temporally averaged, normal
-			// point-sampled — an inconsistent guide OIDN smears on. Instead lock the glass surface's OWN
-			// normal + tint here (deterministic, spatially coherent). Smooth non-dispersive glass is left
-			// alone: its refraction is a per-pixel delta, so the behind-surface aux captured downstream is
-			// already stable. Gated to a genuine dielectric event (not alpha-cutout passthrough or SSS).
-			If( auxOn
-				.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) )
-				.and( interaction.isTransmissive )
-				.and( interaction.isAlphaSkip.not() )
-				.and( interaction.isSubsurface.not() )
-				.and( material.roughness.greaterThan( 0.05 ).or( material.dispersion.greaterThan( 0.0 ) ) ), () => {
-
-				const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
-				writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, albedo.xyz );
-				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
-
-			} );
-
 			// reflection stays on same side, transmission pushes through
 			const reflectOffsetDir = select( interaction.entering, N, N.negate() );
 			const offsetDir = select( interaction.didReflect, reflectOffsetDir, direction );
@@ -835,8 +900,21 @@ export function buildShadeKernel( params ) {
 
 				flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
 
+			} ).Else( () => {
+
+				// Alpha passthrough: charge the guard. N is faceforwarded for the aux commit (a ray
+				// exiting a back-facing skip would otherwise write an inverted normal).
+				transparentCount.addAssign( 1 );
+				If( transparentCount.greaterThan( maxTransparentBounces ), () => {
+
+					commitDeferredAux( select( dot( N, direction.negate() ).lessThan( 0.0 ), N.negate(), N ) );
+					terminatePath();
+					Return();
+
+				} );
+
 			} );
-			writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth, sssSteps );
+			writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth, sssSteps, transparentCount );
 			writeRayDirFlags( rayBufferRW, rayID, interaction.direction, flags );
 			// Free bounce: preserve prevBouncePdf (megakernel keeps the last opaque-scatter pdf across
 			// transmission/alpha-skip/SSS-boundary). Writing 1.0 corrupts the next bounce's env/emissive MIS,
@@ -844,6 +922,13 @@ export function buildShadeKernel( params ) {
 			writeRayThroughputPdf( rayBufferRW, rayID, throughput, readRayPdf( rayBufferRW, rayID ) );
 			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 			writeMediumStack( rayBufferRW, rayID, uint( mediumStackDepth ), uint( transTraversals ), mediumStack_ior_1, mediumStack_ior_2, mediumStack_ior_3, uint( pathWavelength.add( 0.5 ) ) );
+			// DDFA: persist the (possibly tinted) see-through throughput for the next bounce. MUST run after
+			// the writeMediumSigmaA above — both RMW slot 5 (sigmaA.xyz / featTP.w). Gated AUX_LOCKED-clear.
+			If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+
+				writeFeatureThroughput( rayBufferRW, rayID, featCarry );
+
+			} );
 			rngBufferRW.element( rayID ).assign( rngState );
 			Return();
 
@@ -930,22 +1015,29 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		// OIDN clean-aux (megakernel parity: PathTracerCore.js:1300): keep overwriting the per-pixel normal/
-		// albedo through mirror/glass until the first non-specular hit, so aux describes what's actually
-		// visible (the surface reflected in a mirror / seen behind glass), not the specular surface. Glass
-		// Returns at the transparency block above, so its aux is replaced by the surface behind it. Depth
-		// stays at the primary hit (read back + re-packed; the snorm depth re-pack is idempotent — no drift).
-		If( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ).and( auxOn ), () => {
+		// ─── DDFA opaque aux decision: commit at the first diffuse-enough surface, defer through smooth
+		// mirror/metal so the guide describes what the mirror reflects, not the mirror itself. N is already
+		// viewer-facing (two-sided flip above); depth read back + re-packed (idempotent snorm — no drift). ───
+		If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
 
 			const primaryDepth = gbDecodeNormalDepth( readGBuffer( gBufferRW, pixelIndex ) ).w;
-			writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, albedo.xyz );
-
-			const auxIsMirror = material.metalness.greaterThan( 0.7 ).and( material.roughness.lessThan( 0.3 ) );
-			const auxIsTransmissive = material.transmission.greaterThan( 0.5 );
-			If( auxIsMirror.or( auxIsTransmissive ).not(), () => {
+			If( auxCommit, () => {
 
+				// diffuse / glossy / rough-metal: commit the surface guide, tinted by the see-through prefix.
+				writeGBuffer( gBufferRW, pixelIndex, N, primaryDepth, clamp( albedo.mul( featPrefix ), vec3( 0.0 ), vec3( 1.0 ) ) );
 				flags.assign( flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ) );
 
+			} ).Else( () => {
+
+				// smooth mirror / metal: DEFER — tint by the specular directional albedo (metal colour),
+				// matching the opaque throughput (≈ F at the near-delta mirror lobe). Achromatic energy excluded.
+				const NoV = max( dot( N, V ), float( 1e-3 ) );
+				const F0 = clamp(
+					mix( dielectricF0( material.ior ).mul( material.specularColor ), albedo, material.metalness ).mul( material.specularIntensity ),
+					vec3( 0.0 ), vec3( 1.0 ),
+				);
+				featCarry.mulAssign( DFGResult.wrap( evaluateDFG( F0, NoV, max( rawRough, float( 0.02 ) ) ) ).E_total );
+
 			} );
 
 		} );
@@ -955,11 +1047,14 @@ export function buildShadeKernel( params ) {
 			material.clearcoat, material.emissive, material.subsurface,
 		) ).toVar();
 
-		// STBN keyed on (pixel, bounceIndex, frame).
+		// STBN keyed on (GLOBAL pixel, bounceIndex, frame). pixelIndex is the LOCAL path slot; the global pixel
+		// = chunkRowBase·W + localSlot, so the blue-noise pattern stays spatially aligned across row-band chunks
+		// (and matches Generate's per-pixel RNG seed). chunkRowBase is 0 in the single-chunk case.
 		const _resX = int( resolution.x ).toVar();
+		const _globalPixel = int( pixelIndex ).add( chunkRowBase.mul( _resX ) );
 		const _pixelCoord = vec2(
-			float( int( pixelIndex ).mod( _resX ) ).add( 0.5 ),
-			float( int( pixelIndex ).div( _resX ) ).add( 0.5 ),
+			float( _globalPixel.mod( _resX ) ).add( 0.5 ),
+			float( _globalPixel.div( _resX ) ).add( 0.5 ),
 		);
 		const xi = getRandomSample( _pixelCoord, int( 0 ), bounceIndex, rngState, int( - 1 ), resolution, frame ).toVar();
 		const emptyWeights = BRDFWeights( {
@@ -1174,9 +1269,8 @@ export function buildShadeKernel( params ) {
 		).toVar();
 		If( rrSurvival.lessThanEqual( 0.0 ), () => {
 
-			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
-			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-			rngBufferRW.element( rayID ).assign( rngState );
+			commitDeferredAux( N );
+			terminatePath();
 			Return();
 
 		} );
@@ -1185,9 +1279,8 @@ export function buildShadeKernel( params ) {
 		// Terminate on CAMERA depth (opaque scatter count), not path length — glass/SSS free bounces no longer burn the maxBounces budget (gap #4).
 		If( cameraDepth.greaterThanEqual( maxBounceCount ), () => {
 
-			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
-			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-			rngBufferRW.element( rayID ).assign( rngState );
+			commitDeferredAux( N );
+			terminatePath();
 			Return();
 
 		} );
@@ -1195,11 +1288,17 @@ export function buildShadeKernel( params ) {
 		const newOrigin = hitPoint.add( N.mul( 0.001 ) );
 
 		// Opaque scatter: the only bounce that advances camera depth.
-		writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth.add( 1 ), sssSteps );
+		writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth.add( 1 ), sssSteps, transparentCount );
 		writeRayDirFlags( rayBufferRW, rayID, bounceDir, flags );
 		writeRayThroughputPdf( rayBufferRW, rayID, throughput, bouncePdf );
 		writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 		writeMediumStack( rayBufferRW, rayID, uint( mediumStackDepth ), uint( transTraversals ), mediumStack_ior_1, mediumStack_ior_2, mediumStack_ior_3, uint( pathWavelength.add( 0.5 ) ) );
+		// DDFA: persist the (possibly mirror-tinted) see-through throughput for the next bounce.
+		If( auxOn.and( flags.bitAnd( uint( RAY_FLAG.AUX_LOCKED ) ).equal( uint( 0 ) ) ), () => {
+
+			writeFeatureThroughput( rayBufferRW, rayID, featCarry );
+
+		} );
 		rngBufferRW.element( rayID ).assign( rngState );
 
 	} );

package/src/TSL/TextureSampling.js

@@ -47,10 +47,20 @@ const withBucket = ( buckets, packedIndex, fn ) => {
 
 	const bucket = packedIndex.div( int( _STRIDE ) ).toVar();
 	const layer = packedIndex.sub( bucket.mul( int( _STRIDE ) ) ).toVar();
-	let chain = If( bucket.equal( int( 0 ) ), () => fn( buckets[ 0 ], layer ) );
+	// Block bodies, not concise arrows: an If() callback that yields a value makes TSL emit a
+	// `return` inside an inline Fn(), which it comments out and warns about on every arm.
+	let chain = If( bucket.equal( int( 0 ) ), () => {
+
+		fn( buckets[ 0 ], layer );
+
+	} );
 	for ( let i = 1; i < buckets.length; i ++ ) {
 
-		chain = chain.ElseIf( bucket.equal( int( i ) ), () => fn( buckets[ i ], layer ) );
+		chain = chain.ElseIf( bucket.equal( int( i ) ), () => {
+
+			fn( buckets[ i ], layer );
+
+		} );
 
 	}
 

package/src/index.js

@@ -17,6 +17,9 @@ export { EngineEvents } from './EngineEvents.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// Logging — leveled/namespaced console output shared with the workers
+export { Logger, createLogger, fmt, LOG_LEVELS } from './utils/Logger.js';
+
 // Configuration defaults and presets
 export {
 	ENGINE_DEFAULTS,

package/src/managers/EnvironmentManager.js

@@ -13,6 +13,9 @@ import {
 import { EquirectHDRInfo } from '../Processor/EquirectHDRInfo.js';
 import { ProceduralSky } from '../Processor/ProceduralSky.js';
 import { SimpleSky } from '../Processor/SimpleSky.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'env' );
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 
 export class EnvironmentManager {
@@ -231,8 +234,6 @@ export class EnvironmentManager {
 		this.environmentTexture = envTex;
 		this.envTexSize.set( envTex.image.width, envTex.image.height );
 
-		console.log( `EnvironmentManager: Environment map ${envTex.image.width}x${envTex.image.height}` );
-
 	}
 
 	/**
@@ -317,11 +318,14 @@ export class EnvironmentManager {
 
 			}
 
-			console.log( `Environment CDF built in ${this.cdfBuildTime.toFixed( 2 )}ms (worker: ${useWorker})` );
+			log.info( fmt.list( [
+				fmt.px( this.envTexSize.x, this.envTexSize.y ),
+				`CDF ${fmt.ms( this.cdfBuildTime )}${useWorker ? '' : ' (main thread)'}`,
+			] ) );
 
 		} catch ( error ) {
 
-			console.error( 'Error building environment CDF:', error );
+			log.error( 'CDF build failed:', error );
 			this.uniforms.set( 'useEnvMapIS', 0 );
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -437,7 +441,7 @@ export class EnvironmentManager {
 
 		} catch ( error ) {
 
-			console.error( 'Error generating gradient sky:', error );
+			log.error( 'gradient sky generation failed:', error );
 
 		}
 
@@ -467,7 +471,7 @@ export class EnvironmentManager {
 
 		} catch ( error ) {
 
-			console.error( 'Error generating solid color sky:', error );
+			log.error( 'solid color sky generation failed:', error );
 
 		}
 
@@ -503,11 +507,11 @@ export class EnvironmentManager {
 			this.uniforms.set( 'sunAngularSize', 0.0087 );
 			this.uniforms.set( 'hasSun', 1 );
 
-			console.log( `Sun parameters synced: dir=${this.envParams.skySunDirection.toArray().map( v => v.toFixed( 2 ) ).join( ',' )}` );
+			log.debug( `sun synced · dir ${this.envParams.skySunDirection.toArray().map( v => v.toFixed( 2 ) ).join( ',' )}` );
 
 		} catch ( error ) {
 
-			console.error( 'Error generating procedural sky:', error );
+			log.error( 'procedural sky generation failed:', error );
 
 		}
 

package/src/managers/MaterialDataManager.js

@@ -10,6 +10,9 @@
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { storage } from 'three/tsl';
 import { MATERIAL_DATA_LAYOUT as M, TRIANGLE_DATA_LAYOUT as T } from '../EngineDefaults.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'material' );
 
 const PIXELS_PER_MATERIAL = M.SLOTS_PER_MATERIAL;
 // Per-triangle float offsets used by _patchTriangleSideForMaterial / _patchTriangleBlockerForMaterial.
@@ -84,7 +87,7 @@ export class MaterialDataManager {
 		}
 
 		this.materialCount = Math.floor( vec4Count / PIXELS_PER_MATERIAL );
-		console.log( `MaterialDataManager: ${this.materialCount} materials (storage buffer)` );
+		log.debug( `${fmt.n( this.materialCount )} materials (storage buffer)` );
 
 	}
 
@@ -186,7 +189,7 @@ export class MaterialDataManager {
 
 		if ( ! this.materialStorageAttr ) {
 
-			console.warn( 'Material storage buffer not available' );
+			log.warn( 'material storage buffer not available' );
 			return;
 
 		}
@@ -364,7 +367,7 @@ export class MaterialDataManager {
 
 				break;
 			default:
-				console.warn( `Unknown material property: ${property}` );
+				log.warn( `unknown material property: ${property}` );
 				return;
 
 		}
@@ -403,7 +406,7 @@ export class MaterialDataManager {
 
 		if ( ! this.materialStorageAttr ) {
 
-			console.warn( 'Material storage buffer not available' );
+			log.warn( 'material storage buffer not available' );
 			return;
 
 		}
@@ -630,7 +633,7 @@ export class MaterialDataManager {
 
 		if ( ! this.materialStorageAttr ) {
 
-			console.warn( 'Material storage buffer not available' );
+			log.warn( 'material storage buffer not available' );
 			return;
 
 		}
@@ -651,7 +654,7 @@ export class MaterialDataManager {
 		const offset = transformOffsets[ textureName ];
 		if ( offset === undefined ) {
 
-			console.warn( `Unknown texture name for transform update: ${textureName}` );
+			log.warn( `unknown texture name for transform update: ${textureName}` );
 			return;
 
 		}
@@ -683,7 +686,7 @@ export class MaterialDataManager {
 
 		if ( ! this.materialStorageAttr?.array ) {
 
-			console.warn( '[MaterialDataManager] Material storage buffer not available for feature scanning' );
+			log.warn( 'material storage buffer not available for feature scanning' );
 			return false;
 
 		}
@@ -763,7 +766,7 @@ export class MaterialDataManager {
 
 		if ( ! features ) {
 
-			console.warn( '[MaterialDataManager] No sceneFeatures detected, skipping define injection' );
+			log.warn( 'no sceneFeatures detected, skipping define injection' );
 			return;
 
 		}
@@ -780,7 +783,7 @@ export class MaterialDataManager {
 		// For TSL, we can't inject defines into the shader at runtime
 		// Instead, we would need to conditionally generate the shader
 		// For now, log the features for debugging
-		console.log( '[MaterialDataManager] Material features:', features );
+		log.debug( 'material features:', features );
 
 		this.compiledFeatures = featuresJSON;