@jackwener/opencli 1.3.3 → 1.4.0

package/src/browser/cdp.ts

@@ -9,6 +9,8 @@
  */
 
 import { WebSocket, type RawData } from 'ws';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 import { wrapForEval } from './utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
@@ -23,6 +25,7 @@ import {
   networkRequestsJs,
   waitForDomStableJs,
 } from './dom-helpers.js';
+import { isRecord, saveBase64ToFile } from '../utils.js';
 
 export interface CDPTarget {
   type?: string;
@@ -42,7 +45,7 @@ interface RuntimeEvaluateResult {
   };
 }
 
-const CDP_SEND_TIMEOUT = 30_000; // 30s per command
+const CDP_SEND_TIMEOUT = 30_000;
 
 export class CDPBridge {
   private _ws: WebSocket | null = null;
@@ -51,15 +54,14 @@ export class CDPBridge {
   private _eventListeners = new Map<string, Set<(params: unknown) => void>>();
 
   async connect(opts?: { timeout?: number; workspace?: string }): Promise<IPage> {
+    if (this._ws) throw new Error('CDPBridge is already connected. Call close() before reconnecting.');
+
     const endpoint = process.env.OPENCLI_CDP_ENDPOINT;
     if (!endpoint) throw new Error('OPENCLI_CDP_ENDPOINT is not set');
 
-    // If it's a direct ws:// URL, use it. Otherwise, fetch the /json endpoint to find a page.
     let wsUrl = endpoint;
     if (endpoint.startsWith('http')) {
-      const res = await fetch(`${endpoint.replace(/\/$/, '')}/json`);
-      if (!res.ok) throw new Error(`Failed to fetch CDP targets: ${res.statusText}`);
-      const targets = await res.json() as CDPTarget[];
+      const targets = await fetchJsonDirect(`${endpoint.replace(/\/$/, '')}/json`) as CDPTarget[];
       const target = selectCDPTarget(targets);
       if (!target || !target.webSocketDebuggerUrl) {
         throw new Error('No inspectable targets found at CDP endpoint');
@@ -69,19 +71,16 @@ export class CDPBridge {
 
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(wsUrl);
-      const timeoutMs = (opts?.timeout ?? 10) * 1000; // opts.timeout is in seconds
+      const timeoutMs = (opts?.timeout ?? 10) * 1000;
       const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
 
       ws.on('open', async () => {
         clearTimeout(timeout);
         this._ws = ws;
-        // Register stealth script to run before any page JS on every navigation.
         try {
           await this.send('Page.enable');
           await this.send('Page.addScriptToEvaluateOnNewDocument', { source: generateStealthJs() });
-        } catch {
-          // Non-fatal: stealth is best-effort
-        }
+        } catch {}
         resolve(new CDPPage(this));
       });
 
@@ -93,7 +92,6 @@ export class CDPBridge {
       ws.on('message', (data: RawData) => {
         try {
           const msg = JSON.parse(data.toString());
-          // Handle command responses
           if (msg.id && this._pending.has(msg.id)) {
             const entry = this._pending.get(msg.id)!;
             clearTimeout(entry.timer);
@@ -104,16 +102,13 @@ export class CDPBridge {
               entry.resolve(msg.result);
             }
           }
-          // Handle CDP events
           if (msg.method) {
             const listeners = this._eventListeners.get(msg.method);
             if (listeners) {
               for (const fn of listeners) fn(msg.params);
             }
           }
-        } catch {
-          // ignore parsing errors
-        }
+        } catch {}
       });
     });
   }
@@ -131,7 +126,6 @@ export class CDPBridge {
     this._eventListeners.clear();
   }
 
-  /** Send a CDP command with timeout guard (P0 fix #4) */
   async send(method: string, params: Record<string, unknown> = {}, timeoutMs: number = CDP_SEND_TIMEOUT): Promise<unknown> {
     if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
       throw new Error('CDP connection is not open');
@@ -147,19 +141,19 @@ export class CDPBridge {
     });
   }
 
-  /** Listen for a CDP event */
   on(event: string, handler: (params: unknown) => void): void {
     let set = this._eventListeners.get(event);
-    if (!set) { set = new Set(); this._eventListeners.set(event, set); }
+    if (!set) {
+      set = new Set();
+      this._eventListeners.set(event, set);
+    }
     set.add(handler);
   }
 
-  /** Remove a CDP event listener */
   off(event: string, handler: (params: unknown) => void): void {
     this._eventListeners.get(event)?.delete(handler);
   }
 
-  /** Wait for a CDP event to fire (one-shot) */
   waitForEvent(event: string, timeoutMs: number = 15_000): Promise<unknown> {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -177,17 +171,17 @@ export class CDPBridge {
 }
 
 class CDPPage implements IPage {
+  private _pageEnabled = false;
   constructor(private bridge: CDPBridge) {}
 
-  /** Navigate with proper load event waiting (P1 fix #3) */
   async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
-    await this.bridge.send('Page.enable');
-    const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
-      .catch(() => {}); // Don't fail if event times out
+    if (!this._pageEnabled) {
+      await this.bridge.send('Page.enable');
+      this._pageEnabled = true;
+    }
+    const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => {});
     await this.bridge.send('Page.navigate', { url });
     await loadPromise;
-    // Smart settle: use DOM stability detection instead of fixed sleep.
-    // settleMs is now a timeout cap (default 1000ms), not a fixed wait.
     if (options?.waitUntil !== 'none') {
       const maxMs = options?.settleMs ?? 1000;
       await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
@@ -199,7 +193,7 @@ class CDPPage implements IPage {
     const result = await this.bridge.send('Runtime.evaluate', {
       expression,
       returnByValue: true,
-      awaitPromise: true
+      awaitPromise: true,
     }) as RuntimeEvaluateResult;
     if (result.exceptionDetails) {
       throw new Error('Evaluate error: ' + (result.exceptionDetails.exception?.description || 'Unknown exception'));
@@ -212,7 +206,7 @@ class CDPPage implements IPage {
     const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
     const domain = opts.domain;
     return domain
-      ? cookies.filter((cookie): cookie is BrowserCookie => isCookie(cookie) && cookie.domain.includes(domain))
+      ? cookies.filter((cookie): cookie is BrowserCookie => isCookie(cookie) && matchesCookieDomain(cookie.domain, domain))
       : cookies;
   }
 
@@ -228,8 +222,6 @@ class CDPPage implements IPage {
     return this.evaluate(snapshotJs);
   }
 
-  // ── Shared DOM operations (P1 fix #5 — using dom-helpers.ts) ──
-
   async click(ref: string): Promise<void> {
     await this.evaluate(clickJs(ref));
   }
@@ -252,12 +244,12 @@ class CDPPage implements IPage {
 
   async wait(options: number | WaitOptions): Promise<void> {
     if (typeof options === 'number') {
-      await new Promise(resolve => setTimeout(resolve, options * 1000));
+      await new Promise((resolve) => setTimeout(resolve, options * 1000));
       return;
     }
     if (typeof options.time === 'number') {
       const waitTime = options.time;
-      await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+      await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
       return;
     }
     if (options.text) {
@@ -266,8 +258,6 @@ class CDPPage implements IPage {
     }
   }
 
-  // ── Implemented methods (P1 fix #2) ──
-
   async scroll(direction: string = 'down', amount: number = 500): Promise<void> {
     await this.evaluate(scrollJs(direction, amount));
   }
@@ -286,11 +276,7 @@ class CDPPage implements IPage {
     });
     const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
     if (options.path) {
-      const fs = await import('node:fs');
-      const path = await import('node:path');
-      const dir = path.dirname(options.path);
-      await fs.promises.mkdir(dir, { recursive: true });
-      await fs.promises.writeFile(options.path, Buffer.from(base64, 'base64'));
+      await saveBase64ToFile(base64, options.path);
     }
     return base64;
   }
@@ -335,10 +321,6 @@ class CDPPage implements IPage {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function isCookie(value: unknown): value is BrowserCookie {
   return isRecord(value)
     && typeof value.name === 'string'
@@ -346,7 +328,12 @@ function isCookie(value: unknown): value is BrowserCookie {
     && typeof value.domain === 'string';
 }
 
-// ── CDP target selection (unchanged) ──
+function matchesCookieDomain(cookieDomain: string, targetDomain: string): boolean {
+  const normalizedCookieDomain = cookieDomain.replace(/^\./, '').toLowerCase();
+  const normalizedTargetDomain = targetDomain.replace(/^\./, '').toLowerCase();
+  return normalizedTargetDomain === normalizedCookieDomain
+    || normalizedTargetDomain.endsWith(`.${normalizedCookieDomain}`);
+}
 
 function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined {
   const preferredPattern = compilePreferredPattern(process.env.OPENCLI_CDP_TARGET);
@@ -420,3 +407,31 @@ export const __test__ = {
   selectCDPTarget,
   scoreCDPTarget,
 };
+
+function fetchJsonDirect(url: string): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const request = (parsed.protocol === 'https:' ? httpsRequest : httpRequest)(parsed, (res) => {
+      const statusCode = res.statusCode ?? 0;
+      if (statusCode < 200 || statusCode >= 300) {
+        res.resume();
+        reject(new Error(`Failed to fetch CDP targets: HTTP ${statusCode}`));
+        return;
+      }
+
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    });
+
+    request.on('error', reject);
+    request.setTimeout(10_000, () => request.destroy(new Error('Timed out fetching CDP targets')));
+    request.end();
+  });
+}

package/src/browser/dom-snapshot.test.ts

@@ -247,3 +247,45 @@ describe('getFormStateJs', () => {
     expect(js).toContain('data-opencli-ref');
   });
 });
+
+describe('Search Element Detection', () => {
+  it('includes SEARCH_INDICATORS set', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('SEARCH_INDICATORS');
+    expect(js).toContain('search');
+    expect(js).toContain('magnify');
+    expect(js).toContain('glass');
+  });
+
+  it('includes hasFormControlDescendant function', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('hasFormControlDescendant');
+    expect(js).toContain('input');
+    expect(js).toContain('select');
+    expect(js).toContain('textarea');
+  });
+
+  it('includes isSearchElement function', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('isSearchElement');
+    expect(js).toContain('className');
+    expect(js).toContain('data-');
+  });
+
+  it('checks label wrapper detection in isInteractive', () => {
+    const js = generateSnapshotJs();
+    // Label elements without "for" attribute should check for form control descendants
+    expect(js).toContain('hasFormControlDescendant(el, 2)');
+  });
+
+  it('checks span wrapper detection in isInteractive', () => {
+    const js = generateSnapshotJs();
+    // Span elements should check for form control descendants
+    expect(js).toContain("tag === 'span'");
+  });
+
+  it('integrates search element detection into isInteractive', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('isSearchElement(el)');
+  });
+});

package/src/browser/dom-snapshot.ts

@@ -26,7 +26,7 @@
 
 // ─── Types ───────────────────────────────────────────────────────────
 
-export interface SnapshotOptions {
+export interface DomSnapshotOptions {
   /** Extra pixels beyond viewport to include (default 800) */
   viewportExpand?: number;
   /** Maximum DOM depth to traverse (default 50) */
@@ -175,7 +175,7 @@ export function getFormStateJs(): string {
  * - `|iframe|` — iframe content
  * - `|table|` — markdown table rendering
  */
-export function generateSnapshotJs(opts: SnapshotOptions = {}): string {
+export function generateSnapshotJs(opts: DomSnapshotOptions = {}): string {
   const viewportExpand = opts.viewportExpand ?? 800;
   const maxDepth = Math.max(1, Math.min(opts.maxDepth ?? 50, 200));
   const interactiveOnly = opts.interactiveOnly ?? false;
@@ -271,6 +271,13 @@ export function generateSnapshotJs(opts: SnapshotOptions = {}): string {
 
   const AD_SELECTOR_RE = /\\b(ad[_-]?(?:banner|container|wrapper|slot|unit|block|frame|leaderboard|sidebar)|google[_-]?ad|sponsored|adsbygoogle|banner[_-]?ad)\\b/i;
 
+  // Search element indicators for heuristic detection
+  const SEARCH_INDICATORS = new Set([
+    'search', 'magnify', 'glass', 'lookup', 'find', 'query',
+    'search-icon', 'search-btn', 'search-button', 'searchbox',
+    'fa-search', 'icon-search', 'btn-search',
+  ]);
+
   // ── Viewport & Layout Helpers ──────────────────────────────────────
 
   const vw = window.innerWidth;
@@ -339,19 +346,65 @@ export function generateSnapshotJs(opts: SnapshotOptions = {}): string {
 
   // ── Interactivity Detection ────────────────────────────────────────
 
+  // Check if element contains a form control within limited depth (handles label/span wrappers)
+  function hasFormControlDescendant(el, maxDepth = 2) {
+    if (maxDepth <= 0) return false;
+    for (const child of el.children || []) {
+      const tag = child.tagName?.toLowerCase();
+      if (tag === 'input' || tag === 'select' || tag === 'textarea') return true;
+      if (hasFormControlDescendant(child, maxDepth - 1)) return true;
+    }
+    return false;
+  }
+
   function isInteractive(el) {
     const tag = el.tagName.toLowerCase();
     if (INTERACTIVE_TAGS.has(tag)) {
-      if (tag === 'label' && el.hasAttribute('for')) return false;
+      // Skip labels that proxy via "for" to avoid double-activating external inputs
+      if (tag === 'label') {
+        if (el.hasAttribute('for')) return false;
+        // Detect labels that wrap form controls up to two levels deep (label > span > input)
+        if (hasFormControlDescendant(el, 2)) return true;
+      }
       if (el.disabled && (tag === 'button' || tag === 'input')) return false;
       return true;
     }
+    // Span wrappers for UI components - check if they contain form controls
+    if (tag === 'span') {
+      if (hasFormControlDescendant(el, 2)) return true;
+    }
     const role = el.getAttribute('role');
     if (role && INTERACTIVE_ROLES.has(role)) return true;
     if (el.hasAttribute('onclick') || el.hasAttribute('onmousedown') || el.hasAttribute('ontouchstart')) return true;
     if (el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1') return true;
     try { if (window.getComputedStyle(el).cursor === 'pointer') return true; } catch {}
     if (el.isContentEditable && el.getAttribute('contenteditable') !== 'false') return true;
+    // Search element heuristic detection
+    if (isSearchElement(el)) return true;
+    return false;
+  }
+
+  function isSearchElement(el) {
+    // Check class names for search indicators
+    const className = el.className?.toLowerCase() || '';
+    const classes = className.split(/\\s+/).filter(Boolean);
+    for (const cls of classes) {
+      const cleaned = cls.replace(/[^a-z0-9-]/g, '');
+      if (SEARCH_INDICATORS.has(cleaned)) return true;
+    }
+    // Check id for search indicators
+    const id = el.id?.toLowerCase() || '';
+    const cleanedId = id.replace(/[^a-z0-9-]/g, '');
+    if (SEARCH_INDICATORS.has(cleanedId)) return true;
+    // Check data-* attributes for search functionality
+    for (const attr of el.attributes || []) {
+      if (attr.name.startsWith('data-')) {
+        const value = attr.value.toLowerCase();
+        for (const kw of SEARCH_INDICATORS) {
+          if (value.includes(kw)) return true;
+        }
+      }
+    }
     return false;
   }
 

package/src/browser/index.ts

@@ -6,12 +6,12 @@
  */
 
 export { Page } from './page.js';
-export { BrowserBridge, BrowserBridge as PlaywrightMCP } from './mcp.js';
+export { BrowserBridge } from './mcp.js';
 export { CDPBridge } from './cdp.js';
 export { isDaemonRunning } from './daemon-client.js';
 export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 export { generateStealthJs } from './stealth.js';
-export type { SnapshotOptions } from './dom-snapshot.js';
+export type { DomSnapshotOptions } from './dom-snapshot.js';
 
 import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
 import { __test__ as cdpTest } from './cdp.js';

package/src/browser/mcp.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs';
 import type { IPage } from '../types.js';
 import { Page } from './page.js';
 import { isDaemonRunning, isExtensionConnected } from './daemon-client.js';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
 
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 
@@ -112,10 +113,7 @@ export class BrowserBridge {
     throw new Error(
       'Failed to start opencli daemon. Try running manually:\n' +
       `  node ${daemonPath}\n` +
-      'Make sure port 19825 is available.',
+      `Make sure port ${DEFAULT_DAEMON_PORT} is available.`,
     );
   }
 }
-
-/** @deprecated Use BrowserBridge instead */
-export const PlaywrightMCP = BrowserBridge;

package/src/browser/page.ts

@@ -14,6 +14,7 @@ import { formatSnapshot } from '../snapshotFormatter.js';
 import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 import { sendCommand } from './daemon-client.js';
 import { wrapForEval } from './utils.js';
+import { saveBase64ToFile } from '../utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { generateStealthJs } from './stealth.js';
 import {
@@ -36,20 +37,23 @@ export class Page implements IPage {
   /** Active tab ID, set after navigate and used in all subsequent commands */
   private _tabId: number | undefined;
 
-  /** Helper: spread tabId into command params if we have one */
-  private _tabOpt(): { tabId: number } | Record<string, never> {
-    return this._tabId !== undefined ? { tabId: this._tabId } : {};
+  /** Helper: spread workspace into command params */
+  private _wsOpt(): { workspace: string } {
+    return { workspace: this.workspace };
   }
 
-  private _workspaceOpt(): { workspace: string } {
-    return { workspace: this.workspace };
+  /** Helper: spread workspace + tabId into command params */
+  private _cmdOpts(): Record<string, unknown> {
+    return {
+      workspace: this.workspace,
+      ...(this._tabId !== undefined && { tabId: this._tabId }),
+    };
   }
 
   async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     const result = await sendCommand('navigate', {
       url,
-      ...this._workspaceOpt(),
-      ...this._tabOpt(),
+      ...this._cmdOpts(),
     }) as { tabId?: number };
     // Remember the tabId for subsequent exec calls
     if (result?.tabId) {
@@ -59,8 +63,7 @@ export class Page implements IPage {
     try {
       await sendCommand('exec', {
         code: generateStealthJs(),
-        ...this._workspaceOpt(),
-        ...this._tabOpt(),
+        ...this._cmdOpts(),
       });
     } catch {
       // Non-fatal: stealth is best-effort
@@ -71,8 +74,7 @@ export class Page implements IPage {
       const maxMs = options?.settleMs ?? 1000;
       await sendCommand('exec', {
         code: waitForDomStableJs(maxMs, Math.min(500, maxMs)),
-        ...this._workspaceOpt(),
-        ...this._tabOpt(),
+        ...this._cmdOpts(),
       });
     }
   }
@@ -80,7 +82,7 @@ export class Page implements IPage {
   /** Close the automation window in the extension */
   async closeWindow(): Promise<void> {
     try {
-      await sendCommand('close-window', { ...this._workspaceOpt() });
+      await sendCommand('close-window', { ...this._wsOpt() });
     } catch {
       // Window may already be closed or daemon may be down
     }
@@ -88,11 +90,11 @@ export class Page implements IPage {
 
   async evaluate(js: string): Promise<unknown> {
     const code = wrapForEval(js);
-    return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    return sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async getCookies(opts: { domain?: string; url?: string } = {}): Promise<BrowserCookie[]> {
-    const result = await sendCommand('cookies', { ...this._workspaceOpt(), ...opts });
+    const result = await sendCommand('cookies', { ...this._wsOpt(), ...opts });
     return Array.isArray(result) ? result : [];
   }
 
@@ -108,7 +110,7 @@ export class Page implements IPage {
     });
 
     try {
-      const result = await sendCommand('exec', { code: snapshotJs, ...this._workspaceOpt(), ...this._tabOpt() });
+      const result = await sendCommand('exec', { code: snapshotJs, ...this._cmdOpts() });
       // The advanced engine already produces a clean, pruned, LLM-friendly output.
       // Do NOT pass through formatSnapshot — its format is incompatible.
       return result;
@@ -148,7 +150,7 @@ export class Page implements IPage {
         return buildTree(document.body, 0);
       })()
     `;
-    const raw = await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    const raw = await sendCommand('exec', { code, ...this._cmdOpts() });
     if (opts.raw) return raw;
     if (typeof raw === 'string') return formatSnapshot(raw, opts);
     return raw;
@@ -156,27 +158,27 @@ export class Page implements IPage {
 
   async click(ref: string): Promise<void> {
     const code = clickJs(ref);
-    await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    await sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async typeText(ref: string, text: string): Promise<void> {
     const code = typeTextJs(ref, text);
-    await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    await sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async pressKey(key: string): Promise<void> {
     const code = pressKeyJs(key);
-    await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    await sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async scrollTo(ref: string): Promise<unknown> {
     const code = scrollToRefJs(ref);
-    return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    return sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async getFormState(): Promise<Record<string, unknown>> {
     const code = getFormStateJs();
-    return (await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() })) as Record<string, unknown>;
+    return (await sendCommand('exec', { code, ...this._cmdOpts() })) as Record<string, unknown>;
   }
 
   async wait(options: number | WaitOptions): Promise<void> {
@@ -184,42 +186,42 @@ export class Page implements IPage {
       await new Promise(resolve => setTimeout(resolve, options * 1000));
       return;
     }
-    if (options.time) {
+    if (typeof options.time === 'number') {
       await new Promise(resolve => setTimeout(resolve, options.time! * 1000));
       return;
     }
     if (options.text) {
       const timeout = (options.timeout ?? 30) * 1000;
       const code = waitForTextJs(options.text, timeout);
-      await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+      await sendCommand('exec', { code, ...this._cmdOpts() });
     }
   }
 
   async tabs(): Promise<unknown[]> {
-    const result = await sendCommand('tabs', { op: 'list', ...this._workspaceOpt() });
+    const result = await sendCommand('tabs', { op: 'list', ...this._wsOpt() });
     return Array.isArray(result) ? result : [];
   }
 
   async closeTab(index?: number): Promise<void> {
-    await sendCommand('tabs', { op: 'close', ...this._workspaceOpt(), ...(index !== undefined ? { index } : {}) });
+    await sendCommand('tabs', { op: 'close', ...this._wsOpt(), ...(index !== undefined ? { index } : {}) });
     // Invalidate cached tabId — the closed tab might have been our active one.
     // We can't know for sure (close-by-index doesn't return tabId), so reset.
     this._tabId = undefined;
   }
 
   async newTab(): Promise<void> {
-    const result = await sendCommand('tabs', { op: 'new', ...this._workspaceOpt() }) as { tabId?: number };
+    const result = await sendCommand('tabs', { op: 'new', ...this._wsOpt() }) as { tabId?: number };
     if (result?.tabId) this._tabId = result.tabId;
   }
 
   async selectTab(index: number): Promise<void> {
-    const result = await sendCommand('tabs', { op: 'select', index, ...this._workspaceOpt() }) as { selected?: number };
+    const result = await sendCommand('tabs', { op: 'select', index, ...this._wsOpt() }) as { selected?: number };
     if (result?.selected) this._tabId = result.selected;
   }
 
   async networkRequests(includeStatic: boolean = false): Promise<unknown[]> {
     const code = networkRequestsJs(includeStatic);
-    const result = await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    const result = await sendCommand('exec', { code, ...this._cmdOpts() });
     return Array.isArray(result) ? result : [];
   }
 
@@ -241,19 +243,14 @@ export class Page implements IPage {
    */
   async screenshot(options: ScreenshotOptions = {}): Promise<string> {
     const base64 = await sendCommand('screenshot', {
-      ...this._workspaceOpt(),
+      ...this._cmdOpts(),
       format: options.format,
       quality: options.quality,
       fullPage: options.fullPage,
-      ...this._tabOpt(),
     }) as string;
 
     if (options.path) {
-      const fs = await import('node:fs');
-      const path = await import('node:path');
-      const dir = path.dirname(options.path);
-      await fs.promises.mkdir(dir, { recursive: true });
-      await fs.promises.writeFile(options.path, Buffer.from(base64, 'base64'));
+      await saveBase64ToFile(base64, options.path);
     }
 
     return base64;
@@ -261,14 +258,14 @@ export class Page implements IPage {
 
   async scroll(direction: string = 'down', amount: number = 500): Promise<void> {
     const code = scrollJs(direction, amount);
-    await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    await sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async autoScroll(options: { times?: number; delayMs?: number } = {}): Promise<void> {
     const times = options.times ?? 3;
     const delayMs = options.delayMs ?? 2000;
     const code = autoScrollJs(times, delayMs);
-    await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    await sendCommand('exec', { code, ...this._cmdOpts() });
   }
 
   async installInterceptor(pattern: string): Promise<void> {