@monoes/monobrowse 1.0.5 → 1.0.7

package/src/__tests__/storage-eval.test.ts

@@ -0,0 +1,171 @@
+/**
+ * storage.ts builds localStorage/sessionStorage expressions by string
+ * concatenation, so the JSON.stringify escaping is the only thing standing
+ * between a user-supplied key and script injection into the page. That plus
+ * evaluateJs's error/timeout contract is what this file pins down.
+ * Fake client throughout — no browser.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { evaluateJs } from '../browser/actions.js';
+import {
+  getLocalStorageKey,
+  setLocalStorageKey,
+  removeLocalStorageKey,
+  clearLocalStorage,
+  getAllLocalStorage,
+  getSessionStorageKey,
+  setSessionStorageKey,
+  removeSessionStorageKey,
+  clearSessionStorage,
+  getAllSessionStorage,
+} from '../browser/storage.js';
+
+/** Client stub returning a fixed Runtime.evaluate value, recording expressions. */
+function stubClient(value?: unknown, exceptionDetails?: unknown): {
+  client: CdpClient;
+  exprs: string[];
+  sids: Array<string | undefined>;
+} {
+  const exprs: string[] = [];
+  const sids: Array<string | undefined> = [];
+  const client = {
+    send: vi.fn(async (_m: string, params: { expression: string }, sid?: string) => {
+      exprs.push(params.expression);
+      sids.push(sid);
+      return exceptionDetails ? { result: {}, exceptionDetails } : { result: { value, type: 'string' } };
+    }),
+  } as unknown as CdpClient;
+  return { client, exprs, sids };
+}
+
+describe('evaluateJs', () => {
+  it('sends Runtime.evaluate with returnByValue and awaitPromise, scoped to the session', async () => {
+    const client = {
+      send: vi.fn(async () => ({ result: { value: 42, type: 'number' } })),
+    } as unknown as CdpClient;
+    await expect(evaluateJs(client, 'S1', '1 + 41')).resolves.toBe(42);
+    expect((client.send as ReturnType<typeof vi.fn>).mock.calls[0]).toEqual([
+      'Runtime.evaluate',
+      { expression: '1 + 41', returnByValue: true, awaitPromise: true },
+      'S1',
+    ]);
+  });
+
+  it('surfaces the exception description when the page throws', async () => {
+    const { client } = stubClient(undefined, {
+      text: 'Uncaught',
+      exception: { description: 'ReferenceError: foo is not defined' },
+    });
+    await expect(evaluateJs(client, 'S1', 'foo')).rejects.toThrow(
+      'JS evaluation error: ReferenceError: foo is not defined'
+    );
+  });
+
+  it('falls back to exceptionDetails.text when there is no description', async () => {
+    const { client } = stubClient(undefined, { text: 'Uncaught SyntaxError' });
+    await expect(evaluateJs(client, 'S1', '{{')).rejects.toThrow(
+      'JS evaluation error: Uncaught SyntaxError'
+    );
+  });
+
+  it('returns undefined for an expression with no value', async () => {
+    const client = { send: vi.fn(async () => ({ result: { type: 'undefined' } })) } as unknown as CdpClient;
+    await expect(evaluateJs(client, 'S1', 'void 0')).resolves.toBeUndefined();
+  });
+
+  it('rejects rather than hanging when the page never settles the promise', async () => {
+    // awaitPromise:true means a never-settling expression would hang forever
+    // without the race; a 20ms budget proves the timer is armed.
+    const client = { send: vi.fn(() => new Promise(() => {})) } as unknown as CdpClient;
+    await expect(evaluateJs(client, 'S1', 'new Promise(() => {})', 20)).rejects.toThrow(
+      'JS evaluation timed out after 20ms'
+    );
+  });
+
+  it('waits indefinitely when the timeout is disabled with 0', async () => {
+    let resolveSend: (v: unknown) => void = () => {};
+    const client = {
+      send: vi.fn(() => new Promise((r) => { resolveSend = r; })),
+    } as unknown as CdpClient;
+    const p = evaluateJs(client, 'S1', 'slow()', 0);
+    resolveSend({ result: { value: 'done', type: 'string' } });
+    await expect(p).resolves.toBe('done');
+  });
+});
+
+describe('localStorage helpers', () => {
+  it('reads a key through a JSON-escaped getItem call', async () => {
+    const { client, exprs, sids } = stubClient('v');
+    await expect(getLocalStorageKey(client, 'S1', 'token')).resolves.toBe('v');
+    expect(exprs[0]).toBe('localStorage.getItem("token")');
+    expect(sids[0]).toBe('S1');
+  });
+
+  it('escapes a key containing quotes and backslashes instead of breaking out', async () => {
+    const { client, exprs } = stubClient(null);
+    await getLocalStorageKey(client, 'S1', 'a"); alert(1); //');
+    expect(exprs[0]).toBe('localStorage.getItem("a\\"); alert(1); //")');
+    // The payload must survive as *one* string literal: round-tripping the
+    // argument back through JSON.parse recovers the key verbatim, which it
+    // could not if the quote had terminated the literal early.
+    const arg = exprs[0]!.slice('localStorage.getItem('.length, -1);
+    expect(JSON.parse(arg)).toBe('a"); alert(1); //');
+  });
+
+  it('escapes newlines in a key so the expression stays one statement', async () => {
+    const { client, exprs } = stubClient(null);
+    await removeLocalStorageKey(client, 'S1', 'a\nb');
+    expect(exprs[0]).toBe('localStorage.removeItem("a\\nb")');
+    expect(exprs[0]).not.toContain('\n');
+  });
+
+  it('escapes both key and value on write', async () => {
+    const { client, exprs } = stubClient();
+    await setLocalStorageKey(client, 'S1', 'k"1', 'v"2');
+    expect(exprs[0]).toBe('localStorage.setItem("k\\"1", "v\\"2")');
+  });
+
+  it('clears with a literal expression', async () => {
+    const { client, exprs } = stubClient();
+    await clearLocalStorage(client, 'S1');
+    expect(exprs[0]).toBe('localStorage.clear()');
+  });
+
+  it('getAll parses the JSON dump', async () => {
+    const { client } = stubClient('{"a":"1","b":"2"}');
+    await expect(getAllLocalStorage(client, 'S1')).resolves.toEqual({ a: '1', b: '2' });
+  });
+
+  it('getAll degrades to {} on unparseable output rather than throwing', async () => {
+    const { client } = stubClient('not json');
+    await expect(getAllLocalStorage(client, 'S1')).resolves.toEqual({});
+  });
+
+  it('getItem returning null (missing key) is passed through as null', async () => {
+    const { client } = stubClient(null);
+    await expect(getLocalStorageKey(client, 'S1', 'missing')).resolves.toBeNull();
+  });
+});
+
+describe('sessionStorage helpers mirror the localStorage ones', () => {
+  it('read / write / remove / clear all target sessionStorage', async () => {
+    const { client, exprs } = stubClient('v');
+    await getSessionStorageKey(client, 'S1', 'k');
+    await setSessionStorageKey(client, 'S1', 'k', 'v');
+    await removeSessionStorageKey(client, 'S1', 'k');
+    await clearSessionStorage(client, 'S1');
+    expect(exprs).toEqual([
+      'sessionStorage.getItem("k")',
+      'sessionStorage.setItem("k", "v")',
+      'sessionStorage.removeItem("k")',
+      'sessionStorage.clear()',
+    ]);
+    expect(exprs.some((e) => e.includes('localStorage'))).toBe(false);
+  });
+
+  it('getAll parses, and degrades to {} on garbage', async () => {
+    await expect(getAllSessionStorage(stubClient('{"s":"1"}').client, 'S1')).resolves.toEqual({ s: '1' });
+    await expect(getAllSessionStorage(stubClient('<html>').client, 'S1')).resolves.toEqual({});
+  });
+});

package/src/__tests__/tabs.test.ts

@@ -0,0 +1,183 @@
+/**
+ * tabs.ts — target filtering and the CDP command sequences for
+ * close/activate/frame-switch. Fake fetch + fake client; no browser.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { listTabs, newTab, closeTab, activateTab, switchToFrame } from '../browser/tabs.js';
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  vi.restoreAllMocks();
+});
+
+function stubFetch(body: unknown, init: ResponseInit = { status: 200 }): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(() => Promise.resolve(new Response(JSON.stringify(body), init)));
+  globalThis.fetch = fn as unknown as typeof fetch;
+  return fn;
+}
+
+/** Client stub that records calls and answers from a per-method table. */
+function stubClient(table: Record<string, unknown> = {}): {
+  client: CdpClient;
+  calls: Array<{ method: string; params: unknown; sid?: string }>;
+} {
+  const calls: Array<{ method: string; params: unknown; sid?: string }> = [];
+  const client = {
+    send: vi.fn(async (method: string, params: unknown, sid?: string) => {
+      calls.push({ method, params, sid });
+      const entry = table[method];
+      if (entry instanceof Error) throw entry;
+      return entry ?? {};
+    }),
+  } as unknown as CdpClient;
+  return { client, calls };
+}
+
+describe('listTabs', () => {
+  it('keeps only page targets, dropping service workers, iframes and extensions', async () => {
+    stubFetch([
+      { id: 'A', type: 'page', url: 'https://x.test' },
+      { id: 'B', type: 'service_worker', url: 'https://x.test/sw.js' },
+      { id: 'C', type: 'iframe', url: 'https://ads.test' },
+      { id: 'D', type: 'background_page', url: 'chrome-extension://abc' },
+      { id: 'E', type: 'page', url: 'about:blank' },
+    ]);
+    const tabs = await listTabs(9222);
+    expect(tabs.map((t) => t.id)).toEqual(['A', 'E']);
+  });
+
+  it('returns [] when Chrome reports no targets at all', async () => {
+    stubFetch([]);
+    await expect(listTabs(9222)).resolves.toEqual([]);
+  });
+
+  it('propagates a failed /json/list', async () => {
+    globalThis.fetch = vi.fn(() =>
+      Promise.resolve(new Response('', { status: 502, statusText: 'Bad Gateway' }))
+    ) as unknown as typeof fetch;
+    await expect(listTabs(9222)).rejects.toThrow('Failed to fetch targets: Bad Gateway');
+  });
+});
+
+describe('newTab', () => {
+  it('defaults to about:blank', async () => {
+    const fn = stubFetch({ id: 'T1', type: 'page' });
+    await newTab(9222);
+    expect(fn.mock.calls[0]![0]).toBe(
+      'http://127.0.0.1:9222/json/new?' + encodeURIComponent('about:blank')
+    );
+  });
+
+  it('passes an explicit url through, encoded', async () => {
+    const fn = stubFetch({ id: 'T1', type: 'page' });
+    await newTab(9222, 'https://x.test/a b?q=1');
+    expect(fn.mock.calls[0]![0]).toContain(encodeURIComponent('https://x.test/a b?q=1'));
+  });
+});
+
+describe('closeTab', () => {
+  it('sends Target.closeTarget for the given targetId', async () => {
+    const { client, calls } = stubClient();
+    await closeTab(client, 'S1', 'T9');
+    expect(calls).toEqual([{ method: 'Target.closeTarget', params: { targetId: 'T9' }, sid: undefined }]);
+  });
+});
+
+describe('activateTab', () => {
+  it('detaches the old session, activates, then re-attaches flat and returns the new sessionId', async () => {
+    const { client, calls } = stubClient({ 'Target.attachToTarget': { sessionId: 'S-NEW' } });
+    await expect(activateTab(client, 'S-OLD', 'T9')).resolves.toBe('S-NEW');
+    expect(calls.map((c) => c.method)).toEqual([
+      'Target.detachFromTarget',
+      'Target.activateTarget',
+      'Target.attachToTarget',
+    ]);
+    expect(calls[0]!.params).toEqual({ sessionId: 'S-OLD' });
+    expect(calls[2]!.params).toEqual({ targetId: 'T9', flatten: true });
+  });
+
+  it('skips the detach when there is no previous session', async () => {
+    const { client, calls } = stubClient({ 'Target.attachToTarget': { sessionId: 'S-NEW' } });
+    await activateTab(client, '', 'T9');
+    expect(calls.map((c) => c.method)).toEqual(['Target.activateTarget', 'Target.attachToTarget']);
+  });
+
+  it('tolerates a detach failure on an already-dead session', async () => {
+    const calls: string[] = [];
+    const client = {
+      send: vi.fn(async (method: string) => {
+        calls.push(method);
+        if (method === 'Target.detachFromTarget') throw new Error('No session with given id');
+        if (method === 'Target.attachToTarget') return { sessionId: 'S-NEW' };
+        return {};
+      }),
+    } as unknown as CdpClient;
+    await expect(activateTab(client, 'S-STALE', 'T9')).resolves.toBe('S-NEW');
+    expect(calls).toContain('Target.activateTarget');
+  });
+});
+
+describe('switchToFrame', () => {
+  const frameTreeWith = (url: string) => ({
+    frameTree: { childFrames: [{ frame: { id: 'F1', url, securityOrigin: 'https://f.test' } }] },
+  });
+
+  it('returns null url when the selector does not resolve to an IFRAME', async () => {
+    const { client, calls } = stubClient({
+      'Runtime.evaluate': { result: { result: { value: null } } },
+      'Page.getFrameTree': { frameTree: {} },
+    });
+    await expect(switchToFrame(client, 'S1', 'div.not-a-frame')).resolves.toEqual({ url: null, sessionId: null });
+    // The selector is embedded as a JSON string literal, never interpolated raw.
+    const expr = (calls[0]!.params as { expression: string }).expression;
+    expect(expr).toContain('document.querySelector("div.not-a-frame")');
+  });
+
+  it('JSON-escapes a selector containing quotes rather than breaking the expression', async () => {
+    const { client, calls } = stubClient({
+      'Runtime.evaluate': { result: { result: { value: null } } },
+      'Page.getFrameTree': { frameTree: {} },
+    });
+    await switchToFrame(client, 'S1', 'iframe[title="a\\"b"]');
+    const expr = (calls[0]!.params as { expression: string }).expression;
+    expect(expr).toContain(JSON.stringify('iframe[title="a\\"b"]'));
+  });
+
+  it('returns the frame src with null sessionId when no OOPIF target matches', async () => {
+    const { client, calls } = stubClient({
+      'Runtime.evaluate': { result: { result: { value: 'https://f.test/frame' } } },
+      'Page.getFrameTree': frameTreeWith('https://f.test/frame'),
+      'Target.getTargets': { targetInfos: [{ targetId: 'T1', type: 'page', url: 'https://x.test' }] },
+    });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: null });
+    expect(calls.map((c) => c.method)).not.toContain('Target.attachToTarget');
+  });
+
+  it('attaches flat to a matching OOPIF target and returns its sessionId', async () => {
+    const { client, calls } = stubClient({
+      'Runtime.evaluate': { result: { result: { value: 'https://f.test/frame' } } },
+      'Page.getFrameTree': frameTreeWith('https://f.test/frame'),
+      'Target.getTargets': {
+        targetInfos: [
+          { targetId: 'T-PAGE', type: 'page', url: 'https://f.test/frame' },
+          { targetId: 'T-OOPIF', type: 'iframe', url: 'https://f.test/frame' },
+        ],
+      },
+      'Target.attachToTarget': { sessionId: 'S-FRAME' },
+    });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: 'S-FRAME' });
+    const attach = calls.find((c) => c.method === 'Target.attachToTarget');
+    expect(attach!.params).toEqual({ targetId: 'T-OOPIF', flatten: true });
+  });
+
+  it('returns the src with null sessionId when the frame tree has no match', async () => {
+    const { client, calls } = stubClient({
+      'Runtime.evaluate': { result: { result: { value: 'https://f.test/frame' } } },
+      'Page.getFrameTree': frameTreeWith('https://other.test/elsewhere'),
+    });
+    await expect(switchToFrame(client, 'S1', 'iframe')).resolves.toEqual({ url: 'https://f.test/frame', sessionId: null });
+    expect(calls.map((c) => c.method)).not.toContain('Target.getTargets');
+  });
+});

package/src/browser/browser.ts

@@ -8,11 +8,15 @@ import type { BrowserConfig, CdpTarget } from './types.js';
 import { CHROME_EXECUTABLES } from './types.js';
 import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
 import { setupDialogAutoHandling } from './dialog.js';
+import { loadActivePortInfo } from './ref-cache.js';
 
 const DEFAULT_PORT = 9222;
 const LAUNCH_TIMEOUT = 10_000;
 const POLL_INTERVAL = 200;
 const BROWSER_CLOSE_TIMEOUT_MS = 3000;
+// A cross-process persisted PID older than this is not trusted for the
+// SIGKILL fallback in closeBrowser() — see the call site for why.
+const PERSISTED_PID_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 // Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
 // closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
@@ -20,6 +24,19 @@ const BROWSER_CLOSE_TIMEOUT_MS = 3000;
 // to (already-running browser) are never recorded here — we only ever kill
 // processes we launched ourselves.
 const launchedPids = new Map<number, number>();
+// userDataDir per launched port — informational, persisted alongside the pid
+// so a later process could clean up the temp profile dir too if ever needed.
+const launchedUserDataDirs = new Map<number, string>();
+
+/** PID of the Chrome instance *this process* launched on `port`, if any. */
+export function getLaunchedPid(port: number): number | undefined {
+  return launchedPids.get(port);
+}
+
+/** userDataDir of the Chrome instance *this process* launched on `port`, if any. */
+export function getLaunchedUserDataDir(port: number): string | undefined {
+  return launchedUserDataDirs.get(port);
+}
 
 function findChrome(executablePath?: string): string {
   if (executablePath) {
@@ -185,9 +202,13 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     stdio: 'ignore',
   });
   child.unref();
-  if (child.pid) launchedPids.set(port, child.pid);
+  if (child.pid) {
+    launchedPids.set(port, child.pid);
+    launchedUserDataDirs.set(port, userDataDir);
+  }
 
-  const deadline = Date.now() + LAUNCH_TIMEOUT;
+  const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
+  const deadline = Date.now() + launchTimeout;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL);
     if (await isPortOpen(port)) {
@@ -204,12 +225,12 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
   if (await isTcpPortOpen(port)) {
     throw new Error(
-      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${LAUNCH_TIMEOUT}ms). ` +
+      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
       `Free the port or pass a different one.`
     );
   }
 
-  throw new Error(`Chrome failed to start on port ${port} within ${LAUNCH_TIMEOUT}ms`);
+  throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
 }
 
 export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {
@@ -277,12 +298,43 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
     // fall through to PID-kill fallback below
   }
 
-  const pid = launchedPids.get(port);
-  if (pid === undefined) return; // not a process we launched — nothing to kill
+  let pid = launchedPids.get(port);
+  if (pid === undefined) {
+    // Fresh process (each CLI invocation is its own node process — see
+    // module header) — launchedPids is per-process and empty here even
+    // though a prior `open` in a DIFFERENT process launched this Chrome.
+    // Fall back to the PID that process persisted via saveActivePort().
+    try {
+      const persisted = await loadActivePortInfo();
+      if (persisted && persisted.port === port && persisted.launched && persisted.pid) {
+        // Bound how far we trust a cross-process PID: if the Chrome we
+        // launched died outside this flow (OOM-killed, host slept, etc.)
+        // without active-port.json ever being cleared, the OS can recycle
+        // that PID for an unrelated process. There is no cmdline/start-time
+        // check available portably, so a coarse age bound is the practical
+        // guard — a PID persisted more than a day ago is far more likely to
+        // be stale/reused than to still be the same live Chrome.
+        const age = persisted.savedAt !== undefined ? Date.now() - persisted.savedAt : undefined;
+        if (age === undefined || age <= PERSISTED_PID_MAX_AGE_MS) {
+          pid = persisted.pid;
+        }
+      }
+    } catch {
+      // best-effort — fall through to "nothing to kill" below
+    }
+  }
+  if (pid === undefined) return; // not a process we launched, or too stale to trust — nothing to kill
   launchedPids.delete(port);
 
+  // Liveness-check before every SIGKILL (not just the safety-net path below)
+  // — process.kill(pid, 0) throws ESRCH if the PID is no longer running,
+  // which also catches the case where the PID has already been recycled by
+  // an unrelated process that happens to have exited too.
   if (!gracefullyClosed) {
-    try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+    try {
+      process.kill(pid, 0);
+      process.kill(pid, 'SIGKILL');
+    } catch { /* already exited, or never was — nothing to do */ }
     return;
   }
 

package/src/browser/cdp.ts

@@ -1,13 +1,41 @@
 import { WebSocket } from 'ws';
 import type { CdpCommand, CdpResponse, CdpTarget } from './types.js';
 
+// send() had no timeout of its own — a command whose response never arrives
+// (wedged/crashed renderer, dropped socket that never fires 'close') left a
+// pendingCommands entry forever, hanging whatever awaited it (and, since
+// most CLI actions await a single send(), the whole CLI process). Ad-hoc
+// timeouts were previously patched in at a handful of call sites (e.g.
+// actions.ts's evaluateJs) instead of here, so most commands had no
+// protection at all. This is the default for every send() unless a caller
+// passes 0 (no timeout) or a different value.
+export const DEFAULT_CDP_SEND_TIMEOUT_MS = 30_000;
+
 export class CdpClient {
   private ws: WebSocket | null = null;
-  private pendingCommands = new Map<number, { resolve: (r: CdpResponse) => void; reject: (e: Error) => void }>();
+  private pendingCommands = new Map<number, { resolve: (r: CdpResponse) => void; reject: (e: Error) => void; timer?: ReturnType<typeof setTimeout> }>();
   private eventListeners = new Map<string, Set<(params: Record<string, unknown>, sessionId?: string) => void>>();
   private nextId = 1;
   private connected = false;
 
+  constructor() {
+    // Target.targetCrashed/targetDestroyed fire over the same WS connection
+    // as command responses, but a crashed renderer's connection can otherwise
+    // sit open with no 'close'/'error' event ever firing — flush pending
+    // commands here so send() doesn't have to wait out its own timeout.
+    this.on('Target.targetCrashed', () => this.flushPending(new Error('CDP target crashed')));
+    this.on('Target.targetDestroyed', () => this.flushPending(new Error('CDP target destroyed')));
+  }
+
+  private flushPending(err: Error): void {
+    this.connected = false;
+    for (const { reject: r, timer } of this.pendingCommands.values()) {
+      if (timer) clearTimeout(timer);
+      r(err);
+    }
+    this.pendingCommands.clear();
+  }
+
   async connect(wsUrl: string): Promise<void> {
     return new Promise((resolve, reject) => {
       this.ws = new WebSocket(wsUrl);
@@ -22,18 +50,12 @@ export class CdpClient {
           reject(err);
         } else {
           // Post-connect: flush all pending commands — 'close' may not fire on all platforms
-          this.connected = false;
-          for (const { reject: r } of this.pendingCommands.values()) r(err);
-          this.pendingCommands.clear();
+          this.flushPending(err instanceof Error ? err : new Error(String(err)));
         }
       });
 
       this.ws.on('close', () => {
-        this.connected = false;
-        for (const { reject: r } of this.pendingCommands.values()) {
-          r(new Error('CDP connection closed'));
-        }
-        this.pendingCommands.clear();
+        this.flushPending(new Error('CDP connection closed'));
       });
 
       this.ws.on('message', (data) => {
@@ -62,7 +84,12 @@ export class CdpClient {
     });
   }
 
-  send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T> {
+  send<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+    sessionId?: string,
+    timeoutMs: number = DEFAULT_CDP_SEND_TIMEOUT_MS
+  ): Promise<T> {
     return new Promise((resolve, reject) => {
       if (!this.ws || !this.connected) {
         reject(new Error('CDP not connected'));
@@ -76,12 +103,24 @@ export class CdpClient {
       const id = this.nextId++;
       const cmd: CdpCommand = { id, method, params };
       if (sessionId) cmd.sessionId = sessionId;
+
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          this.pendingCommands.delete(id);
+          reject(new Error(`CDP command "${method}" timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+
       this.pendingCommands.set(id, {
-        resolve: (r) => resolve((r.result ?? {}) as T),
-        reject,
+        resolve: (r) => { if (timer) clearTimeout(timer); resolve((r.result ?? {}) as T); },
+        reject: (e) => { if (timer) clearTimeout(timer); reject(e); },
+        timer,
       });
       this.ws.send(JSON.stringify(cmd), (err) => {
         if (err) {
+          if (timer) clearTimeout(timer);
           this.pendingCommands.delete(id);
           reject(err);
         }
@@ -120,9 +159,7 @@ export class CdpClient {
   }
 
   close(): void {
-    this.connected = false;
-    for (const { reject: r } of this.pendingCommands.values()) r(new Error('CDP connection closed'));
-    this.pendingCommands.clear();
+    this.flushPending(new Error('CDP connection closed'));
     this.ws?.close();
     this.ws = null;
     this.eventListeners.clear();

package/src/browser/ref-cache.ts

@@ -97,14 +97,29 @@ export async function clearRefCache(): Promise<void> {
  * falling back to the hardcoded default port and launching/attaching to a
  * second, unrelated Chrome instance.
  */
-export async function saveActivePort(port: number, opts?: { launched?: boolean }): Promise<void> {
+export async function saveActivePort(
+  port: number,
+  opts?: { launched?: boolean; pid?: number; userDataDir?: string }
+): Promise<void> {
   try {
     await mkdir(CACHE_DIR, { recursive: true });
     // `launched` records provenance: true = monobrowse spawned this Chrome
     // (safe to Browser.close later); false = attached to a browser someone
     // else owns (must never be killed). Absent (old files) reads as launched
     // — matches pre-flag behavior where every persisted port came from open.
-    await writeFile(PORT_FILE, JSON.stringify({ port, launched: opts?.launched !== false, savedAt: Date.now() }));
+    //
+    // `pid`/`userDataDir` are persisted so a LATER, fresh CLI process (each
+    // command is its own node process — see module header) can still find
+    // and kill the Chrome this one launched. Without this, closeBrowser()'s
+    // PID-kill fallback can never fire outside the launching process, since
+    // the in-memory launchedPids Map (browser.ts) is empty there.
+    await writeFile(PORT_FILE, JSON.stringify({
+      port,
+      launched: opts?.launched !== false,
+      pid: opts?.pid,
+      userDataDir: opts?.userDataDir,
+      savedAt: Date.now(),
+    }));
   } catch {
     // Best-effort — persistence failure just means the next process falls
     // back to the hardcoded default port, matching prior behavior.
@@ -126,13 +141,21 @@ export async function loadActivePort(): Promise<number | null> {
   return (await loadActivePortInfo())?.port ?? null;
 }
 
-/** Load the persisted active port with its provenance flag. */
-export async function loadActivePortInfo(): Promise<{ port: number; launched: boolean } | null> {
+/** Load the persisted active port with its provenance flag, PID, user-data-dir, and save timestamp. */
+export async function loadActivePortInfo(): Promise<
+  { port: number; launched: boolean; pid?: number; userDataDir?: string; savedAt?: number } | null
+> {
   try {
     const raw = await readFile(PORT_FILE, 'utf8');
-    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown };
+    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown; pid?: unknown; userDataDir?: unknown; savedAt?: unknown };
     if (typeof data.port === 'number' && Number.isInteger(data.port) && data.port >= 1024 && data.port <= 65535) {
-      return { port: data.port, launched: data.launched !== false };
+      return {
+        port: data.port,
+        launched: data.launched !== false,
+        pid: typeof data.pid === 'number' && Number.isInteger(data.pid) && data.pid > 0 ? data.pid : undefined,
+        userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
+        savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
+      };
     }
     return null;
   } catch {

package/src/browser/snapshot.ts

@@ -217,6 +217,17 @@ export async function getObjectIdForRef(
   return result.object?.objectId ?? null;
 }
 
+/**
+ * Returns the element's content box — but `x`/`y` are the CENTER point
+ * (averaged across all four corners of CDP's content quad), not the
+ * top-left origin a `getBoundingClientRect()`-style box normally implies.
+ * This is deliberate: every caller in this file (clickElement, fillElement,
+ * hoverElement, dragElement, ...) uses box.x/box.y directly as the
+ * interaction target, which should land at the element's center. Do NOT
+ * add width/2 or height/2 to these values — that double-offsets away from
+ * the element (see issue #15). If you need the true top-left origin, derive
+ * it as `x - width / 2, y - height / 2`.
+ */
 export async function getElementBox(
   client: CdpClient,
   sessionId: string,