chrome-cdp-manager 1.2.2 → 1.2.6

package/README.md

@@ -49,6 +49,11 @@ chrome-cdp open https://example.com
 # Same, headless (no window/Dock/taskbar)
 chrome-cdp open https://example.com --headless
 
+# Route all traffic through a proxy (defaults to socks5://127.0.0.1:1080)
+chrome-cdp open https://example.com --proxy
+chrome-cdp open https://example.com --proxy socks5://127.0.0.1:9050
+chrome-cdp open https://example.com --proxy http://10.0.0.1:8080
+
 # Fetch a page's rendered HTML over CDP (headless by default)
 chrome-cdp html example.com -o page.html
 
@@ -108,6 +113,36 @@ Playwright over CDP, and returns `{ browser, context, page, config }`. In
 zero-install (npx) setups where Playwright can't be resolved automatically,
 inject it: `connect({ chromium })`.
 
+## Playwright CLI (`playwright-cli`)
+
+The package also installs a **`playwright-cli`** command that runs
+[Playwright's MCP CLI client](https://playwright.dev) against the ChromeCDP
+instance managed here. It's a thin wrapper that, before handing off, guarantees:
+
+1. A **headed** ChromeCDP browser is reachable over CDP. If one is **already
+   running on the port, it just attaches to it** (no relaunch); otherwise it
+   launches a fresh headed instance.
+2. The environment points Playwright at that browser instead of spawning its own:
+
+   ```bash
+   PLAYWRIGHT_MCP_CDP_ENDPOINT=http://localhost:9222   # from config (default 9222)
+   PLAYWRIGHT_MCP_ISOLATED=false
+   ```
+
+Everything after `playwright-cli` is forwarded verbatim to the Playwright CLI:
+
+```bash
+# Drive the attached browser
+playwright-cli goto https://example.com
+playwright-cli click "Sign in"
+
+# Help / version forward straight through (no browser launch)
+playwright-cli --help
+```
+
+Requires the optional `playwright` peer dependency (`npm i playwright`). The
+endpoint port follows your saved config (`~/.config/chrome-cdp-manager/config.json`).
+
 ## Common options
 
 | Option                  | Description                                                   |
@@ -117,6 +152,8 @@ inject it: `connect({ chromium })`.
 | `-b, --browser <name>`  | Browser: `chrome`, `edge`, `brave`, `chromium`, `vivaldi`, `opera`, `arc` |
 | `--path <path>`         | Explicit browser executable (overrides `--browser`)           |
 | `--target <path>`       | Launcher location (`.app` on macOS, `.lnk` on Windows)        |
+| `--proxy [server]`      | Route traffic through a proxy; omit the value for `socks5://127.0.0.1:1080`. Accepts a port (`1080`), `host:port`, or `scheme://host:port` (`socks5`, `socks4`, `http`, `https`) |
+| `--no-proxy`            | Disable any configured proxy for this run                     |
 | `-t, --timeout <secs>`  | Startup / load timeout (`open`, `html`)                       |
 
 `-c, --chrome` and `--bundle` remain as aliases for `--path` and `--target`.
@@ -126,6 +163,17 @@ persisted (`~/.config/chrome-cdp-manager/config.json`) at `setup` time so every
 command agrees on the same environment. Re-run `setup --force` after changing
 them.
 
+### Proxy
+
+`--proxy` passes Chrome's `--proxy-server` flag at launch so traffic routes
+through it. The default is a local SOCKS5 proxy on port `1080` (the common
+`ssh -D` / shadowsocks default). The proxy is a **per-launch** flag — it is not
+baked into the launcher, so a normal (non-proxied) launch is never affected by
+it. Before launching, the proxy port is probed and a warning is printed if
+nothing is listening; `status` reports the configured proxy and whether it's
+reachable. Persist a default proxy with `chrome-cdp setup --proxy …`, or opt out
+of a persisted proxy for a single run with `--no-proxy`.
+
 ## How the icon stays consistent
 
 **macOS** — the bundle's executable is a small bash launcher:

package/bin/playwright-cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * `playwright-cli` — run Playwright's MCP CLI client against the ChromeCDP
+ * instance managed by this package.
+ *
+ * The Playwright CLI itself has nothing to do with this repo; this wrapper only
+ * guarantees the two things it needs before handing off:
+ *
+ *   1. A *headed* ChromeCDP browser is running and reachable over CDP.
+ *   2. The env points Playwright at that browser instead of spawning its own:
+ *        PLAYWRIGHT_MCP_CDP_ENDPOINT=http://localhost:<cdpPort>   (default 9222)
+ *        PLAYWRIGHT_MCP_ISOLATED=false
+ *
+ * Everything after `playwright-cli` is forwarded verbatim — the cli-client reads
+ * process.argv.slice(2) directly, which already holds those args here.
+ */
+import { createRequire } from "node:module";
+
+import { assertSupportedPlatform } from "../src/platform.js";
+import { loadConfig } from "../src/config.js";
+import { getLauncher } from "../src/launcher.js";
+import { ensureBrowserRunning, probeCdp } from "../src/browser.js";
+
+const require = createRequire(import.meta.url);
+
+/** Plain help/version requests don't need a browser — just forward them. */
+function isHelpOrVersionOnly(args) {
+  if (args.length === 0) return true;
+  const hasCommand = args.some((a) => !a.startsWith("-"));
+  if (!hasCommand) return true;
+  return args.some((a) => ["-h", "--help", "-v", "--version"].includes(a));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (!isHelpOrVersionOnly(args)) {
+    assertSupportedPlatform();
+    const config = loadConfig();
+    const endpoint = `http://localhost:${config.cdpPort}`;
+
+    // If a CDP browser is already up on this port, attach to it as-is — never
+    // relaunch (even if it's headless). Only launch a fresh headed instance when
+    // nothing is listening.
+    const existing = await probeCdp(config.cdpPort);
+    if (existing) {
+      console.error(`ChromeCDP already running on port ${config.cdpPort}.`);
+    } else {
+      getLauncher().ensure(config, { force: false });
+      await ensureBrowserRunning(config, { headless: false, timeoutMs: 30_000 });
+      console.error(`Launched ChromeCDP (headed) on port ${config.cdpPort}.`);
+    }
+    console.error(`playwright-cli attaching to ${endpoint} ...`);
+
+    process.env.PLAYWRIGHT_MCP_CDP_ENDPOINT = endpoint;
+    process.env.PLAYWRIGHT_MCP_ISOLATED = "false";
+  }
+
+  let program;
+  try {
+    ({ program } = require("playwright-core/lib/tools/cli-client/program"));
+  } catch {
+    throw new Error(
+      "Playwright not found. The `playwright-cli` command needs Playwright " +
+        "installed:\n  npm i playwright",
+    );
+  }
+
+  const packageJson = require("../package.json");
+  await program({ embedderVersion: packageJson.version });
+}
+
+main().catch((error) => {
+  console.error(`\nError: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-cdp-manager",
-  "version": "1.2.2",
+  "version": "1.2.6",
   "description": "Set up and drive a Chrome DevTools Protocol (CDP) instance on macOS or Windows through a dedicated launcher (consistent Dock/taskbar icon). Works with any Chromium-based browser — Chrome, Edge, Brave, Chromium, Vivaldi, Opera, Arc.",
   "type": "module",
   "main": "./src/index.js",
@@ -18,7 +18,8 @@
   },
   "bin": {
     "chrome-cdp": "bin/cli.js",
-    "chrome-cdp-manager": "bin/cli.js"
+    "chrome-cdp-manager": "bin/cli.js",
+    "playwright-cli": "bin/playwright-cli.js"
   },
   "files": [
     "bin",
@@ -57,6 +58,7 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "cheerio": "^1.2.0",
     "commander": "^12.1.0"
   },
   "peerDependencies": {
@@ -68,6 +70,7 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5.6.0"
+    "playwright": "^1.61.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/browser.js

@@ -1,4 +1,6 @@
 import { getLauncher } from "./launcher.js";
+import { closeBrowser } from "./cdp.js";
+
 
 /** CDP HTTP endpoint helper. */
 function versionUrl(cdpPort) {
@@ -38,7 +40,21 @@ export async function waitForCdp(cdpPort, timeoutMs = 30_000) {
  */
 export async function ensureBrowserRunning(config, { headless, timeoutMs } = {}) {
   const existing = await probeCdp(config.cdpPort);
-  if (existing) return { launched: false, version: existing };
+  if (existing) {
+    const isHeadless =
+      /HeadlessChrome/i.test(existing.Browser) ||
+      /HeadlessChrome/i.test(existing["User-Agent"] || "");
+    if (isHeadless && !headless) {
+      try {
+        await closeBrowser(config.cdpPort);
+        await delay(500);
+      } catch (err) {
+        // ignore
+      }
+    } else {
+      return { launched: false, version: existing };
+    }
+  }
 
   getLauncher().launch(config, { headless });
   const version = await waitForCdp(config.cdpPort, timeoutMs);

package/src/cli.js

@@ -3,6 +3,7 @@ import { Command } from "commander";
 
 import { DEFAULTS } from "./config.js";
 import { browserKeys, DEFAULT_BROWSER } from "./browsers.js";
+import { DEFAULT_PROXY } from "./proxy.js";
 import {
   setupCommand,
   openCommand,
@@ -61,7 +62,13 @@ Run 'chrome-cdp <command> --help' to see all options for a specific command.`,
         `Launcher ${TARGET_LABEL} path (default: ${DEFAULTS.launcherPath})`,
       )
       // Back-compat alias for --target.
-      .option("--bundle <path>", "Alias for --target");
+      .option("--bundle <path>", "Alias for --target")
+      .option(
+        "--proxy [server]",
+        `Route traffic through a proxy; value omitted uses ${DEFAULT_PROXY}. ` +
+          `Accepts a port (1080), host:port, or scheme://host:port`,
+      )
+      .option("--no-proxy", "Disable any configured proxy for this run");
 
   withCommon(
     program

package/src/commands.js

@@ -12,6 +12,7 @@ import {
 import { getLauncher } from "./launcher.js";
 import { ensureBrowserRunning, probeCdp } from "./browser.js";
 import { openUrl, getPageHtml, closeBrowser } from "./cdp.js";
+import { parseProxy, detectProxy } from "./proxy.js";
 
 /** Merge persisted config with CLI overrides into a fully-resolved config. */
 function resolveConfig(opts = {}) {
@@ -51,6 +52,14 @@ function resolveConfig(opts = {}) {
   const target = opts.target || opts.bundle;
   if (target) resolved.launcherPath = path.resolve(target);
   if (opts.port !== undefined) resolved.cdpPort = parsePort(opts.port);
+
+  // --no-proxy => opts.proxy === false; --proxy [server] => true or a string;
+  // absent => undefined (no proxy — it is never persisted).
+  if (opts.proxy === false) {
+    resolved.proxy = null;
+  } else if (opts.proxy !== undefined) {
+    resolved.proxy = parseProxy(opts.proxy).server;
+  }
   return resolved;
 }
 
@@ -86,6 +95,21 @@ function ensureLauncherReady(config) {
   }
 }
 
+/** Probe the configured proxy and report whether it's reachable. */
+async function reportProxy(config) {
+  if (!config.proxy) return;
+  const { server, host, port } = parseProxy(config.proxy);
+  const reachable = await detectProxy({ host, port });
+  if (reachable) {
+    console.error(`Proxy: routing traffic through ${server} (detected listening).`);
+  } else {
+    console.error(
+      `Proxy: ${server} configured, but nothing is listening on ${host}:${port}. ` +
+        `Pages won't load until the proxy is up — or pass --no-proxy.`,
+    );
+  }
+}
+
 // MARK: setup
 export async function setupCommand(opts) {
   assertSupportedPlatform();
@@ -109,6 +133,7 @@ export async function openCommand(url, opts) {
   const timeoutMs = parseTimeoutMs(opts.timeout);
 
   ensureLauncherReady(config);
+  await reportProxy(config);
 
   const { launched, version } = await ensureBrowserRunning(config, { headless, timeoutMs });
   if (launched) {
@@ -136,20 +161,31 @@ export async function htmlCommand(url, opts) {
   const target = normalizeUrl(url);
 
   ensureLauncherReady(config);
-  await ensureBrowserRunning(config, { headless, timeoutMs });
+  await reportProxy(config);
+  const { launched } = await ensureBrowserRunning(config, { headless, timeoutMs });
 
   console.error(`Fetching HTML for ${target} ...`);
-  const html = await getPageHtml(config.cdpPort, target, {
-    close: Boolean(opts.close),
-    timeoutMs,
-  });
-
-  if (opts.output) {
-    const outPath = path.resolve(opts.output);
-    fs.writeFileSync(outPath, html);
-    console.error(`Saved HTML to ${outPath}`);
-  } else {
-    process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+  try {
+    const html = await getPageHtml(config.cdpPort, target, {
+      close: !launched || Boolean(opts.close),
+      timeoutMs,
+    });
+
+    if (opts.output) {
+      const outPath = path.resolve(opts.output);
+      fs.writeFileSync(outPath, html);
+      console.error(`Saved HTML to ${outPath}`);
+    } else {
+      process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+    }
+  } finally {
+    if (launched && headless) {
+      try {
+        await closeBrowser(config.cdpPort);
+      } catch (err) {
+        // ignore errors during shutdown
+      }
+    }
   }
 }
 
@@ -176,6 +212,14 @@ export async function statusCommand(opts) {
   console.log(`  Profile:  ${config.profileDir}`);
   console.log(`  CDP port: ${config.cdpPort}`);
 
+  if (config.proxy) {
+    const { server, host, port } = parseProxy(config.proxy);
+    const reachable = await detectProxy({ host, port });
+    console.log(`  Proxy:    ${server} (${reachable ? "reachable" : "NOT reachable"})`);
+  } else {
+    console.log(`  Proxy:    none (direct connection)`);
+  }
+
   const isHeadless =
     /HeadlessChrome/i.test(version.Browser) ||
     /HeadlessChrome/i.test(version["User-Agent"] || "");

package/src/config.js

@@ -46,6 +46,8 @@ export function computeDefaults({
     bundleId: BUNDLE_ID,
     cdpPort: CDP_PORT,
     profileDir: path.join(os.homedir(), ".chrome_cdp_profile"),
+    // Proxy is opt-in: null means launch with a direct connection.
+    proxy: null,
   };
 }
 
@@ -88,6 +90,8 @@ export function saveConfig(config) {
     bundleId: config.bundleId,
     cdpPort: config.cdpPort,
     profileDir: config.profileDir,
+    // Proxy is intentionally not persisted: it's a per-invocation flag, so it
+    // never leaks into other launches.
   };
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
   fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(toStore, null, 2)}\n`);

package/src/launchers/macBundle.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 
+import { getWindowSizeFromProfile } from "../preferences.js";
+
 /**
  * macOS launcher: a real `.app` bundle whose executable is a small bash
  * launcher. Headed launches go through `open <bundle>` so LaunchServices
@@ -27,6 +29,36 @@ BROWSER=${shellQuote(browserPath)}
 PORT=${shellQuote(String(cdpPort))}
 PROFILE=${shellQuote(profileDir)}
 
+# Gracefully close any background headless Chrome instance using the same port.
+NODE_BIN="node"
+if ! command -v node &> /dev/null; then
+  for path in "/opt/homebrew/bin/node" "/usr/local/bin/node" "$HOME/.nvm/versions/node"/*/bin/node "$HOME/.nvs"/*/bin/node; do
+    if [ -x "$path" ]; then
+      NODE_BIN="$path"
+      break
+    fi
+  done
+fi
+
+"$NODE_BIN" --no-warnings -e "(async () => {
+  try {
+    const res = await fetch('http://127.0.0.1:${cdpPort}/json/version');
+    if (res.ok) {
+      const info = await res.json();
+      const isHeadless = /HeadlessChrome/i.test(info.Browser) || /HeadlessChrome/i.test(info['User-Agent'] || '');
+      if (isHeadless) {
+        const ws = new WebSocket(info.webSocketDebuggerUrl);
+        ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
+        ws.onmessage = () => {
+          ws.close();
+          process.exit(0);
+        };
+        await new Promise(r => setTimeout(r, 800));
+      }
+    }
+  } catch {}
+})()" || true
+
 exec ${archPrefix}"$BROWSER" \\
   --remote-debugging-port="$PORT" \\
   --user-data-dir="$PROFILE" \\
@@ -162,9 +194,20 @@ export function ensure(config, { force = false } = {}) {
  * LaunchServices attaches the Dock icon; headless runs the launcher directly.
  */
 export function launch(config, { headless } = {}) {
+  // The proxy is a per-launch flag, not baked into the (fixed) bundle, so a
+  // normal launch is never affected by it.
+  const proxyArg = config.proxy ? [`--proxy-server=${config.proxy}`] : [];
+
   if (headless) {
     const { executable } = bundleLayout(config.launcherPath);
-    const child = spawn(executable, ["--headless=new"], {
+    const args = ["--headless=new"];
+    const size = getWindowSizeFromProfile(config.profileDir);
+    if (size) {
+      args.push(`--window-size=${size.width},${size.height}`);
+      args.push(`--screen-info={0,0 ${size.width}x${size.height}}`);
+    }
+    args.push(...proxyArg);
+    const child = spawn(executable, args, {
       detached: true,
       stdio: "ignore",
     });
@@ -173,7 +216,10 @@ export function launch(config, { headless } = {}) {
   }
 
   // `open` returns immediately; readiness is awaited via waitForCdp().
-  const child = spawn("open", [config.launcherPath], { stdio: "ignore" });
+  // `--args` forwards the proxy flag to the bundle's launcher ("$@").
+  const openArgs = [config.launcherPath];
+  if (proxyArg.length) openArgs.push("--args", ...proxyArg);
+  const child = spawn("open", openArgs, { stdio: "ignore" });
   child.unref();
 }
 

package/src/launchers/winShortcut.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 
+import { getWindowSizeFromProfile } from "../preferences.js";
+
 /**
  * Windows launcher: a Start Menu `.lnk` shortcut with a custom icon and the CDP
  * flags baked into its arguments. Headed launches go through the shortcut so
@@ -83,16 +85,27 @@ export function ensure(config, { force = false } = {}) {
 /**
  * Launch the browser. Headed goes through the shortcut so the taskbar uses its
  * icon; headless runs the exe directly with the same flags + `--headless=new`.
+ *
+ * The proxy is a per-launch flag, never baked into the (fixed) shortcut. A
+ * `.lnk` can't take extra args at launch time, so a proxied headed launch runs
+ * the exe directly (the dedicated profile still gives a separate taskbar entry).
  */
 export function launch(config, { headless } = {}) {
-  if (headless) {
+  if (headless || config.proxy) {
+    const args = [
+      `--remote-debugging-port=${config.cdpPort}`,
+      `--user-data-dir=${config.profileDir}`,
+    ];
+    if (headless) args.push("--headless=new");
+    if (config.proxy) args.push(`--proxy-server=${config.proxy}`);
+    const size = getWindowSizeFromProfile(config.profileDir);
+    if (size) {
+      args.push(`--window-size=${size.width},${size.height}`);
+      args.push(`--screen-info={0,0 ${size.width}x${size.height}}`);
+    }
     const child = spawn(
       config.browserPath,
-      [
-        `--remote-debugging-port=${config.cdpPort}`,
-        `--user-data-dir=${config.profileDir}`,
-        "--headless=new",
-      ],
+      args,
       { detached: true, stdio: "ignore" },
     );
     child.unref();

package/src/preferences.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Reads the last closed window dimensions from the Chrome profile Preferences file.
+ * @param {string} profileDir
+ * @returns {{ width: number, height: number, maximized: boolean } | null}
+ */
+export function getWindowSizeFromProfile(profileDir) {
+  try {
+    const preferencesPath = path.join(profileDir, "Default", "Preferences");
+    if (fs.existsSync(preferencesPath)) {
+      const content = fs.readFileSync(preferencesPath, "utf8");
+      const prefs = JSON.parse(content);
+      const placement = prefs?.browser?.window_placement;
+      if (placement) {
+        const { left, top, right, bottom, maximized } = placement;
+        const width = right - left;
+        const height = bottom - top;
+        if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+          return { width, height, maximized: Boolean(maximized) };
+        }
+      }
+    }
+  } catch {
+    // Ignore and fallback
+  }
+  return null;
+}

package/src/proxy.js

@@ -0,0 +1,93 @@
+import net from "node:net";
+
+/**
+ * Proxy support: normalise a user-supplied proxy value into a Chrome
+ * `--proxy-server` string and probe whether something is actually listening on
+ * it. The default is a local SOCKS5 proxy on port 1080 (the common SSH/`ssh -D`
+ * and shadowsocks default).
+ */
+
+export const DEFAULT_PROXY_HOST = "127.0.0.1";
+export const DEFAULT_PROXY_PORT = 1080;
+export const DEFAULT_PROXY_SCHEME = "socks5";
+export const DEFAULT_PROXY = `${DEFAULT_PROXY_SCHEME}://${DEFAULT_PROXY_HOST}:${DEFAULT_PROXY_PORT}`;
+
+/** Chrome accepts these proxy schemes for `--proxy-server`. */
+const KNOWN_SCHEMES = new Set(["socks5", "socks4", "http", "https"]);
+
+/**
+ * Parse a proxy value into its parts. Accepts, in order of convenience:
+ *   - `true` / "" / "default"  → the default SOCKS5 proxy
+ *   - "1080"                   → socks5://127.0.0.1:1080
+ *   - "host:1080"              → socks5://host:1080
+ *   - "socks5://host:1080"     → as given
+ *   - "http://host:8080"       → an HTTP proxy
+ * @returns {{ server: string, scheme: string, host: string, port: number }}
+ */
+export function parseProxy(value) {
+  if (value === true || value === undefined || value === null) {
+    value = DEFAULT_PROXY;
+  }
+  let raw = String(value).trim();
+  if (raw === "" || raw.toLowerCase() === "default") raw = DEFAULT_PROXY;
+
+  // Port-only shorthand: "1080".
+  if (/^\d+$/.test(raw)) {
+    raw = `${DEFAULT_PROXY_SCHEME}://${DEFAULT_PROXY_HOST}:${raw}`;
+  } else if (!raw.includes("://")) {
+    // "host:port" shorthand — default the scheme to socks5.
+    raw = `${DEFAULT_PROXY_SCHEME}://${raw}`;
+  }
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      `Invalid --proxy "${value}". Use a port (1080), host:port, or scheme://host:port.`,
+    );
+  }
+
+  const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+  if (!KNOWN_SCHEMES.has(scheme)) {
+    throw new Error(
+      `Unsupported proxy scheme "${scheme}". Use one of: ${[...KNOWN_SCHEMES].join(", ")}.`,
+    );
+  }
+
+  const host = url.hostname || DEFAULT_PROXY_HOST;
+  const port = url.port
+    ? Number(url.port)
+    : scheme.startsWith("socks")
+      ? DEFAULT_PROXY_PORT
+      : 8080;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid proxy port in "${value}". Use an integer 1-65535.`);
+  }
+
+  return { server: `${scheme}://${host}:${port}`, scheme, host, port };
+}
+
+/**
+ * Probe a TCP port to see whether a proxy is actually listening there. This is
+ * a connectivity check only — it can't verify the protocol — but it catches the
+ * common case of routing traffic through a proxy that isn't running.
+ * @returns {Promise<boolean>}
+ */
+export function detectProxy({ host, port, timeoutMs = 1500 } = {}) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (reachable) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(reachable);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    socket.connect(port, host);
+  });
+}

package/types/config.d.ts

@@ -10,6 +10,7 @@ export function computeDefaults({ browser, platform, }?: {
     bundleId: string;
     cdpPort: number;
     profileDir: any;
+    proxy: any;
 };
 /** Load persisted config, falling back to {@link DEFAULTS} for missing keys. */
 export function loadConfig(): any;
@@ -24,5 +25,6 @@ export const DEFAULTS: Readonly<{
     bundleId: string;
     cdpPort: number;
     profileDir: any;
+    proxy: any;
 }>;
 export const CONFIG_FILE: any;

package/types/launchers/winShortcut.d.ts

@@ -14,6 +14,10 @@ export function ensure(config: any, { force }?: {
 /**
  * Launch the browser. Headed goes through the shortcut so the taskbar uses its
  * icon; headless runs the exe directly with the same flags + `--headless=new`.
+ *
+ * The proxy is a per-launch flag, never baked into the (fixed) shortcut. A
+ * `.lnk` can't take extra args at launch time, so a proxied headed launch runs
+ * the exe directly (the dedicated profile still gives a separate taskbar entry).
  */
 export function launch(config: any, { headless }?: {}): void;
 export const targetLabel: "Shortcut";

package/types/preferences.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads the last closed window dimensions from the Chrome profile Preferences file.
+ * @param {string} profileDir
+ * @returns {{ width: number, height: number, maximized: boolean } | null}
+ */
+export function getWindowSizeFromProfile(profileDir: string): {
+    width: number;
+    height: number;
+    maximized: boolean;
+} | null;

package/types/proxy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parse a proxy value into its parts. Accepts, in order of convenience:
+ *   - `true` / "" / "default"  → the default SOCKS5 proxy
+ *   - "1080"                   → socks5://127.0.0.1:1080
+ *   - "host:1080"              → socks5://host:1080
+ *   - "socks5://host:1080"     → as given
+ *   - "http://host:8080"       → an HTTP proxy
+ * @returns {{ server: string, scheme: string, host: string, port: number }}
+ */
+export function parseProxy(value: any): {
+    server: string;
+    scheme: string;
+    host: string;
+    port: number;
+};
+/**
+ * Probe a TCP port to see whether a proxy is actually listening there. This is
+ * a connectivity check only — it can't verify the protocol — but it catches the
+ * common case of routing traffic through a proxy that isn't running.
+ * @returns {Promise<boolean>}
+ */
+export function detectProxy({ host, port, timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<boolean>;
+/**
+ * Proxy support: normalise a user-supplied proxy value into a Chrome
+ * `--proxy-server` string and probe whether something is actually listening on
+ * it. The default is a local SOCKS5 proxy on port 1080 (the common SSH/`ssh -D`
+ * and shadowsocks default).
+ */
+export const DEFAULT_PROXY_HOST: "127.0.0.1";
+export const DEFAULT_PROXY_PORT: 1080;
+export const DEFAULT_PROXY_SCHEME: "socks5";
+export const DEFAULT_PROXY: "socks5://127.0.0.1:1080";