rayzee 5.4.0 → 5.4.1

package/src/TSL/BVHTraversal.js

@@ -43,19 +43,8 @@ const BVH_STRIDE = 4;
 const TRI_STRIDE = 8;
 const HUGE_VAL = 1e8;
 
-// Per-mesh visibility buffer (set by ShaderBuilder before graph construction)
-let _meshVisibilityBuffer = null;
-
-/**
- * Set the per-mesh visibility storage buffer node.
- * Must be called before the shader graph is constructed (i.e., before setupCompute).
- * @param {StorageNode} buffer - TSL storage node indexed by meshIndex
- */
-export function setMeshVisibilityBuffer( buffer ) {
-
-	_meshVisibilityBuffer = buffer;
-
-}
+// Per-mesh visibility is now packed into the TLAS BLAS-pointer leaf's slot [2]
+// by TLASBuilder.flatten() — eliminates the dedicated meshVisibility storage buffer.
 
 // ================================================================================
 // STACK HELPERS (Native WGSL array via TSL ArrayNode)
@@ -276,35 +265,17 @@ export const traverseBVH = Fn( ( [
 
 			} ).Else( () => {
 
-				// BLAS-pointer leaf (marker -2) — push BLAS root node onto stack
-				// nodeData0: [blasRootNodeIndex, meshIndex, 0, -2]
+				// BLAS-pointer leaf (marker -2) — push BLAS root onto stack if mesh is visible
+				// nodeData0: [blasRootNodeIndex, meshIndex, visibility, -2]
+				// Visibility is free-fetched with the leaf — no extra storage read.
 				const blasRoot = int( nodeData0.x ).toVar();
 
-				if ( _meshVisibilityBuffer ) {
-
-					// Per-mesh visibility check — skip entire BLAS if mesh is hidden
-					// getDatafromStorageBuffer( buffer, stride=1, sampleIndex=meshIdx, dataOffset=0 )
-					const meshIdx = int( nodeData0.y ).toVar();
-					const meshVis = getDatafromStorageBuffer( _meshVisibilityBuffer, int( 1 ), meshIdx, int( 0 ) ).x;
-
-					If( meshVis.greaterThan( 0.5 ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
-
-						stack.element( stackPtr ).assign( blasRoot );
-						stackPtr.addAssign( 1 );
-
-					} );
-
-				} else {
-
-					// No visibility buffer — push unconditionally (original behavior)
-					If( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ), () => {
-
-						stack.element( stackPtr ).assign( blasRoot );
-						stackPtr.addAssign( 1 );
+				If( nodeData0.z.greaterThan( 0.5 ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
 
-					} );
+					stack.element( stackPtr ).assign( blasRoot );
+					stackPtr.addAssign( 1 );
 
-				}
+				} );
 
 			} );
 
@@ -466,35 +437,16 @@ export const traverseBVHShadow = Fn( ( [
 
 			} ).Else( () => {
 
-				// BLAS-pointer leaf (marker -2) — push BLAS root node onto stack
-				// nodeData0: [blasRootNodeIndex, meshIndex, 0, -2]
+				// BLAS-pointer leaf (marker -2) — push BLAS root onto stack if mesh is visible
+				// nodeData0: [blasRootNodeIndex, meshIndex, visibility, -2]
 				const blasRoot = int( nodeData0.x ).toVar();
 
-				if ( _meshVisibilityBuffer ) {
-
-					// Per-mesh visibility check — skip entire BLAS if mesh is hidden
-					// getDatafromStorageBuffer( buffer, stride=1, sampleIndex=meshIdx, dataOffset=0 )
-					const meshIdx = int( nodeData0.y ).toVar();
-					const meshVis = getDatafromStorageBuffer( _meshVisibilityBuffer, int( 1 ), meshIdx, int( 0 ) ).x;
-
-					If( meshVis.greaterThan( 0.5 ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
-
-						stack.element( stackPtr ).assign( blasRoot );
-						stackPtr.addAssign( 1 );
-
-					} );
-
-				} else {
+				If( nodeData0.z.greaterThan( 0.5 ).and( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ) ), () => {
 
-					// No visibility buffer — push unconditionally (original behavior)
-					If( stackPtr.lessThan( int( MAX_STACK_DEPTH ) ), () => {
-
-						stack.element( stackPtr ).assign( blasRoot );
-						stackPtr.addAssign( 1 );
-
-					} );
+					stack.element( stackPtr ).assign( blasRoot );
+					stackPtr.addAssign( 1 );
 
-				}
+				} );
 
 			} );
 

package/src/TSL/Clearcoat.js

@@ -13,7 +13,7 @@ import {
 	If,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 import { Ray, HitInfo, RayTracingMaterial, DotProducts } from './Struct.js';
 import { PI, MIN_CLEARCOAT_ROUGHNESS, computeDotProducts } from './Common.js';

package/src/TSL/Displacement.js

@@ -1,6 +1,6 @@
 import { Fn, float, vec2, int, If, Loop, abs, normalize, dot, max } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 import { getDatafromStorageBuffer } from './Common.js';
 import { sampleDisplacementMap } from './TextureSampling.js';
 

package/src/TSL/EmissiveSampling.js

@@ -27,7 +27,7 @@ import {
 	atan,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 import { MIN_PDF, getDatafromStorageBuffer, powerHeuristic, MATERIAL_SLOTS, MATERIAL_SLOT } from './Common.js';
 import { RandomValue } from './Random.js';
 import { calculateMaterialPDF } from './LightsSampling.js';
@@ -361,8 +361,10 @@ export const calculateEmissiveLightPdf = Fn( ( [
 // ================================================================================
 
 // Binary search in CDF for importance-weighted triangle selection
-// CDF values are stored in the .b channel of the emissive buffer
-const binarySearchCDF = Fn( ( [ emissiveTriangleBuffer, emissiveTriangleCount, rand ] ) => {
+// CDF values are stored in the .b channel of the emissive buffer.
+// `emissiveOffset` is the vec4-element offset into the packed light buffer
+// where emissive entries start (0 if using a non-packed buffer).
+const binarySearchCDF = Fn( ( [ emissiveTriangleBuffer, emissiveOffset, emissiveTriangleCount, rand ] ) => {
 
 	const lo = int( 0 ).toVar();
 	const hi = emissiveTriangleCount.sub( 1 ).toVar();
@@ -370,7 +372,7 @@ const binarySearchCDF = Fn( ( [ emissiveTriangleBuffer, emissiveTriangleCount, r
 	Loop( lo.lessThan( hi ), () => {
 
 		const mid = lo.add( hi ).div( 2 ).toVar();
-		const cdfVal = emissiveTriangleBuffer.element( mid.mul( EMISSIVE_STRIDE ) ).b;
+		const cdfVal = emissiveTriangleBuffer.element( emissiveOffset.add( mid.mul( int( EMISSIVE_STRIDE ) ) ) ).b;
 
 		If( cdfVal.lessThan( rand ), () => {
 
@@ -388,11 +390,13 @@ const binarySearchCDF = Fn( ( [ emissiveTriangleBuffer, emissiveTriangleCount, r
 
 } );
 
-// Sample from emissive triangle index using CDF importance sampling
+// Sample from emissive triangle index using CDF importance sampling.
+// `emissiveTriangleBuffer` may be the shared packed light buffer; `emissiveVec4Offset`
+// gives the vec4 offset where emissive entries begin.
 export const sampleEmissiveTriangle = Fn( ( [
 	hitPoint, surfaceNormal, totalTriangleCount,
 	rngState,
-	emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 	triangleBuffer,
 ] ) => {
 
@@ -413,12 +417,12 @@ export const sampleEmissiveTriangle = Fn( ( [
 
 		// CDF importance-weighted triangle selection (brighter triangles sampled more)
 		const randEmissive = RandomValue( rngState );
-		const emissiveIndex = binarySearchCDF( emissiveTriangleBuffer, emissiveTriangleCount, randEmissive ).toVar();
+		const emissiveIndex = binarySearchCDF( emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, randEmissive ).toVar();
 
-		// Fetch emissive triangle data from storage buffer (2 vec4s per entry)
+		// Fetch emissive triangle data from packed light buffer (2 vec4s per entry)
 		// vec4[0] = (triangleIndex, power, cdf, selectionPdf)
 		// vec4[1] = (emission.r, emission.g, emission.b, area)
-		const baseIdx = emissiveIndex.mul( EMISSIVE_STRIDE );
+		const baseIdx = emissiveVec4Offset.add( emissiveIndex.mul( int( EMISSIVE_STRIDE ) ) );
 		const emissiveData0 = emissiveTriangleBuffer.element( baseIdx );
 		const emissiveData1 = emissiveTriangleBuffer.element( baseIdx.add( 1 ) );
 		const triangleIndex = int( emissiveData0.r );
@@ -534,7 +538,7 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 	hitPoint, normal, viewDir, material,
 	totalTriangleCount, bounceIndex, rngState,
 	emissiveBoost,
-	emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 	triangleBuffer,
 	// Callback functions to avoid circular deps
 	traceShadowRayFn,
@@ -557,7 +561,7 @@ export const calculateEmissiveTriangleContributionDebug = Fn( ( [
 		// Sample emissive triangle (CDF importance-weighted)
 		const emissiveSample = EmissiveSample.wrap( sampleEmissiveTriangle(
 			hitPoint, normal, totalTriangleCount, rngState,
-			emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+			emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 			triangleBuffer,
 		) );
 
@@ -619,7 +623,7 @@ export const calculateEmissiveTriangleContribution = Fn( ( [
 	hitPoint, normal, viewDir, material,
 	totalTriangleCount, bounceIndex, rngState,
 	emissiveBoost,
-	emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 	triangleBuffer,
 	traceShadowRayFn,
 	evaluateMaterialResponseFn,
@@ -630,7 +634,7 @@ export const calculateEmissiveTriangleContribution = Fn( ( [
 		hitPoint, normal, viewDir, material,
 		totalTriangleCount, bounceIndex, rngState,
 		emissiveBoost,
-		emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+		emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 		triangleBuffer,
 		traceShadowRayFn,
 		evaluateMaterialResponseFn,

package/src/TSL/Environment.js

@@ -82,8 +82,7 @@ export const sampleEquirect = Fn( ( [ environment, direction, environmentMatrix,
 // Exact implementation from three-gpu-pathtracer
 export const sampleEquirectProbability = Fn( ( [
 	environment,
-	envMarginalWeights,
-	envConditionalWeights,
+	envCDFBuffer,
 	environmentMatrix,
 	environmentIntensity,
 	envTotalSum,
@@ -92,15 +91,19 @@ export const sampleEquirectProbability = Fn( ( [
 	colorOutput
 ] ) => {
 
-	// Sample marginal CDF for V coordinate (1D storage buffer, linear interpolation)
+	// Packed CDF layout: [marginal (envResolution.y floats) | conditional (envResolution.x * envResolution.y floats)]
+	// The conditional offset equals the marginal length, which is envResolution.y.
+	const condOffset = int( envResolution.y ).toVar();
+
+	// Sample marginal CDF for V coordinate (1D, linear interpolation)
 	const marginalSize = envResolution.y;
 	const mIdx = clamp( r.x.mul( marginalSize.sub( 1.0 ) ), 0.0, marginalSize.sub( 1.0 ) );
 	const mI0 = int( floor( mIdx ) );
 	const mI1 = min( mI0.add( 1 ), int( marginalSize ).sub( 1 ) );
 	const mFrac = fract( mIdx );
-	const v = mix( envMarginalWeights.element( mI0 ), envMarginalWeights.element( mI1 ), mFrac ).toVar();
+	const v = mix( envCDFBuffer.element( mI0 ), envCDFBuffer.element( mI1 ), mFrac ).toVar();
 
-	// Sample conditional CDF for U coordinate (2D storage buffer, bilinear interpolation)
+	// Sample conditional CDF for U coordinate (2D grid, bilinear interpolation)
 	const condW = envResolution.x;
 	const condH = envResolution.y;
 	const cxf = clamp( r.y.mul( condW.sub( 1.0 ) ), 0.0, condW.sub( 1.0 ) );
@@ -112,10 +115,10 @@ export const sampleEquirectProbability = Fn( ( [
 	const fx = fract( cxf );
 	const fy = fract( cyf );
 	const condWi = int( condW );
-	const v00 = envConditionalWeights.element( cy0.mul( condWi ).add( cx0 ) );
-	const v10 = envConditionalWeights.element( cy0.mul( condWi ).add( cx1 ) );
-	const v01 = envConditionalWeights.element( cy1.mul( condWi ).add( cx0 ) );
-	const v11 = envConditionalWeights.element( cy1.mul( condWi ).add( cx1 ) );
+	const v00 = envCDFBuffer.element( condOffset.add( cy0.mul( condWi ).add( cx0 ) ) );
+	const v10 = envCDFBuffer.element( condOffset.add( cy0.mul( condWi ).add( cx1 ) ) );
+	const v01 = envCDFBuffer.element( condOffset.add( cy1.mul( condWi ).add( cx0 ) ) );
+	const v11 = envCDFBuffer.element( condOffset.add( cy1.mul( condWi ).add( cx1 ) ) );
 	const u = mix( mix( v00, v10, fx ), mix( v01, v11, fx ), fy ).toVar();
 
 	const uv = vec2( u, v ).toVar();

package/src/TSL/LightBVHSampling.js

@@ -53,6 +53,7 @@ export const sampleLightBVHTriangle = Fn( ( [
 	rngState,
 	lbvhBuffer,
 	emissiveTriangleBuffer,
+	emissiveVec4Offset,
 	triangleBuffer,
 ] ) => {
 
@@ -185,7 +186,7 @@ export const sampleLightBVHTriangle = Fn( ( [
 		Loop( { start: int( 0 ), end: emissiveCount }, ( { i } ) => {
 
 			const entryIdx = emissiveStart.add( i );
-			const baseIdx = entryIdx.mul( int( EMISSIVE_STRIDE ) );
+			const baseIdx = emissiveVec4Offset.add( entryIdx.mul( int( EMISSIVE_STRIDE ) ) );
 			const emData0 = emissiveTriangleBuffer.element( baseIdx );
 			const triPower = max( emData0.g, float( 0.0 ) );
 			cumPower.addAssign( triPower );
@@ -204,7 +205,7 @@ export const sampleLightBVHTriangle = Fn( ( [
 		selectionPdf.mulAssign( selectedPower.div( leafTotalPower ) );
 
 		// Now sample the selected triangle (same path as flat CDF sampling)
-		const baseIdx = selectedEmissiveIndex.mul( int( EMISSIVE_STRIDE ) );
+		const baseIdx = emissiveVec4Offset.add( selectedEmissiveIndex.mul( int( EMISSIVE_STRIDE ) ) );
 		const emissiveData0 = emissiveTriangleBuffer.element( baseIdx );
 		const emissiveData1 = emissiveTriangleBuffer.element( baseIdx.add( int( 1 ) ) );
 

package/src/TSL/LightsCore.js

@@ -13,7 +13,7 @@ import {
 	abs,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 // ================================================================================
 // LIGHT STRUCTURES

package/src/TSL/LightsDirect.js

@@ -41,7 +41,7 @@ import { RandomValue } from './Random.js';
 import { getTransformedUV } from './TextureSampling.js';
 
 // Module-level state for alpha-cutout shadow testing.
-// Set by ShaderBuilder before graph construction (same pattern as _meshVisibilityBuffer in BVHTraversal.js).
+// Set by ShaderBuilder before graph construction.
 let _shadowAlbedoMaps = null;
 let _enableAlphaShadows = null;
 

package/src/TSL/LightsIndirect.js

@@ -273,7 +273,6 @@ export const calculateIndirectLighting = Fn( ( [
 	samplingInfo,
 	// Environment resources
 	envTexture, environmentIntensity, envMatrix,
-	envMarginalWeights, envConditionalWeights,
 	envTotalSum, envResolution,
 	enableEnvironmentLight, useEnvMapIS,
 ] ) => {

package/src/TSL/LightsSampling.js

@@ -934,7 +934,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 	materialBuffer,
 	// Environment resources
 	envTexture, environmentIntensity, envMatrix,
-	envMarginalWeights, envConditionalWeights,
+	envCDFBuffer,
 	envTotalSum, envResolution,
 	enableEnvironmentLight,
 ] ) => {
@@ -1203,7 +1203,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 			// Sample direction + PDF + color from importance-sampled environment
 			const envSampleResult = sampleEquirectProbability(
-				envTexture, envMarginalWeights, envConditionalWeights,
+				envTexture, envCDFBuffer,
 				envMatrix, environmentIntensity, envTotalSum, envResolution, envRandom, envColor
 			).toVar();
 

package/src/TSL/MaterialTransmission.js

@@ -30,7 +30,7 @@ import {
 	fract,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 import { Ray, RayTracingMaterial, RenderState, HitInfo, DotProducts, DirectionSample } from './Struct.js';
 import { PI, EPSILON, MIN_ROUGHNESS, MIN_CLEARCOAT_ROUGHNESS, computeDotProducts } from './Common.js';
 import { iorToFresnel0, fresnelSchlickFloat } from './Fresnel.js';

package/src/TSL/PathTracer.js

@@ -137,14 +137,14 @@ export const pathTracerMain = ( params ) => {
 		pointLightsBuffer, numPointLights,
 		spotLightsBuffer, numSpotLights,
 		envTexture, environmentIntensity, envMatrix,
-		envMarginalWeights, envConditionalWeights,
+		envCDFBuffer,
 		envTotalSum, envResolution,
 		enableEnvironmentLight, useEnvMapIS,
 		maxBounceCount, transmissiveBounces,
 		showBackground, transparentBackground, backgroundIntensity,
 		fireflyThreshold, globalIlluminationIntensity,
 		totalTriangleCount, enableEmissiveTriangleSampling,
-		emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
+		emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
 		lightBVHBuffer, lightBVHNodeCount,
 		debugVisScale,
 		enableAccumulation, hasPreviousAccumulated,
@@ -284,14 +284,14 @@ export const pathTracerMain = ( params ) => {
 				pointLightsBuffer, numPointLights,
 				spotLightsBuffer, numSpotLights,
 				envTexture, environmentIntensity, envMatrix,
-				envMarginalWeights, envConditionalWeights,
+				envCDFBuffer,
 				envTotalSum, envResolution,
 				enableEnvironmentLight, useEnvMapIS,
 				maxBounceCount, transmissiveBounces,
 				backgroundIntensity, showBackground, transparentBackground,
 				fireflyThreshold, globalIlluminationIntensity,
 				totalTriangleCount, enableEmissiveTriangleSampling,
-				emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
+				emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
 				lightBVHBuffer, lightBVHNodeCount,
 				pixelCoord, resolution, frame,
 			) );

package/src/TSL/PathTracerCore.js

@@ -41,7 +41,7 @@ import {
 	sampler,
 } from 'three/tsl';
 
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 import {
 	PI_INV,
@@ -590,7 +590,7 @@ export const Trace = Fn( ( [
 	spotLightsBuffer, numSpotLights,
 	// Environment
 	envTexture, environmentIntensity, envMatrix,
-	envMarginalWeights, envConditionalWeights,
+	envCDFBuffer,
 	envTotalSum, envResolution,
 	enableEnvironmentLight, useEnvMapIS,
 	// Rendering parameters
@@ -598,7 +598,7 @@ export const Trace = Fn( ( [
 	backgroundIntensity, showBackground, transparentBackground,
 	fireflyThreshold, globalIlluminationIntensity,
 	totalTriangleCount, enableEmissiveTriangleSampling,
-	emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
+	emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower, emissiveBoost,
 	lightBVHBuffer, lightBVHNodeCount,
 	// Per-pixel info
 	pixelCoord, resolution, frame,
@@ -1013,7 +1013,7 @@ export const Trace = Fn( ( [
 			triangleBuffer,
 			materialBuffer,
 			envTexture, environmentIntensity, envMatrix,
-			envMarginalWeights, envConditionalWeights,
+			envCDFBuffer,
 			envTotalSum, envResolution,
 			enableEnvironmentLight,
 		);
@@ -1040,6 +1040,7 @@ export const Trace = Fn( ( [
 					rngState,
 					lightBVHBuffer,
 					emissiveTriangleBuffer,
+					emissiveVec4Offset,
 					triangleBuffer,
 				) );
 
@@ -1091,7 +1092,7 @@ export const Trace = Fn( ( [
 					hitInfo.hitPoint, N, V, material,
 					totalTriangleCount, bounceIndex, rngState,
 					emissiveBoost,
-					emissiveTriangleBuffer, emissiveTriangleCount, emissiveTotalPower,
+					emissiveTriangleBuffer, emissiveVec4Offset, emissiveTriangleCount, emissiveTotalPower,
 					triangleBuffer,
 					traceShadowRayWrapped,
 					evaluateMaterialResponse,
@@ -1132,7 +1133,6 @@ export const Trace = Fn( ( [
 			rngState,
 			samplingInfo,
 			envTexture, environmentIntensity, envMatrix,
-			envMarginalWeights, envConditionalWeights,
 			envTotalSum, envResolution,
 			enableEnvironmentLight, useEnvMapIS,
 		) );

package/src/TSL/Struct.js

@@ -1,4 +1,4 @@
-import { struct } from './structProxy.js';
+import { struct } from './patches.js';
 
 export const Ray = struct( {
 	origin: 'vec3',

package/src/TSL/patches.js

@@ -0,0 +1,145 @@
+/**
+ * Rayzee patches for Three.js / TSL.
+ *
+ * Side-effect on import: installs `WebGPUBackend.createNodeBuilder` override
+ * (restores r183 function-scoped `var` emission for compute shaders — prevents
+ * a register-allocation regression in the path tracer's hot loop).
+ *
+ * Export: `struct()` — drop-in replacement for TSL's `struct()` returning
+ * a proxy factory that supports GLSL-style dot-notation field access.
+ */
+
+import { WebGPUBackend } from 'three/webgpu';
+import { struct as _struct } from 'three/tsl';
+
+// ---------------------------------------------------------------------------
+// 1. WGSL global-variable promotion patch (compute-only)
+// ---------------------------------------------------------------------------
+// Three.js r184 introduced `WGSLNodeBuilder.allowGlobalVariables = true`, which
+// emits `.toVar()` declarations at WGSL module scope as `var<private> name : T`
+// instead of function-local `var name : T` inside `fn main()` (as r183 did).
+//
+// For compute shaders with hundreds of `.toVar()` calls in loops (e.g. the BVH
+// traversal + BRDF path tracer), `var<private>` increases GPU register pressure
+// because the Dawn/Chromium WGSL compiler cannot aggressively register-allocate
+// variables with a stable per-invocation memory address. We measured a ~8% fps
+// regression (120 → 110) on the path tracer after upgrading r183 → r184 that
+// traced entirely to GPU execution, not CPU.
+//
+// `allowGlobalVariables` is ONLY consumed by the compute template
+// (`_getWGSLComputeCode`). The vertex/fragment templates always emit
+// `shaderData.vars` at module scope and REQUIRE `allowGlobalVariables=true`
+// (emitting function-local `var` at module scope is invalid WGSL and crashes
+// pipeline creation with "Invalid ShaderModule"). We install a per-instance
+// accessor that returns `false` only when the builder is for a compute node
+// (material === null) and `true` otherwise, so render pipelines keep r184
+// behavior untouched.
+//
+// Relevant upstream lines:
+//  - `node_modules/three/src/renderers/webgpu/nodes/WGSLNodeBuilder.js:247`
+//    (`this.allowGlobalVariables = true`)
+//  - `...WGSLNodeBuilder.js:2458` (module-scope vars block)
+//  - `...WGSLNodeBuilder.js:2467` (function-body vars block)
+//
+// Revisit if upstream adds an official opt-out or fixes register pressure.
+
+const _origCreateNodeBuilder = WebGPUBackend.prototype.createNodeBuilder;
+
+WebGPUBackend.prototype.createNodeBuilder = function ( object, renderer ) {
+
+	const builder = _origCreateNodeBuilder.call( this, object, renderer );
+
+	Object.defineProperty( builder, 'allowGlobalVariables', {
+		get() {
+
+			return this.material !== null;
+
+		},
+		set() { /* ignore — the value is derived from material presence */ },
+		configurable: true,
+	} );
+
+	return builder;
+
+};
+
+// ---------------------------------------------------------------------------
+// 2. TSL struct proxy — enables GLSL-style dot-notation field access
+// ---------------------------------------------------------------------------
+// TSL structs require `.get('fieldName')` for member access, but GLSL-style
+// dot notation (`.fieldName`) is more natural and matches ported code.
+//
+// This wraps TSL's `struct()` so that:
+//  - Direct construction: `MyStruct({...}).toVar('x')` → `.fieldName` works
+//  - Fn return values:    `MyStruct.wrap(someFn(...))` → `.fieldName` works
+//
+// Property access for known struct member names is redirected to `.get('name')`.
+// Swizzle properties (x, y, z, w, etc.), Node methods (.add, .assign, etc.), and
+// other standard properties pass through to the underlying node unmodified.
+
+function createStructProxy( node, memberSet ) {
+
+	return new Proxy( node, {
+
+		get( target, prop, receiver ) {
+
+			// Intercept known struct member names
+			if ( typeof prop === 'string' && memberSet.has( prop ) ) {
+
+				return target.get( prop );
+
+			}
+
+			const val = Reflect.get( target, prop, receiver );
+
+			// Intercept .toVar() to proxy-wrap the result
+			if ( prop === 'toVar' && typeof val === 'function' ) {
+
+				return ( ...args ) => createStructProxy( val.apply( target, args ), memberSet );
+
+			}
+
+			return val;
+
+		}
+
+	} );
+
+}
+
+/**
+ * Drop-in replacement for TSL's `struct()` that returns a proxy-enhanced factory.
+ *
+ * The returned factory:
+ *  - Creates struct nodes where `.toVar()` results support dot-notation field access
+ *  - Has `.wrap(node)` method to proxy-wrap Fn return values for field access
+ *  - Has `.layout` and `.isStruct` matching the original TSL struct API
+ *
+ * @param {Object} members - Struct member layout (e.g., { didHit: 'bool', dst: 'float' })
+ * @param {string|null} name - Optional struct name
+ * @returns {Function} Enhanced struct factory
+ */
+export function struct( members, name = null ) {
+
+	const factory = _struct( members, name );
+	const memberSet = new Set( Object.keys( members ) );
+
+	const wrappedFactory = ( ...args ) => {
+
+		const node = factory( ...args );
+		return createStructProxy( node, memberSet );
+
+	};
+
+	wrappedFactory.layout = factory.layout;
+	wrappedFactory.isStruct = true;
+
+	/**
+	 * Wrap an existing node (e.g., Fn return value) with struct field access proxy.
+	 * Usage: `const hit = HitInfo.wrap(traverseBVH(...).toVar('hit'));`
+	 */
+	wrappedFactory.wrap = ( node ) => createStructProxy( node, memberSet );
+
+	return wrappedFactory;
+
+}

package/src/index.js

@@ -6,7 +6,7 @@
  */
 
 // Patches (side-effect imports — must run before any StorageTexture usage)
-import './TSL/wgslGlobalVarsPatch.js';
+import './TSL/patches.js';
 
 // Main application
 export { PathTracerApp } from './PathTracerApp.js';