Fix ES usage in node (#5522)

* rename three.module.js to three.mjs

* make the imports works in node 22 with --experimental-require-module flag

* stop polyfilling process.browser and modify isBrowserEnvironment check

* make node test running

* alias super-three to three in package.json so it works on node

* window.THREE is set in index.js, no need to do it in lib/three.mjs

* we still need process polyfill for the browser tests

* update documentation about jsdom

* strip npm:super-three@ when showing the three version in console

* use a global INSPECTOR_VERSION variable instead of process.env.INSPECTOR_VERSION

* put back a comment about mocked process in isBrowserEnvironment

* use THREE.REVISION to log three version, when using aframe as ES module, three version may actually be different than the version defined in aframe dependencies

Author: vincentfretin

docs/core/globals.md

@@ -52,13 +52,14 @@ global. This same interface is also exposed if requiring with CommonJS
 
 ## Requiring `AFRAME` in a Node.js Environment
 
-It is possible to run A-Frame in [Node.js](https://nodejs.org/en/about) to get access to its globals. The only catch is we need to supply a browser `window` mock since Node.js lacks a `window` object. A-Frame is tested with [jsdom](https://github.com/jsdom/jsdom), although any JavaScript-based browser implementation should work.
+It is possible to run A-Frame in [Node.js](https://nodejs.org/en/about) to get access to its globals. The only catch is we need to supply a browser `window` mock since Node.js lacks a `window` object. You can do that with [jsdom-global](https://www.npmjs.com/package/jsdom-global), and you also need to mock `customElements`.
 
 ```js
-const jsdom = require("jsdom");
-global.window = new jsdom.JSDOM().window;
+const cleanup = require('jsdom-global')();
+global.customElements = { define: function () {} };
 var aframe = require('aframe/src');
 console.log(aframe.version);
+cleanup();
 ```
 
-Although A-Frame can load in Node.js, A-Frame isn't (yet) able to run any simulations at run time.
+You can't use jsdom to run tests with aframe components because `customElements` api is missing. A-Frame is using karma to open a real browser to run the tests.

package.json

@@ -24,7 +24,7 @@
     "test:firefox": "npm test -- --browsers Firefox",
     "test:chrome": "npm test -- --browsers Chrome",
     "test:nobrowser": "NO_BROWSER=true npm test",
-    "test:node": "mocha --ui tdd tests/node"
+    "test:node": "node --experimental-require-module ./node_modules/mocha/bin/mocha --ui tdd tests/node"
   },
   "repository": "aframevr/aframe",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "deep-assign": "^2.0.0",
     "load-bmfont": "^1.2.3",
     "super-animejs": "^3.1.0",
-    "super-three": "0.164.0",
+    "three": "npm:super-three@0.164.0",
     "three-bmfont-text": "dmarcos/three-bmfont-text#eed4878795be9b3e38cf6aec6b903f56acd1f695",
     "webvr-polyfill": "^0.10.12"
   },
@@ -60,7 +60,8 @@
     "git-rev": "^0.2.1",
     "glob": "^8.0.3",
     "husky": "^0.11.7",
-    "jsdom": "^20.0.0",
+    "jsdom": "^24.0.0",
+    "jsdom-global": "^3.0.2",
     "karma": "^6.4.0",
     "karma-chai-shallow-deep-equal": "0.0.4",
     "karma-chrome-launcher": "^3.1.1",

src/components/scene/inspector.js

@@ -1,4 +1,4 @@
-/* global AFRAME */
+/* global AFRAME, INSPECTOR_VERSION */
 var AFRAME_INJECTED = require('../../constants').AFRAME_INJECTED;
 var pkg = require('../../../package');
 var registerComponent = require('../../core/component').registerComponent;
@@ -16,7 +16,7 @@ function getFuzzyPatchVersion (version) {
 
 var INSPECTOR_DEV_URL = 'https://aframe.io/aframe-inspector/dist/aframe-inspector.js';
 var INSPECTOR_RELEASE_URL = 'https://unpkg.com/aframe-inspector@' + getFuzzyPatchVersion(pkg.version) + '/dist/aframe-inspector.min.js';
-var INSPECTOR_URL = process.env.INSPECTOR_VERSION === 'dev' ? INSPECTOR_DEV_URL : INSPECTOR_RELEASE_URL;
+var INSPECTOR_URL = typeof INSPECTOR_VERSION !== 'undefined' && INSPECTOR_VERSION === 'dev' ? INSPECTOR_DEV_URL : INSPECTOR_RELEASE_URL;
 var LOADING_MESSAGE = 'Loading Inspector';
 var LOADING_ERROR_MESSAGE = 'Error loading Inspector';
 

src/core/scene/a-scene.js

@@ -1,4 +1,4 @@
-/* global Promise, screen, CustomEvent */
+/* global Promise, customElements, screen, CustomEvent */
 var initMetaTags = require('./metaTags').inject;
 var initWakelock = require('./wakelock');
 var loadingScreen = require('./loadingScreen');
@@ -920,7 +920,7 @@ function constrainSizeTo (size, maxSize) {
   return size;
 }
 
-window.customElements.define('a-scene', AScene);
+customElements.define('a-scene', AScene);
 
 /**
  * Return the canvas size where the scene will be rendered.

src/index.js

@@ -80,7 +80,7 @@ require('./extras/primitives/');
 
 console.log('A-Frame Version: 1.5.0 (Date 2024-05-03, Commit #9fe641ce)');
 console.log('THREE Version (https://github.com/supermedium/three.js):',
-            pkg.dependencies['super-three']);
+            THREE.REVISION);
 console.log('WebVR Polyfill Version:', pkg.dependencies['webvr-polyfill']);
 
 // Wait for ready state, unless user asynchronously initializes A-Frame.

src/lib/three.js

@@ -1,4 +1,7 @@
-var THREE = require('./three.module.js').default;
+var THREE = require('./three.mjs').default;
+// TODO: Eventually include these only if they are needed by a component.
+global.THREE = THREE;
+require('../../vendor/DeviceOrientationControls');
 
 // In-memory caching for XHRs (for images, audio files, textures, etc.).
 if (THREE.Cache) {

src/lib/three.mjs

@@ -0,0 +1,21 @@
+import * as SUPER_THREE from 'three';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
+import { OBB } from 'three/addons/math/OBB.js';
+import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
+import { MTLLoader } from 'three/examples/jsm/loaders/MTLLoader.js';
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { LightProbeGenerator } from 'three/examples/jsm/lights/LightProbeGenerator.js';
+
+var THREE = { ...SUPER_THREE };
+THREE.DRACOLoader = DRACOLoader;
+THREE.GLTFLoader = GLTFLoader;
+THREE.KTX2Loader = KTX2Loader;
+THREE.OBJLoader = OBJLoader;
+THREE.MTLLoader = MTLLoader;
+THREE.OBB = OBB;
+THREE.BufferGeometryUtils = BufferGeometryUtils;
+THREE.LightProbeGenerator = LightProbeGenerator;
+
+export default THREE;

src/lib/three.module.js

@@ -1,4 +1,5 @@
 var debug = require('debug');
+var isBrowserEnvironment = require('./device').isBrowserEnvironment;
 
 var settings = {
   colors: {
@@ -114,6 +115,6 @@ if (ls && (parseInt(ls.logs, 10) || ls.logs === 'true')) {
   debug.enable('*:error,*:info,*:warn');
 }
 
-if (process.browser) { window.logs = debug; }
+if (isBrowserEnvironment) { window.logs = debug; }
 
 module.exports = debug;

src/utils/debug.js

@@ -200,9 +200,9 @@ module.exports.isLandscape = function () {
  * We need to check a node api that isn't mocked on either side.
  * `require` and `module.exports` are mocked in browser by bundlers.
  * `window` is mocked in node.
- * `process` is also mocked by browserify, but has custom properties.
+ * `process` is also mocked by webpack running with karma, but has custom properties like process.browser.
  */
-module.exports.isBrowserEnvironment = !!(!process || process.browser);
+module.exports.isBrowserEnvironment = typeof process === 'undefined' || process.browser === true;
 
 /**
  * Check if running in node on the server.