jest-environment-webgpu-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# jest-environment-webgpu-node
+
+Real, headless WebGPU inside Jest, with no browser. Powered by Google's Dawn through the
+[`webgpu`](https://github.com/dawn-gpu/node-webgpu) npm package.
+
+The environment puts `navigator.gpu` and every `GPU*` class and constant (`GPUBufferUsage`,
+`GPUShaderStage`, ...) on the test's global object before each test file and removes them
+afterwards.
+
+## Install
+
+```sh
+pnpm add -D jest jest-environment-webgpu-node
+```
+
+## Usage
+
+```js
+// jest.config.mjs
+export default {
+  testEnvironment: 'jest-environment-webgpu-node',
+  testEnvironmentOptions: { dawnOptions: ['backend=vulkan'] },
+};
+```
+
+```ts
+import { expect, it } from '@jest/globals';
+
+it('runs a compute shader', async () => {
+  const device = await (await navigator.gpu.requestAdapter())!.requestDevice();
+  // ...createShaderModule, dispatch, copy to a MAP_READ buffer, mapAsync, assert
+});
+```
+
+`dawnOptions` are passed straight to Dawn: `backend=<null|d3d11|d3d12|metal|vulkan|opengl|opengles>`,
+`adapter=<name>`, `enable-dawn-features=...`, `disable-dawn-features=...`.
+
+## Canvas
+
+Dawn has no `<canvas>`, so the environment ships a headless one whose `getContext('webgpu')` returns a
+`GPUCanvasContext` backed by a texture. `document.createElement('canvas')`, `HTMLCanvasElement`, `window`,
+`self` and `requestAnimationFrame` are installed too (only when missing), which is enough for three.js
+`WebGPURenderer`, Babylon Lite and vgpu to run unchanged.
+
+`createCanvas` is installed as a global, so CommonJS test files can use it without an import. It is also
+available as a named export for ESM test files:
+
+```ts
+import * as THREE from 'three/webgpu';
+import { createCanvas } from 'jest-environment-webgpu-node';
+
+const canvas = createCanvas(256, 256);
+const renderer = new THREE.WebGPURenderer({ canvas: canvas.asElement() });
+await renderer.init();
+await renderer.renderAsync(scene, camera);
+const { width, height, data } = await canvas.readPixels();
+// data is RGBA8, top row first - feed it to a screenshot matcher such as jest-image-snapshot
+```
+
+`readPixels()` returns `{ width, height, data }` RGBA8 pixels. `asElement()` is the same object typed as an
+`HTMLCanvasElement` for library signatures that demand one.
+
+Import `jest-environment-webgpu-node/globals` in a `.d.ts` (or add it to `types` in `tsconfig.json`) to get
+TypeScript types for the global `createCanvas`.
+
+## ESM and CommonJS
+
+This package ships both an ESM and a CommonJS build, so `require('jest-environment-webgpu-node')`
+works from a plain CommonJS test file, and `testEnvironment: 'jest-environment-webgpu-node'`
+resolves the same way either way. `NODE_OPTIONS=--experimental-vm-modules` is only needed when a
+test file itself imports an ESM-only library, such as `three/webgpu`.
+
+## Author
+
+Created by [Ben Houston](https://ben3d.ca) and sponsored by [Land of Assets](https://landofassets.com).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,203 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let jest_environment_node = require("jest-environment-node");
+//#region src/canvas.ts
+const RENDER_ATTACHMENT = 16;
+const MAP_READ = 1;
+/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */
+var HeadlessCanvasContext = class {
+	canvas;
+	#config;
+	#texture;
+	constructor(canvas) {
+		this.canvas = canvas;
+	}
+	configure(config) {
+		this.#config = config;
+		this.#drop();
+	}
+	unconfigure() {
+		this.#config = void 0;
+		this.#drop();
+	}
+	getConfiguration() {
+		return this.#config ?? null;
+	}
+	getCurrentTexture() {
+		const config = this.#config;
+		if (!config) throw new Error("getCurrentTexture() called before configure()");
+		const { width, height } = this.canvas;
+		if (this.#texture && (this.#texture.width !== width || this.#texture.height !== height)) this.#drop();
+		this.#texture ??= config.device.createTexture({
+			size: [width, height],
+			format: config.format,
+			usage: (config.usage ?? RENDER_ATTACHMENT) | 17,
+			viewFormats: config.viewFormats
+		});
+		return this.#texture;
+	}
+	/** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */
+	async readPixels() {
+		const texture = this.getCurrentTexture();
+		const { device, format } = this.#config;
+		const { width, height } = texture;
+		const bytesPerRow = Math.ceil(width * 4 / 256) * 256;
+		const buffer = device.createBuffer({
+			size: bytesPerRow * height,
+			usage: 9
+		});
+		const encoder = device.createCommandEncoder();
+		encoder.copyTextureToBuffer({ texture }, {
+			buffer,
+			bytesPerRow
+		}, [width, height]);
+		device.queue.submit([encoder.finish()]);
+		await buffer.mapAsync(MAP_READ);
+		const padded = new Uint8Array(buffer.getMappedRange());
+		const data = new Uint8Array(width * height * 4);
+		for (let y = 0; y < height; y++) data.set(padded.subarray(y * bytesPerRow, y * bytesPerRow + width * 4), y * width * 4);
+		buffer.unmap();
+		buffer.destroy();
+		if (format.startsWith("bgra")) for (let i = 0; i < data.length; i += 4) [data[i], data[i + 2]] = [data[i + 2], data[i]];
+		return {
+			width,
+			height,
+			data
+		};
+	}
+	#drop() {
+		this.#texture?.destroy();
+		this.#texture = void 0;
+	}
+};
+/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
+var HeadlessCanvas = class {
+	width;
+	height;
+	#context = new HeadlessCanvasContext(this);
+	style = {};
+	#attributes = /* @__PURE__ */ new Map();
+	constructor(width = 300, height = 150) {
+		this.width = width;
+		this.height = height;
+	}
+	get clientWidth() {
+		return this.width;
+	}
+	get clientHeight() {
+		return this.height;
+	}
+	getContext(id) {
+		return id === "webgpu" ? this.#context : null;
+	}
+	readPixels() {
+		return this.#context.readPixels();
+	}
+	/** This same object, typed as an element for libraries whose signatures demand one. */
+	asElement() {
+		return this;
+	}
+	getBoundingClientRect() {
+		return {
+			x: 0,
+			y: 0,
+			top: 0,
+			left: 0,
+			width: this.width,
+			height: this.height
+		};
+	}
+	setAttribute(name, value) {
+		this.#attributes.set(name, value);
+	}
+	getAttribute(name) {
+		return this.#attributes.get(name) ?? null;
+	}
+	addEventListener() {}
+	removeEventListener() {}
+	dispatchEvent() {
+		return true;
+	}
+};
+const createCanvas = (width, height) => new HeadlessCanvas(width, height);
+//#endregion
+//#region src/index.ts
+/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */
+const requestAnimationFrame = (callback) => setTimeout(() => callback(performance.now()), 16).unref();
+const domShims = () => {
+	const window = {
+		devicePixelRatio: 1,
+		requestAnimationFrame,
+		cancelAnimationFrame: clearTimeout,
+		addEventListener() {},
+		removeEventListener() {}
+	};
+	return {
+		HTMLCanvasElement: HeadlessCanvas,
+		document: {
+			createElement: (tag) => tag === "canvas" ? new HeadlessCanvas() : {},
+			createElementNS: (_ns, tag) => tag === "canvas" ? new HeadlessCanvas() : {},
+			addEventListener() {},
+			removeEventListener() {}
+		},
+		window,
+		self: window,
+		requestAnimationFrame,
+		cancelAnimationFrame: clearTimeout
+	};
+};
+/**
+* Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox
+* global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS
+* tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.
+*/
+var WebgpuEnvironment = class extends jest_environment_node.TestEnvironment {
+	#added = [];
+	#navigator = {};
+	#nativeAdded;
+	#dawnOptions;
+	constructor(config, context) {
+		super(config, context);
+		this.#nativeAdded = !Object.getOwnPropertyNames(this.global).includes("_native");
+		if (this.#nativeAdded) Object.defineProperty(this.global, "_native", {
+			value: void 0,
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+		this.#dawnOptions = config.projectConfig.testEnvironmentOptions.dawnOptions;
+	}
+	async setup() {
+		await super.setup();
+		const { create, globals } = await import("webgpu");
+		const global = this.global;
+		const shims = {
+			...globals,
+			...domShims(),
+			createCanvas
+		};
+		this.#added = Object.keys(shims).filter((key) => !(key in global));
+		for (const key of this.#added) global[key] = shims[key];
+		if (this.#nativeAdded) this.#added.push("_native");
+		this.#navigator = global.navigator ??= {};
+		Object.defineProperty(this.#navigator, "gpu", {
+			value: create(this.#dawnOptions ?? []),
+			configurable: true
+		});
+	}
+	async teardown() {
+		delete this.#navigator.gpu;
+		const global = this.global;
+		for (const key of this.#added) delete global[key];
+		await super.teardown();
+	}
+};
+//#endregion
+exports.HeadlessCanvas = HeadlessCanvas;
+exports.HeadlessCanvasContext = HeadlessCanvasContext;
+exports.createCanvas = createCanvas;
+exports.default = WebgpuEnvironment;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["TestEnvironment"],"sources":["../src/canvas.ts","../src/index.ts"],"sourcesContent":["/** RGBA8 pixels, top row first. Feed it to a screenshot matcher such as jest-image-snapshot after encoding to PNG. */\nexport type RgbaImage = { width: number; height: number; data: Uint8Array };\n\nconst COPY_SRC = 0x01;\nconst RENDER_ATTACHMENT = 0x10;\nconst MAP_READ = 0x01;\nconst COPY_DST = 0x08;\n\n/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */\nexport class HeadlessCanvasContext {\n  #config: GPUCanvasConfiguration | undefined;\n  #texture: GPUTexture | undefined;\n\n  constructor(readonly canvas: HeadlessCanvas) {}\n\n  configure(config: GPUCanvasConfiguration): void {\n    this.#config = config;\n    this.#drop();\n  }\n\n  unconfigure(): void {\n    this.#config = undefined;\n    this.#drop();\n  }\n\n  getConfiguration(): GPUCanvasConfiguration | null {\n    return this.#config ?? null;\n  }\n\n  getCurrentTexture(): GPUTexture {\n    const config = this.#config;\n    if (!config) throw new Error('getCurrentTexture() called before configure()');\n    const { width, height } = this.canvas;\n    if (this.#texture && (this.#texture.width !== width || this.#texture.height !== height)) this.#drop();\n    this.#texture ??= config.device.createTexture({\n      size: [width, height],\n      format: config.format,\n      usage: (config.usage ?? RENDER_ATTACHMENT) | RENDER_ATTACHMENT | COPY_SRC,\n      viewFormats: config.viewFormats,\n    });\n    return this.#texture;\n  }\n\n  /** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */\n  async readPixels(): Promise<RgbaImage> {\n    const texture = this.getCurrentTexture();\n    const { device, format } = this.#config!;\n    const { width, height } = texture;\n    const bytesPerRow = Math.ceil((width * 4) / 256) * 256;\n    const buffer = device.createBuffer({ size: bytesPerRow * height, usage: MAP_READ | COPY_DST });\n    const encoder = device.createCommandEncoder();\n    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [width, height]);\n    device.queue.submit([encoder.finish()]);\n    await buffer.mapAsync(MAP_READ);\n    const padded = new Uint8Array(buffer.getMappedRange());\n    const data = new Uint8Array(width * height * 4);\n    for (let y = 0; y < height; y++)\n      data.set(padded.subarray(y * bytesPerRow, y * bytesPerRow + width * 4), y * width * 4);\n    buffer.unmap();\n    buffer.destroy();\n    if (format.startsWith('bgra')) {\n      for (let i = 0; i < data.length; i += 4) [data[i], data[i + 2]] = [data[i + 2]!, data[i]!];\n    }\n    return { width, height, data };\n  }\n\n  #drop(): void {\n    this.#texture?.destroy();\n    this.#texture = undefined;\n  }\n}\n\n/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */\nexport class HeadlessCanvas {\n  readonly #context = new HeadlessCanvasContext(this);\n  readonly style: Record<string, string> = {};\n  readonly #attributes = new Map<string, string>();\n\n  constructor(\n    public width = 300,\n    public height = 150,\n  ) {}\n\n  get clientWidth(): number {\n    return this.width;\n  }\n\n  get clientHeight(): number {\n    return this.height;\n  }\n\n  getContext(id: 'webgpu'): HeadlessCanvasContext;\n  getContext(id: string): HeadlessCanvasContext | null;\n  getContext(id: string): HeadlessCanvasContext | null {\n    return id === 'webgpu' ? this.#context : null;\n  }\n\n  readPixels(): Promise<RgbaImage> {\n    return this.#context.readPixels();\n  }\n\n  /** This same object, typed as an element for libraries whose signatures demand one. */\n  asElement(): HTMLCanvasElement {\n    return this as unknown as HTMLCanvasElement;\n  }\n\n  getBoundingClientRect(): { x: number; y: number; width: number; height: number; top: number; left: number } {\n    return { x: 0, y: 0, top: 0, left: 0, width: this.width, height: this.height };\n  }\n\n  setAttribute(name: string, value: string): void {\n    this.#attributes.set(name, value);\n  }\n\n  getAttribute(name: string): string | null {\n    return this.#attributes.get(name) ?? null;\n  }\n\n  addEventListener(): void {}\n  removeEventListener(): void {}\n  dispatchEvent(): boolean {\n    return true;\n  }\n}\n\nexport const createCanvas = (width: number, height: number): HeadlessCanvas => new HeadlessCanvas(width, height);\n","import { TestEnvironment } from 'jest-environment-node';\nimport { createCanvas, HeadlessCanvas } from './canvas.js';\n\ntype JestEnvironmentConfig = ConstructorParameters<typeof TestEnvironment>[0];\ntype EnvironmentContext = ConstructorParameters<typeof TestEnvironment>[1];\n\nexport { createCanvas, HeadlessCanvas, HeadlessCanvasContext, type RgbaImage } from './canvas.js';\n\n/** Set under `testEnvironmentOptions` in your Jest config. */\nexport type WebgpuNodeOptions = {\n  /** Dawn options, e.g. `['backend=vulkan', 'enable-dawn-features=allow_unsafe_apis']`. */\n  dawnOptions?: string[];\n};\n\n/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */\nconst requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout =>\n  setTimeout(() => callback(performance.now()), 16).unref();\n\nconst domShims = (): Record<string, unknown> => {\n  const window = {\n    devicePixelRatio: 1,\n    requestAnimationFrame,\n    cancelAnimationFrame: clearTimeout,\n    addEventListener() {},\n    removeEventListener() {},\n  };\n  return {\n    HTMLCanvasElement: HeadlessCanvas,\n    document: {\n      createElement: (tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),\n      createElementNS: (_ns: string, tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),\n      addEventListener() {},\n      removeEventListener() {},\n    },\n    window,\n    self: window,\n    requestAnimationFrame,\n    cancelAnimationFrame: clearTimeout,\n  };\n};\n\n/**\n * Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox\n * global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS\n * tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.\n */\nexport default class WebgpuEnvironment extends TestEnvironment {\n  #added: string[] = [];\n  #navigator: { gpu?: GPU } = {};\n  #nativeAdded: boolean;\n  #dawnOptions: string[] | undefined;\n\n  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {\n    super(config, context);\n    // @babylonjs/core defines a `_native` accessor on `self` at module load; on Jest's proxied\n    // sandbox global that defineProperty violates a proxy invariant, so pre-seed the property to\n    // satisfy Babylon's hasOwnProperty guard.\n    // `Object.hasOwn`/`in` report false negatives here: jest-environment-node's sandbox global is\n    // a Proxy over a vm context, and reads of freshly-added properties from outside the sandbox\n    // (as this constructor runs) don't go through the fast path those use. getOwnPropertyNames is\n    // unaffected, so use that instead.\n    this.#nativeAdded = !Object.getOwnPropertyNames(this.global).includes('_native');\n    if (this.#nativeAdded) {\n      Object.defineProperty(this.global, '_native', {\n        value: undefined,\n        writable: true,\n        configurable: true,\n        enumerable: false,\n      });\n    }\n    this.#dawnOptions = config.projectConfig.testEnvironmentOptions.dawnOptions as string[] | undefined;\n  }\n\n  // `webgpu` is ESM-only. Loading it via a dynamic import here (rather than a static top-level\n  // import) keeps it out of this module's own top-level module graph, so a CommonJS test file's\n  // `require('jest-environment-webgpu-node')` - which only needs `createCanvas` - never forces\n  // Jest's sandboxed CJS loader to load an ESM-only dependency (jestjs/jest#15716). This method\n  // itself runs outside that sandbox, through Jest's own environment setup, where Node's native\n  // `import()` always works.\n  override async setup(): Promise<void> {\n    await super.setup();\n    const { create, globals } = await import('webgpu');\n    const global = this.global as unknown as Record<string, unknown>;\n    const shims = { ...globals, ...domShims(), createCanvas } as Record<string, unknown>;\n    this.#added = Object.keys(shims).filter((key) => !(key in global));\n    for (const key of this.#added) global[key] = shims[key];\n    if (this.#nativeAdded) this.#added.push('_native');\n    this.#navigator = (global.navigator ??= {}) as { gpu?: GPU };\n    Object.defineProperty(this.#navigator, 'gpu', { value: create(this.#dawnOptions ?? []), configurable: true });\n  }\n\n  override async teardown(): Promise<void> {\n    delete this.#navigator.gpu;\n    const global = this.global as unknown as Record<string, unknown>;\n    for (const key of this.#added) delete global[key];\n    await super.teardown();\n  }\n}\n"],"mappings":";;;;;;AAIA,MAAM,oBAAoB;AAC1B,MAAM,WAAW;;AAIjB,IAAa,wBAAb,MAAmC;CAIZ;CAHrB;CACA;CAEA,YAAY,QAAiC;EAAxB,KAAA,SAAA;CAAyB;CAE9C,UAAU,QAAsC;EAC9C,KAAK,UAAU;EACf,KAAK,MAAM;CACb;CAEA,cAAoB;EAClB,KAAK,UAAU,KAAA;EACf,KAAK,MAAM;CACb;CAEA,mBAAkD;EAChD,OAAO,KAAK,WAAW;CACzB;CAEA,oBAAgC;EAC9B,MAAM,SAAS,KAAK;EACpB,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,+CAA+C;EAC5E,MAAM,EAAE,OAAO,WAAW,KAAK;EAC/B,IAAI,KAAK,aAAa,KAAK,SAAS,UAAU,SAAS,KAAK,SAAS,WAAW,SAAS,KAAK,MAAM;EACpG,KAAK,aAAa,OAAO,OAAO,cAAc;GAC5C,MAAM,CAAC,OAAO,MAAM;GACpB,QAAQ,OAAO;GACf,QAAQ,OAAO,SAAS,qBAAqB;GAC7C,aAAa,OAAO;EACtB,CAAC;EACD,OAAO,KAAK;CACd;;CAGA,MAAM,aAAiC;EACrC,MAAM,UAAU,KAAK,kBAAkB;EACvC,MAAM,EAAE,QAAQ,WAAW,KAAK;EAChC,MAAM,EAAE,OAAO,WAAW;EAC1B,MAAM,cAAc,KAAK,KAAM,QAAQ,IAAK,GAAG,IAAI;EACnD,MAAM,SAAS,OAAO,aAAa;GAAE,MAAM,cAAc;GAAQ,OAAO;EAAoB,CAAC;EAC7F,MAAM,UAAU,OAAO,qBAAqB;EAC5C,QAAQ,oBAAoB,EAAE,QAAQ,GAAG;GAAE;GAAQ;EAAY,GAAG,CAAC,OAAO,MAAM,CAAC;EACjF,OAAO,MAAM,OAAO,CAAC,QAAQ,OAAO,CAAC,CAAC;EACtC,MAAM,OAAO,SAAS,QAAQ;EAC9B,MAAM,SAAS,IAAI,WAAW,OAAO,eAAe,CAAC;EACrD,MAAM,OAAO,IAAI,WAAW,QAAQ,SAAS,CAAC;EAC9C,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAC1B,KAAK,IAAI,OAAO,SAAS,IAAI,aAAa,IAAI,cAAc,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC;EACvF,OAAO,MAAM;EACb,OAAO,QAAQ;EACf,IAAI,OAAO,WAAW,MAAM,GAC1B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,GAAG,CAAC,KAAK,IAAI,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,IAAK,KAAK,EAAG;EAE3F,OAAO;GAAE;GAAO;GAAQ;EAAK;CAC/B;CAEA,QAAc;EACZ,KAAK,UAAU,QAAQ;EACvB,KAAK,WAAW,KAAA;CAClB;AACF;;AAGA,IAAa,iBAAb,MAA4B;CAMjB;CACA;CANT,WAAoB,IAAI,sBAAsB,IAAI;CAClD,QAAyC,CAAC;CAC1C,8BAAuB,IAAI,IAAoB;CAE/C,YACE,QAAe,KACf,SAAgB,KAChB;EAFO,KAAA,QAAA;EACA,KAAA,SAAA;CACN;CAEH,IAAI,cAAsB;EACxB,OAAO,KAAK;CACd;CAEA,IAAI,eAAuB;EACzB,OAAO,KAAK;CACd;CAIA,WAAW,IAA0C;EACnD,OAAO,OAAO,WAAW,KAAK,WAAW;CAC3C;CAEA,aAAiC;EAC/B,OAAO,KAAK,SAAS,WAAW;CAClC;;CAGA,YAA+B;EAC7B,OAAO;CACT;CAEA,wBAA4G;EAC1G,OAAO;GAAE,GAAG;GAAG,GAAG;GAAG,KAAK;GAAG,MAAM;GAAG,OAAO,KAAK;GAAO,QAAQ,KAAK;EAAO;CAC/E;CAEA,aAAa,MAAc,OAAqB;EAC9C,KAAK,YAAY,IAAI,MAAM,KAAK;CAClC;CAEA,aAAa,MAA6B;EACxC,OAAO,KAAK,YAAY,IAAI,IAAI,KAAK;CACvC;CAEA,mBAAyB,CAAC;CAC1B,sBAA4B,CAAC;CAC7B,gBAAyB;EACvB,OAAO;CACT;AACF;AAEA,MAAa,gBAAgB,OAAe,WAAmC,IAAI,eAAe,OAAO,MAAM;;;;AC9G/G,MAAM,yBAAyB,aAC7B,iBAAiB,SAAS,YAAY,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM;AAE1D,MAAM,iBAA0C;CAC9C,MAAM,SAAS;EACb,kBAAkB;EAClB;EACA,sBAAsB;EACtB,mBAAmB,CAAC;EACpB,sBAAsB,CAAC;CACzB;CACA,OAAO;EACL,mBAAmB;EACnB,UAAU;GACR,gBAAgB,QAAiB,QAAQ,WAAW,IAAI,eAAe,IAAI,CAAC;GAC5E,kBAAkB,KAAa,QAAiB,QAAQ,WAAW,IAAI,eAAe,IAAI,CAAC;GAC3F,mBAAmB,CAAC;GACpB,sBAAsB,CAAC;EACzB;EACA;EACA,MAAM;EACN;EACA,sBAAsB;CACxB;AACF;;;;;;AAOA,IAAqB,oBAArB,cAA+CA,sBAAAA,gBAAgB;CAC7D,SAAmB,CAAC;CACpB,aAA4B,CAAC;CAC7B;CACA;CAEA,YAAY,QAA+B,SAA6B;EACtE,MAAM,QAAQ,OAAO;EAQrB,KAAK,eAAe,CAAC,OAAO,oBAAoB,KAAK,MAAM,CAAC,CAAC,SAAS,SAAS;EAC/E,IAAI,KAAK,cACP,OAAO,eAAe,KAAK,QAAQ,WAAW;GAC5C,OAAO,KAAA;GACP,UAAU;GACV,cAAc;GACd,YAAY;EACd,CAAC;EAEH,KAAK,eAAe,OAAO,cAAc,uBAAuB;CAClE;CAQA,MAAe,QAAuB;EACpC,MAAM,MAAM,MAAM;EAClB,MAAM,EAAE,QAAQ,YAAY,MAAM,OAAO;EACzC,MAAM,SAAS,KAAK;EACpB,MAAM,QAAQ;GAAE,GAAG;GAAS,GAAG,SAAS;GAAG;EAAa;EACxD,KAAK,SAAS,OAAO,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE,OAAO,OAAO;EACjE,KAAK,MAAM,OAAO,KAAK,QAAQ,OAAO,OAAO,MAAM;EACnD,IAAI,KAAK,cAAc,KAAK,OAAO,KAAK,SAAS;EACjD,KAAK,aAAc,OAAO,cAAc,CAAC;EACzC,OAAO,eAAe,KAAK,YAAY,OAAO;GAAE,OAAO,OAAO,KAAK,gBAAgB,CAAC,CAAC;GAAG,cAAc;EAAK,CAAC;CAC9G;CAEA,MAAe,WAA0B;EACvC,OAAO,KAAK,WAAW;EACvB,MAAM,SAAS,KAAK;EACpB,KAAK,MAAM,OAAO,KAAK,QAAQ,OAAO,OAAO;EAC7C,MAAM,MAAM,SAAS;CACvB;AACF"}

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+import { TestEnvironment } from "jest-environment-node";
+//#region src/canvas.d.ts
+/** RGBA8 pixels, top row first. Feed it to a screenshot matcher such as jest-image-snapshot after encoding to PNG. */
+type RgbaImage = {
+  width: number;
+  height: number;
+  data: Uint8Array;
+};
+/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */
+export declare class HeadlessCanvasContext {
+  #private;
+  readonly canvas: HeadlessCanvas;
+  constructor(canvas: HeadlessCanvas);
+  configure(config: GPUCanvasConfiguration): void;
+  unconfigure(): void;
+  getConfiguration(): GPUCanvasConfiguration | null;
+  getCurrentTexture(): GPUTexture;
+  /** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */
+  readPixels(): Promise<RgbaImage>;
+}
+/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
+export declare class HeadlessCanvas {
+  #private;
+  width: number;
+  height: number;
+  readonly style: Record<string, string>;
+  constructor(width?: number, height?: number);
+  get clientWidth(): number;
+  get clientHeight(): number;
+  getContext(id: 'webgpu'): HeadlessCanvasContext;
+  getContext(id: string): HeadlessCanvasContext | null;
+  readPixels(): Promise<RgbaImage>;
+  /** This same object, typed as an element for libraries whose signatures demand one. */
+  asElement(): HTMLCanvasElement;
+  getBoundingClientRect(): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+  };
+  setAttribute(name: string, value: string): void;
+  getAttribute(name: string): string | null;
+  addEventListener(): void;
+  removeEventListener(): void;
+  dispatchEvent(): boolean;
+}
+export declare const createCanvas: (width: number, height: number) => HeadlessCanvas;
+//#endregion
+//#region src/index.d.ts
+type JestEnvironmentConfig = ConstructorParameters<typeof TestEnvironment>[0];
+type EnvironmentContext = ConstructorParameters<typeof TestEnvironment>[1];
+/** Set under `testEnvironmentOptions` in your Jest config. */
+export type WebgpuNodeOptions = {
+  /** Dawn options, e.g. `['backend=vulkan', 'enable-dawn-features=allow_unsafe_apis']`. */
+  dawnOptions?: string[];
+};
+/**
+ * Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox
+ * global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS
+ * tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.
+ */
+export default class WebgpuEnvironment extends TestEnvironment {
+  #private;
+  constructor(config: JestEnvironmentConfig, context: EnvironmentContext);
+  setup(): Promise<void>;
+  teardown(): Promise<void>;
+}
+//#endregion
+export type { RgbaImage };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/canvas.ts","../src/index.ts"],"mappings":";;;KACY;EAAc;EAAe;EAAgB,MAAM;;;qBAQlD;;WAIU,QAAQ;EAA7B,YAAqB,QAAQ;EAE7B,UAAU,QAAQ;EAKlB;EAKA,oBAAoB;EAIpB,qBAAqB;;EAef,cAAc,QAAQ;;;qBA6BjB;;EAMF;EACA;WALA,OAAO;EAGhB,YACS,gBACA;MAGL;MAIA;EAIJ,WAAW,eAAe;EAC1B,WAAW,aAAa;EAKxB,cAAc,QAAQ;;EAKtB,aAAa;EAIb;IAA2B;IAAW;IAAW;IAAe;IAAgB;IAAa;;EAI7F,aAAa,cAAc;EAI3B,aAAa;EAIb;EACA;EACA;;qBAKW,eAAY,eAAiB,mBAAmB;;;KC1HxD,wBAAwB,6BAA6B;KACrD,qBAAqB,6BAA6B;;YAK3C;;EAEV;;;;;;;qBAmCmB,0BAA0B;;EAM7C,YAAY,QAAQ,uBAAuB,SAAS;EA2BrC,SAAS;EAYT,YAAY"}

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+import { TestEnvironment } from "jest-environment-node";
+//#region src/canvas.d.ts
+/** RGBA8 pixels, top row first. Feed it to a screenshot matcher such as jest-image-snapshot after encoding to PNG. */
+type RgbaImage = {
+  width: number;
+  height: number;
+  data: Uint8Array;
+};
+/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */
+export declare class HeadlessCanvasContext {
+  #private;
+  readonly canvas: HeadlessCanvas;
+  constructor(canvas: HeadlessCanvas);
+  configure(config: GPUCanvasConfiguration): void;
+  unconfigure(): void;
+  getConfiguration(): GPUCanvasConfiguration | null;
+  getCurrentTexture(): GPUTexture;
+  /** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */
+  readPixels(): Promise<RgbaImage>;
+}
+/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
+export declare class HeadlessCanvas {
+  #private;
+  width: number;
+  height: number;
+  readonly style: Record<string, string>;
+  constructor(width?: number, height?: number);
+  get clientWidth(): number;
+  get clientHeight(): number;
+  getContext(id: 'webgpu'): HeadlessCanvasContext;
+  getContext(id: string): HeadlessCanvasContext | null;
+  readPixels(): Promise<RgbaImage>;
+  /** This same object, typed as an element for libraries whose signatures demand one. */
+  asElement(): HTMLCanvasElement;
+  getBoundingClientRect(): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+  };
+  setAttribute(name: string, value: string): void;
+  getAttribute(name: string): string | null;
+  addEventListener(): void;
+  removeEventListener(): void;
+  dispatchEvent(): boolean;
+}
+export declare const createCanvas: (width: number, height: number) => HeadlessCanvas;
+//#endregion
+//#region src/index.d.ts
+type JestEnvironmentConfig = ConstructorParameters<typeof TestEnvironment>[0];
+type EnvironmentContext = ConstructorParameters<typeof TestEnvironment>[1];
+/** Set under `testEnvironmentOptions` in your Jest config. */
+export type WebgpuNodeOptions = {
+  /** Dawn options, e.g. `['backend=vulkan', 'enable-dawn-features=allow_unsafe_apis']`. */
+  dawnOptions?: string[];
+};
+/**
+ * Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox
+ * global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS
+ * tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.
+ */
+export default class WebgpuEnvironment extends TestEnvironment {
+  #private;
+  constructor(config: JestEnvironmentConfig, context: EnvironmentContext);
+  setup(): Promise<void>;
+  teardown(): Promise<void>;
+}
+//#endregion
+export type { RgbaImage };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/canvas.ts","../src/index.ts"],"mappings":";;;KACY;EAAc;EAAe;EAAgB,MAAM;;;qBAQlD;;WAIU,QAAQ;EAA7B,YAAqB,QAAQ;EAE7B,UAAU,QAAQ;EAKlB;EAKA,oBAAoB;EAIpB,qBAAqB;;EAef,cAAc,QAAQ;;;qBA6BjB;;EAMF;EACA;WALA,OAAO;EAGhB,YACS,gBACA;MAGL;MAIA;EAIJ,WAAW,eAAe;EAC1B,WAAW,aAAa;EAKxB,cAAc,QAAQ;;EAKtB,aAAa;EAIb;IAA2B;IAAW;IAAW;IAAe;IAAgB;IAAa;;EAI7F,aAAa,cAAc;EAI3B,aAAa;EAIb;EACA;EACA;;qBAKW,eAAY,eAAiB,mBAAmB;;;KC1HxD,wBAAwB,6BAA6B;KACrD,qBAAqB,6BAA6B;;YAK3C;;EAEV;;;;;;;qBAmCmB,0BAA0B;;EAM7C,YAAY,QAAQ,uBAAuB,SAAS;EA2BrC,SAAS;EAYT,YAAY"}

package/dist/index.mjs

@@ -0,0 +1,196 @@
+import { TestEnvironment } from "jest-environment-node";
+//#region src/canvas.ts
+const RENDER_ATTACHMENT = 16;
+const MAP_READ = 1;
+/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */
+var HeadlessCanvasContext = class {
+	canvas;
+	#config;
+	#texture;
+	constructor(canvas) {
+		this.canvas = canvas;
+	}
+	configure(config) {
+		this.#config = config;
+		this.#drop();
+	}
+	unconfigure() {
+		this.#config = void 0;
+		this.#drop();
+	}
+	getConfiguration() {
+		return this.#config ?? null;
+	}
+	getCurrentTexture() {
+		const config = this.#config;
+		if (!config) throw new Error("getCurrentTexture() called before configure()");
+		const { width, height } = this.canvas;
+		if (this.#texture && (this.#texture.width !== width || this.#texture.height !== height)) this.#drop();
+		this.#texture ??= config.device.createTexture({
+			size: [width, height],
+			format: config.format,
+			usage: (config.usage ?? RENDER_ATTACHMENT) | 17,
+			viewFormats: config.viewFormats
+		});
+		return this.#texture;
+	}
+	/** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */
+	async readPixels() {
+		const texture = this.getCurrentTexture();
+		const { device, format } = this.#config;
+		const { width, height } = texture;
+		const bytesPerRow = Math.ceil(width * 4 / 256) * 256;
+		const buffer = device.createBuffer({
+			size: bytesPerRow * height,
+			usage: 9
+		});
+		const encoder = device.createCommandEncoder();
+		encoder.copyTextureToBuffer({ texture }, {
+			buffer,
+			bytesPerRow
+		}, [width, height]);
+		device.queue.submit([encoder.finish()]);
+		await buffer.mapAsync(MAP_READ);
+		const padded = new Uint8Array(buffer.getMappedRange());
+		const data = new Uint8Array(width * height * 4);
+		for (let y = 0; y < height; y++) data.set(padded.subarray(y * bytesPerRow, y * bytesPerRow + width * 4), y * width * 4);
+		buffer.unmap();
+		buffer.destroy();
+		if (format.startsWith("bgra")) for (let i = 0; i < data.length; i += 4) [data[i], data[i + 2]] = [data[i + 2], data[i]];
+		return {
+			width,
+			height,
+			data
+		};
+	}
+	#drop() {
+		this.#texture?.destroy();
+		this.#texture = void 0;
+	}
+};
+/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
+var HeadlessCanvas = class {
+	width;
+	height;
+	#context = new HeadlessCanvasContext(this);
+	style = {};
+	#attributes = /* @__PURE__ */ new Map();
+	constructor(width = 300, height = 150) {
+		this.width = width;
+		this.height = height;
+	}
+	get clientWidth() {
+		return this.width;
+	}
+	get clientHeight() {
+		return this.height;
+	}
+	getContext(id) {
+		return id === "webgpu" ? this.#context : null;
+	}
+	readPixels() {
+		return this.#context.readPixels();
+	}
+	/** This same object, typed as an element for libraries whose signatures demand one. */
+	asElement() {
+		return this;
+	}
+	getBoundingClientRect() {
+		return {
+			x: 0,
+			y: 0,
+			top: 0,
+			left: 0,
+			width: this.width,
+			height: this.height
+		};
+	}
+	setAttribute(name, value) {
+		this.#attributes.set(name, value);
+	}
+	getAttribute(name) {
+		return this.#attributes.get(name) ?? null;
+	}
+	addEventListener() {}
+	removeEventListener() {}
+	dispatchEvent() {
+		return true;
+	}
+};
+const createCanvas = (width, height) => new HeadlessCanvas(width, height);
+//#endregion
+//#region src/index.ts
+/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */
+const requestAnimationFrame = (callback) => setTimeout(() => callback(performance.now()), 16).unref();
+const domShims = () => {
+	const window = {
+		devicePixelRatio: 1,
+		requestAnimationFrame,
+		cancelAnimationFrame: clearTimeout,
+		addEventListener() {},
+		removeEventListener() {}
+	};
+	return {
+		HTMLCanvasElement: HeadlessCanvas,
+		document: {
+			createElement: (tag) => tag === "canvas" ? new HeadlessCanvas() : {},
+			createElementNS: (_ns, tag) => tag === "canvas" ? new HeadlessCanvas() : {},
+			addEventListener() {},
+			removeEventListener() {}
+		},
+		window,
+		self: window,
+		requestAnimationFrame,
+		cancelAnimationFrame: clearTimeout
+	};
+};
+/**
+* Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox
+* global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS
+* tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.
+*/
+var WebgpuEnvironment = class extends TestEnvironment {
+	#added = [];
+	#navigator = {};
+	#nativeAdded;
+	#dawnOptions;
+	constructor(config, context) {
+		super(config, context);
+		this.#nativeAdded = !Object.getOwnPropertyNames(this.global).includes("_native");
+		if (this.#nativeAdded) Object.defineProperty(this.global, "_native", {
+			value: void 0,
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+		this.#dawnOptions = config.projectConfig.testEnvironmentOptions.dawnOptions;
+	}
+	async setup() {
+		await super.setup();
+		const { create, globals } = await import("webgpu");
+		const global = this.global;
+		const shims = {
+			...globals,
+			...domShims(),
+			createCanvas
+		};
+		this.#added = Object.keys(shims).filter((key) => !(key in global));
+		for (const key of this.#added) global[key] = shims[key];
+		if (this.#nativeAdded) this.#added.push("_native");
+		this.#navigator = global.navigator ??= {};
+		Object.defineProperty(this.#navigator, "gpu", {
+			value: create(this.#dawnOptions ?? []),
+			configurable: true
+		});
+	}
+	async teardown() {
+		delete this.#navigator.gpu;
+		const global = this.global;
+		for (const key of this.#added) delete global[key];
+		await super.teardown();
+	}
+};
+//#endregion
+export { HeadlessCanvas, HeadlessCanvasContext, createCanvas, WebgpuEnvironment as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/canvas.ts","../src/index.ts"],"sourcesContent":["/** RGBA8 pixels, top row first. Feed it to a screenshot matcher such as jest-image-snapshot after encoding to PNG. */\nexport type RgbaImage = { width: number; height: number; data: Uint8Array };\n\nconst COPY_SRC = 0x01;\nconst RENDER_ATTACHMENT = 0x10;\nconst MAP_READ = 0x01;\nconst COPY_DST = 0x08;\n\n/** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */\nexport class HeadlessCanvasContext {\n  #config: GPUCanvasConfiguration | undefined;\n  #texture: GPUTexture | undefined;\n\n  constructor(readonly canvas: HeadlessCanvas) {}\n\n  configure(config: GPUCanvasConfiguration): void {\n    this.#config = config;\n    this.#drop();\n  }\n\n  unconfigure(): void {\n    this.#config = undefined;\n    this.#drop();\n  }\n\n  getConfiguration(): GPUCanvasConfiguration | null {\n    return this.#config ?? null;\n  }\n\n  getCurrentTexture(): GPUTexture {\n    const config = this.#config;\n    if (!config) throw new Error('getCurrentTexture() called before configure()');\n    const { width, height } = this.canvas;\n    if (this.#texture && (this.#texture.width !== width || this.#texture.height !== height)) this.#drop();\n    this.#texture ??= config.device.createTexture({\n      size: [width, height],\n      format: config.format,\n      usage: (config.usage ?? RENDER_ATTACHMENT) | RENDER_ATTACHMENT | COPY_SRC,\n      viewFormats: config.viewFormats,\n    });\n    return this.#texture;\n  }\n\n  /** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */\n  async readPixels(): Promise<RgbaImage> {\n    const texture = this.getCurrentTexture();\n    const { device, format } = this.#config!;\n    const { width, height } = texture;\n    const bytesPerRow = Math.ceil((width * 4) / 256) * 256;\n    const buffer = device.createBuffer({ size: bytesPerRow * height, usage: MAP_READ | COPY_DST });\n    const encoder = device.createCommandEncoder();\n    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [width, height]);\n    device.queue.submit([encoder.finish()]);\n    await buffer.mapAsync(MAP_READ);\n    const padded = new Uint8Array(buffer.getMappedRange());\n    const data = new Uint8Array(width * height * 4);\n    for (let y = 0; y < height; y++)\n      data.set(padded.subarray(y * bytesPerRow, y * bytesPerRow + width * 4), y * width * 4);\n    buffer.unmap();\n    buffer.destroy();\n    if (format.startsWith('bgra')) {\n      for (let i = 0; i < data.length; i += 4) [data[i], data[i + 2]] = [data[i + 2]!, data[i]!];\n    }\n    return { width, height, data };\n  }\n\n  #drop(): void {\n    this.#texture?.destroy();\n    this.#texture = undefined;\n  }\n}\n\n/** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */\nexport class HeadlessCanvas {\n  readonly #context = new HeadlessCanvasContext(this);\n  readonly style: Record<string, string> = {};\n  readonly #attributes = new Map<string, string>();\n\n  constructor(\n    public width = 300,\n    public height = 150,\n  ) {}\n\n  get clientWidth(): number {\n    return this.width;\n  }\n\n  get clientHeight(): number {\n    return this.height;\n  }\n\n  getContext(id: 'webgpu'): HeadlessCanvasContext;\n  getContext(id: string): HeadlessCanvasContext | null;\n  getContext(id: string): HeadlessCanvasContext | null {\n    return id === 'webgpu' ? this.#context : null;\n  }\n\n  readPixels(): Promise<RgbaImage> {\n    return this.#context.readPixels();\n  }\n\n  /** This same object, typed as an element for libraries whose signatures demand one. */\n  asElement(): HTMLCanvasElement {\n    return this as unknown as HTMLCanvasElement;\n  }\n\n  getBoundingClientRect(): { x: number; y: number; width: number; height: number; top: number; left: number } {\n    return { x: 0, y: 0, top: 0, left: 0, width: this.width, height: this.height };\n  }\n\n  setAttribute(name: string, value: string): void {\n    this.#attributes.set(name, value);\n  }\n\n  getAttribute(name: string): string | null {\n    return this.#attributes.get(name) ?? null;\n  }\n\n  addEventListener(): void {}\n  removeEventListener(): void {}\n  dispatchEvent(): boolean {\n    return true;\n  }\n}\n\nexport const createCanvas = (width: number, height: number): HeadlessCanvas => new HeadlessCanvas(width, height);\n","import { TestEnvironment } from 'jest-environment-node';\nimport { createCanvas, HeadlessCanvas } from './canvas.js';\n\ntype JestEnvironmentConfig = ConstructorParameters<typeof TestEnvironment>[0];\ntype EnvironmentContext = ConstructorParameters<typeof TestEnvironment>[1];\n\nexport { createCanvas, HeadlessCanvas, HeadlessCanvasContext, type RgbaImage } from './canvas.js';\n\n/** Set under `testEnvironmentOptions` in your Jest config. */\nexport type WebgpuNodeOptions = {\n  /** Dawn options, e.g. `['backend=vulkan', 'enable-dawn-features=allow_unsafe_apis']`. */\n  dawnOptions?: string[];\n};\n\n/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */\nconst requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout =>\n  setTimeout(() => callback(performance.now()), 16).unref();\n\nconst domShims = (): Record<string, unknown> => {\n  const window = {\n    devicePixelRatio: 1,\n    requestAnimationFrame,\n    cancelAnimationFrame: clearTimeout,\n    addEventListener() {},\n    removeEventListener() {},\n  };\n  return {\n    HTMLCanvasElement: HeadlessCanvas,\n    document: {\n      createElement: (tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),\n      createElementNS: (_ns: string, tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),\n      addEventListener() {},\n      removeEventListener() {},\n    },\n    window,\n    self: window,\n    requestAnimationFrame,\n    cancelAnimationFrame: clearTimeout,\n  };\n};\n\n/**\n * Jest environment that puts real headless WebGPU (Dawn via the `webgpu` package) on the sandbox\n * global: `navigator.gpu`, every `GPU*` class and constant, and a `HeadlessCanvas` shim. CommonJS\n * tests can rely on `createCanvas` being a global; ESM tests can also `import` it from this package.\n */\nexport default class WebgpuEnvironment extends TestEnvironment {\n  #added: string[] = [];\n  #navigator: { gpu?: GPU } = {};\n  #nativeAdded: boolean;\n  #dawnOptions: string[] | undefined;\n\n  constructor(config: JestEnvironmentConfig, context: EnvironmentContext) {\n    super(config, context);\n    // @babylonjs/core defines a `_native` accessor on `self` at module load; on Jest's proxied\n    // sandbox global that defineProperty violates a proxy invariant, so pre-seed the property to\n    // satisfy Babylon's hasOwnProperty guard.\n    // `Object.hasOwn`/`in` report false negatives here: jest-environment-node's sandbox global is\n    // a Proxy over a vm context, and reads of freshly-added properties from outside the sandbox\n    // (as this constructor runs) don't go through the fast path those use. getOwnPropertyNames is\n    // unaffected, so use that instead.\n    this.#nativeAdded = !Object.getOwnPropertyNames(this.global).includes('_native');\n    if (this.#nativeAdded) {\n      Object.defineProperty(this.global, '_native', {\n        value: undefined,\n        writable: true,\n        configurable: true,\n        enumerable: false,\n      });\n    }\n    this.#dawnOptions = config.projectConfig.testEnvironmentOptions.dawnOptions as string[] | undefined;\n  }\n\n  // `webgpu` is ESM-only. Loading it via a dynamic import here (rather than a static top-level\n  // import) keeps it out of this module's own top-level module graph, so a CommonJS test file's\n  // `require('jest-environment-webgpu-node')` - which only needs `createCanvas` - never forces\n  // Jest's sandboxed CJS loader to load an ESM-only dependency (jestjs/jest#15716). This method\n  // itself runs outside that sandbox, through Jest's own environment setup, where Node's native\n  // `import()` always works.\n  override async setup(): Promise<void> {\n    await super.setup();\n    const { create, globals } = await import('webgpu');\n    const global = this.global as unknown as Record<string, unknown>;\n    const shims = { ...globals, ...domShims(), createCanvas } as Record<string, unknown>;\n    this.#added = Object.keys(shims).filter((key) => !(key in global));\n    for (const key of this.#added) global[key] = shims[key];\n    if (this.#nativeAdded) this.#added.push('_native');\n    this.#navigator = (global.navigator ??= {}) as { gpu?: GPU };\n    Object.defineProperty(this.#navigator, 'gpu', { value: create(this.#dawnOptions ?? []), configurable: true });\n  }\n\n  override async teardown(): Promise<void> {\n    delete this.#navigator.gpu;\n    const global = this.global as unknown as Record<string, unknown>;\n    for (const key of this.#added) delete global[key];\n    await super.teardown();\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "jest-environment-webgpu-node",
+  "version": "0.1.0",
+  "description": "Jest environment that provides real headless WebGPU (Dawn via the webgpu package) in Node",
+  "keywords": [
+    "dawn",
+    "headless",
+    "jest",
+    "jest-environment",
+    "testing",
+    "webgpu"
+  ],
+  "homepage": "https://github.com/bhouston/jest-gpu#readme",
+  "bugs": {
+    "url": "https://github.com/bhouston/jest-gpu/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Houston <ben@ben3d.ca> (https://ben3d.ca)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/jest-gpu.git",
+    "directory": "packages/jest-environment-webgpu-node"
+  },
+  "files": [
+    "dist/**/*.cjs",
+    "dist/**/*.cjs.map",
+    "dist/**/*.mjs",
+    "dist/**/*.mjs.map",
+    "dist/**/*.d.cts",
+    "dist/**/*.d.cts.map",
+    "dist/**/*.d.mts",
+    "dist/**/*.d.mts.map",
+    "src/globals.d.ts",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./globals": {
+      "types": "./src/globals.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "tsc": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@webgpu/types": "^0.1.72",
+    "webgpu": "^0.6.1"
+  },
+  "peerDependencies": {
+    "jest": ">=29 <31",
+    "jest-environment-node": ">=29 <31"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,3 @@
+// Ambient typing for the `createCanvas` global this environment installs on `globalThis`, for
+// CommonJS test files that use the global instead of importing this ESM package.
+declare const createCanvas: typeof import('./canvas.js').createCanvas;