@gnsx/three 0.184.19 → 0.184.20

package/package.json

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

package/src/profiler/ProfilerService.js

@@ -9,14 +9,22 @@
  *   __gnsx_profiler.downloadTrace()  // download gnsx-trace.json for Speedscope / Perfetto
  *   __gnsx_profiler.reset()          // clear samples and trace
  *   __gnsx_profiler.disable()
+ *
+ * Chrome trace: `tid=1` is synchronous work; `@profile` on async methods records the
+ * promise lifetime on `tid=2` so long async does not flatten the main row. For manual
+ * spans, use `beginSpan` / `endSpan` with `{ asyncTimeline: true }` in a `.finally()`.
  */
 
 const RING_SIZE = 120;
 const FRAME_BUDGET_MS = 1000 / 60;
-/** Max events in the trace log (~50s at 60fps with 8 labels). */
-const MAX_TRACE_EVENTS = 50_000;
+const TRACE_TID_MAIN = 1;
+const TRACE_TID_ASYNC = 2;
 const NOOP = () => {};
 
+const DUMMY_SPAN = Object.freeze( { label: '', t0: 0, _seq: 0 } );
+const NOOP_BEGIN_SPAN = () => DUMMY_SPAN;
+const NOOP_END_SPAN = () => {};
+
 class ProfilerServiceClass {
 
 	constructor() {
@@ -30,7 +38,7 @@ class ProfilerServiceClass {
 		this.cursors = new Map();
 		/** @type {Map<string, number>} */
 		this.counts = new Map();
-		/** @type {Map<string, Array<{ startTime: number, startMark: string, traced: boolean }>>} */
+		/** @type {Map<string, Array<{ startTime: number, startMark: string }>>} */
 		this.marks = new Map();
 		/** @type {ChromeTraceEvent[]} */
 		this.traceEvents = [];
@@ -56,6 +64,8 @@ class ProfilerServiceClass {
 			this.traceStartTime = performance.now();
 			this.begin = this._beginImpl.bind( this );
 			this.end = this._endImpl.bind( this );
+			this.beginSpan = this._beginSpanImpl.bind( this );
+			this.endSpan = this._endSpanImpl.bind( this );
 			this._exposeGlobal();
 			console.log( `[ProfilerService] auto-started from env (profile: ${this._profile})` );
 
@@ -63,6 +73,8 @@ class ProfilerServiceClass {
 
 			this.begin = NOOP;
 			this.end = NOOP;
+			this.beginSpan = NOOP_BEGIN_SPAN;
+			this.endSpan = NOOP_END_SPAN;
 
 		}
 
@@ -94,6 +106,8 @@ class ProfilerServiceClass {
 		this._enabled = true;
 		this.begin = this._beginImpl.bind( this );
 		this.end = this._endImpl.bind( this );
+		this.beginSpan = this._beginSpanImpl.bind( this );
+		this.endSpan = this._endSpanImpl.bind( this );
 		this._exposeGlobal();
 		console.log( `[ProfilerService] enabled (profile: ${this._profile}) — call __gnsx_profiler.report() or downloadTrace() from the console` );
 
@@ -105,6 +119,8 @@ class ProfilerServiceClass {
 		this._enabled = false;
 		this.begin = NOOP;
 		this.end = NOOP;
+		this.beginSpan = NOOP_BEGIN_SPAN;
+		this.endSpan = NOOP_END_SPAN;
 		console.log( '[ProfilerService] disabled' );
 
 	}
@@ -140,22 +156,8 @@ class ProfilerServiceClass {
 
 		}
 
-		const traced = this._profile === 'full' && this.traceEvents.length < MAX_TRACE_EVENTS;
-		if ( traced ) {
-
-			this.traceEvents.push( {
-				name: label,
-				ph: 'B',
-				ts: this._getTraceTimestamp( startTime ),
-				pid: 1,
-				tid: 1,
-				cat: 'gnsx',
-			} );
-
-		}
-
 		performance.mark( startMark );
-		stack.push( { startTime, startMark, traced } );
+		stack.push( { startTime, startMark } );
 
 		// Push onto the global call stack for exclusive-time tracking.
 		this.callStack.push( { label, childTime: 0 } );
@@ -173,13 +175,61 @@ class ProfilerServiceClass {
 		if ( stack.length === 0 ) this.marks.delete( label );
 
 		const now = performance.now();
-		const { startTime, startMark, traced } = mark;
+		const { startTime, startMark } = mark;
 		const duration = now - startTime;
 		const endMark = `gnsx:${label}:end:${++ this._markId}`;
 
 		performance.mark( endMark );
 		performance.measure( `gnsx:${label}`, startMark, endMark );
 
+		this._commitDurationSample( label, startTime, duration, TRACE_TID_MAIN );
+
+	}
+
+	/**
+	 * Per-invocation span start (pair with {@link ProfilerServiceClass#endSpan}).
+	 * Safe for concurrent async with the same label.
+	 *
+	 * @param {string} label
+	 * @return {import('./ProfilerService.js').SpanHandle}
+	 */
+	_beginSpanImpl( label ) {
+
+		const seq = ++ this._markId;
+		const t0 = performance.now();
+		const startMark = `gnsx:${label}:s${seq}:start`;
+		performance.mark( startMark );
+		return { label, t0, _seq: seq, _startMark: startMark };
+
+	}
+
+	/**
+	 * @param {import('./ProfilerService.js').SpanHandle} handle
+	 * @param {import('./ProfilerService.js').EndSpanOptions} [opts]
+	 */
+	_endSpanImpl( handle, opts ) {
+
+		if ( handle._seq === 0 ) return;
+
+		const now = performance.now();
+		const duration = now - handle.t0;
+		const endMark = `gnsx:${handle.label}:s${handle._seq}:end`;
+		performance.mark( endMark );
+		performance.measure( `gnsx:${handle.label}#${handle._seq}`, handle._startMark, endMark );
+
+		const traceTid = opts?.asyncTimeline === true ? TRACE_TID_ASYNC : TRACE_TID_MAIN;
+		this._commitDurationSample( handle.label, handle.t0, duration, traceTid );
+
+	}
+
+	/**
+	 * @param {string} label
+	 * @param {number} startTime
+	 * @param {number} durationMs
+	 * @param {typeof TRACE_TID_MAIN|typeof TRACE_TID_ASYNC} traceTid
+	 */
+	_commitDurationSample( label, startTime, durationMs, traceTid ) {
+
 		let buffer = this.buffers.get( label );
 		if ( ! buffer ) {
 
@@ -191,7 +241,7 @@ class ProfilerServiceClass {
 		}
 
 		const cursor = this.cursors.get( label );
-		buffer[ cursor ] = duration;
+		buffer[ cursor ] = durationMs;
 		this.cursors.set( label, ( cursor + 1 ) % RING_SIZE );
 		this.counts.set( label, Math.min( ( this.counts.get( label ) + 1 ), RING_SIZE ) );
 
@@ -203,7 +253,7 @@ class ProfilerServiceClass {
 		if ( top !== undefined && top.label === label ) {
 
 			this.callStack.pop();
-			const selfTime = Math.max( 0, duration - top.childTime );
+			const selfTime = Math.max( 0, durationMs - top.childTime );
 
 			let selfBuffer = this.selfBuffers.get( label );
 			if ( ! selfBuffer ) {
@@ -222,7 +272,7 @@ class ProfilerServiceClass {
 
 			// Propagate inclusive duration to the parent scope's child accumulator.
 			const parent = this.callStack.length > 0 ? this.callStack[ this.callStack.length - 1 ] : undefined;
-			if ( parent !== undefined ) parent.childTime += duration;
+			if ( parent !== undefined ) parent.childTime += durationMs;
 
 		} else {
 
@@ -231,14 +281,16 @@ class ProfilerServiceClass {
 
 		}
 
-		if ( traced ) {
+		if ( traceTid ) {
 
+			const traceName = traceTid === TRACE_TID_ASYNC ? `${label} (promise)` : label;
 			this.traceEvents.push( {
-				name: label,
-				ph: 'E',
-				ts: this._getTraceTimestamp( now ),
+				name: traceName,
+				ph: 'X',
+				ts: Math.round( this._getTraceTimestamp( startTime ) ),
+				dur: Math.max( 1, Math.round( durationMs * 1000 ) ),
 				pid: 1,
-				tid: 1,
+				tid: traceTid,
 				cat: 'gnsx',
 			} );
 
@@ -349,13 +401,53 @@ class ProfilerServiceClass {
 	 */
 	exportChromeTrace() {
 
+		const slices = [ ...this.traceEvents ];
+		slices.sort( ( a, b ) => {
+
+			if ( a.ts !== b.ts ) return a.ts - b.ts;
+			if ( a.tid !== b.tid ) return a.tid - b.tid;
+			return a.name.localeCompare( b.name );
+
+		} );
+		const hasAsync = slices.some( e => e.tid === TRACE_TID_ASYNC );
+		/** @type {import('./ProfilerService.js').ChromeTraceMetadataEvent[]} */
+		const prefix = [
+			{
+				cat: '__metadata',
+				name: 'process_name',
+				ph: 'M',
+				pid: 1,
+				tid: 0,
+				ts: 0,
+				args: { name: 'Genesys Profiler' },
+			},
+			{
+				cat: '__metadata',
+				name: 'thread_name',
+				ph: 'M',
+				pid: 1,
+				tid: TRACE_TID_MAIN,
+				ts: 0,
+				args: { name: 'Main thread' },
+			},
+		];
+		if ( hasAsync ) {
+
+			prefix.push( {
+				cat: '__metadata',
+				name: 'thread_name',
+				ph: 'M',
+				pid: 1,
+				tid: TRACE_TID_ASYNC,
+				ts: 0,
+				args: { name: 'Async (promise lifetime)' },
+			} );
+
+		}
+
 		return {
 			displayTimeUnit: 'ms',
-			traceEvents: [
-				{ name: 'process_name', ph: 'M', pid: 1, args: { name: 'Genesys Profiler' } },
-				{ name: 'thread_name', ph: 'M', pid: 1, tid: 1, args: { name: 'Main Thread' } },
-				...this.traceEvents,
-			],
+			traceEvents: [ ...prefix, ...slices ],
 		};
 
 	}
@@ -460,22 +552,38 @@ class ProfilerServiceClass {
  * @property {number|undefined} selfFrameBudget Exclusive time as percentage of a 60 fps frame budget.
  */
 
+/**
+ * @typedef {Object} SpanHandle
+ * @property {string} label
+ * @property {number} t0
+ * @property {number} _seq
+ * @property {string} _startMark
+ */
+
+/**
+ * @typedef {Object} EndSpanOptions
+ * @property {boolean} [asyncTimeline] When true, trace slice uses `tid=2` (virtual async row).
+ */
+
 /**
  * @typedef {Object} ChromeTraceEvent
  * @property {string} name
- * @property {'B'|'E'} ph
+ * @property {'X'} ph
  * @property {number} ts
+ * @property {number} dur
  * @property {1} pid
- * @property {1} tid
+ * @property {number} tid
  * @property {'gnsx'} cat
  */
 
 /**
  * @typedef {Object} ChromeTraceMetadataEvent
+ * @property {'__metadata'} cat
  * @property {'process_name'|'thread_name'} name
  * @property {'M'} ph
  * @property {1} pid
- * @property {1} [tid]
+ * @property {number} [tid]
+ * @property {0} ts
  * @property {{ name: string }} args
  */
 
@@ -491,28 +599,38 @@ class ProfilerServiceClass {
 
 const ProfilerService = new ProfilerServiceClass();
 
+function isThenable( x ) {
+
+	return (
+		( typeof x === 'object' || typeof x === 'function' ) &&
+		x !== null &&
+		typeof x.then === 'function'
+	);
+
+}
+
 function applyProfileToMethod( label, descriptor ) {
 
 	const original = descriptor.value;
 
 	function profiled( ...args ) {
 
-		ProfilerService.begin( label );
+		const span = ProfilerService.beginSpan( label );
 		try {
 
 			const result = original.apply( this, args );
-			if ( result instanceof Promise ) {
+			if ( isThenable( result ) ) {
 
-				return result.finally( () => ProfilerService.end( label ) );
+				return Promise.resolve( result ).finally( () => ProfilerService.endSpan( span, { asyncTimeline: true } ) );
 
 			}
 
-			ProfilerService.end( label );
+			ProfilerService.endSpan( span );
 			return result;
 
 		} catch ( error ) {
 
-			ProfilerService.end( label );
+			ProfilerService.endSpan( span );
 			throw error;
 
 		}
@@ -526,14 +644,39 @@ function applyProfileToMethod( label, descriptor ) {
 
 /**
  * Method decorator that profiles the decorated method.
- * The label is automatically set to `ClassName.methodName`.
+ * Default label: `ClassName.methodName`. Pass a custom tag via `@profile('My tag')`.
  *
+ * @param {Object|string} [targetOrTag]
+ * @param {string|symbol} [propertyKey]
+ * @param {PropertyDescriptor} [descriptor]
+ * @return {PropertyDescriptor|function(Object, string|symbol, PropertyDescriptor): PropertyDescriptor}
+ */
+function profile( targetOrTag, propertyKey, descriptor ) {
+
+	if ( arguments.length === 0 ) {
+
+		return defaultProfileDecorator;
+
+	}
+
+	if ( arguments.length === 1 && typeof targetOrTag === 'string' ) {
+
+		const customTag = targetOrTag;
+		return ( target, key, desc ) => applyProfileToMethod( customTag, desc );
+
+	}
+
+	return defaultProfileDecorator( targetOrTag, propertyKey, descriptor );
+
+}
+
+/**
  * @param {Object} target
  * @param {string|symbol} propertyKey
  * @param {PropertyDescriptor} descriptor
  * @return {PropertyDescriptor}
  */
-function profile( target, propertyKey, descriptor ) {
+function defaultProfileDecorator( target, propertyKey, descriptor ) {
 
 	const className = target.constructor?.name ?? 'Unknown';
 	return applyProfileToMethod( `${className}.${String( propertyKey )}`, descriptor );