rayzee 11.7.0 → 11.9.0

package/dist/{sceneCachePolicy-B9w3BnaP.js → sceneCachePolicy-ywbGKHD3.js}

@@ -1,7 +1,7 @@
 import { t as e } from "./EngineEvents-CLckhYbL.js";
 import { a as t, i as n, r } from "./Logger-dDDGj9Av.js";
-import { f as i, v as a, y as o } from "./BufferLayout-xPRH9jYD.js";
-import { n as s } from "./EngineIssues-CIZnXHsF.js";
+import { f as i, v as a, y as o } from "./BufferLayout-Bzgccg1o.js";
+import { n as s } from "./EngineIssues-CfJiBaNj.js";
 import { n as c, r as l } from "./shared-BGBcSxBQ.js";
 import { n as u } from "./AssetConfig-DSEntE65.js";
 import { BackSide as d, BufferAttribute as f, Color as p, DoubleSide as m, FrontSide as h, Matrix3 as g, Matrix4 as _, RGBAFormat as v, Vector2 as y, Vector3 as b } from "three";
@@ -230,6 +230,7 @@ var E = de({
 	normalScale: [1, 1],
 	bumpScale: 1,
 	displacementScale: 1,
+	displacementBias: 0,
 	transparent: 0,
 	alphaTest: 0,
 	alphaMode: 0,
@@ -1069,7 +1070,7 @@ var Be = class {
 		this.expandedTriangleCount += u.count, this.meshTriangleRanges.push(u), u.count > 0 && !l && a && this._geometryRanges.set(r, {
 			...u,
 			meshIndex: n
-		}), this._recordPlacements(e, n, l, c, u.count > 0 && a), u.count > 0 && this._onRange?.(n, u);
+		}), u.count > 0 && (this._recordPlacements(e, n, l, c, a), this._onRange?.(n, u));
 	}
 	_recordPlacements(e, t, n = !1, r = !1, i = !1) {
 		let a = e.matrixWorld.elements, o = this.instanceSource;
@@ -1232,6 +1233,7 @@ var Be = class {
 			normalScale: o("normalScale"),
 			bumpScale: o("bumpScale"),
 			displacementScale: o("displacementScale"),
+			displacementBias: o("displacementBias"),
 			transparent: +!!e.transparent,
 			alphaTest: o("alphaTest"),
 			alphaMode: Pe(e),
@@ -1298,9 +1300,10 @@ var Be = class {
 	}
 	extractGeometry(e, t, n, r = !1, i = !1) {
 		e.updateMatrix(), e.updateMatrixWorld();
-		let a = e.geometry;
+		let a = e.geometry, o = a.attributes.position;
+		if (!o) return;
 		a.attributes.normal || a.computeVertexNormals();
-		let o = a.attributes.position, s = a.attributes.normal, c = a.attributes.uv, l = a.index ? a.index.array : null, u = l ? l.length / 3 : o.count / 3;
+		let s = a.attributes.normal, c = a.attributes.uv, l = a.index ? a.index.array : null, u = Math.floor((l ? l.length : o.count) / 3);
 		if (i) {
 			let r = e.count ?? e.instanceMatrix.array.length / 16, i = this._matrixPool.mat4, a = new _();
 			for (let d = 0; d < r; d++) {
@@ -1594,7 +1597,7 @@ var vt = class {
 			samples: this.samples.slice()
 		};
 	}
-}, yt = "11.7.0", $ = 1e4, bt = 15e5;
+}, yt = "11.9.0", $ = 1e4, bt = 15e5;
 function xt(e, t, n = $) {
 	return e >= n && t / bt < e / 3;
 }

package/package.json

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

package/src/EngineDefaults.js

@@ -117,6 +117,7 @@ export const MATERIAL_DEFAULTS = deepFreeze( {
 	normalScale: [ 1, 1 ],
 	bumpScale: 1,
 	displacementScale: 1,
+	displacementBias: 0,
 	transparent: 0,
 	alphaTest: 0,
 	alphaMode: 0,

package/src/EngineIssues.js

@@ -6,10 +6,14 @@
  */
 export const ISSUE_CODES = Object.freeze( {
 	ADAPTER_SOFTWARE: 'adapter.software',
+	ADAPTER_UNAVAILABLE: 'adapter.unavailable',
+	DEVICE_UNAVAILABLE: 'device.unavailable',
+	WEBGPU_UNAVAILABLE: 'webgpu.unavailable',
 	ASSET_UNREACHABLE: 'asset.unreachable',
 	ASSET_AMBIGUOUS_ENTRY: 'asset.ambiguous_entry',
 	ASSET_ARCHIVE_TOO_LARGE: 'asset.archive_too_large',
 	ASSET_ENTRY_TOO_LARGE: 'asset.entry_too_large',
+	ASSET_PARAMETERS_IGNORED: 'asset.parameters_ignored',
 	TEXTURE_BUILD_FAILED: 'texture.build_failed',
 	TEXTURE_PROCESSING_FALLBACK: 'texture.processing_fallback',
 	TEXTURE_LIMIT_EXCEEDED: 'texture.limit_exceeded',
@@ -42,9 +46,9 @@ export const ISSUE_SEVERITY = Object.freeze( { ERROR: 'error', WARNING: 'warning
 
 export class EngineIssueError extends Error {
 
-	constructor( issue ) {
+	constructor( issue, options ) {
 
-		super( `[${issue.code}] ${issue.message}` );
+		super( `[${issue.code}] ${issue.message}`, options );
 		this.name = 'EngineIssueError';
 		this.code = issue.code;
 		this.detail = issue.detail;
@@ -67,13 +71,24 @@ export class IssueLog {
 	/** @throws {EngineIssueError} when strict and severity is 'error' */
 	record( code, message, detail = {}, severity = ISSUE_SEVERITY.ERROR ) {
 
-		const issue = Object.freeze( { code, message, detail, severity, at: Date.now() } );
-		this._entries.push( issue );
+		const issue = this._add( code, message, detail, severity );
+		if ( this.strict && severity === ISSUE_SEVERITY.ERROR ) throw new EngineIssueError( issue );
+		return issue;
 
-		this._onIssue?.( issue );
+	}
 
-		if ( this.strict && severity === ISSUE_SEVERITY.ERROR ) throw new EngineIssueError( issue );
+	/** For what nothing can continue past: records an error and throws it, strict or not. */
+	fail( code, message, detail = {}, cause ) {
 
+		throw new EngineIssueError( this._add( code, message, detail, ISSUE_SEVERITY.ERROR ), cause === undefined ? undefined : { cause } );
+
+	}
+
+	_add( code, message, detail, severity ) {
+
+		const issue = Object.freeze( { code, message, detail, severity, at: Date.now() } );
+		this._entries.push( issue );
+		this._onIssue?.( issue );
 		return issue;
 
 	}

package/src/Passes/AIUpscaler.js

@@ -78,6 +78,7 @@ export class AIUpscaler extends EventDispatcher {
 	 * @param {Function} [options.getGPUTextures] - Returns { color: GPUTexture } for HDR path
 	 * @param {Function} [options.getExposure] - Returns current exposure multiplier
 	 * @param {Function} [options.getToneMapping] - Returns Three.js ToneMapping constant
+	 * @param {Function} [options.getTransparentBackground] - Whether the HDR path keeps the render's coverage as alpha
 	 * @param {number} [options.tileSize] - Override default tile size
 	 */
 	constructor( output, renderer, options = {} ) {
@@ -101,6 +102,7 @@ export class AIUpscaler extends EventDispatcher {
 		this.getToneMapping = options.getToneMapping || ( () => ACESFilmicToneMapping );
 		this.getSaturation = options.getSaturation || ( () => 1.0 );
 		this.getDisplayGain = options.getDisplayGain || ( () => null );
+		this.getTransparentBackground = options.getTransparentBackground || ( () => false );
 
 		// Configuration
 		this.enabled = false;
@@ -506,6 +508,8 @@ export class AIUpscaler extends EventDispatcher {
 			gain: this.getDisplayGain(),
 		} );
 		this._toneMapper.release();
+		// The render's alpha is coverage; the canvas shows an opaque backdrop opaque, and so does the upscale.
+		if ( ! this.getTransparentBackground() ) planes.fill( 1, 3 * width * height );
 
 		return { planes, width, height, isHDR: true };
 

package/src/Passes/OIDNDenoiser.js

@@ -443,10 +443,10 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		} while ( this._reloadPending );
 
-		// Fire a start() that arrived mid-load. Guard on unet+enabled so a failed load
-		// or a disable during loading doesn't kick off a denoise. Outside the loop, so a
-		// no-op reload still releases it — it used to be stranded by the early return below.
-		if ( this._pendingStart && this.unet && this.enabled ) {
+		// Fire a start() that arrived mid-load, unless it was disabled meanwhile. After a failed
+		// load too: it denoises nothing but still sends 'end', which its caller waits for. Outside
+		// the loop, so a no-op reload still releases it — it used to be stranded by the early return below.
+		if ( this._pendingStart && this.enabled ) {
 
 			const continuous = this._pendingStartContinuous;
 			this._pendingStart = false;
@@ -617,8 +617,6 @@ export class OIDNDenoiser extends EventDispatcher {
 
 	async execute( continuous = false ) {
 
-		if ( ! this.enabled || ! this.unet ) return false;
-
 		// Create abort controller for this execution
 		const runId = ++ this._runId;
 		this.state.abortController = new AbortController();
@@ -626,6 +624,10 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		try {
 
+			// Inside the try, so the finally ends what start() announced: with no weights (a failed
+			// load) the Denoising badge, the closing upscaler and a video export waited forever.
+			if ( ! this.enabled || ! this.unet ) return false;
+
 			// The GPU path bails out early — no textures yet, no device — by returning false, and
 			// a caller that read that as success published a picture nothing had written to.
 			return await this._executeUNetGPU( continuous ) !== false;

package/src/Passes/OIDNTemporalHistory.js

@@ -221,7 +221,7 @@ fn main( @builtin(global_invocation_id) gid: vec3<u32> ) {
 
 	}
 
-	let rough = textureLoad( shading, p, 0 ).w;
+	let rough = abs( textureLoad( shading, p, 0 ).w );
 	var cap = mix( P.smoothLength, P.maxLength, smoothstep( P.roughStart, P.roughEnd, rough ) );
 	if ( movedPx ) { cap = min( cap, P.movedLength ); }
 	let newLen = min( len + 1.0, cap );

package/src/PathTracerApp.js

@@ -5,6 +5,7 @@ import { MotionVector } from './Stages/MotionVector.js';
 import { NRD } from './Stages/NRD.js';
 import { AutoExposure, AUTO_EXPOSURE_DEFAULTS } from './Stages/AutoExposure.js';
 import { LocalExposure, LOCAL_EXPOSURE_DEFAULTS } from './Stages/LocalExposure.js';
+import { backdropGain } from './Processor/ToneMapCPU.js';
 import { PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings } from './EngineDefaults.js';
 import { createLogger } from './utils/Logger.js';
 import { EngineEvents } from './EngineEvents.js';
@@ -323,6 +324,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 				if ( this.stages.autoExposure ) this.stages.autoExposure.setCompensation( value );
 				else core.applyExposure( value );
+				this.stages.compositor?.setBackdropExposure( value );
 
 			},
 			onCameraProjection: ( value ) => {
@@ -423,7 +425,12 @@ export class PathTracerApp extends RayzeeRenderer {
 		const le = this.stages.localExposure;
 		// A readback outside the loop (headless) can come before the loop would have built it from this image.
 		if ( le?.wantsBuild ) le.build( this.pipeline.context );
-		return le?.toneGain() ?? null;
+		const local = le?.toneGain() ?? null;
+		if ( this.pipeline?.context.getState( 'pathtracer:backdrop' ) !== 'color' ) return local;
+
+		// As the compositor shows it: a solid backdrop at the manual exposure, untouched by auto and local exposure.
+		const { toneMappingExposure, toneMapping } = this.renderer;
+		return { ...local, backdrop: backdropGain( this.settings.get( 'exposure' ) ?? 1, toneMappingExposure, toneMapping ) };
 
 	}
 
@@ -1130,6 +1137,8 @@ export class PathTracerApp extends RayzeeRenderer {
 		if ( ! ae ) return;
 
 		ae.setCompensation( this.settings.get( 'exposure' ) ?? 1 );
+		// A solid backdrop stays at the manual exposure while auto exposure moves the picture.
+		this.stages.compositor.setBackdropExposure( this.settings.get( 'exposure' ) ?? 1 );
 		if ( this.stages.localExposure ) this.stages.localExposure.onChange = () => this._refreshFinished();
 		ae.onChange = () => this._refreshFinished();
 

package/src/Processor/ArchiveImporter.js

@@ -26,9 +26,10 @@ import { loadPBRTScene, pickEntryPath, VirtualFS, PBRT_BUILD_REVISION } from './
 import { loadUSDScene, listUSDRootLayers, listUSDParts, USDFiles, USDStage, USD_LAYER } from './USD/index.js';
 import { pfmTexture } from './PBRT/PFM.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
-import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
+import { ISSUE_CODES, ISSUE_SEVERITY, EngineIssueError } from '../EngineIssues.js';
 import { ARCHIVE_FORMATS } from './archiveFormats.js';
-import { withHostWorker } from '../Platform.js';
+import { withHostWorker, getPlatform } from '../Platform.js';
+import { platformImageFromBytes } from './PlatformImageLoader.js';
 
 const MTL_TEXTURE_TIMEOUT_MS = 30000;
 const MAIN_MODEL_FILES = [ 'scene.gltf', 'scene.glb', 'model.gltf', 'model.glb', 'main.gltf', 'main.glb', 'asset.gltf', 'asset.glb' ];
@@ -81,16 +82,17 @@ export class ArchiveImporter {
 	constructor( loader ) {
 
 		this.loader = loader;
-		this._pendingGraph = null;
+		this._store = null;
 		this.lastPBRTStats = null;
 		this.lastUSDStats = null;
 
 	}
 
-	/** Drops a parsed scene still waiting to be stored: the model it was for is gone. */
+	/** Abandons a parsed scene the engine has not accepted: the model it was for is gone, or its load failed. */
 	release() {
 
-		this._pendingGraph = null;
+		this._store?.decide( false );
+		this._store = null;
 
 	}
 
@@ -382,7 +384,8 @@ export class ArchiveImporter {
 
 	/**
 	 * Stores a freshly parsed scene for the next open. Encoded here, before onModelLoad or the
-	 * build touch it; written in the background.
+	 * build touch it; written in the background, and visible to an open only once the engine
+	 * accepts the scene ({@link commitPendingGraph}).
 	 * @private
 	 */
 	_storeGraph( key, built, label ) {
@@ -400,7 +403,7 @@ export class ArchiveImporter {
 					meshCount: built.meshCount, entryPath: built.entryPath, candidates: built.candidates, frames: built.frames,
 					warnings: built.warnings, triangleCount: built.triangleCount, placementCount: built.placementCount,
 					mergedShapes: built.mergedShapes, skippedForBudget: built.skippedForBudget, droppedNoTemplate: built.droppedNoTemplate,
-					render: built.render ?? null,
+					render: built.render ?? null, parameters: built.parameters ?? null,
 				},
 			} );
 
@@ -412,13 +415,29 @@ export class ArchiveImporter {
 
 		}
 
-		const pending = { key, encoded, label, parseMs: ( built.parseMs ?? 0 ) + ( built.buildMs ?? 0 ), triangles: built.triangleCount ?? null };
+		let settle;
+		const stop = new AbortController();
+		const store = {
+			key, encoded, label, model: built.group, writing: false, signal: stop.signal,
+			parseMs: ( built.parseMs ?? 0 ) + ( built.buildMs ?? 0 ), triangles: built.triangleCount ?? null,
+			accepted: new Promise( resolve => {
+
+				settle = resolve;
+
+			} ),
+			decide: accepted => {
+
+				settle( accepted );
+				if ( ! accepted ) stop.abort();
+
+			},
+		};
+		this._store = store;
 
 		// A parse slow enough on its own is written now, during the build. Held until the build
 		// ends, it kept every array the build replaces alive with it — the float normals and the
 		// instance matrices, ~1 GB on the whole Moana subset, at the build's peak.
-		if ( worthStoring( pending.parseMs, encoded.byteLength ) ) this._writeGraph( area, pending );
-		else this._pendingGraph = pending;
+		if ( worthStoring( store.parseMs, encoded.byteLength ) ) this._writeGraph( area, store );
 
 	}
 
@@ -429,34 +448,57 @@ export class ArchiveImporter {
 	 */
 	flushPendingGraph( buildMs ) {
 
-		const pending = this._pendingGraph;
-		this._pendingGraph = null;
+		const store = this._store;
+		if ( ! store || store.writing ) return;
 		const area = this.loader.storage?.area( ENGINE_AREAS.SCENES );
-		if ( ! pending || ! area || ! worthStoring( pending.parseMs + buildMs, pending.encoded.byteLength ) ) return;
-		this._writeGraph( area, pending );
+		if ( area && worthStoring( store.parseMs + buildMs, store.encoded.byteLength ) ) this._writeGraph( area, store );
+		else this._store = null;
+
+	}
+
+	/**
+	 * The engine accepted `model`: the scene stored for it is committed once written. Until then the
+	 * entry has no metadata, so no open can restore it.
+	 * @param {import('three').Object3D} model - the model whose load the engine finished
+	 */
+	commitPendingGraph( model ) {
+
+		const store = this._store;
+		if ( ! store || store.model !== model ) return;
+		this._store = null;
+		store.model = null;
+		store.decide( store.writing );
 
 	}
 
 	/** Writes an encoded graph in the background, letting each array go once it is on disk. @private */
-	_writeGraph( area, pending ) {
+	_writeGraph( area, store ) {
 
+		store.writing = true;
 		( async () => {
 
-			const writer = await area.create( pending.key, { label: `${pending.label} (scene)`, expectedBytes: pending.encoded.byteLength } );
-			if ( ! writer ) return;
+			let writer = null;
 			try {
 
-				await writeSceneGraph( writer, pending.encoded, { release: true } );
-				await writer.commit( { triangles: pending.triangles } );
+				writer = await area.create( store.key, { label: `${store.label} (scene)`, expectedBytes: store.encoded.byteLength } );
+				if ( ! writer ) return;
+				await writeSceneGraph( writer, store.encoded, { release: true, signal: store.signal } );
+				store.encoded = null;
+				if ( await store.accepted ) await writer.commit( { triangles: store.triangles } );
+				else await writer.abort();
 
 			} catch ( error ) {
 
-				await writer.abort();
-				console.warn( 'Storing the scene failed:', error );
+				await writer?.abort().catch( () => {} );
+				if ( ! store.signal.aborted ) console.warn( 'Storing the scene failed:', error );
+
+			} finally {
+
+				store.encoded = null;
 
 			}
 
-		} )().catch( error => console.warn( 'Storing the scene failed:', error ) );
+		} )();
 
 	}
 
@@ -646,10 +688,11 @@ export class ArchiveImporter {
 
 		const stored = graphKey ? await this._loadStoredGraph( graphKey, source, { imageFromBytes, envFromBytes } ) : null;
 		const built = stored ?? await loadPBRTScene( { vfs: zip, source, entryPath, plyParser, imageFromBytes, envFromBytes, ...shape } );
+		this.loader._throwDeferred();
 
 		const { group, environment, animations, report, warnings, meshCount, entryPath: loadedEntry, candidates,
 			frames, parseMs, buildMs, triangleCount, placementCount, mergedShapes, skippedForBudget,
-			droppedNoTemplate } = built;
+			droppedNoTemplate, parameters } = built;
 		if ( stored ) console.info( `PBRT scene "${loadedEntry}" opened from storage in ${( buildMs / 1000 ).toFixed( 1 )} s, skipping the parse` );
 
 		// Phase breakdown for scaling work; the engine's own build timings live in
@@ -677,6 +720,8 @@ export class ArchiveImporter {
 
 		}
 
+		if ( parameters ) this._reportParameters( parameters, loadedEntry );
+
 		// Diagnostics — surface what each mesh resolved to (helps debug black/wrong materials).
 		if ( report && report.length && typeof console.table === 'function' ) {
 
@@ -726,10 +771,42 @@ export class ArchiveImporter {
 
 	}
 
+	/**
+	 * Every parameter the scene sets that the loader ignored or approximated, once, each with the number of directives
+	 * that set it: one warning and one console list, never cut short.
+	 * @private
+	 */
+	_reportParameters( { unused, approximated }, entry ) {
+
+		const ignored = Object.keys( unused ).length, approx = Object.keys( approximated ).length;
+		if ( ignored + approx === 0 ) return;
+		const message = `${ignored} pbrt parameter(s) ignored and ${approx} approximated in "${entry}"`;
+		const lines = [
+			...Object.entries( unused ).map( ( [ key, count ] ) => `  ignored       ${key} ×${count}` ),
+			...Object.entries( approximated ).map( ( [ key, count ] ) => `  approximated  ${key} ×${count}` )
+		];
+		console.warn( `PBRT loader: ${message} (× directives that set it)\n${lines.join( '\n' )}` );
+		this.loader._issues?.warn( ISSUE_CODES.ASSET_PARAMETERS_IGNORED, message, { entry, unused, approximated } );
+
+	}
+
 	/** A texture map from an archive, tagged with its path so a stored scene can read it back. @private */
 	async _archiveImage( bytes, fname ) {
 
-		const texture = await this._pbrtTextureFromBytes( bytes, fname );
+		let texture;
+		try {
+
+			texture = await this._pbrtTextureFromBytes( bytes, fname );
+
+		} catch ( error ) {
+
+			// As a glTF's image: its surfaces render untextured, and a strict host hears of it at the end of the load.
+			if ( error instanceof EngineIssueError ) throw error;
+			this.loader._reportImageFailure( fname, error );
+			return null;
+
+		}
+
 		if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
 		return texture;
 
@@ -803,6 +880,7 @@ export class ArchiveImporter {
 			maxTriangles: options.maxTriangles, maxPlacements: options.maxPlacements, mergeShapesAbove: options.mergeShapesAbove,
 			curveSteps: options.curveSteps, curveSides: options.curveSides, curveTolerance: options.curveTolerance,
 		} );
+		this.loader._throwDeferred();
 
 		const { group, environment, warnings, triangleCount, placementCount, skippedForBudget, meshCount, parseMs, buildMs, fitNote } = built;
 		this.lastUSDStats = { parseMs, buildMs, loaderMs: performance.now() - start, triangleCount, placementCount, skippedForBudget, meshCount, fitNote };
@@ -915,9 +993,10 @@ export class ArchiveImporter {
 
 		} else {
 
-			// png / jpg / webp / gif / bmp
-			const bitmap = await createImageBitmap( new Blob( [ bytes ] ) );
-			tex = new Texture( bitmap );
+			// png / jpg / webp / gif / bmp: the host's decoder where it has one (Node), else the browser's.
+			if ( getPlatform().decodeImage ) tex = await platformImageFromBytes( bytes, fname );
+			else if ( typeof createImageBitmap === 'function' ) tex = new Texture( await createImageBitmap( new Blob( [ bytes ] ) ) );
+			else throw new Error( 'no image decoder in this runtime: configurePlatform( nodePlatform( { decodeImage } ) ) — see "Running in Node"' );
 			tex.colorSpace = SRGBColorSpace;
 
 		}

package/src/Processor/AssetLoader.js

@@ -52,6 +52,20 @@ function standInForSplit( source ) {
 
 }
 
+// glTF's znear is a camera's near clipping plane (Blender writes its clip start there): the path tracer honours it.
+export const cameraClipPlugin = {
+	name: 'RAYZEE_camera_clip',
+	afterRoot( result ) {
+
+		for ( const scene of result.scenes ) scene.traverse( ( object ) => {
+
+			if ( object.isCamera && object.near > 0 ) object.userData.clipStart = object.near;
+
+		} );
+
+	},
+};
+
 // Luminous efficacy glTF, three.js and Blender's exporter all assume (PBR_WATTS_TO_LUMENS).
 const LUMENS_PER_WATT = 683;
 
@@ -406,6 +420,13 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	/** @see ArchiveImporter#commitPendingGraph */
+	commitPendingGraph( model ) {
+
+		this.archives?.commitPendingGraph( model );
+
+	}
+
 	// Blob's own readers, not FileReader: Node has no FileReader.
 	readFileAsArrayBuffer( file ) {
 
@@ -768,6 +789,7 @@ export class AssetLoader extends EventDispatcher {
 		if ( getPlatform().decodeImage ) loader.register( ( parser ) => platformImagesPlugin( parser, onImageFailure ) );
 		else if ( ! hasImageDecoder() ) loader.register( ( parser ) => missingImageDecoderPlugin( parser, onImageFailure ) );
 		loader.register( ( parser ) => diffuseTransmissionPlugin( parser ) );
+		loader.register( () => cameraClipPlugin );
 
 		return loader;
 

package/src/Processor/BufferLayout.js

@@ -149,8 +149,8 @@ export const MATERIAL_DATA_LAYOUT = {
 	SPECULAR_INTENSITY: 40, SPECULAR_COLOR: 41,
 	// Slot 11: iridescence + iridescenceIOR + iridescenceThicknessRange [extended BxDF]
 	IRIDESCENCE: 44, IRIDESCENCE_IOR: 45, IRIDESCENCE_THICKNESS_RANGE: 46,
-	// Slot 12: bumpScale + displacementScale + displacementMapIndex + (padding)
-	BUMP_SCALE: 48, DISPLACEMENT_SCALE: 49, DISPLACEMENT_MAP_INDEX: 50,
+	// Slot 12: bumpScale + displacementScale + displacementMapIndex + displacementBias
+	BUMP_SCALE: 48, DISPLACEMENT_SCALE: 49, DISPLACEMENT_MAP_INDEX: 50, DISPLACEMENT_BIAS: 51,
 
 	// ── Transform float offsets (8 floats each: 7 matrix values + 1 padding) ──
 	ALBEDO_TRANSFORM: 52,
@@ -193,7 +193,7 @@ export const MATERIAL_DATA_LAYOUT = {
 		SHEEN_COLOR: 9, // [extended] sheenColor, diffuseTransmission
 		SPECULAR: 10, // [extended] specularIntensity, specularColor
 		IRIDESCENCE: 11, // [extended] iridescence, iridescenceIOR, iridescenceThicknessRange
-		BUMP_DISPLACEMENT: 12, // bumpScale, displacementScale, displacementMapIndex
+		BUMP_DISPLACEMENT: 12, // bumpScale, displacementScale, displacementMapIndex, displacementBias
 		ALBEDO_TRANSFORM_A: 13, ALBEDO_TRANSFORM_B: 14,
 		NORMAL_TRANSFORM_A: 15, NORMAL_TRANSFORM_B: 16,
 		ROUGHNESS_TRANSFORM_A: 17, ROUGHNESS_TRANSFORM_B: 18,

package/src/Processor/GeometryExtractor.js

@@ -862,8 +862,13 @@ export class GeometryExtractor {
 		this.expandedTriangleCount += range.count;
 		this.meshTriangleRanges.push( range );
 		if ( range.count > 0 && ! bake && shareable ) this._geometryRanges.set( key, { ...range, meshIndex } );
-		this._recordPlacements( mesh, meshIndex, bake, expand, range.count > 0 && shareable );
-		if ( range.count > 0 ) this._onRange?.( meshIndex, range );
+		// A placement with nothing to trace would get a TLAS leaf with no BLAS to point at.
+		if ( range.count > 0 ) {
+
+			this._recordPlacements( mesh, meshIndex, bake, expand, shareable );
+			this._onRange?.( meshIndex, range );
+
+		}
 
 	}
 
@@ -1227,6 +1232,7 @@ export class GeometryExtractor {
 			normalScale: pick( 'normalScale' ),
 			bumpScale: pick( 'bumpScale' ),
 			displacementScale: pick( 'displacementScale' ),
+			displacementBias: pick( 'displacementBias' ),
 
 			transparent: material.transparent ? 1 : 0,
 			alphaTest: pick( 'alphaTest' ),
@@ -1345,13 +1351,15 @@ export class GeometryExtractor {
 		mesh.updateMatrixWorld();
 
 		const geometry = mesh.geometry;
-		if ( ! geometry.attributes.normal ) geometry.computeVertexNormals();
 		const positions = geometry.attributes.position;
+		if ( ! positions ) return;
+		if ( ! geometry.attributes.normal ) geometry.computeVertexNormals();
 		const normals = geometry.attributes.normal;
 		const uvs = geometry.attributes.uv;
 		const indices = geometry.index ? geometry.index.array : null;
 
-		const triangleCount = indices ? indices.length / 3 : positions.count / 3;
+		// Whole triangles only, as three.js draws them: a trailing vertex or two read past the end as NaN.
+		const triangleCount = Math.floor( ( indices ? indices.length : positions.count ) / 3 );
 
 		if ( expandInstances ) {
 

package/src/Processor/LightSerializer.js

@@ -32,6 +32,9 @@ function effectiveEmission( light ) {
 
 }
 
+// A point or spot light's radius (Blender's Radius, USD's SphereLight radius): `userData.radius`, in scene units.
+const lightRadius = ( light ) => Math.max( 0, Number( light.userData?.radius ) || 0 );
+
 export class LightSerializer {
 
 	constructor() {
@@ -216,7 +219,8 @@ export class LightSerializer {
 				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)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
-				light.decay !== undefined ? light.decay : 2.0 // decay exponent (1)
+				light.decay !== undefined ? light.decay : 2.0, // decay exponent (1)
+				lightRadius( light ), // radius: a disc this size facing the lit point, 0 = a point (1)
 			],
 			importance: importance,
 			light: light
@@ -266,7 +270,7 @@ export class LightSerializer {
 				goboIntensity, // signed gobo strength (1)
 				iesIndex, // IES profile index, -1 = none (1)
 				iesIntensity, // IES blend [0,1] (1)
-				0.0, // reserved (1)
+				lightRadius( light ), // radius, as a point light's (1)
 				0.0, // reserved (1) — keeps stride at 20 (vec4 aligned)
 			],
 			importance: importance,

package/src/Processor/MaterialPacking.js

@@ -16,7 +16,7 @@ const TRANSFORMS = [
 
 /** Floats no field writes; the packer gives them fixed values. */
 export const MATERIAL_RESERVED_FLOATS = Object.freeze( [
-	M.VISIBLE, M.DISPLACEMENT_MAP_INDEX + 1, M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 1, M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 2,
+	M.VISIBLE, M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 1, M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 2,
 ] );
 
 /**
@@ -129,6 +129,7 @@ export function packMaterial( data, base, mat ) {
 	s( M.BUMP_SCALE, mat.bumpScale, D.bumpScale );
 	s( M.DISPLACEMENT_SCALE, mat.displacementScale, D.displacementScale );
 	data[ base + M.DISPLACEMENT_MAP_INDEX ] = mapIndex( mat.displacementMap );
+	s( M.DISPLACEMENT_BIAS, mat.displacementBias, D.displacementBias );
 
 	for ( const [ key, offset ] of TRANSFORMS ) {
 
@@ -163,7 +164,6 @@ export function packMaterial( data, base, mat ) {
 	data[ base + M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX ] = mapIndex( mat.diffuseTransmissionColorMap );
 
 	data[ base + M.VISIBLE ] = 1;
-	data[ base + M.DISPLACEMENT_MAP_INDEX + 1 ] = 0;
 	data[ base + M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 1 ] = 0;
 	data[ base + M.DIFFUSE_TRANSMISSION_COLOR_MAP_INDEX + 2 ] = 0;