@gnsx/three 0.186.1 → 0.186.4

package/examples/jsm/inspector/Inspector.js

@@ -8,7 +8,14 @@ import { Parameters } from './tabs/Parameters.js';
 import { Settings } from './tabs/Settings.js';
 import { Viewer } from './tabs/Viewer.js';
 import { Timeline } from './tabs/Timeline.js';
-import { setText } from './ui/utils.js';
+import {
+	setText,
+	// WITH_GENESYS
+	getJSHeapBytes,
+	startJSHeapSampling,
+	stopJSHeapSampling
+	// !WITH_GENESYS
+} from './ui/utils.js';
 
 import { setConsoleFunction, getConsoleFunction, REVISION } from '@gnsx/three/webgpu';
 
@@ -24,6 +31,10 @@ class Inspector extends RendererInspector {
 
 		this.nonce = nonce;
 
+		// WITH_GENESYS
+		startJSHeapSampling();
+		// !WITH_GENESYS
+
 		// init profiler
 
 		const profiler = new Profiler( this, options );
@@ -589,6 +600,50 @@ class Inspector extends RendererInspector {
 
 			setText( this.profiler.toggleButton.querySelector( '.fps-counter' ), this.fps.toFixed() );
 
+			// WITH_GENESYS
+			const toggle = this.profiler.toggleButton;
+			const gpuCounter = toggle.querySelector( '.gpu-counter' );
+			const gpuLabel = toggle.querySelector( '.gpu-label' );
+			const heapCounter = toggle.querySelector( '.heap-counter' );
+			const heapLabel = toggle.querySelector( '.heap-label' );
+			const gpuBytes = this.getRenderer()?.info?.memory?.total;
+			const heap = getJSHeapBytes();
+
+			if ( gpuCounter ) {
+
+				if ( typeof gpuBytes === 'number' ) {
+
+					setText( gpuCounter, ( gpuBytes / ( 1024 * 1024 ) ).toFixed( 0 ) );
+					gpuCounter.style.display = '';
+					if ( gpuLabel ) gpuLabel.style.display = '';
+
+				} else {
+
+					gpuCounter.style.display = 'none';
+					if ( gpuLabel ) gpuLabel.style.display = 'none';
+
+				}
+
+			}
+
+			if ( heapCounter ) {
+
+				if ( heap ) {
+
+					setText( heapCounter, ( heap.used / ( 1024 * 1024 ) ).toFixed( 0 ) );
+					heapCounter.style.display = '';
+					if ( heapLabel ) heapLabel.style.display = '';
+
+				} else {
+
+					heapCounter.style.display = 'none';
+					if ( heapLabel ) heapLabel.style.display = 'none';
+
+				}
+
+			}
+			// !WITH_GENESYS
+
 			this.performance.updateText( this, frame );
 			this.memory.updateText( this );
 
@@ -633,6 +688,10 @@ class Inspector extends RendererInspector {
 
 	dispose() {
 
+		// WITH_GENESYS
+		stopJSHeapSampling();
+		// !WITH_GENESYS
+
 		super.dispose();
 
 		this.setRenderer( null );

package/examples/jsm/inspector/tabs/Memory.js

@@ -2,7 +2,15 @@ import { Tab } from '../ui/Tab.js';
 import { List } from '../ui/List.js';
 import { Graph } from '../ui/Graph.js';
 import { Item } from '../ui/Item.js';
-import { createValueSpan, setText, formatBytes } from '../ui/utils.js';
+import {
+	createValueSpan,
+	setText,
+	formatBytes,
+	info,
+	// WITH_GENESYS
+	getJSHeapBytes
+	// !WITH_GENESYS
+} from '../ui/utils.js';
 
 class Memory extends Tab {
 
@@ -26,6 +34,9 @@ class Memory extends Tab {
 
 		const graph = new Graph();
 		graph.addLine( 'total', 'var( --color-yellow )' );
+		// WITH_GENESYS
+		graph.addLine( 'jsHeap', 'var( --color-accent )' );
+		// !WITH_GENESYS
 		graphContainer.append( graph.domElement );
 
 		// stats
@@ -37,6 +48,13 @@ class Memory extends Tab {
 		graphItem.itemRow.childNodes[ 0 ].style.gridColumn = '1 / -1';
 		graphStats.add( graphItem );
 
+		// WITH_GENESYS
+		const legend = document.createElement( 'div' );
+		legend.className = 'graph-caption graph-legend';
+		legend.innerHTML = '<span class="graph-legend-item graph-legend-gpu">GPU</span><span class="graph-legend-item graph-legend-heap">JS Heap</span>';
+		graphContainer.prepend( legend );
+		// !WITH_GENESYS
+
 		// info
 
 		this.memoryStats = new Item( 'Renderer Info', '', createValueSpan() );
@@ -73,6 +91,19 @@ class Memory extends Tab {
 		this.uniformBuffers = new Item( 'Uniform Buffers', createValueSpan(), createValueSpan() );
 		this.memoryStats.add( this.uniformBuffers );
 
+		// WITH_GENESYS
+		this.jsHeapStats = new Item( 'JS Heap', '', createValueSpan() );
+		this.jsHeapStats.domElement.firstChild.classList.add( 'no-hover' );
+		memoryList.add( this.jsHeapStats );
+		info( this.jsHeapStats.domElement.querySelector( '.list-item-cell' ), 'Chromium reports V8 heap via performance.memory (used / allocated / limit). Other browsers only report a page-memory estimate if performance.measureUserAgentSpecificMemory is available in a cross-origin isolated document. Safari and Firefox do not expose JS heap size to web pages.' );
+
+		this.jsHeapAllocated = new Item( 'Allocated', '', createValueSpan() );
+		this.jsHeapStats.add( this.jsHeapAllocated );
+
+		this.jsHeapLimit = new Item( 'Limit', '', createValueSpan() );
+		this.jsHeapStats.add( this.jsHeapLimit );
+		// !WITH_GENESYS
+
 		this.graph = graph;
 
 	}
@@ -85,6 +116,16 @@ class Memory extends Tab {
 
 		this.graph.addPoint( 'total', memory.total );
 
+		// WITH_GENESYS
+		const heap = getJSHeapBytes();
+
+		if ( heap ) {
+
+			this.graph.addPoint( 'jsHeap', heap.used );
+
+		}
+		// !WITH_GENESYS
+
 		if ( this.graph.limit === 0 ) this.graph.limit = 1;
 
 		this.graph.update();
@@ -127,6 +168,24 @@ class Memory extends Tab {
 		setText( this.uniformBuffers.data[ 1 ], memory.uniformBuffers.toString() );
 		setText( this.uniformBuffers.data[ 2 ], formatBytes( memory.uniformBuffersSize ) );
 
+		// WITH_GENESYS
+		const heap = getJSHeapBytes();
+
+		if ( heap ) {
+
+			setText( this.jsHeapStats.data[ 2 ], formatBytes( heap.used ) );
+			setText( this.jsHeapAllocated.data[ 2 ], heap.total !== undefined ? formatBytes( heap.total ) : 'N/A' );
+			setText( this.jsHeapLimit.data[ 2 ], heap.limit !== undefined ? formatBytes( heap.limit ) : 'N/A' );
+
+		} else {
+
+			setText( this.jsHeapStats.data[ 2 ], 'Unsupported' );
+			setText( this.jsHeapAllocated.data[ 2 ], 'N/A' );
+			setText( this.jsHeapLimit.data[ 2 ], 'N/A' );
+
+		}
+		// !WITH_GENESYS
+
 	}
 
 }

package/examples/jsm/inspector/tabs/Settings.js

@@ -134,10 +134,46 @@ class Settings extends Parameters {
 
 		} ).info( 'Shows how many times each pixel is shaded.' );
 
+		// WITH_GENESYS
+		// Values match Renderer.debug.view. Not stored with inspector settings.
+		const debugViewState = { view: 'none' };
+
+		this._debugViewState = debugViewState;
+		this._debugViewControl = modesGroup.add( debugViewState, 'view', {
+			'Shaded': 'none',
+			'Shader Complexity': 'shaderComplexity',
+			'Lighting Complexity': 'lightingComplexity'
+		} ).name( 'Debug View' ).onChange( ( view ) => {
+
+			const renderer = this.inspector.getRenderer();
+
+			if ( renderer === null || renderer.debug === undefined ) return;
+
+			renderer.debug.view = view;
+			window.dispatchEvent( new Event( 'genesys-debug-view' ) );
+
+		} ).info( 'Shaded color, a shader-cost heatmap, or a direct-light count. Overdraw draws on top when both are enabled.' );
+		// !WITH_GENESYS
+
 	}
 
 	init() {
 
+		// WITH_GENESYS
+		const renderer = this.inspector.getRenderer();
+		const view = renderer !== null && renderer.debug !== undefined ? renderer.debug.view : null;
+
+		if ( view === 'none' || view === 'shaderComplexity' || view === 'lightingComplexity' ) {
+
+			if ( this._debugViewState.view !== view ) {
+
+				this._debugViewControl.setValue( view );
+
+			}
+
+		}
+		// !WITH_GENESYS
+
 		const extensionsGroup = this.createGroup( 'Extensions' );
 
 		const storageGroup = this.createGroup( 'Storage' );

package/examples/jsm/inspector/ui/Profiler.js

@@ -271,6 +271,12 @@ export class Profiler extends EventDispatcher {
 <span class="toggle-text">
 	<span class="fps-counter">-</span>
 	<span class="fps-label">FPS</span>
+	<!-- WITH_GENESYS -->
+	<span class="gpu-counter" title="GPU memory (MB)">-</span>
+	<span class="gpu-label">GPU</span>
+	<span class="heap-counter" title="JS heap used (MB)">-</span>
+	<span class="heap-label">JS</span>
+	<!-- !WITH_GENESYS -->
 </span>
 <span class="toggle-icon">
 	<svg  xmlns="http://www.w3.org/2000/svg"  width="24"  height="24"  viewBox="0 0 24 24"  fill="none"  stroke="currentColor"  stroke-width="2"  stroke-linecap="round"  stroke-linejoin="round"  class="icon icon-tabler icons-tabler-outline icon-tabler-device-ipad-horizontal-search"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M11.5 20h-6.5a2 2 0 0 1 -2 -2v-12a2 2 0 0 1 2 -2h14a2 2 0 0 1 2 2v5.5" /><path d="M9 17h2" /><path d="M18 18m-3 0a3 3 0 1 0 6 0a3 3 0 1 0 -6 0" /><path d="M20.2 20.2l1.8 1.8" /></svg>

package/examples/jsm/inspector/ui/Style.js

@@ -179,7 +179,10 @@ export class Style {
 		display: flex;
 		align-items: baseline;
 		padding: 8px 14px;
-		min-width: 80px;
+		/* WITH_GENESYS */
+		min-width: 196px;
+		/* !WITH_GENESYS */
+		/* min-width: 80px; */
 		justify-content: right;
 	}
 
@@ -189,6 +192,20 @@ export class Style {
 		color: #999;
 	}
 
+	/* WITH_GENESYS */
+	.toggle-text .gpu-counter,
+	.toggle-text .heap-counter {
+		margin-left: 12px;
+	}
+
+	.toggle-text .gpu-label,
+	.toggle-text .heap-label {
+		font-size: 0.7em;
+		margin-left: 6px;
+		color: #999;
+	}
+	/* !WITH_GENESYS */
+
 	.builtin-tabs-container {
 		position: relative;
 		z-index: 1;
@@ -1251,6 +1268,41 @@ export class Style {
 		position: relative;
 	}
 
+	/* WITH_GENESYS */
+	.graph-caption {
+		font-size: 11px;
+		color: var(--text-secondary);
+		margin-bottom: 4px;
+	}
+
+	.graph-legend {
+		display: flex;
+		gap: 12px;
+	}
+
+	.graph-legend-item {
+		display: inline-flex;
+		align-items: center;
+	}
+
+	.graph-legend-item::before {
+		content: '';
+		display: inline-block;
+		width: 8px;
+		height: 8px;
+		border-radius: 2px;
+		margin-right: 6px;
+	}
+
+	.graph-legend-gpu::before {
+		background: var(--color-yellow);
+	}
+
+	.graph-legend-heap::before {
+		background: var(--color-accent);
+	}
+	/* !WITH_GENESYS */
+
 	.graph-svg, .graph-canvas {
 		width: 0;
 		min-width: 100%;

package/examples/jsm/inspector/ui/utils.js

@@ -62,6 +62,127 @@ export function formatBytes( bytes, decimals = 2 ) {
 
 }
 
+// WITH_GENESYS
+/**
+ * Best-effort JS / page memory sample for the inspector.
+ *
+ * Chromium exposes a sync V8 heap via `performance.memory`. The spec method
+ * `performance.measureUserAgentSpecificMemory()` is async, may include more
+ * than JS heap, and requires a cross-origin isolated document. Firefox and
+ * Safari do not expose JS heap size to web content as of 2026.
+ *
+ * @returns {{ used: number, total?: number, limit?: number } | null}
+ */
+let _specMemoryBytes = null;
+let _specMemoryTimer = 0;
+let _specMemorySampling = false;
+
+function readPerformanceMemory() {
+
+	const memory = performance.memory;
+
+	if ( memory === undefined || typeof memory.usedJSHeapSize !== 'number' ) {
+
+		return null;
+
+	}
+
+	return {
+		used: memory.usedJSHeapSize,
+		total: memory.totalJSHeapSize,
+		limit: memory.jsHeapSizeLimit
+	};
+
+}
+
+async function sampleSpecMemory() {
+
+	const measure = performance.measureUserAgentSpecificMemory;
+
+	if ( typeof measure !== 'function' ) {
+
+		return;
+
+	}
+
+	try {
+
+		const result = await measure.call( performance );
+
+		if ( result && typeof result.bytes === 'number' ) {
+
+			_specMemoryBytes = result.bytes;
+
+		}
+
+	} catch {
+
+		// SecurityError when the document is not cross-origin isolated.
+
+	}
+
+}
+
+function scheduleSpecMemorySample() {
+
+	if ( _specMemorySampling === false ) {
+
+		return;
+
+	}
+
+	// Spec guidance: poll on a randomized interval; the call may wait on GC.
+	_specMemoryTimer = setTimeout( () => {
+
+		sampleSpecMemory().finally( scheduleSpecMemorySample );
+
+	}, 8000 + Math.random() * 7000 );
+
+}
+
+export function startJSHeapSampling() {
+
+	if ( _specMemorySampling ) {
+
+		return;
+
+	}
+
+	_specMemorySampling = true;
+	sampleSpecMemory();
+	scheduleSpecMemorySample();
+
+}
+
+export function stopJSHeapSampling() {
+
+	_specMemorySampling = false;
+	clearTimeout( _specMemoryTimer );
+	_specMemoryTimer = 0;
+
+}
+
+export function getJSHeapBytes() {
+
+	const chromeHeap = readPerformanceMemory();
+
+	if ( chromeHeap ) {
+
+		return chromeHeap;
+
+	}
+
+	if ( typeof _specMemoryBytes === 'number' ) {
+
+		return { used: _specMemoryBytes };
+
+	}
+
+	return null;
+
+}
+// !WITH_GENESYS
+
 export function info( parentNode, text ) {
 
 	let infoIcon = parentNode.querySelector( '.info-icon' );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnsx/three",
-  "version": "0.186.1",
+  "version": "0.186.4",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",

package/src/materials/nodes/NodeMaterial.js

@@ -25,6 +25,9 @@ import { modelViewMatrix } from '../../nodes/accessors/ModelNode.js';
 import { vertexColor } from '../../nodes/accessors/VertexColorNode.js';
 import { premultiplyAlpha } from '../../nodes/display/PremultiplyAlphaFunctions.js';
 import { subBuild } from '../../nodes/core/SubBuildNode.js';
+// WITH_GENESYS
+import { DEBUG_VIEW_LIGHTING_COMPLEXITY, DEBUG_VIEW_SHADER_COMPLEXITY, getShaderComplexityBase, shaderComplexityOutput } from '../../nodes/display/ComplexityDebug.js';
+// !WITH_GENESYS
 
 /**
  * Base class for all node materials.
@@ -597,6 +600,17 @@ class NodeMaterial extends Material {
 
 		}
 
+		// WITH_GENESYS
+		// The screen output pass colorizes the accumulated ratio. Wrapping that pass
+		// would replace the heatmap with this material's own constant cost.
+		if ( renderer.debug.view === DEBUG_VIEW_SHADER_COMPLEXITY && this.isShadowPassMaterial !== true && renderer.isOutputTarget !== true ) {
+
+			builder.shaderComplexityBase = getShaderComplexityBase( this );
+			resultNode = shaderComplexityOutput( resultNode );
+
+		}
+		// !WITH_GENESYS
+
 		builder.stack.outputNode = resultNode;
 
 		builder.addFlow( 'fragment', builder.removeStack() );
@@ -1110,6 +1124,22 @@ class NodeMaterial extends Material {
 
 		}
 
+		// WITH_GENESYS
+		if ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_COMPLEXITY && this.isShadowPassMaterial !== true ) {
+
+			const hasLightLoop = lightsNode && ( materialLightings.length > 0 || lightsNode.getScope().hasLights );
+
+			if ( hasLightLoop !== true ) {
+
+				outgoingLightNode = vec3( 0 );
+
+			}
+
+			return outgoingLightNode;
+
+		}
+		// !WITH_GENESYS
+
 		// EMISSIVE
 
 		if ( ( emissiveNode && emissiveNode.isNode === true ) || ( material.emissive && material.emissive.isColor === true ) ) {

package/src/nodes/core/NodeBuilder.js

@@ -24,6 +24,9 @@ import CubeRenderTarget from '../../renderers/common/CubeRenderTarget.js';
 import BindGroup from '../../renderers/common/BindGroup.js';
 
 import { REVISION, IntType, UnsignedIntType, LinearFilter, LinearMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapLinearFilter, NormalBlending } from '../../constants.js';
+// WITH_GENESYS
+import { SHADER_COMPLEXITY_TEXTURE_COST } from '../display/ComplexityDebug.js';
+// !WITH_GENESYS
 import { RenderTarget } from '../../core/RenderTarget.js';
 import { Color } from '../../math/Color.js';
 import { Vector2 } from '../../math/Vector2.js';
@@ -268,6 +271,31 @@ class NodeBuilder {
 		 */
 		this.fragmentShader = null;
 
+		// WITH_GENESYS
+		/**
+		 * Static material-feature cost for the shader-complexity debug view.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.shaderComplexityBase = 0;
+
+		/**
+		 * Fragment texture samples counted while generating the shader.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.fragmentTextureSamples = 0;
+
+		/**
+		 * Sample sites already counted, so a node that is generated twice is not double-counted.
+		 *
+		 * @type {Set<string>}
+		 */
+		this.shaderComplexitySampleKeys = new Set();
+		// !WITH_GENESYS
+
 		/**
 		 * The generated compute shader.
 		 *
@@ -1296,6 +1324,46 @@ class NodeBuilder {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Counts one fragment texture sample toward the shader-complexity proxy.
+	 * Depth and cube textures are shadow maps and environment maps, and rect-area
+	 * LTC tables belong to the light loop, so they are not material cost.
+	 *
+	 * @param {?Texture} texture - The texture being sampled.
+	 * @param {string} [shaderStage=this.shaderStage] - The stage the sample is emitted for.
+	 * @param {string} [key=''] - Stable id for this sample site. Repeated generation of the same site counts once.
+	 */
+	recordFragmentTextureSample( texture, shaderStage = this.shaderStage, key = '' ) {
+
+		if ( shaderStage !== 'fragment' ) return;
+
+		if ( texture && ( texture.isDepthTexture === true || texture.isCubeTexture === true || texture.isRectAreaLTC === true ) ) return;
+
+		if ( key !== '' ) {
+
+			if ( this.shaderComplexitySampleKeys.has( key ) ) return;
+
+			this.shaderComplexitySampleKeys.add( key );
+
+		}
+
+		this.fragmentTextureSamples ++;
+
+	}
+
+	/**
+	 * Returns the shader-complexity proxy for the material currently being built.
+	 *
+	 * @return {number} Base feature cost plus weighted fragment texture samples.
+	 */
+	getShaderComplexityCost() {
+
+		return this.shaderComplexityBase + this.fragmentTextureSamples * SHADER_COMPLEXITY_TEXTURE_COST;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Generates a texture LOD shader string for the given texture data.
 	 *
@@ -3119,6 +3187,12 @@ class NodeBuilder {
 	 */
 	prebuild() {
 
+		// WITH_GENESYS
+		this.shaderComplexityBase = 0;
+		this.fragmentTextureSamples = 0;
+		this.shaderComplexitySampleKeys.clear();
+		// !WITH_GENESYS
+
 		const { renderer, material } = this;
 
 		// < renderer.contextNode >