rayzee 8.4.0 → 8.4.1

package/package.json

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

package/src/EngineDefaults.js

@@ -10,13 +10,11 @@
  */
 export const RENDER_PROFILES = Object.freeze( {
 	viewer: Object.freeze( {
-		areaLightIntensityScale: 0.1, // scales glTF placeholder area-light power (viewer tuning)
 		environmentRotation: 270.0, // degrees
 		toneMapping: 4, // ACESFilmicToneMapping
 		saturation: 1.2, // compensates for ACES desaturation — see Compositor
 	} ),
 	physical: Object.freeze( {
-		areaLightIntensityScale: 1.0,
 		environmentRotation: 0.0,
 		// AgX, matching Blender/Cycles' default view transform. ACES crushes shadows on this
 		// engine's own corpus (shade 1.48 vs AgX 3.01 from identical radiance).
@@ -27,7 +25,7 @@ export const RENDER_PROFILES = Object.freeze( {
 
 /**
  * @param {string} [name] - a RENDER_PROFILES key
- * @returns {{areaLightIntensityScale: number, environmentRotation: number}}
+ * @returns {{environmentRotation: number, toneMapping: number, saturation: number}}
  * @throws {Error} on an unknown name — a typo must not silently select viewer tuning
  */
 export function getRenderProfile( name = 'viewer' ) {
@@ -1062,7 +1060,8 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 export const PRODUCTION_RENDER_CONFIG = {
 	// maxSamples is a CEILING: adaptive sampling retires the frame once adaptiveStopFraction of pixels converge,
 	// so easy scenes finish well under it while hard GI scenes use the full budget.
-	maxSamples: 150, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
+	// Below 24 a ray that spends its transmissive budget is shaded opaque — black pixels, not dim glass.
+	maxSamples: 30, bounces: 20, transmissiveBounces: 24, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
 	// 'high' is the only tier that reaches OIDN's _large weights (calb_cnrm); ~2x denoise cost.
 	enableOIDN: true, oidnQuality: 'high',
@@ -1077,7 +1076,8 @@ export const PRODUCTION_RENDER_CONFIG = {
 export const INTERACTIVE_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
 	renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
-	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
+	// 12, not 5: a spent budget leaves black glass and costs MORE — the ray then bounces diffusely.
+	transmissiveBounces: 12,
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
 	// On, like production. The final pass costs one cheap denoise when the preview settles, and both
 	// neural passes need a denoised frame to be worth running — on Monte-Carlo noise the upscaler

package/src/EngineIssues.js

@@ -19,6 +19,7 @@ export const ISSUE_CODES = Object.freeze( {
 	STAGE_RENDER_FAILED: 'stage.render_failed',
 	RENDER_RESERVE_CAPPED: 'render.reserve_capped',
 	SCENE_MEMORY_BUDGET: 'scene.memory_budget',
+	LIGHT_PLACEHOLDER_INVALID: 'light.placeholder_invalid',
 	EMISSIVE_INSTANCES_COLLAPSED: 'emissive.instances_collapsed',
 	REFIT_SHARED_GEOMETRY: 'refit.shared_geometry',
 } );

package/src/LightUnits.js

@@ -0,0 +1,122 @@
+/**
+ * The engine's light-unit rule, stated once.
+ *
+ * Every light in the scene graph is a **valid three.js light**: it carries the quantity three.js
+ * expects for its type, measured in radiometric (watt-based) units rather than photometric ones.
+ *
+ *   point / spot  → radiant intensity   W/sr
+ *   directional   → irradiance          W/m²
+ *   rect area     → radiance            W/(sr·m²), `width`/`height` in world metres, unit scale
+ *
+ * three.js' shading maths is unit-agnostic — it divides by distance² and integrates a form factor,
+ * never caring whether the number it was handed is candela or W/sr. Feeding it radiometric values
+ * therefore makes the raster fallback, the light helpers and any host reading `sceneModel` correct
+ * without one of them knowing anything about the path tracer.
+ *
+ * Blender-style **Power in Watts** — what the Lights panel edits — is a view of that, converted
+ * here and nowhere else. `LightSerializer` converts the other way when it fills the GPU buffer.
+ */
+
+/** Luminous efficacy that glTF, three.js and Blender's exporter all assume (lm/W). */
+export const LUMENS_PER_WATT = 683;
+
+/** Emitting area in m², including the ellipse/disk shape factor. Assumes unit world scale. */
+export function areaLightArea( light ) {
+
+	const shape = light.userData?.shape;
+	const shapeFactor = shape === 'ellipse' || shape === 'disk' ? Math.PI / 4 : 1;
+	const area = Math.abs( light.width * light.height ) * shapeFactor;
+	return Number.isFinite( area ) && area > 0 ? area : 0;
+
+}
+
+/**
+ * Blender-style Power for the Lights panel: radiant power in W for point, spot and area lights,
+ * and the Sun's strength in W/m² unchanged.
+ */
+export function lightPower( light ) {
+
+	if ( light.isRectAreaLight ) {
+
+		const normalize = light.userData?.normalize ?? true;
+		return light.intensity * Math.PI * ( normalize ? areaLightArea( light ) : 1 );
+
+	}
+
+	if ( light.isPointLight || light.isSpotLight ) return light.intensity * 4 * Math.PI;
+
+	return light.intensity;
+
+}
+
+/** Inverse of {@link lightPower} — what the panel writes back. */
+export function setLightPower( light, watts ) {
+
+	if ( light.isRectAreaLight ) {
+
+		const normalize = light.userData?.normalize ?? true;
+		const denominator = Math.PI * ( normalize ? areaLightArea( light ) : 1 );
+		light.intensity = denominator > 0 ? watts / denominator : 0;
+		return;
+
+	}
+
+	if ( light.isPointLight || light.isSpotLight ) {
+
+		light.intensity = watts / ( 4 * Math.PI );
+		return;
+
+	}
+
+	light.intensity = watts;
+
+}
+
+/**
+ * Runs `mutate` with the light's Power held constant.
+ *
+ * Resizing a normalized area light is meant to keep its total power and change its radiance —
+ * Blender's Normalize toggle. Since the stored quantity is radiance, that only happens if the
+ * edit puts the Power back afterwards. With Normalize off, Power does not depend on the area,
+ * so this is a no-op and the same call is still correct.
+ */
+export function preserveLightPower( light, mutate ) {
+
+	const watts = lightPower( light );
+	mutate();
+	setLightPower( light, watts );
+
+}
+
+/**
+ * Puts an area light's rectangle in world metres with unit scale, leaving its world size and
+ * placement untouched.
+ *
+ * ⚠️ three.js' rasteriser reads `width`/`height` as WORLD dimensions and drops any scale inherited
+ * from parent nodes — `RectAreaLightNode` builds the light's basis with `extractRotation`, which
+ * normalises the scale away. A light authored as 70 units under a 0.01 node scale therefore rasters
+ * as a **70 metre** panel while the path tracer, which uses the world matrix, renders the 0.7 m one
+ * it should. Measured on 24001884.glb: 58.7x too bright in the raster view. Baking the scale in and
+ * cancelling it on the light itself makes every reader agree.
+ *
+ * Idempotent: a light already at unit scale is left alone, so re-processing a tree is safe.
+ */
+export function bakeAreaLightScale( light ) {
+
+	light.updateWorldMatrix( true, false );
+
+	// Column lengths of the world matrix, read directly so this module needs no three.js import.
+	const e = light.matrixWorld.elements;
+	const sx = Math.hypot( e[ 0 ], e[ 1 ], e[ 2 ] );
+	const sy = Math.hypot( e[ 4 ], e[ 5 ], e[ 6 ] );
+	const sz = Math.hypot( e[ 8 ], e[ 9 ], e[ 10 ] );
+
+	if ( ! Number.isFinite( sx ) || ! Number.isFinite( sy ) || sx === 0 || sy === 0 ) return;
+	if ( Math.abs( sx - 1 ) < 1e-9 && Math.abs( sy - 1 ) < 1e-9 ) return;
+
+	light.width = Math.abs( light.width * sx );
+	light.height = Math.abs( light.height * sy );
+	light.scale.set( light.scale.x / sx, light.scale.y / sy, sz === 0 ? light.scale.z : light.scale.z / sz );
+	light.updateMatrixWorld( true );
+
+}

package/src/PathTracerApp.js

@@ -764,8 +764,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * by reference, and any ancestor transform is baked in. Later edits to `object3d` do not
 	 * reach the render — mutate {@link sceneModel}, then {@link refitBVH}/{@link refitBLASes}.
 	 *
-	 * Lights keep three.js units — `RectAreaLight.intensity` in nits, point/spot in candela — and are
-	 * converted to radiant power on the copy. `areaLightIntensityScale` does not apply here.
+	 * Lights are read as three.js lights in RADIOMETRIC units — W/sr for point and spot, W/m² for
+	 * directional, radiance for area — and are left as they are; only an area light's rectangle is
+	 * put into world metres on the copy. See `LightUnits.js`.
 	 *
 	 * @param {import('three').Object3D} object3d - The Object3D to render; left untouched.
 	 * @param {string} [name='object3d'] - Display name for the object
@@ -3106,6 +3107,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager.setOverlayManager( this.overlayManager );
 		this.denoisingManager.setResetCallback( () => this.reset() );
 		this.denoisingManager.setPostProcessRefreshCallback( () => this.requestPostProcessRefresh() );
+		this.denoisingManager.setDisplayRefreshCallback( () => this.refreshFrame() );
 		this.denoisingManager.setSettings( this.settings );
 
 		// Expose environment manager (lives on pathTracer stage)

package/src/Processor/AssetLoader.js

@@ -19,6 +19,7 @@ import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
 import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
+import { bakeAreaLightScale, LUMENS_PER_WATT } from '../LightUnits.js';
 import { getRenderProfile } from '../EngineDefaults.js';
 
 // Define supported file formats
@@ -67,16 +68,43 @@ function standInForSplit( source ) {
 
 }
 
-// three.js nits → the engine's radiant power, inverting areaLightRadiance.
-function areaLightPowerFactor( node, width, height, userData ) {
+const PLACEHOLDER_SHAPES = new Set( [ 'rectangle', 'square', 'disk', 'ellipse' ] );
 
-	if ( ! ( userData.normalize ?? true ) ) return Math.PI;
+/**
+ * Build the light a placeholder node stands for. glTF has no area light, so a three.js host's
+ * patched GLTFExporter writes the RectAreaLight into the node's `extras` and leaves the node
+ * itself carrying the transform. `intensity` is three.js radiance, which is what the engine
+ * stores, so the number is used as authored; only the rectangle needs normalising to world
+ * metres (see `bakeAreaLightScale`).
+ *
+ * `power`, `position`, `rotation` and `direction` are present in the record and deliberately
+ * unused. The node's matrix already carries the transform, `direction` is not even normalised,
+ * and `power` was written from the light's UNSCALED dimensions — on 24155522.glb's window light,
+ * whose ancestor scale is non-uniform (1.6 × 1.2 m in world, not 1.2 × 1.2), it is 25 % low.
+ *
+ * @returns {RectAreaLight|null} null when the record carries no usable size or intensity.
+ */
+function areaLightFromPlaceholder( node, record ) {
 
-	const shapeFactor = userData.shape === 'ellipse' || userData.shape === 'disk' ? Math.PI / 4 : 1;
-	const scale = node.getWorldScale( new Vector3() );
-	// abs: a mirrored ancestor decomposes negative; the serializer takes the area as |u × v|.
-	const factor = Math.PI * shapeFactor * Math.abs( width * scale.x * height * scale.y );
-	return Number.isFinite( factor ) ? factor : Math.PI;
+	const width = Number( record.width );
+	const height = Number( record.height );
+	const intensity = Number( record.intensity );
+	if ( ! ( width > 0 ) || ! ( height > 0 ) || ! Number.isFinite( intensity ) ) return null;
+
+	const shape = PLACEHOLDER_SHAPES.has( record.shape ) ? record.shape : 'rectangle';
+	const color = Array.isArray( record.color ) && record.color.length >= 3 ? record.color : [ 1, 1, 1 ];
+
+	const light = new RectAreaLight( new Color( ...color ), intensity, width, height );
+	light.name = record.name || 'RectAreaLight';
+	light.userData.normalize = record.normalize ?? true;
+	light.userData.spread = Number.isFinite( record.spread ) ? record.spread : Math.PI;
+	light.userData.shape = shape;
+
+	// Parented before baking: the bake needs the node's world scale, and on the append path
+	// nothing has refreshed the tree yet.
+	node.add( light );
+	bakeAreaLightScale( light );
+	return light;
 
 }
 
@@ -2081,50 +2109,40 @@ export class AssetLoader extends EventDispatcher {
 
 			const userData = object.userData;
 
-			// An adopted light carries three.js units; convert as point/spot are below.
-			if ( object.isRectAreaLight && ! userData.__radianceConverted ) {
+			// three.js states RectAreaLight.intensity as radiance, which is what the engine
+			// stores, so only the rectangle needs putting into world metres.
+			if ( object.isRectAreaLight ) bakeAreaLightScale( object );
 
-				object.intensity *= areaLightPowerFactor( object, object.width, object.height, userData );
-				userData.__radianceConverted = true;
+			// Punctual lights arrive photometric: glTF (and three.js) state point/spot in
+			// candela and directional in lux. The engine keeps the same QUANTITY in radiometric
+			// units — W/sr and W/m² — so only the luminous efficacy is divided back out, which
+			// is what Blender's own glTF importer does. Skipping it rendered every Blender lamp
+			// 683x too bright.
+			if ( ( object.isPointLight || object.isSpotLight ) && ! userData.__candelaConverted ) {
+
+				object.intensity /= LUMENS_PER_WATT;
+				userData.__candelaConverted = true;
 
 			}
 
-			// glTF punctual point/spot intensity is candela (W/sr); the engine's light
-			// model is Blender-style Power (W) that LightSerializer divides by 4π. Convert
-			// glTF candela → Power once at import (×4π) so it nets to the correct I/d².
-			// Directional (lux ≈ irradiance) is used directly and needs no conversion.
-			if ( ( object.isPointLight || object.isSpotLight ) && ! userData.__candelaConverted ) {
+			if ( object.isDirectionalLight && ! userData.__luxConverted ) {
 
-				object.intensity *= 4 * Math.PI;
-				userData.__candelaConverted = true;
+				object.intensity /= LUMENS_PER_WATT;
+				userData.__luxConverted = true;
 
 			}
 
-			// Process ceiling lights
-			if ( object.name.startsWith( 'RectAreaLightPlaceholder' ) &&
-				userData.name
-				// && userData.name.includes( "ceilingLight" )
-			) {
-
-				if ( userData.type === 'RectAreaLight' ) {
-
-					const normalize = userData.normalize ?? true;
-					const shape = userData.shape ?? 'rectangle';
-					const power = userData.intensity * areaLightPowerFactor( object, userData.width, userData.height, userData );
-					const light = new RectAreaLight(
-						new Color( ...userData.color ),
-						power * this._profile.areaLightIntensityScale,
-						userData.width,
-						userData.height
-					);
-					light.userData.normalize = normalize;
-					light.userData.spread = Number.isFinite( userData.spread ) ? userData.spread : Math.PI;
-					light.userData.shape = shape;
-					light.userData.__radianceConverted = true; // already power, and traverse() reaches it
-					light.name = userData.name;
-					object.add( light );
+			// An area light serialized into a placeholder node. Keyed on the record's own type
+			// rather than the node's name, so a renamed placeholder still lights the scene.
+			if ( userData.type === 'RectAreaLight' ) {
 
-				}
+				const light = areaLightFromPlaceholder( object, userData );
+				if ( ! light ) this._issues?.record(
+					ISSUE_CODES.LIGHT_PLACEHOLDER_INVALID,
+					`area-light placeholder "${object.name}" carries no usable size or intensity`,
+					{ node: object.name, record: userData },
+					ISSUE_SEVERITY.WARNING,
+				);
 
 			}
 

package/src/Processor/LightSerializer.js

@@ -1,10 +1,11 @@
 import { Vector3, Quaternion } from 'three';
 import { blackbodyToLinearRGB } from './blackbody.js';
+import { lightPower } from '../LightUnits.js';
 
-// Point & spot lights specify Power in Watts; the shader uses radiant intensity
-// (W/sr) as `intensity / dist²`, so convert with I = P / 4π (isotropic emitter),
-// matching Blender. Area lights are already radiant power; the Sun is irradiance.
-const INV_4PI = 1 / ( 4 * Math.PI );
+// Scene lights hold the three.js quantity in radiometric units (see LightUnits.js): point and
+// spot in W/sr, the Sun in W/m², area lights in radiance. The GPU buffer wants radiant intensity
+// for point/spot — already what they hold — and radiant POWER for area lights, which the shader
+// turns back into radiance with its own π·area. This is where that adaptation happens.
 
 // Effective emission colour + intensity after per-light Exposure (EV stops) and
 // optional blackbody Temperature tint (Blender-style). Both fold into the values
@@ -61,9 +62,10 @@ export class LightSerializer {
 
 	calculateLightImportance( light, type = 'directional' ) {
 
-		// Calculate luminance-weighted importance
+		// Ranked on Power, so the ordering does not shift when a light type's stored quantity
+		// differs from what the panel shows.
 		const luminance = 0.2126 * light.color.r + 0.7152 * light.color.g + 0.0722 * light.color.b;
-		let importance = light.intensity * luminance;
+		let importance = lightPower( light ) * luminance;
 
 		// Area lights get additional importance based on size
 		if ( type === 'area' ) {
@@ -172,6 +174,12 @@ export class LightSerializer {
 
 		const em = effectiveEmission( light );
 
+		// The shader recovers radiance as power/(π·area), so hand it the power that inverts to
+		// the radiance the light holds. Area is measured off u/v exactly as the shader does it.
+		const rectArea = 4 * u.clone().cross( v ).length();
+		const emittingArea = shape > 0.5 ? rectArea * Math.PI / 4 : rectArea;
+		const power = em.intensity * Math.PI * ( normalize > 0.5 ? emittingArea : 1 );
+
 		// Store in cache with importance (16 floats, vec4-aligned)
 		this.areaLightCache.push( {
 			data: [
@@ -179,7 +187,7 @@ export class LightSerializer {
 				u.x, u.y, u.z, // u half-vector (3)
 				v.x, v.y, v.z, // v half-vector (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity, // radiant power in Watts (1) — incl. exposure
+				power, // radiant power in Watts (1) — incl. exposure
 				normalize, // power-normalize flag (1)
 				spread, // emission spread in radians (1)
 				shape, // 0 = rect, 1 = disk/ellipse (1)
@@ -209,7 +217,7 @@ export class LightSerializer {
 			data: [
 				position.x, position.y, position.z, // position (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
+				em.intensity, // radiant intensity W/sr, incl. exposure (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
 				light.decay !== undefined ? light.decay : 2.0 // decay exponent (1)
 			],
@@ -252,7 +260,7 @@ export class LightSerializer {
 				position.x, position.y, position.z, // position (3)
 				direction.x, direction.y, direction.z, // direction (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
+				em.intensity, // radiant intensity W/sr, incl. exposure (1)
 				light.angle || Math.PI / 4, // cone half-angle in radians (1)
 				light.penumbra || 0.0, // penumbra [0,1] (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)

package/src/Stages/PathTracer.js

@@ -88,6 +88,8 @@ export class PathTracer extends PathTracerStage {
 		this._lastBounceEnergy = null;
 		// maxBounces the curve was measured at; the curve is ignored once this no longer matches (-1 = none).
 		this._lastBounceCountsBudget = - 1;
+		// Loop length the curve covers; maxBounces alone is not it (free bounces extend the loop).
+		this._lastBounceCountsLoopBound = - 1;
 		this._readbackPending = false;
 		this._readbackEveryNFrames = 4;
 		this._readbackFrameCounter = 0;
@@ -341,7 +343,7 @@ export class PathTracer extends PathTracerStage {
 
 		const maxBounces = this.maxBounces.value;
 		// Transmissive/SSS steps consume iterations without advancing camera-bounce depth, so the loop must run far enough for deep glass/subsurface walks (mirror PathTracerCore); the survivor curve + early-exit break it early on non-SSS scenes.
-		const loopBound = maxBounces + this.transmissiveBounces.value + this.maxSubsurfaceSteps.value;
+		const loopBound = this._bounceLoopBound();
 
 		const frameHeight = this._wfRenderHeight.value;
 		const chunkRows = this._chunkRows;
@@ -356,9 +358,17 @@ export class PathTracer extends PathTracerStage {
 		// new camera-bounce caps the counts are cap-independent, so trust it up to that cutoff (whole curve when
 		// same/decreasing budget; only the [0, oldBudget) overlap when increasing). budget=-1 → cutoff 0 → full
 		// dispatch everywhere. This avoids the full-work spike on every bounce-count change.
+		// A curve measured with a smaller free-bounce budget under-counts survivors at EVERY depth, not
+		// just past its tail, so sizing off it drops the deep glass paths the bigger budget bought.
+		if ( loopBound > this._lastBounceCountsLoopBound ) this._curveSizingValid = false;
+
 		const curve = this._lastBounceCounts;
+		const curveMeasuredThisFar = maxBounces <= this._lastBounceCountsBudget
+			&& loopBound <= this._lastBounceCountsLoopBound;
 		const curveReliableUpto = ( singleChunk && curve )
-			? ( maxBounces <= this._lastBounceCountsBudget ? loopBound + 1 : this._lastBounceCountsBudget )
+			? ( curveMeasuredThisFar
+				? loopBound + 1
+				: Math.min( this._lastBounceCountsBudget, this._lastBounceCountsLoopBound ) )
 			: 0;
 
 		// Blender-style row-band streaming: the fixed-budget path pool processes the image in bands of ≤ chunkRows
@@ -698,6 +708,12 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	_bounceLoopBound() {
+
+		return this.maxBounces.value + this.transmissiveBounces.value + this.maxSubsurfaceSteps.value;
+
+	}
+
 	// Async readback of the per-bounce snapshot every N frames; never awaited, so the early-exit uses past-frame data.
 	_maybeReadbackCounters() {
 
@@ -722,7 +738,8 @@ export class PathTracer extends PathTracerStage {
 		// the budget 3 -> 20 doubles the frame's dispatch work (13 -> 26 bounce iterations, 109 -> 214
 		// compute passes) for as long as that lasts. Waiting out the N-frame cadence just extends it, so
 		// re-measure on the next frame instead — same idiom as the mid-motion priming above.
-		if ( this.maxBounces.value !== this._lastBounceCountsBudget ) {
+		if ( this.maxBounces.value !== this._lastBounceCountsBudget
+			|| this._bounceLoopBound() !== this._lastBounceCountsLoopBound ) {
 
 			this._readbackFrameCounter = this._readbackEveryNFrames;
 
@@ -738,6 +755,7 @@ export class PathTracer extends PathTracerStage {
 		this._readbackPending = true;
 		const gen = this._readbackGeneration;
 		const budget = this.maxBounces.value;
+		const measuredLoopBound = this._bounceLoopBound();
 		const n = this._queueManager.MAX_BOUNCE_SNAPSHOTS;
 		this.renderer.getArrayBufferAsync( attr ).then( ( buf ) => {
 
@@ -750,6 +768,7 @@ export class PathTracer extends PathTracerStage {
 				this._lastBounceCounts = all.subarray( 0, n );
 				this._lastBounceEnergy = all.subarray( n, 2 * n );
 				this._lastBounceCountsBudget = budget;
+				this._lastBounceCountsLoopBound = measuredLoopBound;
 				this._curveSizingValid = true;
 
 			}
@@ -837,6 +856,7 @@ export class PathTracer extends PathTracerStage {
 		this._lastBounceCounts = null;
 		this._lastBounceEnergy = null;
 		this._lastBounceCountsBudget = - 1;
+		this._lastBounceCountsLoopBound = - 1;
 		this._curveSizingValid = false;
 		this._readbackFrameCounter = 0;
 		this._readbackGeneration ++;

package/src/TSL/LightsCore.js

@@ -251,10 +251,15 @@ export const getDistanceAttenuation = /*@__PURE__*/ wgslFn( `
 	}
 ` );
 
-// Spot light attenuation
+// Spot cone falloff, Blender/Cycles' shape: the soft edge is a smoothstep over a band of
+// COSINE width (1 - cosCone) * blend, not one that ends at the inner cone's angle. The two
+// agree at blend 0 and 1 and diverge in between — three.js' ramp ran twice as wide at 0.5,
+// leaving the penumbra up to 2x dark against a Cycles render of the same lamp.
 export const getSpotAttenuation = /*@__PURE__*/ wgslFn( `
-	fn getSpotAttenuation( coneCosine: f32, penumbraCosine: f32, angleCosine: f32 ) -> f32 {
-		return smoothstep( coneCosine, penumbraCosine, angleCosine );
+	fn getSpotAttenuation( coneCosine: f32, blend: f32, angleCosine: f32 ) -> f32 {
+		let smoothWidth = ( 1.0 - coneCosine ) * blend;
+		if ( smoothWidth <= 0.0 ) { return 1.0; }
+		return smoothstep( 0.0, 1.0, ( angleCosine - coneCosine ) / smoothWidth );
 	}
 ` );
 

package/src/TSL/LightsSampling.js

@@ -261,10 +261,7 @@ export const sampleSpotLightWithRadius = Fn( ( [ light, rayOrigin, lightSelectio
 
 		If( ls_valid, () => {
 
-			// Penumbra: inner cone angle = outerAngle * (1 - penumbra)
-			// Clamp penumbraCosAngle > coneCosAngle to avoid smoothstep UB when penumbra = 0
-			const penumbraCosAngle = cos( light.angle.mul( float( 1.0 ).sub( light.penumbra ) ) ).max( coneCosAngle.add( 1e-5 ) ).toVar();
-			const coneAttenuation = getSpotAttenuation( { coneCosine: coneCosAngle, penumbraCosine: penumbraCosAngle, angleCosine: spotCosAngle } );
+			const coneAttenuation = getSpotAttenuation( { coneCosine: coneCosAngle, blend: light.penumbra, angleCosine: spotCosAngle } );
 			const distanceAttenuation = getDistanceAttenuation( { lightDistance: lightDist, cutoffDistance: light.distance, decayExponent: light.decay } );
 
 			// Gobo projection mask + IES photometric profile — both 1.0 when not assigned.

package/src/index.js

@@ -18,6 +18,7 @@ export { EngineEvents } from './EngineEvents.js';
 export { renderHeadless, openHeadless, captureHeadless } from './Headless.js';
 
 // Degradation contract — what the engine survived instead of failing on
+export { LUMENS_PER_WATT, areaLightArea, bakeAreaLightScale, lightPower, preserveLightPower, setLightPower } from './LightUnits.js';
 export { ISSUE_CODES, ISSUE_SEVERITY, IssueLog, EngineIssueError } from './EngineIssues.js';
 
 // Settings provenance + viewer-vs-physical tuning

package/src/managers/DenoisingManager.js

@@ -149,6 +149,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._holdWhileMoving = null;
 		this._onReset = null;
 		this._onPostProcessRefresh = null;
+		this._onDisplayRefresh = null;
 
 		// Resolution tracking — used for canvas restoration on reset
 		this._lastRenderWidth = 0;
@@ -1057,6 +1058,10 @@ export class DenoisingManager extends EventDispatcher {
 
 			if ( ! isStillComplete() ) return;
 
+			// The loop stops one tick after a render completes, so nothing is left to draw the closing
+			// denoise. Ordered after `_denoiserEndHandler`, which publishes the picture.
+			if ( closing ) this._onDisplayRefresh?.();
+
 			// One owner of the overlay canvas, so the neural chain and the ONNX upscaler are
 			// exclusive. The neural chain also runs on its own when only its detail pass is on.
 			if ( this.neuralRendering || ( this.upscaler?.enabled && this.upscalerBackend === 'dlss' ) ) {
@@ -1220,6 +1225,10 @@ export class DenoisingManager extends EventDispatcher {
 		this._upscalerProgressHandler = null;
 		this._upscalerEndHandler = null;
 
+		this._onReset = null;
+		this._onPostProcessRefresh = null;
+		this._onDisplayRefresh = null;
+
 		if ( this.upscalerCanvas?.parentNode ) {
 
 			this.upscalerCanvas.parentNode.removeChild( this.upscalerCanvas );
@@ -1252,6 +1261,13 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** @param {Function} fn - () => void, redraws the finished frame without re-running the completion chain */
+	setDisplayRefreshCallback( fn ) {
+
+		this._onDisplayRefresh = fn;
+
+	}
+
 	/** @param {import('../RenderSettings.js').RenderSettings} settings */
 	setSettings( settings ) {