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

package/node/media.mjs

@@ -0,0 +1,454 @@
+import * as codecs from '@napi-rs/webcodecs';
+
+// Decode on native FFmpeg threads, then expose straight-alpha sRGB pixels to
+// ANGLE/Dawn. The generated Three.js shader and capture manifest stay unchanged.
+const pixels = new WeakMap();
+const pending = new WeakMap();
+const NativeFrame = codecs.VideoFrame;
+const cloneFrame = NativeFrame.prototype.clone;
+const copyFrame = NativeFrame.prototype.copyTo;
+
+async function rgbaPixels( frame ) {
+
+	const width = frame.visibleRect.width, height = frame.visibleRect.height;
+	// Read native accessors once, not millions of times inside the pixel loop.
+	const format = frame.format;
+	if ( ! /^(I420|I422|I444|NV12)(A)?$/.test( format ) ) {
+
+		const data = new Uint8Array( width * height * 4 );
+		await copyFrame.call( frame, data, { format: 'RGBA' } );
+		return { width, height, data };
+
+	}
+	// webcodecs 1.4.1 keeps decoder color-space overrides on VideoFrame but its
+	// FFmpeg RGBA copy reads the original bitstream range. Convert the raw planes
+	// using the declared range/matrix so full-range DATA bytes survive upload.
+	const bytes = new Uint8Array( frame.allocationSize() );
+	const { matrix, fullRange } = frame.colorSpace;
+	const planes = await copyFrame.call( frame, bytes );
+	const coefficients = { bt709: [ 0.2126, 0.0722 ], smpte170m: [ 0.299, 0.114 ], bt470bg: [ 0.299, 0.114 ], 'bt2020-ncl': [ 0.2627, 0.0593 ] };
+	const [ kr, kb ] = coefficients[ matrix ?? 'bt709' ] ?? [];
+	if ( kr === undefined ) throw new Error( `Unsupported native YUV matrix: ${matrix}` );
+	const yuv = { bytes, planes, format, fullRange, kr, kb };
+	let data;
+	// GPU uploads consume planes directly; only CPU/ANGLE readers need RGBA bytes.
+	return Object.defineProperty( { width, height, get data() { return data ??= convertYUV( width, height, yuv ); } }, 'yuv', { value: yuv } );
+
+}
+
+function convertYUV( width, height, { bytes, planes, format, fullRange, kr, kb } ) {
+
+	const data = new Uint8Array( width * height * 4 ), kg = 1 - kr - kb;
+	const xSub = format.startsWith( 'I444' ) ? 1 : 2, ySub = /^(I420|NV12)/.test( format ) ? 2 : 1;
+	const sample = ( plane, x, y ) => bytes[ planes[ plane ].offset + y * planes[ plane ].stride + x ];
+	for ( let y = 0; y < height; y ++ ) for ( let x = 0; x < width; x ++ ) {
+
+		const cx = Math.floor( x / xSub ), cy = Math.floor( y / ySub );
+		const luma = ( sample( 0, x, y ) - ( fullRange ? 0 : 16 ) ) * ( fullRange ? 1 : 255 / 219 );
+		const u = ( sample( 1, format === 'NV12' ? cx * 2 : cx, cy ) - 128 ) * ( fullRange ? 1 : 255 / 224 );
+		const v = ( ( format === 'NV12' ? sample( 1, cx * 2 + 1, cy ) : sample( 2, cx, cy ) ) - 128 ) * ( fullRange ? 1 : 255 / 224 );
+		const offset = ( y * width + x ) * 4;
+		data[ offset ] = Math.max( 0, Math.min( 255, Math.round( luma + 2 * ( 1 - kr ) * v ) ) );
+		data[ offset + 1 ] = Math.max( 0, Math.min( 255, Math.round( luma - 2 * kb * ( 1 - kb ) / kg * u - 2 * kr * ( 1 - kr ) / kg * v ) ) );
+		data[ offset + 2 ] = Math.max( 0, Math.min( 255, Math.round( luma + 2 * ( 1 - kb ) * u ) ) );
+		data[ offset + 3 ] = format.endsWith( 'A' ) ? sample( 3, x, y ) : 255;
+
+	}
+	return data;
+
+}
+NativeFrame.prototype.preparePixels = function () {
+
+	if ( pixels.has( this ) ) return Promise.resolve();
+	if ( ! pending.has( this ) ) {
+
+		// Hold the native planes until asynchronous conversion finishes, even if
+		// the caller closes its frame immediately after submitting it to an encoder.
+		const source = cloneFrame.call( this );
+		pending.set( this, rgbaPixels( source ).then( image => { pixels.set( this, image ); } ).finally( () => source.close() ) );
+
+	}
+	return pending.get( this );
+
+};
+NativeFrame.prototype._toRGBA8 = function () {
+
+	if ( this.closed ) throw new DOMException( 'VideoFrame is closed.', 'InvalidStateError' );
+	const image = pixels.get( this );
+	if ( ! image ) throw new Error( 'VideoFrame pixels are not ready for GPU upload.' );
+	return image;
+
+};
+NativeFrame.prototype.clone = function () {
+
+	const frame = cloneFrame.call( this );
+	if ( pixels.has( this ) ) pixels.set( frame, pixels.get( this ) );
+	return frame;
+
+};
+
+export async function installMedia( createElement ) {
+
+	for ( const name of [ 'AudioData', 'AudioDecoder', 'AudioEncoder', 'VideoEncoder', 'EncodedAudioChunk', 'EncodedVideoChunk', 'ImageDecoder', 'VideoColorSpace' ] ) globalThis[ name ] = codecs[ name ];
+	// Keep the native prototype: lifecycle instrumentation must observe decoded
+	// frames as well as frames constructed from canvas pixels.
+	globalThis.VideoFrame = new Proxy( NativeFrame, {
+
+		construct( _target, [ source, init ] ) {
+
+			const image = source._toRGBA8?.();
+			const frame = new NativeFrame( image ? new Uint8Array( image.data ) : source, image ? {
+				...init, format: 'RGBA', codedWidth: image.width, codedHeight: image.height,
+			} : init );
+			if ( image ) pixels.set( frame, image );
+			else if ( init?.format === 'RGBA' && ArrayBuffer.isView( source ) && ! init.layout && ! init.visibleRect ) pixels.set( frame, {
+				width: init.codedWidth, height: init.codedHeight, data: new Uint8Array( source.buffer, source.byteOffset, source.byteLength ).slice(),
+			} );
+			else void frame.preparePixels();
+			return frame;
+
+		}
+
+	} );
+	globalThis.VideoDecoder = class VideoDecoder extends codecs.VideoDecoder {
+
+		#config;
+		#flushed = false;
+		#avcLength = 4;
+
+		constructor( init ) {
+
+			let outputs = Promise.resolve();
+			super( { ...init, output: frame => {
+
+				outputs = outputs.then( async () => { await frame.preparePixels(); init.output( frame ); } ).catch( init.error );
+
+			} } );
+			const flush = this.flush.bind( this );
+			this.flush = async () => { this.#flushed = true; await flush(); await outputs; };
+
+		}
+
+		configure( config ) {
+
+			const original = structuredClone( config );
+			let length = 4;
+			if ( /^avc[13]\./.test( config.codec ) && config.description ) {
+
+				const source = config.description;
+				const description = new Uint8Array( ArrayBuffer.isView( source ) ? source.buffer.slice( source.byteOffset, source.byteOffset + source.byteLength ) : source.slice( 0 ) );
+				if ( description.length >= 5 && description[ 0 ] === 1 ) {
+
+					length = ( description[ 4 ] & 3 ) + 1;
+					// webcodecs 1.4.1's native decoder requires four-byte AVC lengths.
+					if ( length === 1 || length === 2 ) { description[ 4 ] |= 3; config = { ...config, description }; }
+
+				}
+
+			}
+			super.configure( config );
+			this.#config = original; this.#flushed = false; this.#avcLength = length;
+
+		}
+		decode( chunk ) {
+
+			// webcodecs 1.4.1 does not count flush outputs toward its hardware
+			// watchdog. Reconfigure in FIFO order after draining, before the next
+			// required keyframe, so repeated seeks do not trigger a false failure.
+			if ( this.#flushed && this.state === 'configured' ) this.configure( this.#config );
+			if ( this.#avcLength === 1 || this.#avcLength === 2 ) {
+
+				const bytes = Buffer.alloc( chunk.byteLength ), parts = [];
+				chunk.copyTo( bytes );
+				for ( let offset = 0; offset < bytes.length; ) {
+
+					if ( offset + this.#avcLength > bytes.length ) throw new DOMException( 'Truncated AVC length.', 'DataError' );
+					const size = bytes.readUIntBE( offset, this.#avcLength ); offset += this.#avcLength;
+					if ( size === 0 || offset + size > bytes.length ) throw new DOMException( 'Invalid AVC NAL length.', 'DataError' );
+					const prefix = Buffer.alloc( 4 ); prefix.writeUInt32BE( size );
+					parts.push( prefix, bytes.subarray( offset, offset + size ) ); offset += size;
+
+				}
+				chunk = new codecs.EncodedVideoChunk( { type: chunk.type, timestamp: chunk.timestamp, ...( chunk.duration === null ? {} : { duration: chunk.duration } ), data: Buffer.concat( parts ) } );
+
+			}
+			super.decode( chunk );
+
+		}
+
+	};
+	const states = new WeakMap();
+	const prepareVideo = element => {
+
+		if ( states.has( element ) ) return element;
+		const media = new NativeVideo(); states.set( element, media );
+		Object.setPrototypeOf( element, HTMLVideoElement.prototype );
+		const setAttribute = element.setAttribute.bind( element ), removeAttribute = element.removeAttribute.bind( element );
+		element.setAttribute = ( name, value ) => { setAttribute( name, value ); if ( name in media ) media.setAttribute( name, value ); };
+		element.removeAttribute = name => { removeAttribute( name ); if ( name === 'src' ) media.removeAttribute( name ); };
+		for ( const { name, value } of element.attributes ) if ( name !== 'src' && name in media ) media.setAttribute( name, value );
+		const source = element.getAttribute( 'src' ) || [ ...element.querySelectorAll( 'source' ) ].find( source => ! source.type || media.canPlayType( source.type ) )?.getAttribute( 'src' );
+		if ( source ) media.src = source;
+		return element;
+
+	};
+	globalThis.HTMLMediaElement = class HTMLMediaElement extends HTMLElement {};
+	globalThis.HTMLVideoElement = class HTMLVideoElement extends HTMLMediaElement {
+
+		constructor() { return prepareVideo( createElement( 'video' ) ); }
+
+	};
+	Object.assign( HTMLMediaElement, { HAVE_NOTHING: 0, HAVE_METADATA: 1, HAVE_CURRENT_DATA: 2, HAVE_FUTURE_DATA: 3, HAVE_ENOUGH_DATA: 4 } );
+	const sample = new NativeVideo();
+	for ( const name of new Set( [ ...Object.keys( sample ), ...Object.getOwnPropertyNames( NativeVideo.prototype ), 'addEventListener', 'removeEventListener', 'onloadedmetadata', 'onloadeddata', 'oncanplay', 'oncanplaythrough', 'onerror', 'onseeked', 'onseeking', 'ontimeupdate', 'onended', 'onplay', 'onpause', 'onplaying' ] ) ) {
+
+		if ( [ 'constructor', 'style', 'setAttribute', 'removeAttribute' ].includes( name ) ) continue;
+		Object.defineProperty( HTMLMediaElement.prototype, name, typeof sample[ name ] === 'function'
+			? { configurable: true, writable: true, value: function ( ...args ) { return states.get( this )[ name ]( ...args ); } }
+			: { configurable: true, get() { return states.get( this )[ name ]; }, set( value ) { states.get( this )[ name ] = value; } } );
+
+	}
+	return prepareVideo;
+
+}
+
+class NativeVideo extends EventTarget {
+
+	readyState = 0;
+	HAVE_CURRENT_DATA = 2;
+	HAVE_ENOUGH_DATA = 4;
+	duration = NaN;
+	videoWidth = 0;
+	videoHeight = 0;
+	paused = true;
+	loop = false;
+	muted = true;
+	playbackRate = 1;
+	style = {};
+	#src = '';
+	#time = 0;
+	#loaded;
+	#demuxer;
+	#decoder;
+	#frame;
+	#decodedFrame;
+	#callbacks = new Map();
+	#nextCallback = 0;
+	#timer;
+	#chunks = [];
+	#operation = Promise.resolve();
+	#target = 0;
+	#generation = 0;
+	error = null;
+	seeking = false;
+	ended = false;
+
+	get src() { return this.#src; }
+	set src( value ) {
+
+		this.pause(); this.#generation ++;
+		this.#decoder?.close(); this.#demuxer?.close(); this.#frame?.close(); this.#decodedFrame?.close();
+		this.#decoder = this.#demuxer = this.#frame = this.#decodedFrame = undefined;
+		this.#chunks = []; this.#time = 0; this.readyState = 0; this.error = null;
+		this.#src = value ? new URL( value, location.href ).href : ''; this.#loaded = undefined;
+		if ( this.#src ) queueMicrotask( () => { void this.load().catch( error => this.#fail( error ) ); } );
+
+	}
+	get currentSrc() { return this.src; }
+	get currentTime() { return this.#time; }
+	set currentTime( value ) {
+
+		this.seeking = true; this.dispatchEvent( new Event( 'seeking' ) );
+		this.#operation = this.#operation.then( () => this.#seek( value ) ).then( () => { this.seeking = false; this.dispatchEvent( new Event( 'seeked' ) ); } ).catch( error => this.#fail( error ) );
+
+	}
+	dispatchEvent( event ) { this[ `on${event.type}` ]?.( event ); return super.dispatchEvent( event ); }
+	#fail( error ) { this.error = error; this.dispatchEvent( Object.assign( new Event( 'error' ), { error, message: error.message } ) ); }
+
+	async #load() {
+
+		const generation = this.#generation;
+		const response = await fetch( this.src );
+		if ( ! response.ok ) throw new Error( `Video ${this.src}: HTTP ${response.status}` );
+		const bytes = new Uint8Array( await response.arrayBuffer() );
+		if ( generation !== this.#generation ) return;
+		const Demuxer = bytes[ 0 ] === 0x1a && bytes[ 1 ] === 0x45 ? codecs.WebMDemuxer : codecs.Mp4Demuxer;
+		this.#demuxer = new Demuxer( {
+			videoOutput: chunk => this.#chunks.push( chunk ),
+			error: error => this.#fail( error ),
+		} );
+		await this.#demuxer.loadBuffer( bytes );
+		const config = this.#demuxer.videoDecoderConfig;
+		if ( ! config ) throw new Error( 'Media has no video track.' );
+		await this.#demuxer.demuxAsync();
+		if ( generation !== this.#generation ) return;
+		this.videoWidth = config.codedWidth; this.videoHeight = config.codedHeight;
+		this.duration = this.#demuxer.duration / 1e6;
+		this.#decoder = new VideoDecoder( {
+			output: frame => {
+				if ( ! this.#decodedFrame || frame.timestamp <= this.#target && frame.timestamp >= this.#decodedFrame.timestamp ) { this.#decodedFrame?.close(); this.#decodedFrame = frame; }
+				else frame.close();
+			},
+			error: error => this.#fail( error ),
+		} );
+		this.#decoder.configure( config );
+		this.readyState = 1; this.dispatchEvent( new Event( 'loadedmetadata' ) );
+		await this.#decode( 0 );
+		this.readyState = 4;
+		for ( const type of [ 'loadeddata', 'canplay', 'canplaythrough' ] ) this.dispatchEvent( new Event( type ) );
+
+	}
+	load() { return this.#loaded ??= this.#src ? this.#load() : Promise.resolve(); }
+	async #decode( time ) {
+
+		time = Math.max( 0, Math.min( time, this.duration ) );
+		this.#target = Math.round( time * 1e6 );
+		let start = 0;
+		for ( let i = 0; i < this.#chunks.length; i ++ ) if ( this.#chunks[ i ].type === 'key' && this.#chunks[ i ].timestamp <= this.#target ) start = i;
+		this.#decodedFrame?.close(); this.#decodedFrame = undefined;
+		this.#decoder.reset(); this.#decoder.configure( this.#demuxer.videoDecoderConfig );
+		// ponytail: decode one complete GOP per seek; use a streaming frame queue if HTML video playback becomes the capture bottleneck.
+		for ( let i = start; i < this.#chunks.length; i ++ ) {
+
+			const chunk = this.#chunks[ i ];
+			if ( i > start && chunk.type === 'key' && chunk.timestamp > this.#target ) break;
+			this.#decoder.decode( chunk );
+
+		}
+		await this.#decoder.flush();
+		if ( ! this.#decodedFrame ) throw new Error( `Video decoded no frame at ${time}s.` );
+		// Keep the last presented frame available to textures throughout a seek.
+		this.#frame?.close(); this.#frame = this.#decodedFrame; this.#decodedFrame = undefined; this.#time = time;
+		this.dispatchEvent( new Event( 'timeupdate' ) );
+		const callbacks = [ ...this.#callbacks.values() ]; this.#callbacks.clear();
+		for ( const callback of callbacks ) callback( performance.now(), { mediaTime: this.#frame.timestamp / 1e6, expectedDisplayTime: performance.now(), presentationTime: performance.now(), width: this.videoWidth, height: this.videoHeight, presentedFrames: Math.round( time * 30 ) + 1 } );
+
+	}
+	async #seek( time ) { await this.load(); await this.#decode( time ); }
+	async play() {
+
+		await this.load();
+		if ( ! this.paused ) return;
+		this.paused = false; this.ended = false; this.dispatchEvent( new Event( 'play' ) ); this.dispatchEvent( new Event( 'playing' ) );
+		const tick = async () => {
+
+			if ( this.paused ) return;
+			let time = this.#time + this.playbackRate / 30;
+			if ( time >= this.duration ) {
+
+				if ( ! this.loop ) { this.pause(); this.ended = true; this.dispatchEvent( new Event( 'ended' ) ); return; }
+				time = 0;
+
+			}
+			this.#operation = this.#operation.then( () => { if ( ! this.paused ) return this.#decode( time ); } );
+			try { await this.#operation; } catch ( error ) { this.#fail( error ); this.pause(); return; }
+			if ( ! this.paused ) this.#timer = setTimeout( tick, 1000 / 30 );
+
+		};
+		this.#timer = setTimeout( tick, 1000 / 30 );
+
+	}
+	pause() { const changed = ! this.paused; this.paused = true; clearTimeout( this.#timer ); if ( changed ) this.dispatchEvent( new Event( 'pause' ) ); }
+	requestVideoFrameCallback( callback ) { const id = ++ this.#nextCallback; this.#callbacks.set( id, callback ); return id; }
+	cancelVideoFrameCallback( id ) { this.#callbacks.delete( id ); }
+	canPlayType( type ) { return /video\/(mp4|webm)/.test( type ) ? 'probably' : ''; }
+	setAttribute( name, value ) { this[ name ] = [ 'loop', 'muted', 'autoplay', 'playsinline' ].includes( name ) ? true : value; }
+	removeAttribute( name ) { if ( name === 'src' ) this.src = ''; }
+	_toRGBA8() { return this.#frame?._toRGBA8(); }
+
+}
+
+export function installExternalTextures( device ) {
+
+	const yuvPipelines = new Map();
+	const copyYUV = ( image, source, destination, size ) => {
+
+		if ( ! image.yuv ) return false;
+		const { bytes, planes, format, fullRange, kr, kb } = image.yuv, kg = 1 - kr - kb;
+		const width = size.width ?? size[ 0 ], height = size.height ?? size[ 1 ] ?? 1;
+		const x = source.origin?.x ?? source.origin?.[ 0 ] ?? 0, y = source.origin?.y ?? source.origin?.[ 1 ] ?? 0;
+		if ( x + width > image.width || y + height > image.height ) throw new Error( 'External image copy exceeds source bounds.' );
+		const key = `${format}/${kr}/${kb}/${fullRange}`;
+		let pipeline = yuvPipelines.get( key );
+		if ( ! pipeline ) {
+
+			const module = device.createShaderModule( { code: `
+@group(0) @binding(0) var<storage, read> bytes: array<u32>;
+@group(0) @binding(1) var<uniform> p: array<vec4u, 4>;
+@group(0) @binding(2) var output: texture_storage_2d<rgba8unorm, write>;
+fn sampleByte(offset: u32) -> f32 { return f32((bytes[offset / 4u] >> ((offset % 4u) * 8u)) & 255u); }
+@compute @workgroup_size(8, 8) fn main(@builtin(global_invocation_id) id: vec3u) {
+  if (id.x >= p[3].x || id.y >= p[3].y) { return; }
+  let x = p[2].y + id.x;
+  let y = select(p[2].z + id.y, p[2].x - 1u - p[2].z - id.y, p[2].w == 1u);
+  let cx = (x / ${format.startsWith( 'I444' ) ? 1 : 2}u) * ${format === 'NV12' ? 2 : 1}u;
+  let cy = y / ${/^(I420|NV12)/.test( format ) ? 2 : 1}u;
+  let luma = (sampleByte(p[0].x + y * p[0].y + x) - ${fullRange ? '0.0' : '16.0'}) * ${fullRange ? '1.0' : 255 / 219};
+  let u = (sampleByte(p[0].z + cy * p[0].w + cx) - 128.0) * ${fullRange ? '1.0' : 255 / 224};
+  let v = (sampleByte(p[1].x + cy * p[1].y + cx) - 128.0) * ${fullRange ? '1.0' : 255 / 224};
+  var rgb = floor(clamp(vec3f(luma + ${2 * ( 1 - kr )} * v, luma - ${2 * kb * ( 1 - kb ) / kg} * u - ${2 * kr * ( 1 - kr ) / kg} * v, luma + ${2 * ( 1 - kb )} * u), vec3f(0.0), vec3f(255.0)) + 0.5) / 255.0;
+  let alpha = ${format.endsWith( 'A' ) ? 'sampleByte(p[1].z + y * p[1].w + x) / 255.0' : '1.0'};
+  if (p[3].z == 1u) { rgb = floor(rgb * alpha * 255.0 + 0.5) / 255.0; }
+  textureStore(output, id.xy, vec4f(rgb, alpha));
+}` } );
+			pipeline = device.createComputePipeline( { layout: 'auto', compute: { module, entryPoint: 'main' } } );
+			yuvPipelines.set( key, pipeline );
+
+		}
+		const [ yp, up ] = planes, vp = planes[ format === 'NV12' ? 1 : 2 ], ap = format.endsWith( 'A' ) ? planes[ 3 ] : null;
+		const input = device.createBuffer( { size: Math.ceil( bytes.length / 4 ) * 4, usage: GPUBufferUsage.STORAGE, mappedAtCreation: true } );
+		new Uint8Array( input.getMappedRange() ).set( bytes ); input.unmap();
+		const parameters = device.createBuffer( { size: 64, usage: GPUBufferUsage.UNIFORM, mappedAtCreation: true } );
+		new Uint32Array( parameters.getMappedRange() ).set( [ yp.offset, yp.stride, up.offset, up.stride, vp.offset + ( format === 'NV12' ? 1 : 0 ), vp.stride, ap?.offset ?? 0, ap?.stride ?? 0, image.height, x, y, source.flipY ? 1 : 0, width, height, destination.premultipliedAlpha ? 1 : 0, 0 ] );
+		parameters.unmap();
+		const texture = device.createTexture( { size: [ width, height ], format: 'rgba8unorm', usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.COPY_SRC } );
+		try {
+
+			const encoder = device.createCommandEncoder(), pass = encoder.beginComputePass();
+			pass.setPipeline( pipeline );
+			pass.setBindGroup( 0, device.createBindGroup( { layout: pipeline.getBindGroupLayout( 0 ), entries: [ { binding: 0, resource: { buffer: input } }, { binding: 1, resource: { buffer: parameters } }, { binding: 2, resource: texture.createView() } ] } ) );
+			pass.dispatchWorkgroups( Math.ceil( width / 8 ), Math.ceil( height / 8 ) ); pass.end();
+			encoder.copyTextureToTexture( { texture }, destination, [ width, height ] );
+			device.queue.submit( [ encoder.finish() ] );
+
+		} finally { input.destroy(); parameters.destroy(); texture.destroy(); }
+		return true;
+
+	};
+	const shaderModule = device.createShaderModule.bind( device );
+	device.createShaderModule = descriptor => {
+
+		if ( ! /\btexture_external\b/.test( descriptor.code ) ) return shaderModule( descriptor );
+		const code = descriptor.code.replace( /\btexture_external\b/g, 'texture_2d<f32>' ).replace( /\btextureSampleBaseClampToEdge\b/g, 'tbNativeSampleExternal' );
+		return shaderModule( { ...descriptor, code: `${code}\nfn tbNativeSampleExternal(t: texture_2d<f32>, s: sampler, uv: vec2f) -> vec4f { let edge = vec2f(0.5) / vec2f(textureDimensions(t)); return textureSampleLevel(t, s, clamp(uv, edge, vec2f(1.0) - edge), 0.0); }` } );
+
+	};
+	const bindGroupLayout = device.createBindGroupLayout.bind( device );
+	device.createBindGroupLayout = descriptor => bindGroupLayout( { ...descriptor, entries: [ ...descriptor.entries ].map( entry => {
+
+		if ( ! entry.externalTexture ) return entry;
+		const { externalTexture, ...rest } = entry;
+		return { ...rest, texture: { sampleType: 'float', viewDimension: '2d', multisampled: false } };
+
+	} ) } );
+	const textures = new WeakMap();
+	device.importExternalTexture = ( { source, colorSpace = 'srgb' } ) => {
+
+		if ( colorSpace !== 'srgb' ) throw new Error( `Unsupported external texture color space: ${colorSpace}` );
+		const image = source._toRGBA8?.();
+		if ( ! image ) throw new Error( 'External texture source has no decoded pixels.' );
+		let record = textures.get( source );
+		if ( ! record || record.texture.width !== image.width || record.texture.height !== image.height ) {
+
+			record?.texture.destroy();
+			const texture = device.createTexture( { size: [ image.width, image.height ], format: 'rgba8unorm', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST } );
+			record = { texture, view: texture.createView() }; textures.set( source, record );
+
+		}
+		if ( ! copyYUV( image, {}, { texture: record.texture }, [ image.width, image.height ] ) ) device.queue.writeTexture( { texture: record.texture }, image.data, { bytesPerRow: image.width * 4 }, [ image.width, image.height ] );
+		return record.view;
+
+	};
+	return copyYUV;
+
+}

package/node/recording.mjs

@@ -0,0 +1,67 @@
+import { copyFile, mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { VideoEncoder, VideoFrame, WebMMuxer } from '@napi-rs/webcodecs';
+
+// Record actual native canvas readbacks on a wall clock. Duplicate the last
+// frame when readback falls behind, preserving the duration of pointer tests.
+export async function recordCanvas( readPixels, { path, fps = 30 } ) {
+
+	const muxer = new WebMMuxer();
+	let encoder, failure, stopped = false, index = 0;
+	const first = await readPixels();
+	const { width, height } = first;
+	muxer.addVideoTrack( { codec: 'vp8', width, height, frameRate: fps } );
+	encoder = new VideoEncoder( { output: ( chunk, metadata ) => muxer.addVideoChunk( chunk, metadata ), error: error => { failure = error; } } );
+	encoder.configure( { codec: 'vp8', width, height, bitrate: Math.max( 8_000_000, width * height * fps ), framerate: fps } );
+	const started = performance.now();
+	const encode = image => {
+
+		if ( image.width !== width || image.height !== height ) throw new Error( 'Canvas resized during recording.' );
+		const frame = new VideoFrame( image.data, { format: 'RGBA', codedWidth: width, codedHeight: height, timestamp: Math.round( index * 1e6 / fps ), duration: Math.round( 1e6 / fps ) } );
+		try { encoder.encode( frame, { keyFrame: index % ( fps * 2 ) === 0 } ); index ++; }
+		finally { frame.close(); }
+
+	};
+	encode( first );
+	const recording = ( async () => {
+
+		let previous = first;
+		while ( ! stopped ) {
+
+			await delay( Math.max( 0, started + index * 1000 / fps - performance.now() ) );
+			if ( stopped ) break;
+			const next = await readPixels();
+			while ( index < Math.floor( ( performance.now() - started ) * fps / 1000 ) ) encode( previous );
+			encode( next ); previous = next;
+			if ( failure ) throw failure;
+
+		}
+
+	} )();
+	// Keep failures observable at stop without an unhandled rejection mid-capture.
+	void recording.catch( error => { failure = error; } );
+	let completion;
+	return {
+		stop() {
+
+			return completion ??= ( async () => {
+
+				stopped = true;
+				try {
+
+					await recording; await encoder.flush();
+					if ( failure ) throw failure;
+					await mkdir( dirname( path ), { recursive: true } );
+					await writeFile( path, muxer.finalize() );
+
+				} finally { encoder.close(); }
+
+			} )();
+
+		},
+		async saveAs( destination ) { await this.stop(); await copyFile( path, destination ); },
+		async delete() { await this.stop(); await rm( path, { force: true } ); },
+	};
+
+}