rayzee 9.1.2 → 9.2.1

package/src/managers/CameraManager.js

@@ -363,7 +363,7 @@ export class CameraManager extends EventDispatcher {
 		onReset?.();
 
 		this.dispatchEvent( {
-			type: 'CameraSwitched', cameraIndex: index, effects: this._captureEffects(), fov: this.camera.fov,
+			type: EngineEvents.CAMERA_SWITCHED, cameraIndex: index, effects: this._captureEffects(), fov: this.camera.fov,
 			cameraProjection: this._getSettings?.( 'cameraProjection' ),
 		} );
 
@@ -717,7 +717,7 @@ export class CameraManager extends EventDispatcher {
 		this.resetAutoFocus();
 		this._reportOrthoHeight();
 		this.dispatchEvent( {
-			type: 'CameraSwitched', cameraIndex: this.currentCameraIndex, effects: this._captureEffects(), fov: this.camera.fov,
+			type: EngineEvents.CAMERA_SWITCHED, cameraIndex: this.currentCameraIndex, effects: this._captureEffects(), fov: this.camera.fov,
 			cameraProjection: this._getSettings?.( 'cameraProjection' ),
 		} );
 

package/src/managers/DenoisingManager.js

@@ -3,6 +3,7 @@ import { OIDNDenoiser } from '../Passes/OIDNDenoiser.js';
 import { OIDNTemporalHistory } from '../Passes/OIDNTemporalHistory.js';
 import { AIUpscaler } from '../Passes/AIUpscaler.js';
 import { EngineEvents } from '../EngineEvents.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger } from '../utils/Logger.js';
 
 // The neural passes live in `../neural/` but report through the manager that drives them, so they
@@ -100,12 +101,14 @@ export class DenoisingManager extends EventDispatcher {
 	 * @param {import('../Pipeline/RenderPipeline.js').RenderPipeline} params.pipeline
 	 * @param {Function}                               params.getExposure       - () => current exposure value
 	 * @param {Function}                               params.getSaturation     - () => current saturation value
+	 * @param {import('../EngineIssues.js').IssueLog}  [params.issues]
 	 */
-	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation } ) {
+	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation, issues = null } ) {
 
 		super();
 
 		this.renderer = renderer;
+		this._issues = issues;
 		this.mainCanvas = mainCanvas;
 		this.upscalerCanvas = this._createUpscalerCanvas( mainCanvas );
 		this.pipeline = pipeline;
@@ -183,6 +186,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._denoiserStartHandler = null;
 		this._denoiserEndHandler = null;
 		this._denoiserTileHandler = null;
+		this._denoiserErrorHandler = null;
 		this._upscalerResChangedHandler = null;
 		this._upscalerStartHandler = null;
 		this._upscalerProgressHandler = null;
@@ -214,6 +218,23 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** GPU bytes of OIDN's inputs, output and motion history. */
+	gpuBytes() {
+
+		return ( this.denoiser?.gpuBytes?.() ?? 0 ) + ( this._history?.gpuBytes?.() ?? 0 );
+
+	}
+
+	_recordNoOverlayCanvas( pass ) {
+
+		this._issues?.record(
+			ISSUE_CODES.DENOISER_UNAVAILABLE,
+			`the ${pass} pass needs the render canvas to be in a document, and it is not — skipped`,
+			{ pass }
+		);
+
+	}
+
 	/**
 	 * Updates the render resolution and propagates to denoiser/upscaler.
 	 * @param {number} width
@@ -280,8 +301,6 @@ export class DenoisingManager extends EventDispatcher {
 	 */
 	setupDenoiser() {
 
-		if ( ! this.upscalerCanvas ) return;
-
 		const pt = this._stages.pathTracer;
 
 		// No canvas: the denoiser hands its result to the pipeline as a picture, and the
@@ -335,9 +354,17 @@ export class DenoisingManager extends EventDispatcher {
 
 		};
 
+		// Only the weight load names a URL; the init wrapper re-reports that same failure.
+		this._denoiserErrorHandler = e => e.url && this._issues?.record(
+			ISSUE_CODES.ASSET_UNREACHABLE,
+			`denoiser weights "${e.url}" could not be loaded — the render is not denoised`,
+			{ url: e.url, asset: 'oidn-weights', cause: String( e.error?.message ?? e.error ) }
+		);
+
 		this.denoiser.addEventListener( 'start', this._denoiserStartHandler );
 		this.denoiser.addEventListener( 'end', this._denoiserEndHandler );
 		this.denoiser.addEventListener( 'tileProgress', this._denoiserTileHandler );
+		this.denoiser.addEventListener( 'error', this._denoiserErrorHandler );
 
 	}
 
@@ -384,7 +411,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Forward lifecycle events (store refs for removal on re-setup / dispose)
 		this._upscalerResChangedHandler = ( e ) =>
-			this.dispatchEvent( { type: 'resolution_changed', width: e.width, height: e.height } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: e.width, height: e.height } );
 		this._upscalerStartHandler = () =>
 			this.dispatchEvent( { type: EngineEvents.UPSCALING_START } );
 		this._upscalerProgressHandler = ( e ) =>
@@ -1101,7 +1128,7 @@ export class DenoisingManager extends EventDispatcher {
 		// The nominal size, not the path tracer's: that one is smaller while the camera moves.
 		if ( wasShowing && this._lastRenderWidth && this._lastRenderHeight ) {
 
-			this.dispatchEvent( { type: 'resolution_changed', width: this._lastRenderWidth, height: this._lastRenderHeight } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: this._lastRenderWidth, height: this._lastRenderHeight } );
 
 		}
 
@@ -1166,7 +1193,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		if ( ! this.upscalerCanvas ) {
 
-			neuralLog.warn( 'neural pass skipped: the engine has no overlay canvas to present on' );
+			this._recordNoOverlayCanvas( 'neural' );
 			return;
 
 		}
@@ -1282,7 +1309,7 @@ export class DenoisingManager extends EventDispatcher {
 			if ( this.mainCanvas ) this.mainCanvas.style.opacity = '0';
 
 			// The host shows the output dimensions; without this they keep reading the render size.
-			this.dispatchEvent( { type: 'resolution_changed', width: image.width, height: image.height } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: image.width, height: image.height } );
 
 		} catch ( error ) {
 
@@ -1297,6 +1324,44 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * One denoise of the accumulation at the final tier, resolved once its picture is published.
+	 * Unlike onRenderComplete(), leaves the render loop and the upscaler alone.
+	 * @returns {Promise<boolean>} whether a denoised picture was published
+	 */
+	async denoiseOnce() {
+
+		const dn = this.denoiser;
+		if ( ! dn?.enabled ) return false;
+
+		this._cleanupCompletionListener();
+		this._resetCadence();
+		this._useFinalQuality();
+
+		// start() refuses during a run and only defers during a weight load.
+		while ( dn.state.isLoading || dn.state.isDenoising ) {
+
+			await ( dn.state.isLoading ? dn.whenLoaded() : new Promise( ( resolve ) => {
+
+				const onEnd = () => {
+
+					dn.removeEventListener( 'end', onEnd );
+					resolve();
+
+				};
+
+				dn.addEventListener( 'end', onEnd );
+
+			} ) );
+
+		}
+
+		const ok = await dn.start();
+		if ( ok ) this._onDisplayRefresh?.();
+		return ok && dn.hasOutput;
+
+	}
+
 	onRenderComplete( { isStillComplete } ) {
 
 		// Remove any stale completion-chain listener from a previous render cycle
@@ -1459,6 +1524,7 @@ export class DenoisingManager extends EventDispatcher {
 			if ( this._denoiserStartHandler ) this.denoiser.removeEventListener( 'start', this._denoiserStartHandler );
 			if ( this._denoiserEndHandler ) this.denoiser.removeEventListener( 'end', this._denoiserEndHandler );
 			if ( this._denoiserTileHandler ) this.denoiser.removeEventListener( 'tileProgress', this._denoiserTileHandler );
+			if ( this._denoiserErrorHandler ) this.denoiser.removeEventListener( 'error', this._denoiserErrorHandler );
 			this.denoiser.dispose();
 			this.denoiser = null;
 
@@ -1482,6 +1548,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._denoiserStartHandler = null;
 		this._denoiserEndHandler = null;
 		this._denoiserTileHandler = null;
+		this._denoiserErrorHandler = null;
 		this._upscalerResChangedHandler = null;
 		this._upscalerStartHandler = null;
 		this._upscalerProgressHandler = null;
@@ -1490,6 +1557,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._onReset = null;
 		this._onPostProcessRefresh = null;
 		this._onDisplayRefresh = null;
+		this._issues = null;
 
 		if ( this.upscalerCanvas?.parentNode ) {
 
@@ -1669,6 +1737,7 @@ export class DenoisingManager extends EventDispatcher {
 	setUpscalerEnabled( enabled ) {
 
 		if ( this.upscaler ) this.upscaler.enabled = enabled;
+		else if ( enabled ) this._recordNoOverlayCanvas( 'upscaler' );
 		// The enlarged picture describes a setting that is no longer on.
 		if ( ! enabled ) this._restoreRenderDisplay();
 

package/src/managers/GoboManager.js

@@ -1,5 +1,6 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { cachedObjectURL } from '../Storage/DownloadCache.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 /**
  * Manages projection masks ("gobos" / "cookies") for spot lights.
@@ -33,6 +34,7 @@ export class GoboManager {
 
 		this.pathTracer = pathTracer;
 		this._onReset = options.onReset || null;
+		this._issues = options.issues ?? null;
 
 		/** @type {DataArrayTexture | null} */
 		this.texture = null;
@@ -140,7 +142,11 @@ export class GoboManager {
 			const entry = this.entries.find( e => e.name === name );
 			if ( ! entry ) {
 
-				console.warn( `GoboManager: unknown gobo "${name}"` );
+				this._issues?.record(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`no gobo named "${name}" is loaded — the light projects without one`,
+					{ name, asset: 'gobo' }
+				);
 				return false;
 
 			}
@@ -237,6 +243,7 @@ export class GoboManager {
 		this.entries = [];
 		this.pathTracer = null;
 		this._onReset = null;
+		this._issues = null;
 
 	}
 

package/src/managers/IESManager.js

@@ -1,6 +1,7 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { parseIES, resampleIESToGrid, deriveIESBeamAngle, deriveIESPenumbra } from '../Processor/IESParser.js';
 import { sharedDownloads } from '../Storage/DownloadCache.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 /**
  * Manages IES photometric profiles for spot lights.
@@ -31,6 +32,7 @@ export class IESManager {
 
 		this.pathTracer = pathTracer;
 		this._onReset = options.onReset || null;
+		this._issues = options.issues ?? null;
 
 		/** @type {DataArrayTexture | null} */
 		this.texture = null;
@@ -72,7 +74,11 @@ export class IESManager {
 
 			} catch ( err ) {
 
-				console.warn( `IESManager: failed to load "${it.name}": ${err.message}` );
+				this._issues?.warn(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`IES profile "${it.name}" could not be loaded: ${err.message}`,
+					{ url: it.url, asset: 'ies', cause: err.message }
+				);
 				return null;
 
 			}
@@ -188,7 +194,11 @@ export class IESManager {
 			const entry = this.entries.find( e => e.name === name );
 			if ( ! entry ) {
 
-				console.warn( `IESManager: unknown profile "${name}"` );
+				this._issues?.record(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`no IES profile named "${name}" is loaded — the light keeps its plain distribution`,
+					{ name, asset: 'ies' }
+				);
 				return empty;
 
 			}
@@ -249,6 +259,7 @@ export class IESManager {
 		this.entries = [];
 		this.pathTracer = null;
 		this._onReset = null;
+		this._issues = null;
 
 	}
 

package/src/managers/InteractionManager.js

@@ -809,7 +809,7 @@ export class InteractionManager extends EventDispatcher {
 		this.addEventListener( 'focusChanged', ( event ) => {
 
 			app.settings.set( 'focusDistance', event.worldDistance );
-			app.dispatchEvent( { type: 'focusChanged', distance: event.distance } );
+			app.dispatchEvent( { type: EngineEvents.FOCUS_CHANGED, distance: event.distance } );
 
 		} );
 

package/src/managers/LightManager.js

@@ -109,6 +109,37 @@ export class LightManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * The light the path tracer traces, by UUID from getAll(). A model's own lights are copied in
+	 * at load, so editing those does nothing: edit this one, then call sync().
+	 * @param {string} uuid
+	 * @returns {?import('three').Light}
+	 */
+	getLight( uuid ) {
+
+		const light = this.scene.getObjectByProperty( 'uuid', uuid );
+		return light?.isLight ? light : null;
+
+	}
+
+	/**
+	 * Sets a traced light's intensity (watts, or W/m² for directional — see the README) and uploads it.
+	 * @param {string} uuid
+	 * @param {number} intensity
+	 * @returns {boolean} false when no traced light has that UUID
+	 */
+	setIntensity( uuid, intensity ) {
+
+		const light = this.getLight( uuid );
+		if ( ! light ) return false;
+
+		light.intensity = intensity;
+		this.updateLights();
+		this._onReset?.();
+		return true;
+
+	}
+
 	/**
 	 * Removes a light by UUID.
 	 * @param {string} uuid

package/src/managers/OverlayManager.js

@@ -3,6 +3,7 @@ import { OutlineHelper } from './helpers/OutlineHelper.js';
 import { ViewOverlayRenderer } from './helpers/ViewOverlayRenderer.js';
 import { createOverlayCanvas, viewPixelSize } from './helpers/overlaySurface.js';
 import { createLogger } from '../utils/Logger.js';
+import { EngineEvents } from '../EngineEvents.js';
 
 const log = createLogger( 'overlay' );
 
@@ -84,6 +85,15 @@ export class OverlayManager {
 
 	}
 
+	/** The overlay surface while it is shown: one presented image and three's output buffers. */
+	gpuResources() {
+
+		const view = this._viewOverlay;
+		if ( ! view?.isVisible ) return [];
+		return [ { bytes: view.canvas.width * view.canvas.height * 4 }, ...( view.renderer?._frameBufferTargets?.values() ?? [] ) ];
+
+	}
+
 	/**
 	 * Sets the SceneHelpers instance used for 3D overlay rendering.
 	 * @param {import('../SceneHelpers.js').SceneHelpers} helperScene
@@ -149,7 +159,7 @@ export class OverlayManager {
 
 		tileHelper.setRenderSize( renderWidth || 1, renderHeight || 1 );
 
-		app.addEventListener( 'resolution_changed', ( e ) => {
+		app.addEventListener( EngineEvents.RESOLUTION_CHANGED, ( e ) => {
 
 			tileHelper.setRenderSize( e.width, e.height );
 

package/src/managers/VideoRenderManager.js

@@ -219,6 +219,14 @@ export class VideoRenderManager {
 
 		while ( ! pathTracer.isComplete && ! this._cancelled ) {
 
+			const wait = pathTracer.readbackWait();
+			if ( wait ) {
+
+				await wait;
+				continue;
+
+			}
+
 			app.cameraManager.camera.updateMatrixWorld();
 			app.pipeline.render();
 

package/src/node/NodeWorker.js

@@ -0,0 +1,144 @@
+import { Worker as ThreadWorker } from 'node:worker_threads';
+import { Buffer, resolveObjectURL } from 'node:buffer';
+
+// Evaluated inside the thread: a dedicated worker's `self` over parentPort, then the module. Messages
+// that arrive before the module has installed its handler are held, not dropped. No require(): a
+// thread inherits --input-type=module, which evaluates this as an ES module.
+const BOOTSTRAP = `
+const { parentPort } = process.getBuiltinModule( 'node:worker_threads' );
+const listeners = { message: new Set(), error: new Set(), messageerror: new Set() };
+const held = [];
+let ready = false;
+
+const transferable = ( list ) => ( list ?? [] ).filter( ( item ) => item instanceof ArrayBuffer || item?.constructor?.name === 'MessagePort' );
+const deliver = ( data ) => {
+
+	const event = { type: 'message', data };
+	globalThis.onmessage?.( event );
+	for ( const fn of listeners.message ) fn( event );
+
+};
+
+globalThis.self = globalThis;
+globalThis.onmessage = null;
+globalThis.postMessage = ( data, transfer ) => parentPort.postMessage( data, transferable( Array.isArray( transfer ) ? transfer : transfer?.transfer ) );
+globalThis.addEventListener = ( type, fn ) => listeners[ type ]?.add( fn );
+globalThis.removeEventListener = ( type, fn ) => listeners[ type ]?.delete( fn );
+globalThis.close = () => process.exit( 0 );
+
+parentPort.on( 'message', ( message ) => {
+
+	if ( message?.__rayzeeModule !== undefined ) {
+
+		const release = () => {
+
+			ready = true;
+			for ( const data of held.splice( 0 ) ) deliver( data );
+
+		};
+
+		// A classic worker is a script in the global scope (three's Draco decoder is one).
+		if ( message.classic ) {
+
+			process.getBuiltinModule( 'node:vm' ).runInThisContext( message.__rayzeeModule );
+			release();
+
+		} else {
+
+			import( 'data:text/javascript;charset=utf-8,' + encodeURIComponent( message.__rayzeeModule ) ).then( release, ( error ) => { throw error; } );
+
+		}
+
+		return;
+
+	}
+
+	if ( ready ) deliver( message );
+	else held.push( message );
+
+} );
+`;
+
+const DATA_URL = /^data:([^,]*?)(;base64)?,(.*)$/s;
+
+function readModuleSource( url ) {
+
+	const href = String( url );
+
+	if ( href.startsWith( 'blob:' ) ) {
+
+		const blob = resolveObjectURL( href );
+		if ( ! blob ) throw new Error( `NodeWorker: no blob behind ${href}` );
+		return blob.text();
+
+	}
+
+	const match = DATA_URL.exec( href );
+	if ( ! match ) throw new Error( `NodeWorker: only data: and blob: worker URLs are supported, got ${href.slice( 0, 64 )}` );
+	const [ , , base64, body ] = match;
+	return base64 ? Buffer.from( body, 'base64' ).toString( 'utf8' ) : decodeURIComponent( body );
+
+}
+
+/**
+ * The Web Worker API over `worker_threads`, for hosts with no browser (see nodePlatform). It runs
+ * `data:` and `blob:` workers, module or classic: the engine's own, which the published build inlines,
+ * and three.js's. Those call the global `Worker`, so a model using Draco or KTX2 also needs
+ * `globalThis.Worker = NodeWorker`. ArrayBuffers transfer and
+ * SharedArrayBuffers share as in a browser; an ImageBitmap cannot exist here to transfer.
+ */
+export class NodeWorker {
+
+	constructor( url, options = {} ) {
+
+		this.onmessage = null;
+		this.onerror = null;
+		this.onmessageerror = null;
+		this._listeners = { message: new Set(), error: new Set(), messageerror: new Set() };
+
+		this._thread = new ThreadWorker( BOOTSTRAP, { eval: true, name: options.name } );
+		this._thread.on( 'message', ( data ) => this._emit( 'message', { type: 'message', data } ) );
+		this._thread.on( 'messageerror', ( error ) => this._emit( 'messageerror', { type: 'messageerror', error } ) );
+		this._thread.on( 'error', ( error ) => this._emit( 'error', { type: 'error', error, message: error?.message ?? String( error ) } ) );
+
+		// Anything the caller posts before the module lands is held in the thread, in order.
+		const source = readModuleSource( url );
+		const load = ( code ) => this._thread.postMessage( { __rayzeeModule: code, classic: options.type !== 'module' } );
+		if ( typeof source === 'string' ) load( source );
+		else source.then( load, ( error ) => this._emit( 'error', { type: 'error', error, message: error.message } ) );
+
+	}
+
+	postMessage( data, transfer ) {
+
+		const list = Array.isArray( transfer ) ? transfer : transfer?.transfer;
+		this._thread.postMessage( data, ( list ?? [] ).filter( ( item ) => item instanceof ArrayBuffer ) );
+
+	}
+
+	addEventListener( type, fn ) {
+
+		this._listeners[ type ]?.add( fn );
+
+	}
+
+	removeEventListener( type, fn ) {
+
+		this._listeners[ type ]?.delete( fn );
+
+	}
+
+	terminate() {
+
+		this._thread.terminate();
+
+	}
+
+	_emit( type, event ) {
+
+		this[ `on${type}` ]?.( event );
+		for ( const fn of this._listeners[ type ] ) fn( event );
+
+	}
+
+}

package/src/node/index.js

@@ -0,0 +1,9 @@
+/**
+ * Node-only helpers, kept out of the main entry so a browser bundle never sees `node:` imports.
+ *
+ *   import { configurePlatform, openHeadless } from 'rayzee';
+ *   import { nodePlatform } from 'rayzee/node';
+ *   configurePlatform( nodePlatform( { decodeImage } ) );
+ */
+export { NodeWorker } from './NodeWorker.js';
+export { nodePlatform } from './nodePlatform.js';

package/src/node/nodePlatform.js

@@ -0,0 +1,86 @@
+import { NodeWorker } from './NodeWorker.js';
+
+// three.js's FileLoader constructs one on every chunk of a streamed download.
+class NodeProgressEvent extends Event {
+
+	constructor( type, { lengthComputable = false, loaded = 0, total = 0 } = {} ) {
+
+		super( type );
+		this.lengthComputable = lengthComputable;
+		this.loaded = loaded;
+		this.total = total;
+
+	}
+
+}
+
+const SHARED_UPLOAD_CHUNK = 64 * 2 ** 20;
+const WRAPPED = Symbol.for( 'rayzee.sharedUploads' );
+
+function sharedBytes( data, elementOffset = 0, elementCount = undefined ) {
+
+	const isView = ArrayBuffer.isView( data );
+	const backing = isView ? data.buffer : data;
+	if ( ! ( backing instanceof SharedArrayBuffer ) ) return null;
+
+	const size = isView ? data.BYTES_PER_ELEMENT ?? 1 : 1;
+	const start = ( isView ? data.byteOffset : 0 ) + elementOffset * size;
+	const length = elementCount !== undefined ? elementCount * size : ( isView ? data.byteLength : backing.byteLength ) - elementOffset * size;
+	return new Uint8Array( backing, start, length );
+
+}
+
+// dawn.node (webgpu 0.6.1) segfaults writing from a SharedArrayBuffer, which WebGPU allows and the
+// engine's triangle and BVH stores are. Such uploads are copied out first, 64 MB at a time.
+function copySharedUploads() {
+
+	const Queue = globalThis.GPUQueue;
+	if ( ! Queue ) throw new Error( 'nodePlatform(): install the webgpu globals first — Object.assign( globalThis, globals )' );
+	if ( Queue.prototype[ WRAPPED ] ) return;
+
+	const { writeBuffer, writeTexture } = Queue.prototype;
+
+	Queue.prototype.writeBuffer = function ( ...args ) {
+
+		const [ buffer, bufferOffset, data, dataOffset, size ] = args;
+		const bytes = sharedBytes( data, dataOffset ?? 0, size );
+		if ( ! bytes ) return writeBuffer.apply( this, args );
+
+		for ( let at = 0; at < bytes.length; at += SHARED_UPLOAD_CHUNK ) {
+
+			writeBuffer.call( this, buffer, bufferOffset + at, bytes.slice( at, at + SHARED_UPLOAD_CHUNK ) );
+
+		}
+
+	};
+
+	Queue.prototype.writeTexture = function ( ...args ) {
+
+		const bytes = sharedBytes( args[ 1 ] );
+		if ( bytes ) args[ 1 ] = bytes.slice();
+		return writeTexture.apply( this, args );
+
+	};
+
+	Queue.prototype[ WRAPPED ] = true;
+
+}
+
+/**
+ * Everything the engine needs from Node, for `configurePlatform( nodePlatform( { decodeImage } ) )`:
+ * the worker class and the host's image decoder — the engine carries none. It also defines
+ * `ProgressEvent` where the runtime lacks it, the one browser class three.js's loaders construct.
+ * WebGPU itself is the host's: install the `webgpu` package's globals and `navigator.gpu` first, since
+ * its queue is wrapped here to copy uploads out of shared memory.
+ *
+ * @param {Object} [options]
+ * @param {( bytes: Uint8Array, mimeType: string ) => Promise<{data: Uint8Array, width: number, height: number}>} [options.decodeImage]
+ *   PNG/JPEG/WebP bytes to RGBA8 pixels, top row first. Without it a model's textures cannot load.
+ */
+export function nodePlatform( { decodeImage } = {} ) {
+
+	globalThis.ProgressEvent ??= NodeProgressEvent;
+	copySharedUploads();
+	return { Worker: NodeWorker, decodeImage: decodeImage ?? null };
+
+}