vitest-environment-webgl-node 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,5 @@
-## [vitest-environment-webgl-node-v0.1.1](https://github.com/bhouston/vitest-gpu/compare/vitest-environment-webgl-node-v0.1.0...vitest-environment-webgl-node-v0.1.1) (2026-09-18)
+## [vitest-environment-webgl-node-v0.1.3](https://github.com/bhouston/vitest-gpu/compare/vitest-environment-webgl-node-v0.1.2...vitest-environment-webgl-node-v0.1.3) (2026-09-21)
 
 ### Bug Fixes
 
-* **test:** set testTimeout explicitly on every vitest project ([49858e1](https://github.com/bhouston/vitest-gpu/commit/49858e1e84916e0852add97075666ffeb82c0e7b)), closes [#8](https://github.com/bhouston/vitest-gpu/issues/8)
+* support public types across TypeScript versions ([0f3df06](https://github.com/bhouston/vitest-gpu/commit/0f3df067f28308e0154045304ecbcaf2ba840fcc)), closes [#24](https://github.com/bhouston/vitest-gpu/issues/24)

package/README.md

@@ -8,6 +8,10 @@ the `WebGL*` classes and a file-reading `fetch()` before each test file, and rem
 `document.createElement('canvas').getContext('webgl2')` returns a GPU-backed context, so three.js,
 regl, pixi and plain WebGL code run unchanged.
 
+Using Jest instead? See the equivalent
+[`jest-environment-webgl-node`](https://github.com/bhouston/jest-gpu/tree/main/packages/jest-environment-webgl-node)
+in [jest-gpu](https://github.com/bhouston/jest-gpu).
+
 ## Install
 
 ```sh
@@ -43,7 +47,19 @@ Options are those of node-webgl's `init()` (`backend`, `api`) and `installDOM()`
 (`baseDir`, `fetch`, `devicePixelRatio`, `innerWidth`, `innerHeight`, `frameInterval`).
 Pair with [`vitest-screenshot`](../vitest-screenshot) for pixel-diff assertions.
 
-Types for the installed globals: add `import 'vitest-environment-webgl-node/globals';` to a `.d.ts` file your tsconfig includes.
+For a Node-only TypeScript project, opt into types for the installed globals by adding
+`import 'vitest-environment-webgl-node/globals';` to a `.d.ts` file your tsconfig includes. Do not include
+this entry in projects that load TypeScript's DOM library: the real browser globals and node-webgl's shims
+intentionally have different types. DOM projects can use their standard global declarations and cast a
+node-webgl canvas at the library boundary when necessary.
 
 On Linux CI install Mesa (`apt-get install libegl1 libgles2 libgl1-mesa-dri`) and set
 `LIBGL_ALWAYS_SOFTWARE=1`. macOS and Windows use prebuilt binaries.
+
+## Author
+
+Created by [Ben Houston](https://ben3d.ca) and sponsored by [Land of Assets](https://landofassets.com).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,7 +1,15 @@
 import { type InitOptions, type InstallDOMOptions } from '@onirenaud/node-webgl';
-import type { Environment } from 'vitest/environments';
 /** Set under `test.environmentOptions.webglNode` in your Vitest config. */
 export type WebglNodeOptions = InitOptions & InstallDOMOptions;
-declare const _default: Environment;
+declare const _default: {
+    name: string;
+    transformMode: "ssr";
+    viteEnvironment: "ssr";
+    setup(global: typeof globalThis, { webglNode }: {
+        webglNode?: WebglNodeOptions;
+    }): {
+        teardown(g: Record<string, unknown>): void;
+    };
+};
 export default _default;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;wBAE/C,WAAW"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAMnG,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;;;;;kBAmF/C,OAAO,UAAU,iBAAsB;QAAE,SAAS,CAAC,EAAE,gBAAgB,CAAA;KAAE;oBA2BrE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}

package/dist/index.js

@@ -1,26 +1,117 @@
 import { init, installDOM } from '@onirenaud/node-webgl';
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const mimeTypes = {
+    '.basis': 'application/octet-stream',
+    '.bin': 'application/octet-stream',
+    '.drc': 'application/octet-stream',
+    '.exr': 'image/x-exr',
+    '.fbx': 'application/octet-stream',
+    '.gif': 'image/gif',
+    '.glb': 'model/gltf-binary',
+    '.gltf': 'model/gltf+json',
+    '.hdr': 'image/vnd.radiance',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.ktx': 'image/ktx',
+    '.ktx2': 'image/ktx2',
+    '.mjs': 'text/javascript',
+    '.mtl': 'text/plain',
+    '.obj': 'text/plain',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.wasm': 'application/wasm',
+    '.webp': 'image/webp',
+};
+const snapshot = (target) => new Map(Reflect.ownKeys(target).map((key) => [key, Object.getOwnPropertyDescriptor(target, key)]));
+const changedProperties = (before, target) => {
+    const changed = new Set();
+    for (const key of new Set([...before.keys(), ...Reflect.ownKeys(target)])) {
+        const previous = before.get(key);
+        const current = Object.getOwnPropertyDescriptor(target, key);
+        if (previous?.configurable !== current?.configurable ||
+            previous?.enumerable !== current?.enumerable ||
+            previous?.get !== current?.get ||
+            previous?.set !== current?.set ||
+            previous?.value !== current?.value ||
+            previous?.writable !== current?.writable) {
+            changed.add(key);
+        }
+    }
+    return changed;
+};
+const restore = (target, before, changed) => {
+    for (const key of changed) {
+        const descriptor = before.get(key);
+        if (descriptor)
+            Object.defineProperty(target, key, descriptor);
+        else
+            Reflect.deleteProperty(target, key);
+    }
+};
+const installFetch = (global, baseDir) => {
+    const originalFetch = global.fetch;
+    const localFetch = async (input, requestInit) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        if (/^(https?|data|blob):/i.test(url))
+            return originalFetch(input, requestInit);
+        const path = url.startsWith('file:') ? fileURLToPath(url) : resolve(baseDir, url.replace(/[?#].*$/, ''));
+        try {
+            const bytes = await readFile(path);
+            return new Response(bytes, {
+                status: 200,
+                headers: { 'content-type': mimeTypes[extname(path).toLowerCase()] ?? 'application/octet-stream' },
+            });
+        }
+        catch {
+            return new Response(null, { status: 404, statusText: 'Not Found' });
+        }
+    };
+    Object.defineProperty(global, 'fetch', { value: localFetch, writable: true, configurable: true });
+};
 export default {
     name: 'webgl-node',
+    transformMode: 'ssr',
     viteEnvironment: 'ssr',
     setup(global, { webglNode = {} }) {
         const { backend, api, ...dom } = webglNode;
         if (backend || api)
             init({ backend, api });
-        const before = new Set(Object.getOwnPropertyNames(global));
-        installDOM(dom);
-        // node-webgl's window/document have no event methods; engines like Babylon.js register resize/blur listeners.
-        const { window, document } = global;
-        for (const target of [window, document]) {
-            if (!target)
-                continue;
-            target.addEventListener ??= () => { };
-            target.removeEventListener ??= () => { };
+        const before = snapshot(global);
+        const nested = [];
+        try {
+            // node-webgl remembers fetch installation at module scope, which cannot represent separate Vitest environments.
+            installDOM({ ...dom, fetch: false });
+            if (dom.fetch !== false)
+                installFetch(global, dom.baseDir ?? process.cwd());
+            // node-webgl's window/document have no event methods; engines like Babylon.js register resize/blur listeners.
+            const { window, document } = global;
+            for (const target of [window, document]) {
+                if (!target)
+                    continue;
+                const targetBefore = snapshot(target);
+                nested.push({ target, before: targetBefore });
+                target.addEventListener ??= () => { };
+                target.removeEventListener ??= () => { };
+                nested.at(-1).changed = changedProperties(targetBefore, target);
+            }
+        }
+        catch (error) {
+            for (const item of nested.toReversed())
+                restore(item.target, item.before, item.changed ?? changedProperties(item.before, item.target));
+            restore(global, before, changedProperties(before, global));
+            throw error;
         }
-        const added = Object.getOwnPropertyNames(global).filter((key) => !before.has(key));
+        const changed = changedProperties(before, global);
         return {
             teardown(g) {
-                for (const key of added)
-                    delete g[key];
+                for (const item of nested.toReversed())
+                    restore(item.target, item.before, item.changed);
+                restore(g, before, changed);
             },
         };
     },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAA4C,MAAM,uBAAuB,CAAC;AAMnG,eAA4B;IAC1B,IAAI,EAAE,YAAY;IAClB,eAAe,EAAE,KAAK;IACtB,KAAK,CAAC,MAAyB,EAAE,EAAE,SAAS,GAAG,EAAE,EAAoC;QACnF,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,GAAG,SAAS,CAAC;QAC3C,IAAI,OAAO,IAAI,GAAG;YAAE,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,UAAU,CAAC,GAAG,CAAC,CAAC;QAChB,8GAA8G;QAC9G,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAA4D,CAAC;QAC1F,KAAK,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,MAAM,CAAC,gBAAgB,KAAK,GAAG,EAAE,GAAE,CAAC,CAAC;YACrC,MAAM,CAAC,mBAAmB,KAAK,GAAG,EAAE,GAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACnF,OAAO;YACL,QAAQ,CAAC,CAA0B;gBACjC,KAAK,MAAM,GAAG,IAAI,KAAK;oBAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-environment-webgl-node",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Vitest environment that provides real headless WebGL 1/2 (ANGLE via @onirenaud/node-webgl) in Node",
   "keywords": [
     "headless",
@@ -28,6 +28,8 @@
     "dist/**/*.js.map",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
     "CHANGELOG.md"
   ],
   "type": "module",

package/src/index.ts

@@ -0,0 +1,124 @@
+import { init, installDOM, type InitOptions, type InstallDOMOptions } from '@onirenaud/node-webgl';
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Environment } from 'vitest/environments';
+
+/** Set under `test.environmentOptions.webglNode` in your Vitest config. */
+export type WebglNodeOptions = InitOptions & InstallDOMOptions;
+
+const mimeTypes: Record<string, string> = {
+  '.basis': 'application/octet-stream',
+  '.bin': 'application/octet-stream',
+  '.drc': 'application/octet-stream',
+  '.exr': 'image/x-exr',
+  '.fbx': 'application/octet-stream',
+  '.gif': 'image/gif',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.hdr': 'image/vnd.radiance',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.ktx': 'image/ktx',
+  '.ktx2': 'image/ktx2',
+  '.mjs': 'text/javascript',
+  '.mtl': 'text/plain',
+  '.obj': 'text/plain',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain',
+  '.wasm': 'application/wasm',
+  '.webp': 'image/webp',
+};
+
+type PropertySnapshot = Map<PropertyKey, PropertyDescriptor>;
+
+const snapshot = (target: object): PropertySnapshot =>
+  new Map(Reflect.ownKeys(target).map((key) => [key, Object.getOwnPropertyDescriptor(target, key)!]));
+
+const changedProperties = (before: PropertySnapshot, target: object): Set<PropertyKey> => {
+  const changed = new Set<PropertyKey>();
+  for (const key of new Set([...before.keys(), ...Reflect.ownKeys(target)])) {
+    const previous = before.get(key);
+    const current = Object.getOwnPropertyDescriptor(target, key);
+    if (
+      previous?.configurable !== current?.configurable ||
+      previous?.enumerable !== current?.enumerable ||
+      previous?.get !== current?.get ||
+      previous?.set !== current?.set ||
+      previous?.value !== current?.value ||
+      previous?.writable !== current?.writable
+    ) {
+      changed.add(key);
+    }
+  }
+  return changed;
+};
+
+const restore = (target: object, before: PropertySnapshot, changed: Iterable<PropertyKey>): void => {
+  for (const key of changed) {
+    const descriptor = before.get(key);
+    if (descriptor) Object.defineProperty(target, key, descriptor);
+    else Reflect.deleteProperty(target, key);
+  }
+};
+
+const installFetch = (global: typeof globalThis, baseDir: string): void => {
+  const originalFetch = global.fetch;
+  const localFetch = async (input: string | URL | Request, requestInit?: RequestInit): Promise<Response> => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    if (/^(https?|data|blob):/i.test(url)) return originalFetch(input, requestInit);
+    const path = url.startsWith('file:') ? fileURLToPath(url) : resolve(baseDir, url.replace(/[?#].*$/, ''));
+    try {
+      const bytes = await readFile(path);
+      return new Response(bytes, {
+        status: 200,
+        headers: { 'content-type': mimeTypes[extname(path).toLowerCase()] ?? 'application/octet-stream' },
+      });
+    } catch {
+      return new Response(null, { status: 404, statusText: 'Not Found' });
+    }
+  };
+  Object.defineProperty(global, 'fetch', { value: localFetch, writable: true, configurable: true });
+};
+
+export default {
+  name: 'webgl-node',
+  transformMode: 'ssr',
+  viteEnvironment: 'ssr',
+  setup(global: typeof globalThis, { webglNode = {} }: { webglNode?: WebglNodeOptions }) {
+    const { backend, api, ...dom } = webglNode;
+    if (backend || api) init({ backend, api });
+    const before = snapshot(global);
+    const nested: { target: object; before: PropertySnapshot; changed?: Set<PropertyKey> }[] = [];
+    try {
+      // node-webgl remembers fetch installation at module scope, which cannot represent separate Vitest environments.
+      installDOM({ ...dom, fetch: false });
+      if (dom.fetch !== false) installFetch(global, dom.baseDir ?? process.cwd());
+      // node-webgl's window/document have no event methods; engines like Babylon.js register resize/blur listeners.
+      const { window, document } = global as unknown as Record<string, Record<string, unknown>>;
+      for (const target of [window, document]) {
+        if (!target) continue;
+        const targetBefore = snapshot(target);
+        nested.push({ target, before: targetBefore });
+        target.addEventListener ??= () => {};
+        target.removeEventListener ??= () => {};
+        nested.at(-1)!.changed = changedProperties(targetBefore, target);
+      }
+    } catch (error) {
+      for (const item of nested.toReversed())
+        restore(item.target, item.before, item.changed ?? changedProperties(item.before, item.target));
+      restore(global, before, changedProperties(before, global));
+      throw error;
+    }
+    const changed = changedProperties(before, global);
+    return {
+      teardown(g: Record<string, unknown>) {
+        for (const item of nested.toReversed()) restore(item.target, item.before, item.changed!);
+        restore(g, before, changed);
+      },
+    };
+  },
+} satisfies Environment;