@xevy/heny-connect 0.2.0 → 0.3.0

package/README.md

@@ -1,60 +1,70 @@
 # @xevy/heny-connect
 
-Heny Connect pairs a computer with a Heny workspace and keeps the device's availability current.
+Heny Connect runs a dedicated browser worker on a paired Windows PC. It stays in the system tray, starts at sign-in, and executes three explicit commands from Heny Desktop:
+
+- Navigate to an approved public HTTP(S) URL
+- Read up to 50,000 characters of visible page text
+- Capture a viewport PNG up to 2 MiB
 
 ## Requirements
 
-- Node.js 20 or newer
-- A six-digit pairing code from the Heny **Desktop** page
+- Windows 10 or 11
+- Microsoft Edge or Google Chrome
+- Node.js 22 or newer
+- A six-digit code from Heny **Desktop**
+
+## Install and pair
 
-## Pair a computer
+Open PowerShell once:
 
-```bash
-npx @xevy/heny-connect pair --code 123456 --server https://heny.vyte.dev --run
+```powershell
+npm.cmd install -g @xevy/heny-connect@latest
+heny-connect.cmd pair --code 123456 --server https://heny.vyte.dev
+heny-connect.cmd install
 ```
 
-The pairing code works once and expires after 15 minutes. Pairing state is stored in `.heny-connect.json` in the current user's home directory.
+The code works once and expires after 15 minutes. `install` starts the tray immediately and registers **HenyConnect** for the current user's Windows sign-in.
 
-## Run an existing pairing
+Heny Connect stores its registration and dedicated browser profile under `%LOCALAPPDATA%\Heny Connect`. Windows ACLs grant access to the current user and SYSTEM.
 
-```bash
-npx @xevy/heny-connect run
-```
+## System tray
 
-The process sends a heartbeat every 30 seconds. Keep it running for the device to remain available in Heny.
+The tray reports:
 
-## Windows system tray
+- Browser starting
+- Available
+- Working, including the current action
+- Paused
+- Error
+- Offline
 
-Install the tray companion after pairing:
+The menu provides **Open Heny**, **Pause/Resume**, **Reconnect now**, **Start at sign-in**, and **Quit**. Pause aborts current work, closes the dedicated browser, and reaches the local Paused state within five seconds during a network interruption.
 
-```powershell
-heny-connect install
-```
+## Dedicated browser
 
-Heny Connect starts at Windows sign-in and runs without an open terminal. The tray menu shows the connection state and provides these controls:
+The companion owns a separate persistent Chromium profile. Logins created in that window remain available after worker and browser restarts.
 
-- Open Heny
-- Pause or resume the connection
-- Reconnect now
-- Turn start-at-sign-in on or off
-- Quit until the next sign-in
+Browser traffic uses a loopback validating proxy. Each HTTP request and HTTPS tunnel resolves the destination, rejects local/private/reserved addresses, and connects directly to the validated address. Chromium retains the destination Host and TLS certificate checks. Downloads, popups, external protocols, and browser permission grants are blocked.
 
-To start the tray for the current session without installing start-at-sign-in:
+The command protocol excludes click, type, submit, upload, shell execution, command-supplied JavaScript, and personal-profile attachment.
 
-```powershell
-heny-connect tray
-```
-
-To remove start-at-sign-in:
+## Commands
 
 ```powershell
-heny-connect uninstall
+heny-connect.cmd status
+heny-connect.cmd pause
+heny-connect.cmd resume
+heny-connect.cmd tray
+heny-connect.cmd install
+heny-connect.cmd uninstall
 ```
 
-## Check status
+`status` shows server registration plus content-free local worker status. Device tokens, browsing content, URLs, page titles, screenshots, and browser debugger details stay out of console output.
 
-```bash
-npx @xevy/heny-connect status
+## Remove start-at-sign-in
+
+```powershell
+heny-connect.cmd uninstall
 ```
 
-Heny Connect currently provides device registration and availability reporting. Browser and shell execution are planned capabilities.
+Use **Quit** from the tray to end the current worker session.

package/bin/heny-connect.mjs

@@ -1,21 +1,16 @@
 #!/usr/bin/env node
 /**
- * Heny Connect — pairs this computer with a Heny workspace and keeps it
- * reporting in. Node 20+; no dependencies.
- *
- *   npx @xevy/heny-connect pair --code 123456 --server https://heny.example
- *   npx @xevy/heny-connect run
- *   npx @xevy/heny-connect status
- *
- * Pairing state is stored in ~/.heny-connect.json (mode 600).
+ * Heny Connect — pairs a Windows computer, owns a dedicated browser profile,
+ * and runs bounded browser commands without an open terminal.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { chmod, readFile, writeFile } from "node:fs/promises";
-import { homedir, hostname, platform, release } from "node:os";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { hostname, platform, release } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CAPABILITIES, DeviceApi, runWorker } from "../lib/worker.mjs";
+import { CONNECT_HOME, PAUSE_FILE, STATUS_FILE, loadState, protectConnectHome, saveState, writeStatus } from "../lib/state.mjs";
 
-const STATE_FILE = join(process.env.HENY_CONNECT_HOME || homedir(), ".heny-connect.json");
 const CLI_FILE = fileURLToPath(import.meta.url);
 const TRAY_SCRIPT = join(dirname(CLI_FILE), "..", "windows", "heny-connect-tray.ps1");
 const args = process.argv.slice(2);
@@ -29,63 +24,73 @@ function systemLabel() {
   return `${os} ${release()}`;
 }
 
-async function loadState() { try { return JSON.parse(await readFile(STATE_FILE, "utf8")); } catch { return null; } }
-async function saveState(state) { await writeFile(STATE_FILE, JSON.stringify(state, null, 2)); await chmod(STATE_FILE, 0o600).catch(() => undefined); }
-
 async function call(server, path, body, token) {
-  const res = await fetch(new URL(path, server), { method: "POST", headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body), signal: AbortSignal.timeout(20_000) });
-  const text = await res.text();
-  let parsed; try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
-  if (!res.ok) throw new Error(parsed?.error?.message || `HTTP ${res.status}`);
+  const response = await fetch(new URL(path, server), {
+    method: "POST",
+    headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  let parsed = null;
+  try { parsed = await response.json(); } catch {}
+  if (!response.ok) throw Object.assign(new Error(parsed?.error?.message || `Server answered HTTP ${response.status}`), { status: response.status, code: parsed?.error?.code || "server_error" });
   return parsed;
 }
 
 async function pair() {
-  const code = opt("code"); const server = opt("server", process.env.HENY_SERVER);
+  const code = opt("code");
+  const server = opt("server", process.env.HENY_SERVER);
   if (!code || !server) { console.error("Usage: heny-connect pair --code 123456 --server https://heny.example"); process.exitCode = 2; return; }
-  const result = await call(server, "/api/devices/pair", { code, system: systemLabel(), hostname: hostname(), capabilities: ["browser", "shell"] });
+  await protectConnectHome();
+  const result = await call(server, "/api/devices/pair", { code, system: systemLabel(), hostname: hostname(), capabilities: CAPABILITIES });
   await saveState({ server, token: result.token, deviceId: result.deviceId, workspace: result.workspace, pairedAt: new Date().toISOString() });
+  await unlink(PAUSE_FILE).catch(() => undefined);
   console.log(`Paired with ${result.workspace?.name ?? "workspace"} as device ${result.deviceId}.`);
-  if (!args.includes("--once") && args.includes("--run")) await run();
-}
-
-async function heartbeat(state, detail) {
-  return call(state.server, "/api/devices/heartbeat", { state: detail.state, detail: detail.message }, state.token);
-}
-
-async function sendHeartbeat(stateName = "available", message = `${hostname()}: browser ready`) {
-  const state = await loadState();
-  if (!state) { console.error("Not paired. Run: heny-connect pair --code … --server …"); process.exitCode = 2; return false; }
-  if (!["online", "available", "offline"].includes(stateName)) { console.error("State must be online, available, or offline."); process.exitCode = 2; return false; }
-  await heartbeat(state, { state: stateName, message });
-  return true;
+  if (args.includes("--run")) await run();
 }
 
 async function run() {
   const state = await loadState();
-  if (!state) { console.error("Not paired. Run: heny-connect pair --code … --server …"); process.exitCode = 2; return; }
-  const every = Number(opt("every", 30)) * 1000;
-  const beats = Number(opt("beats", 0)); let count = 0;
-  const tick = async () => {
-    try { await heartbeat(state, { state: "available", message: `${hostname()}: browser ready` }); count += 1; console.log(`${new Date().toISOString()} heartbeat ok (${count})`); }
-    catch (err) { console.error(`${new Date().toISOString()} heartbeat failed: ${err.message}`); if (/Unknown device token/.test(err.message)) process.exit(3); }
-    if (beats && count >= beats) process.exit(0);
-  };
-  await tick();
-  if (!beats || count < beats) setInterval(tick, every);
+  if (!state) { console.error("This computer needs pairing. Open Heny Desktop to get a code."); process.exitCode = 2; return; }
+  try {
+    await runWorker(state);
+  } catch (error) {
+    const detailCode = error?.status === 401 ? "re_pair_required" : (/^[a-z0-9_]{1,40}$/.test(error?.code || "") ? error.code : "worker_error");
+    await writeStatus({ state: "error", detailCode, currentCommandId: null, currentAction: null }).catch(() => undefined);
+    console.error(error?.code === "device_revoked" ? "Registration was revoked. Pair this computer again." : error.message);
+    process.exitCode = error?.status === 401 ? 3 : 1;
+  }
 }
 
 async function heartbeatOnce() {
+  const state = await loadState();
+  if (!state) { console.error("This computer needs pairing. Open Heny Desktop to get a code."); process.exitCode = 2; return; }
   const stateName = opt("state", "available");
-  const message = opt("detail", stateName === "offline" ? `${hostname()}: paused locally` : `${hostname()}: browser ready`);
-  if (await sendHeartbeat(stateName, message)) console.log(`Heartbeat reported ${stateName}.`);
+  if (!["available", "paused", "offline", "browser_starting", "error"].includes(stateName)) { console.error("Choose a valid worker state."); process.exitCode = 2; return; }
+  const browserReady = stateName === "available";
+  await new DeviceApi(state).heartbeat(stateName, browserReady);
+  console.log(`Heartbeat reported ${stateName}.`);
 }
 
 async function status() {
   const state = await loadState();
   if (!state) { console.log("Not paired."); return; }
-  const res = await fetch(new URL("/api/devices/me", state.server), { headers: { Authorization: `Bearer ${state.token}` }, signal: AbortSignal.timeout(20_000) });
-  console.log(res.ok ? JSON.stringify(await res.json(), null, 2) : `Server answered HTTP ${res.status}`);
+  const response = await fetch(new URL("/api/devices/me", state.server), { headers: { authorization: `Bearer ${state.token}` }, signal: AbortSignal.timeout(20_000) });
+  let local = null;
+  try { local = JSON.parse(await readFile(STATUS_FILE, "utf8")); } catch {}
+  if (!response.ok) { console.log(`Server answered HTTP ${response.status}`); return; }
+  console.log(JSON.stringify({ ...(await response.json()), local }, null, 2));
+}
+
+async function pause() {
+  await protectConnectHome();
+  await writeFile(PAUSE_FILE, "paused\n", { mode: 0o600 });
+  console.log("Heny Connect is pausing.");
+}
+
+async function resume() {
+  await unlink(PAUSE_FILE).catch(() => undefined);
+  console.log("Heny Connect is resuming.");
 }
 
 function requireWindows() {
@@ -96,7 +101,7 @@ function requireWindows() {
 }
 
 function trayArgs(mode) {
-  const values = ["-NoLogo", "-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-File", TRAY_SCRIPT, "-NodePath", process.execPath, "-CliPath", CLI_FILE];
+  const values = ["-NoLogo", "-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-File", TRAY_SCRIPT, "-NodePath", process.execPath, "-CliPath", CLI_FILE, "-HomePath", CONNECT_HOME];
   if (mode === "install") values.push("-Install");
   if (mode === "uninstall") values.push("-Uninstall");
   return values;
@@ -104,7 +109,7 @@ function trayArgs(mode) {
 
 async function tray() {
   if (!requireWindows()) return;
-  if (!await loadState()) { console.error("Not paired. Pair this computer before starting the tray."); process.exitCode = 2; return; }
+  if (!await loadState()) { console.error("Pair this computer before starting the tray."); process.exitCode = 2; return; }
   const child = spawn("powershell.exe", trayArgs("tray"), { detached: true, stdio: "ignore", windowsHide: true });
   child.unref();
   console.log("Heny Connect is running in the system tray.");
@@ -112,7 +117,8 @@ async function tray() {
 
 async function install() {
   if (!requireWindows()) return;
-  if (!await loadState()) { console.error("Not paired. Pair this computer before installing the tray."); process.exitCode = 2; return; }
+  if (!await loadState()) { console.error("Pair this computer before installing the tray."); process.exitCode = 2; return; }
+  if (CLI_FILE.includes("\\_npx\\")) { console.error("Install the package globally before enabling start at sign-in: npm.cmd install -g @xevy/heny-connect"); process.exitCode = 2; return; }
   const result = spawnSync("powershell.exe", trayArgs("install"), { encoding: "utf8", windowsHide: true });
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.status !== 0) { if (result.stderr) process.stderr.write(result.stderr); process.exitCode = result.status || 1; }
@@ -125,10 +131,11 @@ async function uninstall() {
   if (result.status !== 0) { if (result.stderr) process.stderr.write(result.stderr); process.exitCode = result.status || 1; }
 }
 
-const commands = { pair, run, status, heartbeat: heartbeatOnce, tray, install, uninstall, help: async () => console.log("Commands: pair --code <6 digits> --server <url> [--run] | run [--every 30] [--beats N] | status | tray | install | uninstall") };
+const help = async () => console.log("Commands: pair --code <6 digits> --server <url> [--run] | run | status | pause | resume | heartbeat --state <state> | tray | install | uninstall");
+const commands = { pair, run, status, pause, resume, heartbeat: heartbeatOnce, tray, install, uninstall, help };
 try {
-  await (commands[command] || commands.help)();
-} catch (err) {
-  console.error(err.message);
+  await (commands[command] || help)();
+} catch (error) {
+  console.error(error.message);
   process.exitCode = 1;
 }

package/lib/browser-controller.mjs

@@ -0,0 +1,242 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import net from "node:net";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { CdpSession } from "./cdp.mjs";
+import { parsePublicUrl, resolvePublicUrl } from "./network-policy.mjs";
+import { createValidatingProxy } from "./validating-proxy.mjs";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const DENIED_PERMISSIONS = ["geolocation", "notifications", "midi", "midiSysex", "camera", "microphone", "backgroundSync", "sensors", "clipboardReadWrite", "clipboardSanitizedWrite", "paymentHandler", "idleDetection", "localFonts", "windowManagement"];
+
+async function randomPort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const port = server.address().port;
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+function browserCandidates() {
+  const local = process.env.LOCALAPPDATA;
+  const programs = process.env.PROGRAMFILES;
+  const programs86 = process.env["PROGRAMFILES(X86)"];
+  return [
+    process.env.HENY_BROWSER_PATH,
+    local && join(local, "Microsoft", "Edge", "Application", "msedge.exe"),
+    programs && join(programs, "Microsoft", "Edge", "Application", "msedge.exe"),
+    programs86 && join(programs86, "Microsoft", "Edge", "Application", "msedge.exe"),
+    local && join(local, "Google", "Chrome", "Application", "chrome.exe"),
+    programs && join(programs, "Google", "Chrome", "Application", "chrome.exe"),
+    programs86 && join(programs86, "Google", "Chrome", "Application", "chrome.exe"),
+  ].filter(Boolean);
+}
+
+function findBrowser() {
+  const browser = browserCandidates().find((candidate) => existsSync(candidate));
+  if (!browser) throw Object.assign(new Error("Install Microsoft Edge or Google Chrome."), { code: "browser_missing" });
+  return browser;
+}
+
+export class BrowserController {
+  constructor({ home, browserPath = findBrowser(), lookup } = {}) {
+    this.home = home;
+    this.browserPath = browserPath;
+    this.lookup = lookup;
+    this.process = null;
+    this.proxy = null;
+    this.session = null;
+    this.targetId = null;
+    this.mainFrameId = null;
+  }
+
+  async start() {
+    if (this.session) return;
+    const profile = join(this.home, "browser-profile");
+    await mkdir(profile, { recursive: true });
+    this.proxy = await createValidatingProxy({ lookup: this.lookup });
+    const port = await randomPort();
+    const args = [
+      `--remote-debugging-address=127.0.0.1`,
+      `--remote-debugging-port=${port}`,
+      `--user-data-dir=${profile}`,
+      `--proxy-server=http://127.0.0.1:${this.proxy.port}`,
+      "--proxy-bypass-list=<-loopback>",
+      "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1",
+      "--disable-quic",
+      "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-sync",
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-features=ExternalProtocolDialog",
+      "--disable-notifications",
+      "--disable-extensions",
+      "--disable-session-crashed-bubble",
+      "--no-service-autorun",
+      "--new-window",
+      "about:blank",
+    ];
+    this.process = spawn(this.browserPath, args, { stdio: "ignore", windowsHide: false });
+    const browserProcess = this.process;
+    this.process.once("exit", () => {
+      if (this.process === browserProcess) this.process = null;
+      if (this.session) { const session = this.session; this.session = null; session.close(); }
+      if (this.proxy) { const proxy = this.proxy; this.proxy = null; void proxy.close().catch(() => undefined); }
+    });
+    let version;
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      try {
+        const response = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(500) });
+        if (response.ok) { version = await response.json(); break; }
+      } catch {}
+      await sleep(250);
+    }
+    if (!version) { await this.stop(); throw Object.assign(new Error("The dedicated browser did not start."), { code: "browser_start_failed" }); }
+    let targets = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+    let target = targets.find((entry) => entry.type === "page");
+    if (!target) target = await (await fetch(`http://127.0.0.1:${port}/json/new?about%3Ablank`, { method: "PUT" })).json();
+    this.targetId = target.id;
+    this.session = await CdpSession.open(target.webSocketDebuggerUrl);
+    const connectedSession = this.session;
+    this.session.onClose(() => {
+      if (this.session !== connectedSession) return;
+      this.session = null;
+      this.targetId = null;
+      this.mainFrameId = null;
+      void this.stop();
+    });
+    await Promise.all([
+      this.session.send("Page.enable"),
+      this.session.send("Runtime.enable"),
+      this.session.send("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] }),
+      this.session.send("Target.setDiscoverTargets", { discover: true }),
+      this.session.send("Browser.setDownloadBehavior", { behavior: "deny" }).catch(() => undefined),
+      this.session.send("Browser.resetPermissions").catch(() => undefined),
+      this.session.send("Page.setInterceptFileChooserDialog", { enabled: true }).catch(() => undefined),
+      ...DENIED_PERMISSIONS.map((name) => this.session.send("Browser.setPermission", { permission: { name }, setting: "denied" }).catch(() => undefined)),
+    ]);
+    const frameTree = await this.session.send("Page.getFrameTree");
+    this.mainFrameId = frameTree.frameTree.frame.id;
+    this.session.on("Fetch.requestPaused", async ({ requestId, request }) => {
+      try {
+        await resolvePublicUrl(request.url, this.lookup);
+        await this.session?.send("Fetch.continueRequest", { requestId });
+      } catch {
+        await this.session?.send("Fetch.failRequest", { requestId, errorReason: "BlockedByClient" }).catch(() => undefined);
+      }
+    });
+    this.session.on("Page.javascriptDialogOpening", () => this.session?.send("Page.handleJavaScriptDialog", { accept: false }).catch(() => undefined));
+    this.session.on("Page.fileChooserOpened", () => undefined);
+    this.session.on("Page.frameRequestedNavigation", ({ frameId, url }) => {
+      let protocol = "";
+      try { protocol = new URL(url).protocol; } catch {}
+      const external = !["http:", "https:", "about:", "data:", "blob:"].includes(protocol);
+      const blockedMainFrame = frameId === this.mainFrameId && !["http:", "https:"].includes(protocol);
+      if (external || blockedMainFrame) {
+        void this.session?.send("Page.stopLoading").catch(() => undefined);
+      }
+    });
+    this.session.on("Target.targetCreated", ({ targetInfo }) => {
+      if (targetInfo?.type === "page" && targetInfo.targetId !== this.targetId) void this.session?.send("Target.closeTarget", { targetId: targetInfo.targetId }).catch(() => undefined);
+    });
+  }
+
+  async execute(action, payload, { signal, timeoutMs }) {
+    if (signal?.aborted) throw Object.assign(new Error("Command cancelled."), { code: "command_cancelled" });
+    await this.start();
+    if (signal?.aborted) throw Object.assign(new Error("Command cancelled."), { code: "command_cancelled" });
+    const onAbort = () => { void this.session?.send("Page.stopLoading").catch(() => undefined); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      const operation = action === "browser.navigate" ? this.navigate(payload.url, timeoutMs, signal)
+        : action === "browser.read" ? this.read()
+          : action === "browser.screenshot" ? this.screenshot()
+            : Promise.reject(Object.assign(new Error("Unsupported command."), { code: "unsupported_action" }));
+      const cancelled = new Promise((_, reject) => signal?.addEventListener("abort", () => reject(Object.assign(new Error("Command cancelled."), { code: "command_cancelled" })), { once: true }));
+      return await Promise.race([operation, cancelled]);
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+
+  async pageIdentity() {
+    const result = await this.session.send("Runtime.evaluate", {
+      expression: "({title:String(document.title||'').slice(0,1000),url:String(location.href)})",
+      returnByValue: true,
+    });
+    return result.result.value;
+  }
+
+  async navigate(value, timeoutMs, signal) {
+    const url = parsePublicUrl(value);
+    await resolvePublicUrl(url.href, this.lookup);
+    const navigationAbort = new AbortController();
+    const abortNavigation = () => navigationAbort.abort();
+    signal?.addEventListener("abort", abortNavigation, { once: true });
+    const loaded = this.session.waitFor("Page.loadEventFired", timeoutMs, navigationAbort.signal).then(
+      () => ({ error: null }),
+      (error) => ({ error }),
+    );
+    try {
+      const result = await this.session.send("Page.navigate", { url: url.href }, timeoutMs);
+      if (result.errorText) throw Object.assign(new Error("Navigation failed."), { code: "navigation_failed" });
+      const loadOutcome = await loaded;
+      if (loadOutcome.error) throw loadOutcome.error;
+      const identity = await this.pageIdentity();
+      parsePublicUrl(identity.url);
+      return identity;
+    } catch (error) {
+      navigationAbort.abort();
+      await loaded;
+      throw error;
+    } finally {
+      signal?.removeEventListener("abort", abortNavigation);
+    }
+  }
+
+  async read() {
+    const result = await this.session.send("Runtime.evaluate", {
+      expression: `(()=>{const raw=(document.body?.innerText||"").replace(/\\r/g,"").replace(/[ \\t]+/g," ").replace(/\\n{3,}/g,"\\n\\n").trim();return {title:String(document.title||"").slice(0,1000),url:String(location.href),text:raw.slice(0,50000),truncated:raw.length>50000}})()`,
+      returnByValue: true,
+    });
+    parsePublicUrl(result.result.value.url);
+    return result.result.value;
+  }
+
+  async screenshot() {
+    const identity = await this.pageIdentity();
+    parsePublicUrl(identity.url);
+    const metrics = await this.session.send("Page.getLayoutMetrics");
+    const viewport = metrics.cssVisualViewport || metrics.visualViewport;
+    const result = await this.session.send("Page.captureScreenshot", { format: "png", fromSurface: true, captureBeyondViewport: false });
+    if (Buffer.byteLength(result.data, "base64") > 2 * 1024 * 1024) throw Object.assign(new Error("Screenshot is too large."), { code: "screenshot_too_large" });
+    return { ...identity, mimeType: "image/png", dataBase64: result.data, width: Math.round(viewport.clientWidth), height: Math.round(viewport.clientHeight) };
+  }
+
+  async stop() {
+    const session = this.session;
+    this.session = null;
+    this.mainFrameId = null;
+    const browserProcess = this.process;
+    this.process = null;
+    if (browserProcess) {
+      const exited = browserProcess.exitCode !== null;
+      const exit = exited ? Promise.resolve(true) : new Promise((resolve) => browserProcess.once("exit", () => resolve(true)));
+      if (session) await session.send("Browser.close", {}, 2_000).catch(() => undefined);
+      const closed = exited || await Promise.race([exit, sleep(3_000).then(() => false)]);
+      if (!closed) {
+        if (platform() === "win32" && browserProcess.pid) spawnSync("taskkill.exe", ["/PID", String(browserProcess.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        else browserProcess.kill();
+      }
+    }
+    session?.close();
+    if (this.proxy) {
+      await this.proxy.close().catch(() => undefined);
+      this.proxy = null;
+    }
+  }
+}

package/lib/cdp.mjs

@@ -0,0 +1,95 @@
+export class CdpSession {
+  constructor(socket) {
+    this.socket = socket;
+    this.id = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.closeListeners = new Set();
+    this.closed = false;
+    socket.onmessage = (event) => this.onMessage(JSON.parse(typeof event.data === "string" ? event.data : event.data.toString()));
+    socket.onerror = () => this.onClosed();
+    socket.onclose = () => this.onClosed();
+  }
+
+  onClosed() {
+    if (this.closed) return;
+    this.closed = true;
+    const error = Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" });
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    for (const listener of this.closeListeners) void listener(error);
+    this.closeListeners.clear();
+  }
+
+  static async open(url) {
+    if (typeof WebSocket !== "function") throw Object.assign(new Error("Heny Connect requires Node 22 or newer."), { code: "node_unsupported" });
+    const socket = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      socket.onopen = resolve;
+      socket.onerror = () => reject(Object.assign(new Error("Dedicated browser connection failed."), { code: "browser_connection_failed" }));
+    });
+    return new CdpSession(socket);
+  }
+
+  onMessage(message) {
+    if (message.id && this.pending.has(message.id)) {
+      const pending = this.pending.get(message.id);
+      this.pending.delete(message.id);
+      if (message.error) pending.reject(Object.assign(new Error(message.error.message), { code: "browser_protocol_error" }));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (message.method) {
+      for (const listener of this.listeners.get(message.method) || []) void listener(message.params || {});
+    }
+  }
+
+  on(method, listener) {
+    const entries = this.listeners.get(method) || [];
+    entries.push(listener);
+    this.listeners.set(method, entries);
+    return () => this.listeners.set(method, entries.filter((entry) => entry !== listener));
+  }
+
+  onClose(listener) {
+    if (this.closed) { void listener(Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" })); return () => undefined; }
+    this.closeListeners.add(listener);
+    return () => this.closeListeners.delete(listener);
+  }
+
+  send(method, params = {}, timeoutMs = 20_000) {
+    if (this.closed) return Promise.reject(Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" }));
+    const id = ++this.id;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(Object.assign(new Error("Dedicated browser timed out."), { code: "browser_timeout" }));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => { clearTimeout(timer); resolve(value); },
+        reject: (error) => { clearTimeout(timer); reject(error); },
+      });
+      try { this.socket.send(JSON.stringify({ id, method, params })); } catch { this.onClosed(); }
+    });
+  }
+
+  waitFor(method, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+      const done = (error, value) => {
+        clearTimeout(timer);
+        remove();
+        signal?.removeEventListener("abort", aborted);
+        error ? reject(error) : resolve(value);
+      };
+      const remove = this.on(method, (params) => done(null, params));
+      const timer = setTimeout(() => done(Object.assign(new Error("Dedicated browser timed out."), { code: "browser_timeout" })), timeoutMs);
+      const aborted = () => done(Object.assign(new Error("Command cancelled."), { code: "command_cancelled" }));
+      if (signal?.aborted) queueMicrotask(aborted);
+      else signal?.addEventListener("abort", aborted, { once: true });
+    });
+  }
+
+  close() {
+    try { this.socket.close(); } finally { this.onClosed(); }
+  }
+}