@jackwener/opencli 1.6.1 → 1.6.3

package/dist/download/media-download.js

@@ -1,114 +1,2 @@
-/**
- * Media download helper — shared logic for batch downloading images/videos.
- *
- * Used by: xiaohongshu/download, twitter/download, bilibili/download,
- * and future media adapters.
- *
- * Flow: MediaItem[] → DownloadProgressTracker → httpDownload/ytdlpDownload → results
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { getErrorMessage } from '../errors.js';
-import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, } from './index.js';
-import { DownloadProgressTracker, formatBytes } from './progress.js';
-// ============================================================
-// Main API
-// ============================================================
-/**
- * Batch download media files with progress tracking.
- *
- * Handles:
- * - DownloadProgressTracker for terminal UX
- * - Automatic httpDownload vs ytdlpDownload routing via MediaItem.type
- * - Cookie export to Netscape format for yt-dlp (auto-cleanup)
- * - Directory creation
- * - Error handling with per-file results
- */
-export async function downloadMedia(items, options) {
-    const { output, subdir, cookies, browserCookies, timeout, filenamePrefix = 'download', ytdlpExtraArgs = [], verbose = true, } = options;
-    if (!items || items.length === 0) {
-        return [{ index: 0, type: '-', status: 'failed', size: 'No media found' }];
-    }
-    // Create output directory
-    const outputDir = subdir ? path.join(output, subdir) : output;
-    fs.mkdirSync(outputDir, { recursive: true });
-    // Pre-check yt-dlp availability (once, not per-item)
-    const hasYtdlp = checkYtdlp();
-    // Auto-export browser cookies to Netscape format for yt-dlp
-    let cookiesFile;
-    const needsYtdlp = items.some(m => m.type === 'video-tweet' || m.type === 'video-ytdlp');
-    if (needsYtdlp && browserCookies && browserCookies.length > 0) {
-        const tempDir = getTempDir();
-        fs.mkdirSync(tempDir, { recursive: true });
-        cookiesFile = path.join(tempDir, `media_cookies_${Date.now()}.txt`);
-        exportCookiesToNetscape(browserCookies, cookiesFile);
-    }
-    const tracker = new DownloadProgressTracker(items.length, verbose);
-    const results = [];
-    try {
-        for (let i = 0; i < items.length; i++) {
-            const media = items[i];
-            const isVideo = media.type !== 'image';
-            const ext = isVideo ? 'mp4' : 'jpg';
-            const filename = media.filename || `${filenamePrefix}_${i + 1}.${ext}`;
-            const destPath = path.join(outputDir, filename);
-            const progressBar = tracker.onFileStart(filename, i);
-            try {
-                let result;
-                const useYtdlp = (media.type === 'video-tweet' || media.type === 'video-ytdlp') && hasYtdlp;
-                if (useYtdlp) {
-                    result = await ytdlpDownload(media.url, destPath, {
-                        cookiesFile,
-                        extraArgs: ytdlpExtraArgs,
-                        onProgress: (percent) => {
-                            if (progressBar)
-                                progressBar.update(percent, 100);
-                        },
-                    });
-                }
-                else {
-                    // Direct HTTP download for images and direct video URLs
-                    const dlTimeout = timeout || (isVideo ? 60000 : 30000);
-                    result = await httpDownload(media.url, destPath, {
-                        cookies,
-                        timeout: dlTimeout,
-                        onProgress: (received, total) => {
-                            if (progressBar)
-                                progressBar.update(received, total);
-                        },
-                    });
-                }
-                if (progressBar) {
-                    progressBar.complete(result.success, result.success ? formatBytes(result.size) : undefined);
-                }
-                tracker.onFileComplete(result.success);
-                results.push({
-                    index: i + 1,
-                    type: media.type === 'video-tweet' || media.type === 'video-ytdlp' ? 'video' : media.type,
-                    status: result.success ? 'success' : 'failed',
-                    size: result.success ? formatBytes(result.size) : (result.error || 'unknown error'),
-                });
-            }
-            catch (err) {
-                const msg = getErrorMessage(err);
-                if (progressBar)
-                    progressBar.fail(msg);
-                tracker.onFileComplete(false);
-                results.push({
-                    index: i + 1,
-                    type: media.type,
-                    status: 'failed',
-                    size: msg,
-                });
-            }
-        }
-    }
-    finally {
-        tracker.finish();
-        // Auto-cleanup exported cookies file
-        if (cookiesFile && fs.existsSync(cookiesFile)) {
-            fs.unlinkSync(cookiesFile);
-        }
-    }
-    return results;
-}
+// Shim: re-exports from src/download/ for adapter imports
+export * from '../src/download/media-download.js';

package/dist/download/progress.d.ts

@@ -1,36 +1 @@
-/**
- * Download progress display: terminal progress bars, status updates.
- */
-export interface ProgressBar {
-    update(current: number, total: number, label?: string): void;
-    complete(success: boolean, message?: string): void;
-    fail(error: string): void;
-}
-/**
- * Format bytes as human-readable string (KB, MB, GB).
- */
-export declare function formatBytes(bytes: number): string;
-/**
- * Format milliseconds as human-readable duration.
- */
-export declare function formatDuration(ms: number): string;
-/**
- * Create a simple progress bar for terminal display.
- */
-export declare function createProgressBar(filename: string, index: number, total: number): ProgressBar;
-/**
- * Multi-file download progress tracker.
- */
-export declare class DownloadProgressTracker {
-    private completed;
-    private failed;
-    private skipped;
-    private total;
-    private startTime;
-    private verbose;
-    constructor(total: number, verbose?: boolean);
-    onFileStart(filename: string, index: number): ProgressBar | null;
-    onFileComplete(success: boolean, skipped?: boolean): void;
-    getSummary(): string;
-    finish(): void;
-}
+export * from '../src/download/progress.js';

package/dist/download/progress.js

@@ -1,111 +1,2 @@
-/**
- * Download progress display: terminal progress bars, status updates.
- */
-import chalk from 'chalk';
-/**
- * Format bytes as human-readable string (KB, MB, GB).
- */
-export function formatBytes(bytes) {
-    if (bytes === 0)
-        return '0 B';
-    const k = 1024;
-    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`;
-}
-/**
- * Format milliseconds as human-readable duration.
- */
-export function formatDuration(ms) {
-    if (ms < 1000)
-        return `${ms}ms`;
-    const seconds = Math.floor(ms / 1000);
-    if (seconds < 60)
-        return `${seconds}s`;
-    const minutes = Math.floor(seconds / 60);
-    const remainingSeconds = seconds % 60;
-    return `${minutes}m ${remainingSeconds}s`;
-}
-/**
- * Create a simple progress bar for terminal display.
- */
-export function createProgressBar(filename, index, total) {
-    const prefix = chalk.dim(`[${index + 1}/${total}]`);
-    const truncatedName = filename.length > 40 ? filename.slice(0, 37) + '...' : filename;
-    return {
-        update(current, totalBytes, label) {
-            const percent = totalBytes > 0 ? Math.round((current / totalBytes) * 100) : 0;
-            const bar = createBar(percent);
-            const size = totalBytes > 0 ? formatBytes(totalBytes) : '';
-            const extra = label ? ` ${label}` : '';
-            process.stderr.write(`\r${prefix} ${truncatedName} ${bar} ${percent}% ${size}${extra}`);
-        },
-        complete(success, message) {
-            const icon = success ? chalk.green('✓') : chalk.red('✗');
-            const msg = message ? ` ${chalk.dim(message)}` : '';
-            process.stderr.write(`\r${prefix} ${icon} ${truncatedName}${msg}\n`);
-        },
-        fail(error) {
-            process.stderr.write(`\r${prefix} ${chalk.red('✗')} ${truncatedName} ${chalk.red(error)}\n`);
-        },
-    };
-}
-/**
- * Create a progress bar string.
- */
-function createBar(percent, width = 20) {
-    const filled = Math.round((percent / 100) * width);
-    const empty = width - filled;
-    return chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(empty));
-}
-/**
- * Multi-file download progress tracker.
- */
-export class DownloadProgressTracker {
-    completed = 0;
-    failed = 0;
-    skipped = 0;
-    total;
-    startTime;
-    verbose;
-    constructor(total, verbose = true) {
-        this.total = total;
-        this.startTime = Date.now();
-        this.verbose = verbose;
-    }
-    onFileStart(filename, index) {
-        if (!this.verbose)
-            return null;
-        return createProgressBar(filename, index, this.total);
-    }
-    onFileComplete(success, skipped = false) {
-        if (skipped) {
-            this.skipped++;
-        }
-        else if (success) {
-            this.completed++;
-        }
-        else {
-            this.failed++;
-        }
-    }
-    getSummary() {
-        const elapsed = formatDuration(Date.now() - this.startTime);
-        const parts = [];
-        if (this.completed > 0) {
-            parts.push(chalk.green(`${this.completed} downloaded`));
-        }
-        if (this.skipped > 0) {
-            parts.push(chalk.yellow(`${this.skipped} skipped`));
-        }
-        if (this.failed > 0) {
-            parts.push(chalk.red(`${this.failed} failed`));
-        }
-        return `${parts.join(', ')} in ${elapsed}`;
-    }
-    finish() {
-        if (this.verbose) {
-            process.stderr.write(`\n${chalk.bold('Download complete:')} ${this.getSummary()}\n`);
-        }
-    }
-}
+// Shim: re-exports from src/download/ for adapter imports
+export * from '../src/download/progress.js';

package/dist/pipeline/index.d.ts

@@ -1,5 +1 @@
-/**
- * Pipeline module: re-exports for backward compatibility.
- */
-export { executePipeline, type PipelineContext } from './executor.js';
-export { render, evalExpr, resolvePath, normalizeEvaluateSource, type RenderContext } from './template.js';
+export * from '../src/pipeline/index.js';

package/dist/pipeline/index.js

@@ -1,5 +1,2 @@
-/**
- * Pipeline module: re-exports for backward compatibility.
- */
-export { executePipeline } from './executor.js';
-export { render, evalExpr, resolvePath, normalizeEvaluateSource } from './template.js';
+// Shim: re-exports from src/pipeline/ for adapter imports
+export * from '../src/pipeline/index.js';

package/dist/src/browser/base-page.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BasePage — shared IPage method implementations for DOM helpers.
+ *
+ * Both Page (daemon-backed) and CDPPage (direct CDP) execute JS the same way
+ * for DOM operations. This base class deduplicates ~200 lines of identical
+ * click/type/scroll/wait/snapshot/interceptor methods.
+ *
+ * Subclasses implement the transport-specific methods: goto, evaluate,
+ * getCookies, screenshot, tabs, etc.
+ */
+import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+export declare abstract class BasePage implements IPage {
+    protected _lastUrl: string | null;
+    /** Cached previous snapshot hashes for incremental diff marking */
+    private _prevSnapshotHashes;
+    abstract goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    abstract evaluate(js: string): Promise<unknown>;
+    abstract getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    abstract screenshot(options?: ScreenshotOptions): Promise<string>;
+    abstract tabs(): Promise<unknown[]>;
+    abstract selectTab(index: number): Promise<void>;
+    click(ref: string): Promise<void>;
+    /** Override in subclasses with CDP native click support */
+    protected tryNativeClick(_x: number, _y: number): Promise<boolean>;
+    typeText(ref: string, text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    scrollTo(ref: string): Promise<unknown>;
+    getFormState(): Promise<Record<string, unknown>>;
+    scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<unknown[]>;
+    consoleMessages(_level?: string): Promise<unknown[]>;
+    wait(options: number | WaitOptions): Promise<void>;
+    snapshot(opts?: SnapshotOptions): Promise<unknown>;
+    getCurrentUrl(): Promise<string | null>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<unknown[]>;
+    waitForCapture(timeout?: number): Promise<void>;
+    /** Fallback basic snapshot */
+    protected _basicSnapshot(opts?: Pick<SnapshotOptions, 'interactive' | 'compact' | 'maxDepth' | 'raw'>): Promise<unknown>;
+}

package/dist/src/browser/base-page.js

@@ -0,0 +1,193 @@
+/**
+ * BasePage — shared IPage method implementations for DOM helpers.
+ *
+ * Both Page (daemon-backed) and CDPPage (direct CDP) execute JS the same way
+ * for DOM operations. This base class deduplicates ~200 lines of identical
+ * click/type/scroll/wait/snapshot/interceptor methods.
+ *
+ * Subclasses implement the transport-specific methods: goto, evaluate,
+ * getCookies, screenshot, tabs, etc.
+ */
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { formatSnapshot } from '../snapshotFormatter.js';
+export class BasePage {
+    _lastUrl = null;
+    /** Cached previous snapshot hashes for incremental diff marking */
+    _prevSnapshotHashes = null;
+    // ── Shared DOM helper implementations ──
+    async click(ref) {
+        const result = await this.evaluate(clickJs(ref));
+        // Backwards compat: old format returned 'clicked' string
+        if (typeof result === 'string' || result == null)
+            return;
+        // JS click succeeded
+        if (result.status === 'clicked')
+            return;
+        // JS click failed — try CDP native click if coordinates available
+        if (result.x != null && result.y != null) {
+            const success = await this.tryNativeClick(result.x, result.y);
+            if (success)
+                return;
+        }
+        throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
+    }
+    /** Override in subclasses with CDP native click support */
+    async tryNativeClick(_x, _y) {
+        return false;
+    }
+    async typeText(ref, text) {
+        await this.evaluate(typeTextJs(ref, text));
+    }
+    async pressKey(key) {
+        await this.evaluate(pressKeyJs(key));
+    }
+    async scrollTo(ref) {
+        return this.evaluate(scrollToRefJs(ref));
+    }
+    async getFormState() {
+        return (await this.evaluate(getFormStateJs()));
+    }
+    async scroll(direction = 'down', amount = 500) {
+        await this.evaluate(scrollJs(direction, amount));
+    }
+    async autoScroll(options) {
+        const times = options?.times ?? 3;
+        const delayMs = options?.delayMs ?? 2000;
+        await this.evaluate(autoScrollJs(times, delayMs));
+    }
+    async networkRequests(includeStatic = false) {
+        const result = await this.evaluate(networkRequestsJs(includeStatic));
+        return Array.isArray(result) ? result : [];
+    }
+    async consoleMessages(_level = 'info') {
+        return [];
+    }
+    async wait(options) {
+        if (typeof options === 'number') {
+            if (options >= 1) {
+                try {
+                    const maxMs = options * 1000;
+                    await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+                    return;
+                }
+                catch {
+                    // Fallback: fixed sleep
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, options * 1000));
+            return;
+        }
+        if (typeof options.time === 'number') {
+            await new Promise(resolve => setTimeout(resolve, options.time * 1000));
+            return;
+        }
+        if (options.selector) {
+            const timeout = (options.timeout ?? 10) * 1000;
+            await this.evaluate(waitForSelectorJs(options.selector, timeout));
+            return;
+        }
+        if (options.text) {
+            const timeout = (options.timeout ?? 30) * 1000;
+            await this.evaluate(waitForTextJs(options.text, timeout));
+        }
+    }
+    async snapshot(opts = {}) {
+        const snapshotJs = generateSnapshotJs({
+            viewportExpand: opts.viewportExpand ?? 2000,
+            maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+            interactiveOnly: opts.interactive ?? false,
+            maxTextLength: opts.maxTextLength ?? 120,
+            includeScrollInfo: true,
+            bboxDedup: true,
+            previousHashes: this._prevSnapshotHashes,
+        });
+        try {
+            const result = await this.evaluate(snapshotJs);
+            // Read back the hashes stored by the snapshot for next diff
+            try {
+                const hashes = await this.evaluate('window.__opencli_prev_hashes');
+                this._prevSnapshotHashes = typeof hashes === 'string' ? hashes : null;
+            }
+            catch {
+                // Non-fatal: diff is best-effort
+            }
+            return result;
+        }
+        catch (err) {
+            // Log snapshot failure for debugging, then fallback to basic accessibility tree
+            if (process.env.DEBUG_SNAPSHOT) {
+                console.error('[snapshot] DOM snapshot failed, falling back to accessibility tree:', err?.message?.slice(0, 200));
+            }
+            return this._basicSnapshot(opts);
+        }
+    }
+    async getCurrentUrl() {
+        if (this._lastUrl)
+            return this._lastUrl;
+        try {
+            const current = await this.evaluate('window.location.href');
+            if (typeof current === 'string' && current) {
+                this._lastUrl = current;
+                return current;
+            }
+        }
+        catch {
+            // Best-effort
+        }
+        return null;
+    }
+    async installInterceptor(pattern) {
+        const { generateInterceptorJs } = await import('../interceptor.js');
+        await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {
+            arrayName: '__opencli_xhr',
+            patchGuard: '__opencli_interceptor_patched',
+        }));
+    }
+    async getInterceptedRequests() {
+        const { generateReadInterceptedJs } = await import('../interceptor.js');
+        const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
+        return Array.isArray(result) ? result : [];
+    }
+    async waitForCapture(timeout = 10) {
+        const maxMs = timeout * 1000;
+        await this.evaluate(waitForCaptureJs(maxMs));
+    }
+    /** Fallback basic snapshot */
+    async _basicSnapshot(opts = {}) {
+        const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
+        const code = `
+      (async () => {
+        function buildTree(node, depth) {
+          if (depth > ${maxDepth}) return '';
+          const role = node.getAttribute?.('role') || node.tagName?.toLowerCase() || 'generic';
+          const name = node.getAttribute?.('aria-label') || node.getAttribute?.('alt') || node.textContent?.trim().slice(0, 80) || '';
+          const isInteractive = ['a', 'button', 'input', 'select', 'textarea'].includes(node.tagName?.toLowerCase()) || node.getAttribute?.('tabindex') != null;
+
+          ${opts.interactive ? 'if (!isInteractive && !node.children?.length) return "";' : ''}
+
+          let indent = '  '.repeat(depth);
+          let line = indent + role;
+          if (name) line += ' "' + name.replace(/"/g, '\\\\\\"') + '"';
+          if (node.tagName?.toLowerCase() === 'a' && node.href) line += ' [' + node.href + ']';
+          if (node.tagName?.toLowerCase() === 'input') line += ' [' + (node.type || 'text') + ']';
+
+          let result = line + '\\n';
+          if (node.children) {
+            for (const child of node.children) {
+              result += buildTree(child, depth + 1);
+            }
+          }
+          return result;
+        }
+        return buildTree(document.body, 0);
+      })()
+    `;
+        const raw = await this.evaluate(code);
+        if (opts.raw)
+            return raw;
+        if (typeof raw === 'string')
+            return formatSnapshot(raw, opts);
+        return raw;
+    }
+}

package/dist/src/browser/bridge.js

@@ -0,0 +1,109 @@
+/**
+ * Browser session manager — auto-spawns daemon and provides IPage.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { Page } from './page.js';
+import { fetchDaemonStatus, isExtensionConnected } from './daemon-client.js';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
+/**
+ * Browser factory: manages daemon lifecycle and provides IPage instances.
+ */
+export class BrowserBridge {
+    _state = 'idle';
+    _page = null;
+    _daemonProc = null;
+    get state() {
+        return this._state;
+    }
+    async connect(opts = {}) {
+        if (this._state === 'connected' && this._page)
+            return this._page;
+        if (this._state === 'connecting')
+            throw new Error('Already connecting');
+        if (this._state === 'closing')
+            throw new Error('Session is closing');
+        if (this._state === 'closed')
+            throw new Error('Session is closed');
+        this._state = 'connecting';
+        try {
+            await this._ensureDaemon(opts.timeout);
+            this._page = new Page(opts.workspace);
+            this._state = 'connected';
+            return this._page;
+        }
+        catch (err) {
+            this._state = 'idle';
+            throw err;
+        }
+    }
+    async close() {
+        if (this._state === 'closed')
+            return;
+        this._state = 'closing';
+        // We don't kill the daemon — it auto-exits on idle.
+        // Just clean up our reference.
+        this._page = null;
+        this._state = 'closed';
+    }
+    async _ensureDaemon(timeoutSeconds) {
+        const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
+        const timeoutMs = effectiveSeconds * 1000;
+        // Single status check instead of two separate fetchDaemonStatus() calls
+        const status = await fetchDaemonStatus();
+        // Fast path: extension already connected
+        if (status?.extensionConnected)
+            return;
+        // Daemon running but no extension — wait for extension with progress
+        if (status !== null) {
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+            }
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                await new Promise(resolve => setTimeout(resolve, 200));
+                if (await isExtensionConnected())
+                    return;
+            }
+            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
+                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+        }
+        // No daemon — spawn one
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const parentDir = path.resolve(__dirname, '..');
+        const daemonTs = path.join(parentDir, 'daemon.ts');
+        const daemonJs = path.join(parentDir, 'daemon.js');
+        const isTs = fs.existsSync(daemonTs);
+        const daemonPath = isTs ? daemonTs : daemonJs;
+        if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+            process.stderr.write('⏳ Starting daemon...\n');
+        }
+        const spawnArgs = isTs
+            ? [process.execPath, '--import', 'tsx/esm', daemonPath]
+            : [process.execPath, daemonPath];
+        this._daemonProc = spawn(spawnArgs[0], spawnArgs.slice(1), {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...process.env },
+        });
+        this._daemonProc.unref();
+        // Wait for daemon + extension with faster polling
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            if (await isExtensionConnected())
+                return;
+        }
+        if ((await fetchDaemonStatus()) !== null) {
+            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
+                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+        }
+        throw new Error('Failed to start opencli daemon. Try running manually:\n' +
+            `  node ${daemonPath}\n` +
+            `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
+    }
+}

package/dist/src/browser/cdp.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CDP client — implements IPage by connecting directly to a Chrome/Electron CDP WebSocket.
+ *
+ * Fixes applied:
+ * - send() now has a 30s timeout guard (P0 #4)
+ * - goto() waits for Page.loadEventFired instead of hardcoded 1s sleep (P1 #3)
+ * - Implemented scroll, autoScroll, screenshot, networkRequests (P1 #2)
+ * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
+ */
+import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
+export interface CDPTarget {
+    type?: string;
+    url?: string;
+    title?: string;
+    webSocketDebuggerUrl?: string;
+}
+export declare class CDPBridge implements IBrowserFactory {
+    private _ws;
+    private _idCounter;
+    private _pending;
+    private _eventListeners;
+    connect(opts?: {
+        timeout?: number;
+        workspace?: string;
+        cdpEndpoint?: string;
+    }): Promise<IPage>;
+    close(): Promise<void>;
+    send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    on(event: string, handler: (params: unknown) => void): void;
+    off(event: string, handler: (params: unknown) => void): void;
+    waitForEvent(event: string, timeoutMs?: number): Promise<unknown>;
+}
+declare function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined;
+declare function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number;
+export declare const __test__: {
+    selectCDPTarget: typeof selectCDPTarget;
+    scoreCDPTarget: typeof scoreCDPTarget;
+};
+export {};