vitest-environment-webgpu-node 3.0.0 → 3.0.2

package/README.md

@@ -1,30 +1,83 @@
+<p align="center">
+  <a href="https://npmjs.com/package/vitest-environment-webgpu-node"><img src="https://img.shields.io/npm/v/vitest-environment-webgpu-node.svg" alt="npm package"></a>
+  <a href="https://www.npmtrends.com/vitest-environment-webgpu-node"><img src="https://img.shields.io/npm/dw/vitest-environment-webgpu-node.svg" alt="npm downloads"></a>
+  <a href="https://codecov.io/gh/bhouston/vitest-gpu"><img src="https://codecov.io/gh/bhouston/vitest-gpu/branch/main/graph/badge.svg" alt="coverage"></a>
+  <a href="https://discord.gg/fwupDN493R"><img src="https://img.shields.io/badge/chat-discord-blue?style=flat&logo=discord" alt="discord chat"></a>
+  <a href="https://vitest-gpu.ben3d.ca/"><img src="https://img.shields.io/badge/docs-read-blue?style=flat" alt="documentation"></a>
+</p>
+<br/>
+
 # vitest-environment-webgpu-node
 
-[![npm version][npm-badge]][npm-url]
-[![npm downloads][downloads-badge]][npm-url]
-[![Tests][tests-badge]][tests-url]
-[![Discord][discord-badge]][discord-url]
+> Real WebGPU tests in Vitest, with no browser.
+
+- 🖥️ Real WebGPU via Dawn
+- 🚫 No Browser or Mocks
+- 🧩 Headless Canvas Included
+- 🔧 Dawn Backend Options
+- ⚡ Up to 2.4x Faster Than Browsers
+
+Headless GPU testing for CI: `navigator.gpu` is backed by Google's Dawn through the
+[`webgpu`](https://github.com/dawn-gpu/node-webgpu) npm package. Native GPU testing is up to 2.4x faster than
+running the same tests in a browser, see the [blog post](https://ben3d.ca/blog/native-gpu-testing-for-vitest-and-jest).
+
+Part of [vitest-gpu](https://github.com/bhouston/vitest-gpu), which also provides WebGL and image snapshot packages.
+
+[Read the Docs to Learn More](https://vitest-gpu.ben3d.ca/docs/webgpu/) about the WebGPU environment: Dawn options, TypeScript types, the headless canvas and CI setup.
+
+```sh
+pnpm add -D vitest vitest-environment-webgpu-node
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({ test: { environment: 'webgpu-node' } });
+```
+
+```ts
+// gpu.test.ts
+import { expect, it } from 'vitest';
 
-Real, headless WebGPU inside Vitest, with no browser. Native GPU testing is up to 2.4x faster
-than running the same tests in a browser — see the
-[blog post](https://ben3d.ca/blog/native-gpu-testing-for-vitest-and-jest) for details.
-Powered by Google's Dawn through the
-[`webgpu`](https://github.com/dawn-gpu/node-webgpu) npm package.
+it('has a real GPU device', async () => {
+  const adapter = await navigator.gpu.requestAdapter();
+  const device = await adapter!.requestDevice();
+  const buffer = device.createBuffer({ size: 16, usage: GPUBufferUsage.COPY_DST });
+  expect(buffer.size).toBe(16);
+});
+```
 
 The environment puts `navigator.gpu` and every `GPU*` class and constant (`GPUBufferUsage`,
 `GPUShaderStage`, ...) on the global object before each test file and removes them afterwards.
 
 Using Jest instead? See the equivalent
 [`jest-environment-webgpu-node`](https://github.com/bhouston/jest-gpu/tree/main/packages/jest-environment-webgpu-node)
-in [jest-gpu](https://github.com/bhouston/jest-gpu).
+in [jest-gpu](https://github.com/bhouston/jest-gpu), documented at [jest-gpu.ben3d.ca](https://jest-gpu.ben3d.ca/).
 
-## Install
+## Compared to alternatives
 
-```sh
-pnpm add -D vitest vitest-environment-webgpu-node
-```
+WebGPU has no mock equivalent of a canvas stub that runs shaders, so the realistic options are a browser or
+Dawn in Node.
+
+| Approach                          | Real rendering | Notes                                                                                                         |
+| --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
+| Hand-written `navigator.gpu` mock | No             | You can assert calls, not shader output or readbacks.                                                         |
+| Vitest browser mode or Playwright | Yes            | A real browser with WebGPU enabled: heavier to install and slower to start; right when you need browser APIs. |
+| vitest-environment-webgpu-node    | Yes            | Dawn in the Node process (Metal, Vulkan, D3D12 and others via `dawnOptions`). Not a browser.                  |
+
+## Supported versions and platforms
+
+- Vitest 4 and 5 (CI tests both). Vitest 3 is not supported.
+- Node 22 or later. CI runs Node 22 and 26 on `macos-latest`, `ubuntu-latest` and `windows-latest`.
+- Type checking needs TypeScript 6 or later (see [TypeScript types](#typescript-types)).
+- Linux without a GPU needs Mesa's software Vulkan driver, see [Linux and CI](#linux-and-ci).
+
+## Useful for
 
-Requires Vitest 4 or 5 (Vitest 3 is not supported). Type checking needs TypeScript 6 or later (see [TypeScript types](#typescript-types)).
+three.js `WebGPURenderer`, Babylon Lite, Vercel's vgpu and raw WebGPU compute or render code. The demos exercise
+those three; other WebGPU libraries such as TypeGPU or luma.gl use the same API but are not covered by this
+repo's tests. These are compatible use cases, not endorsements.
 
 ## Usage
 
@@ -77,7 +130,7 @@ sudo apt-get update && sudo apt-get install -y libegl1 libgles2 libgl1-mesa-dri
 export LIBGL_ALWAYS_SOFTWARE=1
 ```
 
-This repo's own [CI workflow](../../.github/workflows/ci.yml) does exactly this, so WebGPU tests run
+This repo's own [CI workflow](https://github.com/bhouston/vitest-gpu/blob/main/.github/workflows/ci.yml) does exactly this, so WebGPU tests run
 for real (not mocked) on `ubuntu-latest` on every PR. macOS runners use Dawn's Metal backend and need no
 extra setup.
 
@@ -100,24 +153,36 @@ await expect(canvas).toMatchScreenshot('scene.png');
 ```
 
 `readPixels()` returns `{ width, height, data }` RGBA8 pixels, ready for
-[`vitest-screenshot`](../vitest-screenshot). Readback supports `rgba8unorm`, `rgba8unorm-srgb`,
+[`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot). Readback supports `rgba8unorm`, `rgba8unorm-srgb`,
 `bgra8unorm`, and `bgra8unorm-srgb`; other canvas formats remain valid for rendering but
 `readPixels()` rejects them with an unsupported-format error. `asElement()` returns the same object and
 defaults to `HTMLCanvasElement` when DOM types are available. You can also request a library-specific type
 explicitly with `canvas.asElement<HTMLCanvasElement>()`.
 
-## Author
+## Image snapshots
+
+`await expect(canvas).toMatchScreenshot('scene.png')` comes from [`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot).
+Call `extendMatchers()` from it once, then pass the canvas as in the example above.
+
+## See also
+
+- [`vitest-environment-webgl-node`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-environment-webgl-node) for headless WebGL.
+- [`vitest-screenshot`](https://github.com/bhouston/vitest-gpu/tree/main/packages/vitest-screenshot) for `toMatchScreenshot()`.
+- [`demo/`](https://github.com/bhouston/vitest-gpu/tree/main/demo/test/webgpu) for device, upload, readback, triangle, three.js, Babylon Lite and vgpu tests,
+  and the [repository README](https://github.com/bhouston/vitest-gpu#readme).
+
+## Resource cleanup
 
-Created by [Ben Houston](https://ben3d.ca) and sponsored by [Land of Assets](https://landofassets.com).
+Environment teardown destroys devices requested through its `navigator.gpu` and cancels pending callbacks scheduled through its animation-frame shim. Device requests that finish after teardown are destroyed and rejected. Devices created through another GPU instance remain the caller's responsibility. Keep disposing renderers, buffers, textures and devices during long-running files to release resources sooner.
+
+## Contribution
+
+See [Contributing Guide](https://github.com/bhouston/vitest-gpu/blob/main/CONTRIBUTING.md).
 
 ## License
 
 MIT
 
-[npm-badge]: https://img.shields.io/npm/v/vitest-environment-webgpu-node.svg
-[npm-url]: https://www.npmjs.com/package/vitest-environment-webgpu-node
-[downloads-badge]: https://img.shields.io/npm/dm/vitest-environment-webgpu-node.svg
-[tests-badge]: https://github.com/bhouston/vitest-gpu/actions/workflows/ci.yml/badge.svg
-[tests-url]: https://github.com/bhouston/vitest-gpu/actions/workflows/ci.yml
-[discord-badge]: https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white
-[discord-url]: https://discord.gg/fwupDN493R
+## Author
+
+[Ben Houston](https://ben3d.ca), Sponsored by [Land of Assets](https://landofassets.com).

package/dist/canvas.d.ts

@@ -1,7 +1,10 @@
 /** RGBA8 pixels, top row first. Feed it to `vitest-screenshot`'s `toMatchScreenshot`. */
 export type RgbaImage = {
+    /** Width in pixels. */
     width: number;
+    /** Height in pixels. */
     height: number;
+    /** RGBA8 bytes, four per pixel, row by row from the top. */
     data: Uint8Array;
 };
 type DefaultCanvasElement = typeof globalThis extends {
@@ -12,11 +15,30 @@ type DefaultCanvasElement = typeof globalThis extends {
 /** Minimal `GPUCanvasContext`: `getCurrentTexture()` is a texture the size of the canvas, kept until reconfigured or resized. */
 export declare class HeadlessCanvasContext {
     #private;
+    /** The canvas this context belongs to. */
     readonly canvas: HeadlessCanvas;
-    constructor(canvas: HeadlessCanvas);
+    /**
+     * Creates the context for a canvas. Canvases create their own; you rarely call this.
+     *
+     * @param canvas - The canvas whose size this context's texture follows.
+     */
+    constructor(
+    /** The canvas this context belongs to. */
+    canvas: HeadlessCanvas);
+    /**
+     * Stores the configuration and discards any texture created under the previous one, as `GPUCanvasContext.configure()` does.
+     *
+     * @param config - Device, format and usage for the canvas texture.
+     */
     configure(config: GPUCanvasConfiguration): void;
+    /** Clears the configuration and discards the current texture. */
     unconfigure(): void;
+    /** The configuration passed to `configure()`, or `null` before it is called or after `unconfigure()`. */
     getConfiguration(): GPUCanvasConfiguration | null;
+    /**
+     * The texture the canvas renders into. It is created on first use at the canvas size and reused until the context
+     * is reconfigured or the canvas is resized. Throws if `configure()` has not been called.
+     */
     getCurrentTexture(): GPUTexture;
     /** Copies the current texture to the CPU. BGRA formats are swizzled to RGBA. */
     readPixels(): Promise<RgbaImage>;
@@ -24,31 +46,92 @@ export declare class HeadlessCanvasContext {
 /** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
 export declare class HeadlessCanvas {
     #private;
+    /** Canvas width in pixels. */
     width: number;
+    /** Canvas height in pixels. */
     height: number;
+    /** A plain object libraries can write CSS properties to; it has no effect on rendering. */
     readonly style: Record<string, string>;
-    constructor(width?: number, height?: number);
+    /**
+     * Creates a canvas of the given size. {@link createCanvas} is the usual entry point.
+     *
+     * @param width - Canvas width in pixels.
+     * @param height - Canvas height in pixels.
+     */
+    constructor(
+    /** Canvas width in pixels. */
+    width?: number, 
+    /** Canvas height in pixels. */
+    height?: number);
+    /** Same as `width`; there is no layout in Node. */
     get clientWidth(): number;
+    /** Same as `height`; there is no layout in Node. */
     get clientHeight(): number;
+    /**
+     * Returns the canvas's `GPUCanvasContext` for `'webgpu'`.
+     *
+     * @param id - The context type. Only `'webgpu'` is supported.
+     * @returns The context for `'webgpu'`, or `null` for any other type.
+     */
     getContext(id: 'webgpu'): HeadlessCanvasContext;
+    /**
+     * Returns the canvas's `GPUCanvasContext` for `'webgpu'`.
+     *
+     * @param id - The context type. Only `'webgpu'` is supported.
+     * @returns The context for `'webgpu'`, or `null` for any other type.
+     */
     getContext(id: string): HeadlessCanvasContext | null;
+    /** Reads the current texture back as RGBA8 pixels; see {@link HeadlessCanvasContext.readPixels}. */
     readPixels(): Promise<RgbaImage>;
-    /** This same object, cast to the element type a rendering library expects. */
+    /**
+     * This same object, cast to the element type a rendering library expects.
+     *
+     * @typeParam TElement - The element type to cast to. Defaults to `HTMLCanvasElement` when DOM types are available.
+     */
     asElement<TElement = DefaultCanvasElement>(): TElement;
+    /** A rectangle at the origin with the canvas's width and height. */
     getBoundingClientRect(): {
+        /** Always 0. */
         x: number;
+        /** Always 0. */
         y: number;
+        /** The canvas width. */
         width: number;
+        /** The canvas height. */
         height: number;
+        /** Always 0. */
         top: number;
+        /** Always 0. */
         left: number;
     };
+    /**
+     * Stores an attribute on the canvas.
+     *
+     * @param name - Attribute name.
+     * @param value - Attribute value.
+     */
     setAttribute(name: string, value: string): void;
+    /**
+     * Reads an attribute stored with `setAttribute()`.
+     *
+     * @param name - Attribute name.
+     * @returns The stored value, or `null` if none was set.
+     */
     getAttribute(name: string): string | null;
+    /** Does nothing; present so libraries that register listeners keep working. */
     addEventListener(): void;
+    /** Does nothing; present so libraries that remove listeners keep working. */
     removeEventListener(): void;
+    /** Does nothing and returns `true`. */
     dispatchEvent(): boolean;
 }
+/**
+ * Creates a headless canvas for WebGPU tests.
+ *
+ * @param width - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ * @returns A {@link HeadlessCanvas}; pass `canvas.asElement()` to libraries that expect an `HTMLCanvasElement`.
+ */
 export declare const createCanvas: (width: number, height: number) => HeadlessCanvas;
 export {};
 //# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAE5E,KAAK,oBAAoB,GAAG,OAAO,UAAU,SAAS;IACpD,iBAAiB,EAAE;QAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;KAAE,CAAC;CAClD,GACG,QAAQ,GACR,cAAc,CAAC;AAanB,iIAAiI;AACjI,qBAAa,qBAAqB;;IAIpB,QAAQ,CAAC,MAAM,EAAE,cAAc;IAA3C,YAAqB,MAAM,EAAE,cAAc,EAAI;IAE/C,SAAS,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAG9C;IAED,WAAW,IAAI,IAAI,CAGlB;IAED,gBAAgB,IAAI,sBAAsB,GAAG,IAAI,CAEhD;IAED,iBAAiB,IAAI,UAAU,CAY9B;IAED,gFAAgF;IAC1E,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAmCrC;CAMF;AAED,6FAA6F;AAC7F,qBAAa,cAAc;;IAMhB,KAAK;IACL,MAAM;IALf,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAG5C,YACS,KAAK,SAAM,EACX,MAAM,SAAM,EACjB;IAEJ,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,qBAAqB,CAAC;IAChD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAAC;IAKrD,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAE/B;IAED,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,GAAG,oBAAoB,KAAK,QAAQ,CAErD;IAED,qBAAqB,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAE1G;IAED,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;IAED,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExC;IAED,gBAAgB,IAAI,IAAI,CAAG;IAC3B,mBAAmB,IAAI,IAAI,CAAG;IAC9B,aAAa,IAAI,OAAO,CAEvB;CACF;AAED,eAAO,MAAM,YAAY,UAAW,MAAM,UAAU,MAAM,KAAG,cAAmD,CAAC"}
+{"version":3,"file":"canvas.d.ts","sources":["../src/canvas.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG;IACtB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEF,KAAK,oBAAoB,GAAG,OAAO,UAAU,SAAS;IACpD,iBAAiB,EAAE;QAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;KAAE,CAAC;CAClD,GACG,QAAQ,GACR,cAAc,CAAC;AAanB,iIAAiI;AACjI,qBAAa,qBAAqB;;IAU9B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,cAAc;IAPjC;;;;OAIG;IACH;IACE,0CAA0C;IACjC,MAAM,EAAE,cAAc,EAC7B;IAEJ;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAG9C;IAED,iEAAiE;IACjE,WAAW,IAAI,IAAI,CAGlB;IAED,yGAAyG;IACzG,gBAAgB,IAAI,sBAAsB,GAAG,IAAI,CAEhD;IAED;;;OAGG;IACH,iBAAiB,IAAI,UAAU,CAY9B;IAED,gFAAgF;IAC1E,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAmCrC;CAMF;AAED,6FAA6F;AAC7F,qBAAa,cAAc;;IAavB,8BAA8B;IACvB,KAAK;IACZ,+BAA+B;IACxB,MAAM;IAdf,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAG5C;;;;;OAKG;IACH;IACE,8BAA8B;IACvB,KAAK,SAAM;IAClB,+BAA+B;IACxB,MAAM,SAAM,EACjB;IAEJ,mDAAmD;IACnD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,oDAAoD;IACpD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,qBAAqB,CAAC;IAChD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAAC;IAKrD,oGAAoG;IACpG,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAE/B;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAQ,GAAG,oBAAoB,KAAK,QAAQ,CAErD;IAED,oEAAoE;IACpE,qBAAqB,IAAI;QACvB,gBAAgB;QAChB,CAAC,EAAE,MAAM,CAAC;QACV,gBAAgB;QAChB,CAAC,EAAE,MAAM,CAAC;QACV,wBAAwB;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,yBAAyB;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,gBAAgB;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAEA;IAED;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;IAED;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExC;IAED,+EAA+E;IAC/E,gBAAgB,IAAI,IAAI,CAAG;IAC3B,6EAA6E;IAC7E,mBAAmB,IAAI,IAAI,CAAG;IAC9B,uCAAuC;IACvC,aAAa,IAAI,OAAO,CAEvB;CACF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,UAAW,MAAM,UAAU,MAAM,KAAG,cAAmD,CAAC"}

package/dist/canvas.js

@@ -13,20 +13,38 @@ export class HeadlessCanvasContext {
     canvas;
     #config;
     #texture;
-    constructor(canvas) {
+    /**
+     * Creates the context for a canvas. Canvases create their own; you rarely call this.
+     *
+     * @param canvas - The canvas whose size this context's texture follows.
+     */
+    constructor(
+    /** The canvas this context belongs to. */
+    canvas) {
         this.canvas = canvas;
     }
+    /**
+     * Stores the configuration and discards any texture created under the previous one, as `GPUCanvasContext.configure()` does.
+     *
+     * @param config - Device, format and usage for the canvas texture.
+     */
     configure(config) {
         this.#config = config;
         this.#drop();
     }
+    /** Clears the configuration and discards the current texture. */
     unconfigure() {
         this.#config = undefined;
         this.#drop();
     }
+    /** The configuration passed to `configure()`, or `null` before it is called or after `unconfigure()`. */
     getConfiguration() {
         return this.#config ?? null;
     }
+    /**
+     * The texture the canvas renders into. It is created on first use at the canvas size and reused until the context
+     * is reconfigured or the canvas is resized. Throws if `configure()` has not been called.
+     */
     getCurrentTexture() {
         const config = this.#config;
         if (!config)
@@ -92,42 +110,83 @@ export class HeadlessCanvas {
     width;
     height;
     #context = new HeadlessCanvasContext(this);
+    /** A plain object libraries can write CSS properties to; it has no effect on rendering. */
     style = {};
     #attributes = new Map();
-    constructor(width = 300, height = 150) {
+    /**
+     * Creates a canvas of the given size. {@link createCanvas} is the usual entry point.
+     *
+     * @param width - Canvas width in pixels.
+     * @param height - Canvas height in pixels.
+     */
+    constructor(
+    /** Canvas width in pixels. */
+    width = 300, 
+    /** Canvas height in pixels. */
+    height = 150) {
         this.width = width;
         this.height = height;
     }
+    /** Same as `width`; there is no layout in Node. */
     get clientWidth() {
         return this.width;
     }
+    /** Same as `height`; there is no layout in Node. */
     get clientHeight() {
         return this.height;
     }
     getContext(id) {
         return id === 'webgpu' ? this.#context : null;
     }
+    /** Reads the current texture back as RGBA8 pixels; see {@link HeadlessCanvasContext.readPixels}. */
     readPixels() {
         return this.#context.readPixels();
     }
-    /** This same object, cast to the element type a rendering library expects. */
+    /**
+     * This same object, cast to the element type a rendering library expects.
+     *
+     * @typeParam TElement - The element type to cast to. Defaults to `HTMLCanvasElement` when DOM types are available.
+     */
     asElement() {
         return this;
     }
+    /** A rectangle at the origin with the canvas's width and height. */
     getBoundingClientRect() {
         return { x: 0, y: 0, top: 0, left: 0, width: this.width, height: this.height };
     }
+    /**
+     * Stores an attribute on the canvas.
+     *
+     * @param name - Attribute name.
+     * @param value - Attribute value.
+     */
     setAttribute(name, value) {
         this.#attributes.set(name, value);
     }
+    /**
+     * Reads an attribute stored with `setAttribute()`.
+     *
+     * @param name - Attribute name.
+     * @returns The stored value, or `null` if none was set.
+     */
     getAttribute(name) {
         return this.#attributes.get(name) ?? null;
     }
+    /** Does nothing; present so libraries that register listeners keep working. */
     addEventListener() { }
+    /** Does nothing; present so libraries that remove listeners keep working. */
     removeEventListener() { }
+    /** Does nothing and returns `true`. */
     dispatchEvent() {
         return true;
     }
 }
+/**
+ * Creates a headless canvas for WebGPU tests.
+ *
+ * @param width - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ * @returns A {@link HeadlessCanvas}; pass `canvas.asElement()` to libraries that expect an `HTMLCanvasElement`.
+ */
 export const createCanvas = (width, height) => new HeadlessCanvas(width, height);
 //# sourceMappingURL=canvas.js.map

package/dist/canvas.js.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.js","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canvas.js","sources":["../src/canvas.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,13 +4,33 @@ export type WebgpuNodeOptions = {
     /** Dawn options, e.g. `['backend=vulkan', 'enable-dawn-features=allow_unsafe_apis']`. */
     dawnOptions?: string[];
 };
+/**
+ * The Vitest environment registered as `webgpu-node`. Before each test file it puts `navigator.gpu`, the `GPU*`
+ * classes and constants, and minimal `window`, `document`, `HTMLCanvasElement` and `requestAnimationFrame` shims
+ * on the global object (only where missing), and it removes them afterwards.
+ */
 declare const _default: {
+    /** The name Vitest uses to select this environment: `test.environment: 'webgpu-node'`. */
     name: string;
+    /** Runs test files through Vite's `ssr` environment, as Node code. */
     viteEnvironment: "ssr";
+    /**
+     * Creates the Dawn-backed `navigator.gpu` and installs the DOM shims on the test file's global object.
+     *
+     * @param global - The global object of the test file's context.
+     * @param __namedParameters - The environment options from the Vitest config; `webgpuNode` holds {@link WebgpuNodeOptions}.
+     * @returns A `teardown` hook that destroys the devices this environment created and restores the globals.
+     */
     setup(global: Record<string, unknown>, { webgpuNode }: {
         webgpuNode?: WebgpuNodeOptions;
     }): {
-        teardown(_global?: Record<string, unknown>): void;
+        /**
+         * Destroys the GPU devices requested through this environment, cancels pending animation-frame callbacks and
+         * removes the globals that `setup` added.
+         *
+         * @param _global - Unused; teardown restores the global object it captured in `setup`.
+         */
+        teardown: (_global?: Record<string, unknown>) => void;
     };
 };
 export default _default;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAElG,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;;;;kBAyCc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAuB;QAAE,UAAU,CAAC,EAAE,iBAAiB,CAAA;KAAE;2BA8BvE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAElG,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAwDF;;;;GAIG;;IAED,0FAA0F;;IAE1F,sEAAsE;;IAEtE;;;;;;OAMG;kBACW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAuB;QAAE,UAAU,CAAC,EAAE,iBAAiB,CAAA;KAAE;QA6D1F;;;;;WAKG;6BACkB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;AA/ElD,wBA0FwB"}

package/dist/index.js

@@ -1,17 +1,38 @@
 import { create, globals } from 'webgpu';
 import { HeadlessCanvas } from './canvas.js';
 export { createCanvas, HeadlessCanvas, HeadlessCanvasContext } from './canvas.js';
-/** 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();
+/** Each environment owns its frame callbacks; unref alone does not release them. */
 const domShims = () => {
+    const frames = new Set();
+    let disposed = false;
+    const requestAnimationFrame = (callback) => {
+        if (disposed)
+            return 0;
+        const frame = setTimeout(() => {
+            frames.delete(frame);
+            callback(performance.now());
+        }, 16).unref();
+        frames.add(frame);
+        return frame;
+    };
+    const cancelAnimationFrame = (frame) => {
+        frames.delete(frame);
+        clearTimeout(frame);
+    };
+    const dispose = () => {
+        disposed = true;
+        for (const frame of frames)
+            clearTimeout(frame);
+        frames.clear();
+    };
     const window = {
         devicePixelRatio: 1,
         requestAnimationFrame,
-        cancelAnimationFrame: clearTimeout,
+        cancelAnimationFrame,
         addEventListener() { },
         removeEventListener() { },
     };
-    return {
+    const shims = {
         HTMLCanvasElement: HeadlessCanvas,
         document: {
             createElement: (tag) => (tag === 'canvas' ? new HeadlessCanvas() : {}),
@@ -22,8 +43,9 @@ const domShims = () => {
         window,
         self: window,
         requestAnimationFrame,
-        cancelAnimationFrame: clearTimeout,
+        cancelAnimationFrame,
     };
+    return { shims, dispose };
 };
 const restore = (properties) => {
     for (const { target, key, descriptor } of properties.toReversed()) {
@@ -33,11 +55,36 @@ const restore = (properties) => {
             Reflect.deleteProperty(target, key);
     }
 };
+/**
+ * The Vitest environment registered as `webgpu-node`. Before each test file it puts `navigator.gpu`, the `GPU*`
+ * classes and constants, and minimal `window`, `document`, `HTMLCanvasElement` and `requestAnimationFrame` shims
+ * on the global object (only where missing), and it removes them afterwards.
+ */
 export default {
+    /** The name Vitest uses to select this environment: `test.environment: 'webgpu-node'`. */
     name: 'webgpu-node',
+    /** Runs test files through Vite's `ssr` environment, as Node code. */
     viteEnvironment: 'ssr',
+    /**
+     * Creates the Dawn-backed `navigator.gpu` and installs the DOM shims on the test file's global object.
+     *
+     * @param global - The global object of the test file's context.
+     * @param __namedParameters - The environment options from the Vitest config; `webgpuNode` holds {@link WebgpuNodeOptions}.
+     * @returns A `teardown` hook that destroys the devices this environment created and restores the globals.
+     */
     setup(global, { webgpuNode = {} }) {
-        const shims = { ...globals, ...domShims() };
+        const dom = domShims();
+        // oxlint-disable-next-line typescript/no-misused-spread -- intentionally copies the own enumerable GPU* globals
+        const shims = { ...globals, ...dom.shims };
+        const devices = new Set();
+        let disposed = false;
+        const dispose = () => {
+            disposed = true;
+            dom.dispose();
+            for (const device of devices)
+                device.destroy();
+            devices.clear();
+        };
         const modified = [];
         try {
             for (const key of Object.keys(shims)) {
@@ -56,20 +103,57 @@ export default {
             }
             const navigator = global.navigator;
             modified.push({ target: navigator, key: 'gpu', descriptor: Object.getOwnPropertyDescriptor(navigator, 'gpu') });
+            const gpu = create(webgpuNode.dawnOptions ?? []);
+            const requestAdapter = gpu.requestAdapter.bind(gpu);
+            gpu.requestAdapter = async (options) => {
+                if (disposed)
+                    throw new Error('WebGPU environment has been torn down');
+                const adapter = await requestAdapter(options);
+                if (adapter) {
+                    const requestDevice = adapter.requestDevice.bind(adapter);
+                    adapter.requestDevice = async (descriptor) => {
+                        if (disposed)
+                            throw new Error('WebGPU environment has been torn down');
+                        const device = await requestDevice(descriptor);
+                        if (disposed) {
+                            device.destroy();
+                            throw new Error('WebGPU environment has been torn down');
+                        }
+                        devices.add(device);
+                        return device;
+                    };
+                }
+                return adapter;
+            };
             Object.defineProperty(navigator, 'gpu', {
-                value: create(webgpuNode.dawnOptions ?? []),
+                value: gpu,
                 writable: false,
                 enumerable: false,
                 configurable: true,
             });
         }
         catch (error) {
+            dispose();
             restore(modified);
             throw error;
         }
         return {
-            teardown(_global) {
-                restore(modified);
+            /**
+             * Destroys the GPU devices requested through this environment, cancels pending animation-frame callbacks and
+             * removes the globals that `setup` added.
+             *
+             * @param _global - Unused; teardown restores the global object it captured in `setup`.
+             */
+            teardown: (_global) => {
+                if (disposed)
+                    return;
+                try {
+                    dispose();
+                }
+                finally {
+                    restore(modified);
+                    modified.length = 0;
+                }
             },
         };
     },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "vitest-environment-webgpu-node",
-  "version": "3.0.0",
-  "description": "Vitest environment that provides real headless WebGPU (Dawn via the webgpu package) in Node",
+  "version": "3.0.2",
+  "description": "Vitest environment for real headless WebGPU tests in Node (Dawn via the webgpu package): no browser, Playwright or mocks",
   "keywords": [
+    "ci",
+    "compute-shader",
     "dawn",
+    "gpu",
+    "gpu-testing",
     "headless",
+    "node",
     "testing",
+    "three.js",
     "vitest",
     "vitest-environment",
-    "webgpu"
+    "webgpu",
+    "webgpu-testing",
+    "wgsl"
   ],
   "homepage": "https://github.com/bhouston/vitest-gpu#readme",
   "bugs": {
@@ -42,7 +50,10 @@
     "access": "public"
   },
   "dependencies": {
-    "webgpu": "^0.6.1"
+    "webgpu": "^0.6.2"
+  },
+  "devDependencies": {
+    "typescript": "7.1.0-beta"
   },
   "peerDependencies": {
     "typescript": ">=6",
@@ -57,7 +68,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc",
-    "tsc": "tsc"
+    "build": "tsc -p tsconfig.build.json",
+    "tsc": "tsc --noEmit"
   }
 }

package/src/canvas.ts

@@ -1,5 +1,12 @@
 /** RGBA8 pixels, top row first. Feed it to `vitest-screenshot`'s `toMatchScreenshot`. */
-export type RgbaImage = { width: number; height: number; data: Uint8Array };
+export type RgbaImage = {
+  /** Width in pixels. */
+  width: number;
+  /** Height in pixels. */
+  height: number;
+  /** RGBA8 bytes, four per pixel, row by row from the top. */
+  data: Uint8Array;
+};
 
 type DefaultCanvasElement = typeof globalThis extends {
   HTMLCanvasElement: { prototype: infer TElement };
@@ -23,22 +30,41 @@ export class HeadlessCanvasContext {
   #config: GPUCanvasConfiguration | undefined;
   #texture: GPUTexture | undefined;
 
-  constructor(readonly canvas: HeadlessCanvas) {}
+  /**
+   * Creates the context for a canvas. Canvases create their own; you rarely call this.
+   *
+   * @param canvas - The canvas whose size this context's texture follows.
+   */
+  constructor(
+    /** The canvas this context belongs to. */
+    readonly canvas: HeadlessCanvas,
+  ) {}
 
+  /**
+   * Stores the configuration and discards any texture created under the previous one, as `GPUCanvasContext.configure()` does.
+   *
+   * @param config - Device, format and usage for the canvas texture.
+   */
   configure(config: GPUCanvasConfiguration): void {
     this.#config = config;
     this.#drop();
   }
 
+  /** Clears the configuration and discards the current texture. */
   unconfigure(): void {
     this.#config = undefined;
     this.#drop();
   }
 
+  /** The configuration passed to `configure()`, or `null` before it is called or after `unconfigure()`. */
   getConfiguration(): GPUCanvasConfiguration | null {
     return this.#config ?? null;
   }
 
+  /**
+   * The texture the canvas renders into. It is created on first use at the canvas size and reused until the context
+   * is reconfigured or the canvas is resized. Throws if `configure()` has not been called.
+   */
   getCurrentTexture(): GPUTexture {
     const config = this.#config;
     if (!config) throw new Error('getCurrentTexture() called before configure()');
@@ -100,54 +126,118 @@ export class HeadlessCanvasContext {
 /** Enough of `HTMLCanvasElement` for three.js `WebGPURenderer`, Babylon Lite and friends. */
 export class HeadlessCanvas {
   readonly #context = new HeadlessCanvasContext(this);
+  /** A plain object libraries can write CSS properties to; it has no effect on rendering. */
   readonly style: Record<string, string> = {};
   readonly #attributes = new Map<string, string>();
 
+  /**
+   * Creates a canvas of the given size. {@link createCanvas} is the usual entry point.
+   *
+   * @param width - Canvas width in pixels.
+   * @param height - Canvas height in pixels.
+   */
   constructor(
+    /** Canvas width in pixels. */
     public width = 300,
+    /** Canvas height in pixels. */
     public height = 150,
   ) {}
 
+  /** Same as `width`; there is no layout in Node. */
   get clientWidth(): number {
     return this.width;
   }
 
+  /** Same as `height`; there is no layout in Node. */
   get clientHeight(): number {
     return this.height;
   }
 
+  /**
+   * Returns the canvas's `GPUCanvasContext` for `'webgpu'`.
+   *
+   * @param id - The context type. Only `'webgpu'` is supported.
+   * @returns The context for `'webgpu'`, or `null` for any other type.
+   */
   getContext(id: 'webgpu'): HeadlessCanvasContext;
+  /**
+   * Returns the canvas's `GPUCanvasContext` for `'webgpu'`.
+   *
+   * @param id - The context type. Only `'webgpu'` is supported.
+   * @returns The context for `'webgpu'`, or `null` for any other type.
+   */
   getContext(id: string): HeadlessCanvasContext | null;
   getContext(id: string): HeadlessCanvasContext | null {
     return id === 'webgpu' ? this.#context : null;
   }
 
+  /** Reads the current texture back as RGBA8 pixels; see {@link HeadlessCanvasContext.readPixels}. */
   readPixels(): Promise<RgbaImage> {
     return this.#context.readPixels();
   }
 
-  /** This same object, cast to the element type a rendering library expects. */
+  /**
+   * This same object, cast to the element type a rendering library expects.
+   *
+   * @typeParam TElement - The element type to cast to. Defaults to `HTMLCanvasElement` when DOM types are available.
+   */
   asElement<TElement = DefaultCanvasElement>(): TElement {
     return this as unknown as TElement;
   }
 
-  getBoundingClientRect(): { x: number; y: number; width: number; height: number; top: number; left: number } {
+  /** A rectangle at the origin with the canvas's width and height. */
+  getBoundingClientRect(): {
+    /** Always 0. */
+    x: number;
+    /** Always 0. */
+    y: number;
+    /** The canvas width. */
+    width: number;
+    /** The canvas height. */
+    height: number;
+    /** Always 0. */
+    top: number;
+    /** Always 0. */
+    left: number;
+  } {
     return { x: 0, y: 0, top: 0, left: 0, width: this.width, height: this.height };
   }
 
+  /**
+   * Stores an attribute on the canvas.
+   *
+   * @param name - Attribute name.
+   * @param value - Attribute value.
+   */
   setAttribute(name: string, value: string): void {
     this.#attributes.set(name, value);
   }
 
+  /**
+   * Reads an attribute stored with `setAttribute()`.
+   *
+   * @param name - Attribute name.
+   * @returns The stored value, or `null` if none was set.
+   */
   getAttribute(name: string): string | null {
     return this.#attributes.get(name) ?? null;
   }
 
+  /** Does nothing; present so libraries that register listeners keep working. */
   addEventListener(): void {}
+  /** Does nothing; present so libraries that remove listeners keep working. */
   removeEventListener(): void {}
+  /** Does nothing and returns `true`. */
   dispatchEvent(): boolean {
     return true;
   }
 }
 
+/**
+ * Creates a headless canvas for WebGPU tests.
+ *
+ * @param width - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ * @returns A {@link HeadlessCanvas}; pass `canvas.asElement()` to libraries that expect an `HTMLCanvasElement`.
+ */
 export const createCanvas = (width: number, height: number): HeadlessCanvas => new HeadlessCanvas(width, height);

package/src/index.ts

@@ -10,19 +10,36 @@ export type WebgpuNodeOptions = {
   dawnOptions?: string[];
 };
 
-/** Just enough DOM for libraries that make their own canvas and drive a frame loop. Only installed when missing. */
-const requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout =>
-  setTimeout(() => callback(performance.now()), 16).unref();
-
-const domShims = (): Record<string, unknown> => {
+/** Each environment owns its frame callbacks; unref alone does not release them. */
+const domShims = () => {
+  const frames = new Set<NodeJS.Timeout>();
+  let disposed = false;
+  const requestAnimationFrame = (callback: (time: number) => void): NodeJS.Timeout | number => {
+    if (disposed) return 0;
+    const frame = setTimeout(() => {
+      frames.delete(frame);
+      callback(performance.now());
+    }, 16).unref();
+    frames.add(frame);
+    return frame;
+  };
+  const cancelAnimationFrame = (frame: NodeJS.Timeout) => {
+    frames.delete(frame);
+    clearTimeout(frame);
+  };
+  const dispose = () => {
+    disposed = true;
+    for (const frame of frames) clearTimeout(frame);
+    frames.clear();
+  };
   const window = {
     devicePixelRatio: 1,
     requestAnimationFrame,
-    cancelAnimationFrame: clearTimeout,
+    cancelAnimationFrame,
     addEventListener() {},
     removeEventListener() {},
   };
-  return {
+  const shims = {
     HTMLCanvasElement: HeadlessCanvas,
     document: {
       createElement: (tag: string) => (tag === 'canvas' ? new HeadlessCanvas() : {}),
@@ -33,8 +50,9 @@ const domShims = (): Record<string, unknown> => {
     window,
     self: window,
     requestAnimationFrame,
-    cancelAnimationFrame: clearTimeout,
+    cancelAnimationFrame,
   };
+  return { shims, dispose };
 };
 
 type SavedProperty = { target: object; key: PropertyKey; descriptor?: PropertyDescriptor };
@@ -46,11 +64,35 @@ const restore = (properties: SavedProperty[]): void => {
   }
 };
 
+/**
+ * The Vitest environment registered as `webgpu-node`. Before each test file it puts `navigator.gpu`, the `GPU*`
+ * classes and constants, and minimal `window`, `document`, `HTMLCanvasElement` and `requestAnimationFrame` shims
+ * on the global object (only where missing), and it removes them afterwards.
+ */
 export default {
+  /** The name Vitest uses to select this environment: `test.environment: 'webgpu-node'`. */
   name: 'webgpu-node',
+  /** Runs test files through Vite's `ssr` environment, as Node code. */
   viteEnvironment: 'ssr',
+  /**
+   * Creates the Dawn-backed `navigator.gpu` and installs the DOM shims on the test file's global object.
+   *
+   * @param global - The global object of the test file's context.
+   * @param __namedParameters - The environment options from the Vitest config; `webgpuNode` holds {@link WebgpuNodeOptions}.
+   * @returns A `teardown` hook that destroys the devices this environment created and restores the globals.
+   */
   setup(global: Record<string, unknown>, { webgpuNode = {} }: { webgpuNode?: WebgpuNodeOptions }) {
-    const shims = { ...globals, ...domShims() } as Record<string, unknown>;
+    const dom = domShims();
+    // oxlint-disable-next-line typescript/no-misused-spread -- intentionally copies the own enumerable GPU* globals
+    const shims = { ...globals, ...dom.shims } as Record<string, unknown>;
+    const devices = new Set<GPUDevice>();
+    let disposed = false;
+    const dispose = () => {
+      disposed = true;
+      dom.dispose();
+      for (const device of devices) device.destroy();
+      devices.clear();
+    };
     const modified: SavedProperty[] = [];
     try {
       for (const key of Object.keys(shims)) {
@@ -68,19 +110,52 @@ export default {
       }
       const navigator = global.navigator as object;
       modified.push({ target: navigator, key: 'gpu', descriptor: Object.getOwnPropertyDescriptor(navigator, 'gpu') });
+      const gpu = create(webgpuNode.dawnOptions ?? []);
+      const requestAdapter = gpu.requestAdapter.bind(gpu);
+      gpu.requestAdapter = async (options) => {
+        if (disposed) throw new Error('WebGPU environment has been torn down');
+        const adapter = await requestAdapter(options);
+        if (adapter) {
+          const requestDevice = adapter.requestDevice.bind(adapter);
+          adapter.requestDevice = async (descriptor) => {
+            if (disposed) throw new Error('WebGPU environment has been torn down');
+            const device = await requestDevice(descriptor);
+            if (disposed) {
+              device.destroy();
+              throw new Error('WebGPU environment has been torn down');
+            }
+            devices.add(device);
+            return device;
+          };
+        }
+        return adapter;
+      };
       Object.defineProperty(navigator, 'gpu', {
-        value: create(webgpuNode.dawnOptions ?? []),
+        value: gpu,
         writable: false,
         enumerable: false,
         configurable: true,
       });
     } catch (error) {
+      dispose();
       restore(modified);
       throw error;
     }
     return {
-      teardown(_global?: Record<string, unknown>) {
-        restore(modified);
+      /**
+       * Destroys the GPU devices requested through this environment, cancels pending animation-frame callbacks and
+       * removes the globals that `setup` added.
+       *
+       * @param _global - Unused; teardown restores the global object it captured in `setup`.
+       */
+      teardown: (_global?: Record<string, unknown>) => {
+        if (disposed) return;
+        try {
+          dispose();
+        } finally {
+          restore(modified);
+          modified.length = 0;
+        }
       },
     };
   },