@onting/browser 0.0.0-0 → 0.1.0-main.202606180757.8b506d4

package/dist/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,21 +1,33 @@
 {
   "name": "@onting/browser",
-  "version": "0.0.0-0",
+  "version": "0.1.0-main.202606180757.8b506d4",
   "description": "",
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "open": "./src/bin-open/index.ts"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "type": "module",
   "main": "./dist/browser.js",
   "typings": "./dist/browser.d.ts",
   "exports": {
-    ".": {
+    "./browser.js": {
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "./*.js",
-    "./dist/"
+    "./dist/",
+    "./src/bin-open/"
   ],
   "scripts": {
     "build": "tsup",
@@ -57,6 +69,7 @@
     "@tsconfig/recommended": "^1.0.13",
     "@tsconfig/strictest": "^2.0.8",
     "@types/node": "^25.9.3",
+    "@types/selenium-webdriver": "^4.35.6",
     "esbuild": "^0.28.1",
     "escape-string-regexp": "^5.0.0",
     "expect": "^30.4.1",
@@ -66,5 +79,15 @@
     "typescript": "^6.0.3"
   },
   "license": "MIT",
-  "pinDependencies": {}
+  "pinDependencies": {},
+  "dependencies": {
+    "@onting/browser": "^0.1.0-main.202606180757.8b506d4",
+    "@onting/rpc": "^0.1.0-main.202606142148.67b5d79",
+    "@onting/selenium-webdriver-message-port": "^0.2.0",
+    "@onting/stub": "^0.1.0-main.202606180715.1310683",
+    "commander": "^15.0.0",
+    "find-up": "^8.0.0",
+    "message-port-rpc": "^3.0.1",
+    "selenium-webdriver": "^4.45.0"
+  }
 }

package/src/bin-open/index.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+/// <reference types="node" />
+
+import { listen } from '@onting/rpc/server.js';
+import { viaBiDi } from '@onting/selenium-webdriver-message-port/host.js';
+import { program } from 'commander';
+import os from 'node:os';
+import { BrowsingContext, error as SeleniumWebDriverError } from 'selenium-webdriver';
+import getScriptManagerInstance from 'selenium-webdriver/bidi/scriptManager.js';
+import buildWebDriver from './private/buildWebDriver.ts';
+import createSequencer from './private/createSequencer.ts';
+import delta from './private/delta.ts';
+import isWSL2 from './private/isWSL2.ts';
+import shortenRealmId from './private/shortenRealmId.ts';
+
+program.name('@onting/browser').description('Run browser with RPC stub');
+
+program.arguments('[url]');
+
+program.option('--chrome', 'run Chrome/Chromium');
+program.option('--edge', 'run Edge');
+program.option('--firefox', 'run Firefox');
+program.option('--safari', 'run Safari');
+program.option('--stub <stub-package-or-path>', 'load stub from the package or path', '@onting/stub');
+program.option('--pipe', 'pipe WebDriver output to stdio');
+program.option('--wsl', 'run browser on Windows (if under WSL2)');
+
+program.parse(process.argv);
+
+const opts =
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  program.opts() satisfies {} as {
+    chrome: boolean | undefined;
+    edge: boolean | undefined;
+    firefox: boolean | undefined;
+    pipe: boolean | undefined;
+    safari: boolean | undefined;
+    stub: string;
+    wsl: boolean | undefined;
+  };
+
+let useWindowsBinary = !!opts.wsl;
+
+if (opts.wsl && !(await isWSL2())) {
+  console.warn('Not running under WSL2, ignoring --wsl.');
+
+  useWindowsBinary = false;
+} else if (os.platform() === 'win32') {
+  useWindowsBinary = true;
+}
+
+const webDriver = await buildWebDriver(
+  opts.edge ? 'edge' : opts.firefox ? 'firefox' : opts.safari ? 'safari' : 'chrome',
+  { pipeStdio: !!opts.pipe, useWindowsBinary }
+);
+
+// Patch WebSocket so to handle large amount of ScriptManager.
+const { socket } = await webDriver.getBidi();
+
+'setMaxListeners' in socket && typeof socket.setMaxListeners === 'function' && socket.setMaxListeners(100);
+
+type RealmInfo = {
+  readonly browsingContext: string;
+  readonly origin: string;
+  readonly realmId: string;
+  readonly realmType: string;
+};
+
+type ScriptManager = {
+  close(): Promise<void>;
+  getAllRealms(): Promise<readonly RealmInfo[]>;
+  onRealmCreated(callback: () => void): Promise<string>;
+  onRealmDestroyed(callback: () => void): Promise<string>;
+};
+
+type ActiveRealmContextReadWrite = {
+  messagePortPromise: Promise<MessagePort>;
+  realmInfo: RealmInfo;
+  scriptManagerPromise: Promise<ScriptManager>;
+
+  abort(): void;
+};
+
+type ActiveRealmContext = Readonly<ActiveRealmContextReadWrite>;
+
+async function attachRealm(realmInfo: RealmInfo): Promise<void> {
+  const { realmId } = realmInfo;
+
+  if (activeRealms.has(realmId)) {
+    throw new Error(`Realm "${realmId}" has already attached`);
+  }
+
+  console.log(
+    `[${shortenRealmId(realmId)}] Attach "${realmInfo.realmType}" realm of browsing context "${realmInfo.browsingContext}" at ${realmInfo.origin}`
+  );
+
+  const abortController = new AbortController();
+
+  const scriptManagerPromise = getScriptManagerInstance(
+    realmInfo.browsingContext,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    webDriver as any
+  ) as unknown as Promise<ScriptManager>;
+
+  const messagePortPromise = scriptManagerPromise
+    .then(scriptManager => {
+      if (abortController.signal.aborted) {
+        throw new Error('Aborted');
+      }
+
+      return viaBiDi(scriptManager, { realmId });
+    })
+    .then(({ messagePort }) => messagePort);
+
+  const entry: ActiveRealmContextReadWrite = {
+    abort: abortController.abort.bind(abortController),
+    messagePortPromise,
+    realmInfo,
+    // TODO: It seems `selenium-webdriver@4.44.0` is bugged.
+    //       If we use a shared `ScriptManager`, we will receive channel messages more than once.
+    //       It seems if `onMessage()` is called twice, `selenium-webdriver` will call every `onMessage()` twice as well (4 times in total).
+    scriptManagerPromise
+  };
+
+  activeRealms.set(realmId, entry);
+
+  const teardown = listen(
+    // Security risk: intentionally load code from user-supplied path.
+    (await import(opts.stub)).default,
+    {
+      browsingContext: await BrowsingContext(webDriver, { browsingContextId: realmInfo.browsingContext }),
+      webDriver
+    },
+    await entry.messagePortPromise
+  );
+
+  abortController.signal.addEventListener('abort', () => {
+    (async () => {
+      try {
+        (await entry.messagePortPromise).close();
+      } catch {}
+    })();
+
+    (async () => {
+      try {
+        (await entry.scriptManagerPromise).close();
+      } catch {}
+    })();
+
+    try {
+      teardown();
+    } catch {}
+  });
+}
+
+async function detachRealm(realmInfo: RealmInfo): Promise<void> {
+  const { realmId } = realmInfo;
+
+  const realmContext = activeRealms.get(realmId);
+
+  if (!realmContext) {
+    throw new Error(`Realm "${realmId}" has already detached`);
+  }
+
+  console.log(
+    `[${shortenRealmId(realmId)}] Detach "${realmInfo.realmType}" realm of browsing context "${realmInfo.browsingContext}" at ${realmInfo.origin}`
+  );
+
+  realmContext.abort();
+
+  activeRealms.delete(realmId);
+}
+
+async function reconcileRealms(): Promise<void> {
+  const realms = (await scriptManager.getAllRealms()) as readonly RealmInfo[];
+
+  const realmMap = new Map<string, RealmInfo>(realms.map(realm => [realm.realmId, realm]));
+
+  const [added, _, deleted] = delta<string>(new Set(realmMap.keys()), new Set(activeRealms.keys()));
+
+  for (const realmId of deleted.values()) {
+    await detachRealm(activeRealms.get(realmId)!.realmInfo);
+  }
+
+  for (const realmId of added.values()) {
+    await attachRealm(realmMap.get(realmId)!);
+  }
+}
+
+const activeRealms: Map<string, ActiveRealmContext> = new Map();
+
+// @types/selenium-webdriver@4.35.0 does not match selenium-webdriver@4.44.0
+const scriptManager = (await getScriptManagerInstance(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  webDriver as any
+)) as unknown as ScriptManager;
+
+const sequenceReconcileRealmsCall = createSequencer();
+
+const reconcileRealmsInSequence: typeof reconcileRealms = (...args) => {
+  return sequenceReconcileRealmsCall(async () => {
+    try {
+      return await reconcileRealms(...args);
+    } catch {}
+  });
+};
+
+await reconcileRealmsInSequence();
+
+await scriptManager.onRealmCreated(() => void reconcileRealmsInSequence());
+await scriptManager.onRealmDestroyed(() => void reconcileRealmsInSequence());
+
+const [url] = program.args;
+
+url && (await webDriver.navigate().to(url));
+
+for (;;) {
+  try {
+    // Detects when user closed the browser manually.
+    await webDriver.getAllWindowHandles();
+  } catch (error) {
+    if (error instanceof SeleniumWebDriverError.NoSuchSessionError) {
+      break;
+    }
+
+    throw error;
+  }
+
+  // WebDriver.getAllWindowHandles() is not event-driven, we need to call it once every second or so.
+  await new Promise(resolve => setTimeout(resolve, 1_000));
+}
+
+// We cannot use SIGINT to shutdown browsers automatically.
+// When WSL2 is running chromedriver.exe (on Windows):
+//
+// 1. SIGINT will terminate chromedriver.exe (on Windows) immediately, seems behavior from WSL2
+//    - Node.js seems intercepted SIGINT but chromedriver.exe is still being terminated
+// 2. Browser still open because chromedriver don't close child browser processes (probably detached)
+// 3. We lost chromedriver.exe and has no way to delete the session
+//
+// However, for Linux binary of chromedriver, it works. Maybe it is about how WSL2 terminate Windows-side child processes.
+
+console.log('Shutting down');
+
+try {
+  await scriptManager.close();
+} catch {}
+
+for (const realmContext of activeRealms.values()) {
+  realmContext.abort();
+}

package/src/bin-open/private/buildWebDriver.ts

@@ -0,0 +1,100 @@
+import { Browser, Builder } from 'selenium-webdriver';
+import { Options as ChromeOptions, ServiceBuilder as ChromeServiceBuilder } from 'selenium-webdriver/chrome.js';
+import { Options as EdgeOptions, ServiceBuilder as EdgeServiceBuilder } from 'selenium-webdriver/edge.js';
+import { Options as FirefoxOptions, ServiceBuilder as FirefoxServiceBuilder } from 'selenium-webdriver/firefox.js';
+import { Options as SafariOptions, ServiceBuilder as SafariServiceBuilder } from 'selenium-webdriver/safari.js';
+import findChromeDriverBin from './findChromeDriverBin.ts';
+import findEdgeDriverBin from './findEdgeDriverBin.ts';
+import findGeckoDriverBin from './findGeckoDriverBin.ts';
+import findHostIP from './findHostIP.ts';
+import findLocalIP from './findLocalIP.ts';
+import findSafariDriverBin from './findSafariDriverBin.ts';
+
+export default async function buildWebDriver(
+  browser: 'chrome' | 'edge' | 'firefox' | 'safari',
+  {
+    pipeStdio,
+    useWindowsBinary
+  }: {
+    readonly pipeStdio: boolean;
+    readonly useWindowsBinary: boolean;
+  }
+) {
+  const hostIP = useWindowsBinary ? await findHostIP() : '127.0.0.1';
+  const localIP = useWindowsBinary ? await findLocalIP() : '127.0.0.1';
+
+  switch (browser) {
+    case 'edge': {
+      const builder = new EdgeServiceBuilder(await findEdgeDriverBin({ windows: useWindowsBinary }))
+        // WSL2: Despite ChromeDriver hosted on same subnet, local IP must be explicitly allowed.
+        .addArguments('--allowed-ips', localIP)
+        .setHostname(hostIP);
+
+      pipeStdio && builder.setStdio([0, 1, 2]);
+
+      const options = new EdgeOptions();
+
+      options.enableBidi();
+
+      return await new Builder()
+        .forBrowser(Browser.EDGE)
+        .setEdgeOptions(options)
+        .usingServer(await builder.build().start())
+        .build();
+    }
+
+    case 'firefox': {
+      const builder = new FirefoxServiceBuilder(await findGeckoDriverBin({ windows: useWindowsBinary }))
+        // WSL2: Firefox currently has a bug that it does not use host for the `webSocketUrl`, https://github.com/mozilla/geckodriver/issues/2249.
+        .addArguments('--host', hostIP)
+        .setHostname(hostIP);
+
+      pipeStdio && builder.setStdio([0, 1, 2]);
+
+      const options = new FirefoxOptions();
+
+      options.enableBidi();
+
+      const serverURL = await builder.build().start();
+
+      return await new Builder().forBrowser(Browser.FIREFOX).setFirefoxOptions(options).usingServer(serverURL).build();
+    }
+
+    case 'safari': {
+      const builder = new SafariServiceBuilder(await findSafariDriverBin())
+        .addArguments('--host', hostIP)
+        .setHostname(hostIP);
+
+      pipeStdio && builder.setStdio([0, 1, 2]);
+
+      const options = new SafariOptions();
+
+      'enableBidi' in options && typeof options.enableBidi === 'function' && options.enableBidi();
+
+      const serverURL = await builder.build().start();
+
+      return await new Builder().forBrowser(Browser.SAFARI).setSafariOptions(options).usingServer(serverURL).build();
+    }
+
+    default: {
+      browser satisfies 'chrome';
+
+      const builder = new ChromeServiceBuilder(await findChromeDriverBin({ windows: useWindowsBinary }))
+        // WSL2: Despite ChromeDriver hosted on same subnet, local IP must be explicitly allowed.
+        .addArguments('--allowed-ips', localIP)
+        .setHostname(hostIP);
+
+      pipeStdio && builder.setStdio([0, 1, 2]);
+
+      const options = new ChromeOptions();
+
+      options.enableBidi();
+
+      return await new Builder()
+        .forBrowser(Browser.CHROME)
+        .setChromeOptions(options)
+        .usingServer(await builder.build().start())
+        .build();
+    }
+  }
+}

package/src/bin-open/private/createSequencer.ts

@@ -0,0 +1,46 @@
+type Fn<T = unknown> = () => Promise<T>;
+
+// We could use `p-queue` and set `{ concurrency: 1 }` but it has too many features and too big.
+
+/**
+ * Creates a sequencer which sequence function calls with concurrency of 1.
+ *
+ * @returns A function, when called, will queue the passing function into the sequencer.
+ */
+function createSequencer(): <T>(fn: Fn<T>) => Promise<T> {
+  const backlog: Fn<void>[] = [];
+  let isBusy = false;
+
+  async function kickoff() {
+    if (isBusy) {
+      return;
+    }
+
+    isBusy = true;
+
+    try {
+      let fn: Fn<void> | undefined;
+
+      while ((fn = backlog.shift())) {
+        await fn();
+      }
+    } finally {
+      isBusy = false;
+    }
+  }
+
+  return <T>(fn: Fn<T>): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+      backlog.push(async () => {
+        try {
+          resolve(await fn());
+        } catch (error) {
+          reject(error);
+        }
+      });
+
+      kickoff();
+    });
+}
+
+export default createSequencer;

package/src/bin-open/private/delta.ts

@@ -0,0 +1,13 @@
+export default function delta<T>(left: Set<T>, right: Set<T>): readonly [Set<T>, Set<T>, Set<T>] {
+  const common = left.intersection(right);
+  const leftOnly = left.difference(common);
+  const rightOnly = right.difference(common);
+
+  if (leftOnly.size + common.size !== left.size) {
+    throw new Error('Internal error: wrong leftOnly or common');
+  } else if (rightOnly.size + common.size !== right.size) {
+    throw new Error('Internal error: wrong rightOnly or common');
+  }
+
+  return Object.freeze([leftOnly, common, rightOnly]);
+}

package/src/bin-open/private/findChromeDriverBin.ts

@@ -0,0 +1,21 @@
+import { findUp } from 'find-up';
+
+async function findChromeDriverBin_({ windows }: { readonly windows?: boolean | undefined }): Promise<string> {
+  const path = windows
+    ? await findUp('chromedriver.exe')
+    : (await findUp('chromedriver')) || (await findUp('/usr/bin/chromedriver'));
+
+  if (!path) {
+    throw new Error('ChromeDriver is not found under the current path up to the root, please download ChromeDriver');
+  }
+
+  return path;
+}
+
+let findChromeDriverBinResult: Promise<string>;
+
+export default function findChromeDriverBin({
+  windows
+}: { readonly windows?: boolean | undefined } = {}): Promise<string> {
+  return findChromeDriverBinResult || (findChromeDriverBinResult = findChromeDriverBin_({ windows }));
+}

package/src/bin-open/private/findEdgeDriverBin.ts

@@ -0,0 +1,21 @@
+import { findUp } from 'find-up';
+
+async function findEdgeDriverBin_({ windows }: { readonly windows?: boolean | undefined }): Promise<string> {
+  const path = windows
+    ? await findUp('msedgedriver.exe')
+    : (await findUp('msedgedriver')) || (await findUp('/usr/bin/msedgedriver'));
+
+  if (!path) {
+    throw new Error('EdgeDriver is not found under the current path up to the root, please download EdgeDriver');
+  }
+
+  return path;
+}
+
+let findEdgeDriverBinResult: Promise<string>;
+
+export default function findEdgeDriverBin({
+  windows
+}: { readonly windows?: boolean | undefined } = {}): Promise<string> {
+  return findEdgeDriverBinResult || (findEdgeDriverBinResult = findEdgeDriverBin_({ windows }));
+}

package/src/bin-open/private/findGeckoDriverBin.ts

@@ -0,0 +1,21 @@
+import { findUp } from 'find-up';
+
+async function findGeckoDriverBin_({ windows }: { readonly windows?: boolean | undefined }): Promise<string> {
+  const path = windows
+    ? await findUp('geckodriver.exe')
+    : (await findUp('geckodriver')) || (await findUp('/usr/bin/geckodriver'));
+
+  if (!path) {
+    throw new Error('GeckoDriver is not found under the current path up to the root, please download GeckoDriver');
+  }
+
+  return path;
+}
+
+let findGeckoDriverBinResult: Promise<string>;
+
+export default function findGeckoDriverBin({
+  windows
+}: { readonly windows?: boolean | undefined } = {}): Promise<string> {
+  return findGeckoDriverBinResult || (findGeckoDriverBinResult = findGeckoDriverBin_({ windows }));
+}

package/src/bin-open/private/findHostIP.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+
+import { exec } from 'node:child_process';
+
+export default async function findHostIP(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec('ip route show default', (error, stdout) => {
+      if (error) {
+        return reject(error);
+      }
+
+      resolve(stdout.split(' ')?.[2] || '127.0.0.1');
+    });
+  });
+}

package/src/bin-open/private/findLocalIP.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+
+import { exec } from 'node:child_process';
+
+export default async function findLocalIP(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec('hostname -I', (error, stdout) => {
+      if (error) {
+        return reject(error);
+      }
+
+      resolve(stdout.split(' ')?.[0] || '127.0.0.1');
+    });
+  });
+}

package/src/bin-open/private/findSafariDriverBin.ts

@@ -0,0 +1,17 @@
+import { findUp } from 'find-up';
+
+async function findSafariDriverBin_(): Promise<string> {
+  const path = (await findUp('safaridriver')) || (await findUp('/usr/bin/safaridriver'));
+
+  if (!path) {
+    throw new Error('SafariDriver is not found under the current path up to the root, please download SafariDriver');
+  }
+
+  return path;
+}
+
+let findSafariDriverBinResult: Promise<string>;
+
+export default function findSafariDriverBin(): Promise<string> {
+  return findSafariDriverBinResult || (findSafariDriverBinResult = findSafariDriverBin_());
+}

package/src/bin-open/private/isWSL2.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+
+import { readFile } from 'node:fs/promises';
+
+// https://docs.microsoft.com/en-us/windows/wsl/compare-versions#accessing-windows-networking-apps-from-linux-host-ip
+async function isWSL2_(): Promise<boolean> {
+  try {
+    const procVersion = await readFile('/proc/version', 'utf-8');
+
+    return /WSL2/iu.test(procVersion);
+  } catch {
+    return false;
+  }
+}
+
+let promise: Promise<boolean>;
+
+export default function isWSL2(): Promise<boolean> {
+  return promise || (promise = isWSL2_());
+}

package/src/bin-open/private/shortenRealmId.ts

@@ -0,0 +1,7 @@
+export default function shortenRealmId(value: string): string {
+  if (value.length > 8) {
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+  }
+
+  return value;
+}

package/dist/browser.mjs

@@ -1,3 +0,0 @@
-// src/index.ts
-console.log("Hello, World!");
-//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["console.log('Hello, World!');\n"],"mappings":";AAAA,QAAQ,IAAI,eAAe;","names":[]}