@three-blocks/devtools 11.0.0 → 11.1.0-alpha.395.g9b8ccb48a515

package/node/index.mjs

@@ -0,0 +1,407 @@
+import { fork } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { EventEmitter } from 'node:events';
+import { writeFile } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { encodeIPC, decodeIPC } from './ipc.mjs';
+
+const jsonIPC = Boolean( process.versions.bun );
+
+// The small page API shared by our GPU harnesses and shader driver. Each page
+// owns a Node process: native crashes, module caches and GPU lifetimes stay local.
+class NodePage extends EventEmitter {
+
+	#context;
+	#child;
+	#pending = new Map();
+	#sequence = 0;
+	#failure;
+	#closing = false;
+	#url;
+	#ready = false;
+	#requests = new Map();
+	#recording;
+	#frame = { url: () => this.#url, parentFrame: () => null };
+
+	constructor( context ) {
+
+		super();
+		this.#context = context;
+
+	}
+
+	context() { return this.#context; }
+	mainFrame() { return this.#frame; }
+	url() { return this.#url; }
+	isClosed() { return this.#closing; }
+	route( pattern, handler ) { return this.#context.route( pattern, handler ); }
+
+	async goto( url, { timeout = 30_000 } = {} ) {
+		url = new URL( url ).href;
+
+		if ( this.#child ) await this.close();
+		this.#closing = false;
+		this.#url = String( url );
+		this.#ready = false;
+		this.#requests.clear();
+		this.#failure = undefined;
+		this.#child = fork( new URL( './worker.mjs', import.meta.url ), [], {
+			execPath: process.versions.bun ? 'node' : process.execPath,
+			execArgv: [ '--experimental-vm-modules', '--expose-gc' ], serialization: jsonIPC ? 'json' : 'advanced', stdio: [ 'ignore', 'pipe', 'pipe', 'ipc' ],
+			env: { ...process.env, THREE_BLOCKS_NODE_JSON_IPC: jsonIPC ? '1' : '0' },
+		} );
+		let output = '';
+		for ( const stream of [ this.#child.stdout, this.#child.stderr ] ) stream.on( 'data', data => {
+
+			output = ( output + data ).slice( -32_768 );
+
+		} );
+		this.#child.on( 'message', async message => {
+
+			if ( jsonIPC ) message = decodeIPC( message );
+			if ( message.event === 'console' ) this.emit( 'console', {
+				type: () => message.level, text: () => message.text, location: () => ( { url } ),
+			} );
+			else if ( message.event === 'network' ) this.#network( message );
+			else if ( message.event === 'storage' ) this.#context.storage = message.storage;
+			else if ( message.event === 'cookies' ) this.#context.cookies = message.cookies;
+			else if ( message.event === 'url' ) this.#url = message.url;
+			else if ( message.event === 'unhandledrejection' ) { this.emit( 'unhandledrejection', message.error ); this.#fail( new Error( message.error ) ); }
+			else if ( message.event === 'navigate' ) void this.goto( message.url ).catch( error => this.#fail( error ) );
+			else if ( message.event === 'pageerror' ) this.#fail( new Error( message.error ) );
+			else if ( message.event === 'route' ) {
+
+				try {
+
+					let response;
+					await this.#context.handler?.( {
+						request: () => ( {
+							url: () => message.url, method: () => message.method,
+							headers: () => message.headers, resourceType: () => message.resourceType,
+							postDataBuffer: () => message.body === undefined ? null : Buffer.from( message.body ),
+						} ),
+						fulfill: async value => { response = value; },
+						abort: async ( reason = 'blockedbyclient' ) => { response = { error: reason }; },
+						continue: async () => {},
+					} );
+					const reply = { route: message.id, response };
+					this.#child?.send( jsonIPC ? encodeIPC( reply ) : reply );
+
+				} catch ( error ) {
+					const reply = { route: message.id, response: { error: String( error ) } };
+					this.#child?.send( jsonIPC ? encodeIPC( reply ) : reply );
+					this.#fail( error );
+				}
+
+			} else {
+
+				const pending = this.#pending.get( message.id );
+				if ( ! pending ) return;
+				this.#pending.delete( message.id );
+				clearTimeout( pending.timer );
+				if ( message.error ) pending.reject( new Error( message.error ) );
+				else pending.resolve( message.value );
+
+			}
+
+		} );
+		this.#child.on( 'error', error => this.#fail( error ) );
+		this.#child.on( 'exit', ( code, signal ) => {
+
+			if ( ! this.#closing ) this.#fail( new Error( `Native renderer exited (${signal ?? code}). ${output}` ) );
+
+		} );
+		const result = await this.#call( 'goto', {
+			url, viewport: this.#context.viewport, scripts: this.#context.scripts,
+				routes: Boolean( this.#context.handler ), storage: this.#context.storage, media: this.#context.media,
+				cookies: this.#context.cookies, gpu: this.#context.gpu,
+		}, timeout );
+		if ( this.#context.recordVideo ) this.#recording = await this.screencast( { path: join( this.#context.recordVideo.dir, `${randomUUID()}.webm` ) } );
+		this.#ready = true;
+		this.emit( 'framenavigated', this.#frame );
+		return result;
+
+	}
+
+	#network( message ) {
+
+		if ( message.phase === 'request' ) {
+
+			const row = { ...message };
+			row.request = { url: () => row.url, method: () => row.method, headers: () => row.headers, resourceType: () => row.resourceType ?? 'fetch', failure: () => row.error ? { errorText: row.error } : null, response: async () => row.response };
+			this.#requests.set( message.id, row ); this.emit( 'request', row.request );
+
+		} else {
+
+			const row = this.#requests.get( message.id );
+			if ( ! row ) return;
+			if ( message.phase === 'response' ) {
+
+				row.response = { url: () => row.url, request: () => row.request, status: () => message.status, statusText: () => message.statusText, headers: () => message.headers, body: async () => row.body ?? Buffer.alloc( 0 ) };
+				this.emit( 'response', row.response );
+
+			} else {
+
+				row.body = message.body === undefined ? undefined : Buffer.from( message.body ); row.error = message.error;
+				this.emit( message.phase === 'failed' ? 'requestfailed' : 'requestfinished', row.request );
+				this.#requests.delete( message.id );
+
+			}
+
+		}
+
+	}
+
+	#fail( error ) {
+
+		this.#failure ??= error;
+		for ( const pending of this.#pending.values() ) {
+
+			clearTimeout( pending.timer ); pending.reject( error );
+
+		}
+		this.#pending.clear();
+		this.emit( 'pageerror', error );
+
+	}
+
+	#call( method, args, timeout = 240_000 ) {
+
+		if ( this.#failure ) return Promise.reject( this.#failure );
+		if ( ! this.#child?.connected ) return Promise.reject( new Error( 'Native renderer is not running.' ) );
+		const id = ++ this.#sequence;
+		return new Promise( ( resolve, reject ) => {
+
+			const timer = setTimeout( () => {
+
+				this.#pending.delete( id );
+				reject( new Error( `Native renderer ${method} timed out after ${timeout}ms.` ) );
+				void this.close();
+
+			}, timeout );
+			this.#pending.set( id, { resolve, reject, timer } );
+			const message = { id, method, args };
+			this.#child.send( jsonIPC ? encodeIPC( message ) : message, error => { if ( error ) this.#fail( error ); } );
+
+		} );
+
+	}
+
+	evaluate( fn, ...args ) { return this.#call( 'evaluate', { source: String( fn ), args, callable: typeof fn === 'function' } ); }
+
+	async evaluateHandle( fn, ...args ) {
+
+		const { id, element } = await this.#call( 'handle', { source: String( fn ), args, callable: typeof fn === 'function' } );
+		const handle = {
+			asElement: () => element ? handle : null,
+			evaluate: ( fn, ...args ) => this.#call( 'handleEvaluate', { id, source: String( fn ), args } ),
+			boundingBox: () => handle.evaluate( element => { const { x, y, width, height } = element.getBoundingClientRect(); return { x, y, width, height }; } ),
+			screenshot: options => this.screenshot( { ...options, handle: id } ),
+			dispose: () => this.#call( 'releaseHandle', { id } ),
+		};
+		return handle;
+
+	}
+
+	async $( selector ) { return ( await this.evaluate( selector => document.querySelector( selector ) !== null, selector ) ) ? ( await this.evaluateHandle( selector => document.querySelector( selector ), selector ) ).asElement() : null; }
+
+	async waitForSelector( selector, options ) {
+
+		await this.waitForFunction( selector => document.querySelector( selector ) !== null, selector, options );
+		return this.evaluateHandle( selector => document.querySelector( selector ), selector );
+
+	}
+
+	async evaluateOnNewDocument( fn, ...args ) { await this.#context.addInitScript( `(${fn})(...${JSON.stringify( args )});` ); }
+	viewport() { return this.#context.viewport; }
+	async setViewport( viewport ) {
+
+		Object.assign( this.#context.viewport, viewport );
+		if ( this.#child ) await this.evaluate( viewport => { Object.assign( globalThis, { innerWidth: viewport.width, innerHeight: viewport.height, devicePixelRatio: viewport.deviceScaleFactor ?? 1 } ); dispatchEvent( new Event( 'resize' ) ); }, viewport );
+
+	}
+	async emulateMediaFeatures( features ) { this.#context.media = features; }
+	async bringToFront() {}
+	async waitForLoadState() {} // goto resolves after the document's scripts and load event.
+	reload( options ) { return this.goto( this.#url, options ); }
+	mouse = {
+		move: ( x, y ) => this.evaluate( ( { x, y } ) => {
+			const target = document.querySelector( 'canvas' ) ?? document.body;
+			for ( const type of [ 'pointermove', 'mousemove' ] ) target.dispatchEvent( new PointerEvent( type, { clientX: x, clientY: y, bubbles: true, pointerId: 1, pointerType: 'mouse' } ) );
+		}, { x, y } ),
+		wheel: options => this.evaluate( options => ( document.querySelector( 'canvas' ) ?? document.body ).dispatchEvent( new WheelEvent( 'wheel', { ...options, bubbles: true } ) ), options ),
+	};
+
+	async waitForFunction( fn, arg, options ) {
+
+		if ( options === undefined && arg && ( 'timeout' in Object( arg ) || 'polling' in Object( arg ) ) ) { options = arg; arg = undefined; }
+		const { timeout = 30_000 } = options ?? {};
+
+		return this.#call( 'wait', { source: String( fn ), arg, callable: typeof fn === 'function', timeout }, timeout + 1_000 );
+
+	}
+
+	async screenshot( options = {} ) {
+
+		const bytes = Buffer.from( await this.#call( 'screenshot', { selector: options.selector, index: options.index, handle: options.handle, clip: options.clip, omitBackground: options.omitBackground }, options.timeout ) );
+		if ( options.path ) await writeFile( options.path, bytes );
+		return options.encoding === 'base64' ? bytes.toString( 'base64' ) : bytes;
+
+	}
+
+	locator( selector ) {
+
+		const make = steps => {
+
+			const evaluateAll = ( fn, arg ) => this.evaluate( ( { steps, source, arg } ) => ( 0, eval )( `(${source})` )( globalThis.__THREE_BLOCKS_LOCATE__( steps ), arg ), { steps, source: String( fn ), arg } );
+			const evaluate = ( fn, arg ) => evaluateAll( ( elements, { source, arg } ) => { if ( ! elements[ 0 ] ) throw new Error( 'Native locator matched no element.' ); return ( 0, eval )( `(${source})` )( elements[ 0 ], arg ); }, { source: String( fn ), arg } );
+			const locator = {
+				locator: selector => make( [ ...steps, { selector } ] ),
+				nth: index => make( [ ...steps.slice( 0, -1 ), { ...steps.at( -1 ), index } ] ),
+				first: () => locator.nth( 0 ),
+				filter: filter => make( [ ...steps.slice( 0, -1 ), { ...steps.at( -1 ), text: filter.hasText } ] ),
+				evaluate, evaluateAll,
+				count: () => evaluateAll( elements => elements.length ),
+				textContent: () => evaluate( element => element.textContent ),
+				innerHTML: () => evaluate( element => element.innerHTML ),
+				getAttribute: name => evaluate( ( element, name ) => element.getAttribute( name ), name ),
+				isVisible: () => evaluateAll( elements => Boolean( elements[ 0 ] && ! elements[ 0 ].hidden && getComputedStyle( elements[ 0 ] ).display !== 'none' ) ),
+				boundingBox: () => evaluate( element => { const { x, y, width, height } = element.getBoundingClientRect(); return { x, y, width, height }; } ),
+				screenshot: async options => {
+
+					const handle = await this.evaluateHandle( steps => globalThis.__THREE_BLOCKS_LOCATE__( steps )[ 0 ], steps );
+					try { return await handle.screenshot( options ); } finally { await handle.dispose(); }
+
+				},
+				click: () => evaluate( element => { element.focus(); element.click(); if ( element.tagName === 'SUMMARY' ) element.parentElement.open = ! element.parentElement.open; } ),
+				hover: () => evaluate( element => { for ( const type of [ 'pointerover', 'mouseover', 'mouseenter' ] ) element.dispatchEvent( new MouseEvent( type, { bubbles: true } ) ); } ),
+				focus: () => evaluate( element => element.focus() ),
+			};
+			return locator;
+
+		};
+		return make( [ { selector } ] );
+
+	}
+
+	keyboard = { press: key => this.evaluate( key => dispatchEvent( Object.assign( new Event( 'keydown' ), { key, code: key, altKey: false, ctrlKey: false, metaKey: false, shiftKey: false } ) ), key ) };
+	async waitForURL( expected, { timeout = 30_000 } = {} ) {
+
+		const deadline = performance.now() + timeout;
+		while ( ! this.#ready || ! ( typeof expected === 'function' ? expected( new URL( this.#url ) ) : expected instanceof RegExp ? expected.test( this.#url ) : this.#url === expected ) ) {
+
+			if ( this.#failure ) throw this.#failure;
+			if ( performance.now() >= deadline ) throw new Error( `Native navigation did not reach ${expected}.` );
+			await delay( 5 );
+
+		}
+
+	}
+
+	waitForTimeout( ms ) { return delay( ms ); }
+
+	async screencast( options ) {
+
+		const { recordCanvas } = await import( './recording.mjs' );
+		return recordCanvas( () => this.#call( 'pixels', {} ), options );
+
+	}
+	video() { return this.#recording ?? null; }
+
+	async close() {
+
+		let recordingError;
+		try { await this.#recording?.stop(); } catch ( error ) { recordingError = error; }
+		this.#closing = true;
+		const child = this.#child;
+		this.#child = undefined;
+		if ( child && child.exitCode === null && child.signalCode === null ) await new Promise( resolve => {
+
+			child.once( 'exit', resolve ); child.kill( 'SIGKILL' );
+
+		} );
+		for ( const pending of this.#pending.values() ) {
+
+			clearTimeout( pending.timer ); pending.reject( new Error( 'Native renderer closed.' ) );
+
+		}
+		this.#pending.clear();
+		if ( recordingError ) throw recordingError;
+
+	}
+
+}
+
+class NodeContext {
+
+	scripts = [];
+	pages = [];
+	storage = {};
+	cookies;
+	media = [];
+	constructor( browser, { viewport = { width: 1280, height: 720 }, deviceScaleFactor = 1, frameIntervalMs = 0, recordVideo, gpu = true } = {} ) {
+
+		if ( ! Number.isFinite( frameIntervalMs ) || frameIntervalMs < 0 ) throw new TypeError( 'frameIntervalMs must be a non-negative finite number.' );
+		this.owner = browser; this.viewport = { ...viewport, deviceScaleFactor, frameIntervalMs }; this.recordVideo = recordVideo;
+		this.gpu = gpu;
+
+	}
+	browser() { return this.owner; }
+	async newPage() { const page = new NodePage( this ); this.pages.push( page ); return page; }
+	async addInitScript( script, arg ) { this.scripts.push( typeof script === 'function' ? `(${script})(${JSON.stringify( arg )});` : typeof script === 'string' ? script : script.content ); }
+	async route( pattern, handler ) {
+
+		if ( this.pages.some( page => page.url() && ! page.isClosed() ) ) throw new Error( 'Configure native request routes before navigation.' );
+		const previous = this.handler;
+		const regex = new RegExp( '^' + pattern.replace( /[.+?^${}()|[\]\\]/g, '\\$&' ).replace( /\*\*/g, '\u0000' ).replace( /\*/g, '[^/]*' ).replace( /\u0000/g, '.*' ) + '$' );
+		this.handler = route => regex.test( route.request().url() ) ? handler( route ) : previous?.( route );
+
+	}
+	async close() { await Promise.all( this.pages.map( page => page.close() ) ); this.pages = []; }
+
+}
+
+export async function launchNodeRenderer() {
+
+	const renderer = new EventEmitter();
+	renderer.execution = 'node';
+	renderer.gpuInfo = async () => {
+
+		const context = await renderer.newContext();
+		try {
+
+			const page = await context.newPage();
+			await page.goto( 'data:text/html,<html><body></body></html>' );
+			return await page.evaluate( async () => {
+
+				const adapter = await navigator.gpu.requestAdapter();
+				return { execution: 'node', ...Object.fromEntries( [ 'vendor', 'architecture', 'device', 'description', 'isFallbackAdapter' ].map( key => [ key, adapter.info[ key ] ] ) ) };
+
+			} );
+
+		} finally { await context.close(); }
+
+	};
+	const contexts = [];
+	let connected = true;
+	renderer.isConnected = () => connected;
+	renderer.version = () => `Node ${process.versions.node} (ANGLE/Dawn)`;
+	renderer.newContext = async options => {
+
+		const context = new NodeContext( renderer, options ); contexts.push( context ); return context;
+
+	};
+	renderer.newPage = async options => ( await renderer.newContext( options ) ).newPage();
+	renderer.close = async () => {
+
+		await Promise.all( contexts.map( context => context.close() ) );
+		contexts.length = 0; connected = false; renderer.emit( 'disconnected' );
+		process.off( 'exit', cleanup );
+
+	};
+	const cleanup = () => { void renderer.close(); };
+	process.once( 'exit', cleanup );
+	return renderer;
+
+}

package/node/ipc.mjs

@@ -0,0 +1,31 @@
+import { serialize, deserialize } from '@ungap/structured-clone';
+
+// Bun and Node have incompatible binary IPC formats. Keep Node's fast native
+// transport; Bun uses the existing structured-clone codec over JSON instead.
+export function encodeIPC( value ) {
+
+	return JSON.stringify( serialize( value ), ( _key, item ) => {
+
+		if ( typeof item === 'bigint' ) return { bigint: item.toString() };
+		if ( typeof item === 'number' && ( ! Number.isFinite( item ) || Object.is( item, -0 ) ) ) return { number: Object.is( item, -0 ) ? '-0' : String( item ) };
+		return item;
+
+	} );
+
+}
+
+export function decodeIPC( value ) {
+
+	return deserialize( JSON.parse( value, ( _key, item ) => {
+
+		if ( item && typeof item === 'object' && ! Array.isArray( item ) ) {
+
+			if ( typeof item.number === 'string' ) return Number( item.number );
+			if ( typeof item.bigint === 'string' ) return BigInt( item.bigint );
+
+		}
+		return item;
+
+	} ) );
+
+}