From 54d84ff2e0cc4fac5b8fef00d37681ce08d2170a Mon Sep 17 00:00:00 2001
From: sunwen <1102633262@qq.com>
Date: Mon, 7 Sep 2026 15:24:27 +0800
Subject: [PATCH 01/32] feat: add browser environment builtin
---
doc/api/browser-env.md | 87 +++
doc/api/cli.md | 14 +
doc/api/index.md | 1 +
lib/browser-env.js | 9 +
lib/internal/browser_env.js | 798 +++++++++++++++++++++++++
lib/internal/process/pre_execution.js | 8 +
node.gyp | 1 +
src/node_binding.cc | 1 +
src/node_browser_env.cc | 148 +++++
src/node_external_reference.h | 1 +
src/node_options.cc | 4 +
src/node_options.h | 1 +
test/fixtures/browser-env/profile.json | 19 +
test/parallel/test-browser-env.js | 133 +++++
14 files changed, 1225 insertions(+)
create mode 100644 doc/api/browser-env.md
create mode 100644 lib/browser-env.js
create mode 100644 lib/internal/browser_env.js
create mode 100644 src/node_browser_env.cc
create mode 100644 test/fixtures/browser-env/profile.json
create mode 100644 test/parallel/test-browser-env.js
diff --git a/doc/api/browser-env.md b/doc/api/browser-env.md
new file mode 100644
index 000000000000..1eef339488c3
--- /dev/null
+++ b/doc/api/browser-env.md
@@ -0,0 +1,87 @@
+# Browser environment
+
+
+
+
+
+> Stability: 1 - Experimental
+
+
+
+The `node:browser-env` module installs a browser-compatible global environment
+in the current Realm. It provides a lightweight DOM tree, virtual navigation,
+profiled `navigator` and `screen` values, in-memory storage, and a native
+`document.all` implementation. It does not provide rendering, layout, Canvas,
+WebGL, real page navigation, or automatic execution of scripts in HTML.
+
+```cjs
+const { install } = require('node:browser-env');
+
+install({
+ url: 'https://example.test/page',
+ html: 'Hello',
+ navigator: { platform: 'Win32', languages: ['zh-CN', 'zh'] },
+ window: { properties: { customFlag: true } },
+ document: { properties: { visibilityState: 'hidden' } },
+});
+
+console.log(document.querySelector('#app').textContent);
+```
+
+```mjs
+import { install } from 'node:browser-env';
+
+install({ url: 'https://example.test/' });
+```
+
+## `browserEnv.install(options)`
+
+Installs the environment in the current Realm and returns
+`{ window, document, navigator, location }`. It must be called before loading
+code that reads browser globals. It throws if the Realm already has an
+installed browser environment.
+
+* `options` {Object}
+ * `url` {string} Required initial URL. `location.href` is also accepted for
+ JSON profile compatibility.
+ * `html` {string} Optional initial HTML. Scripts in this HTML are not run.
+ * `navigator` {Object} Optional overrides for browser identity fields such
+ as `userAgent`, `platform`, `language`, and `languages`.
+ * `screen` {Object} Optional screen-dimension overrides.
+ * `cookies` {string|Object} Optional initial in-memory cookies.
+ * `localStorage` {Object} Optional initial local storage values.
+ * `sessionStorage` {Object} Optional initial session storage values.
+ * `window.properties` {Object} Optional ordinary custom global properties.
+ * `window.descriptors` {Object} Optional custom property descriptors.
+ * `document.properties` {Object} Optional ordinary custom document
+ properties.
+ * `document.descriptors` {Object} Optional custom document property
+ descriptors.
+
+Core browser-environment properties, including `document.all`, DOM methods,
+`location`, `navigator`, and the `window` identity aliases cannot be replaced
+through `properties` or `descriptors`.
+
+## `browserEnv.isInstalled()`
+
+Returns `true` when `install()` or `--browser-env-profile` has installed the
+environment in the current Realm.
+
+## `--browser-env-profile=file`
+
+The command-line option loads the same `options` shape from a JSON file before
+user code executes:
+
+```json
+{
+ "url": "https://example.test/",
+ "html": "",
+ "navigator": { "platform": "Win32" }
+}
+```
+
+The CLI profile is applied independently in each Node Realm that starts with
+the option. Programmatic installation applies only to the Realm that calls
+`install()`.
diff --git a/doc/api/cli.md b/doc/api/cli.md
index 514af04c02cd..c8242adacd72 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -564,6 +564,18 @@ The following options are currently supported:
When using this flag, additional script files provided on the command line will
not be executed and instead be interpreted as regular command line arguments.
+### `--browser-env-profile=file`
+
+
+
+Install the browser-compatible environment described by the JSON profile before
+any user code is evaluated. The profile must contain a `url` string and can
+provide initial HTML, browser identity values, and custom `window` or
+`document` properties. See [`node:browser-env`][] for the supported profile
+shape and limitations.
+
### `-c`, `--check`
|<\/?([A-Za-z][\w:-]*)([^>]*)>|([^<]+)/g;
let match;
while ((match = tokenPattern.exec(source)) !== null) {
+ if (match[0].startsWith('