browser-cdp 0.3.0 → 0.6.1

package/README.md

@@ -1,5 +1,7 @@
 # browser-cdp
 
+[![npm version](https://img.shields.io/npm/v/browser-cdp.svg)](https://www.npmjs.com/package/browser-cdp)
+
 Browser automation via Chrome DevTools Protocol. Control Chrome, Brave, or Edge using your real browser - same fingerprint, real cookies, no automation detection.
 
 ## Install
@@ -12,7 +14,10 @@ npm install -g browser-cdp
 
 ```bash
 # Start browser with CDP enabled
-browser-cdp start [browser] [--isolated] [--port=PORT]
+browser-cdp start [browser] [--profile=NAME] [--isolated] [--port=PORT]
+
+# Close the browser
+browser-cdp close
 
 # Navigate to URL
 browser-cdp nav <url> [--new]
@@ -23,14 +28,20 @@ browser-cdp eval '<code>'
 # Take screenshot
 browser-cdp screenshot
 
+# Export page as PDF
+browser-cdp pdf [--path=FILE] [--format=A4|Letter|Legal|Tabloid] [--landscape]
+
 # Interactive element picker
 browser-cdp pick '<message>'
 
-# Stream browser console output
+# Stream browser console output (network errors, exceptions, logs)
 browser-cdp console [--duration=SECONDS]
 
 # Show page performance metrics
 browser-cdp insights [--json]
+
+# Run Lighthouse audit (Chrome only)
+browser-cdp lighthouse [--json] [--category=NAME]
 ```
 
 ## Environment Variables
@@ -47,6 +58,9 @@ browser-cdp insights [--json]
 # Start Brave with real profile
 browser-cdp start brave
 
+# Start Brave with specific profile (by name)
+browser-cdp start brave --profile=Work
+
 # Start Chrome on custom port
 DEBUG_PORT=9333 browser-cdp start
 
@@ -58,18 +72,35 @@ browser-cdp eval 'document.querySelector("textarea").value = "hello"'
 browser-cdp screenshot
 # Returns: /tmp/screenshot-2024-01-01T12-00-00.png
 
+# Export page as PDF
+browser-cdp pdf
+# Returns: /tmp/pdf-2024-01-01T12-00-00.pdf
+
+# Export to specific file in A4 landscape
+browser-cdp pdf --path report.pdf --format A4 --landscape
+
 # Pick elements interactively
 browser-cdp pick "Select the login button"
 
-# Stream console output for 10 seconds
+# Stream console output (captures network errors, exceptions, console.log)
+browser-cdp console
+# Then refresh the page to see errors
+
+# Stream console for 10 seconds
 browser-cdp console --duration=10
 
 # Get page performance insights
 browser-cdp insights
 # Returns: TTFB, First Paint, FCP, DOM loaded, resources, memory
 
-# Get insights as JSON
-browser-cdp insights --json
+# Run Lighthouse audit (Chrome only - Brave blocks CDP debugger)
+browser-cdp start chrome --isolated
+browser-cdp nav https://example.com
+browser-cdp lighthouse
+# Returns: Performance, Accessibility, Best Practices, SEO scores
+
+# Close browser when done
+browser-cdp close
 ```
 
 ## Pre-started Browser
@@ -116,6 +147,29 @@ Use `BROWSER_PATH` env var to override if your browser is installed elsewhere.
 | Detection | Not detectable as automation | Automation flags present |
 | Use case | Real-world testing, scraping | Isolated E2E tests |
 
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run all tests
+bun run test
+
+# Run unit tests only (fast, no browser needed)
+bun run test:unit
+
+# Run integration tests (requires browser)
+bun run test:integration
+
+# Watch mode
+bun run test:watch
+```
+
+## See Also
+
+- [dev-browser](https://github.com/SawyerHood/dev-browser) - Browser automation plugin for Claude Code with LLM-optimized DOM snapshots
+
 ## License
 
 MIT

package/cli.js

@@ -11,13 +11,17 @@ const command = process.argv[2];
 const args = process.argv.slice(3);
 
 const commands = {
-  start: "./start.js",
-  nav: "./nav.js",
-  eval: "./eval.js",
-  screenshot: "./screenshot.js",
-  pick: "./pick.js",
-  console: "./console.js",
-  insights: "./insights.js",
+  start: "./src/start.js",
+  close: "./src/close.js",
+  nav: "./src/nav.js",
+  eval: "./src/eval.js",
+  dom: "./src/dom.js",
+  screenshot: "./src/screenshot.js",
+  pdf: "./src/pdf.js",
+  pick: "./src/pick.js",
+  console: "./src/console.js",
+  insights: "./src/insights.js",
+  lighthouse: "./src/lighthouse.js",
 };
 
 function printUsage() {
@@ -27,12 +31,16 @@ function printUsage() {
   console.log("");
   console.log("Commands:");
   console.log("  start [browser]     Start browser with CDP (uses real profile)");
-  console.log("  nav <url>           Navigate to URL");
-  console.log("  eval '<code>'       Evaluate JavaScript in page");
+  console.log("  close               Close the browser");
+  console.log("  nav <url>           Navigate to URL (--console to capture logs)");
+  console.log("  eval '<code>'       Evaluate JS in page (--console to capture logs)");
+  console.log("  dom                 Capture full page DOM/HTML");
   console.log("  screenshot          Take screenshot of current page");
+  console.log("  pdf                 Export current page as PDF");
   console.log("  pick '<message>'    Interactive element picker");
   console.log("  console             Stream browser console output");
   console.log("  insights            Show page performance metrics");
+  console.log("  lighthouse          Run Lighthouse audit");
   console.log("");
   console.log("Environment:");
   console.log("  DEBUG_PORT          CDP port (default: 9222)");
@@ -43,6 +51,7 @@ function printUsage() {
   console.log("  browser-cdp start brave");
   console.log("  browser-cdp nav https://google.com");
   console.log("  browser-cdp eval 'document.title'");
+  console.log("  browser-cdp dom > page.html");
   console.log("  browser-cdp console --duration=10");
   console.log("  browser-cdp insights --json");
   process.exit(0);

package/package.json

@@ -1,23 +1,21 @@
 {
   "name": "browser-cdp",
-  "version": "0.3.0",
+  "version": "0.6.1",
   "description": "Browser automation via Chrome DevTools Protocol - control Chrome, Brave, Edge with real browser profiles",
   "type": "module",
   "bin": {
     "browser-cdp": "./cli.js"
   },
   "scripts": {
-    "start": "node cli.js"
+    "start": "node cli.js",
+    "test": "node --test 'tests/*.test.js'",
+    "test:unit": "node --test tests/utils.test.js",
+    "test:integration": "node --test tests/commands.test.js",
+    "test:watch": "node --test --watch tests/"
   },
   "files": [
     "cli.js",
-    "start.js",
-    "nav.js",
-    "eval.js",
-    "screenshot.js",
-    "pick.js",
-    "console.js",
-    "insights.js",
+    "src/",
     "README.md",
     "LICENSE"
   ],
@@ -33,6 +31,7 @@
     "url": "https://github.com/dpaluy/browser-cdp/issues"
   },
   "dependencies": {
+    "lighthouse": "^13.0.1",
     "playwright": "^1.49.0"
   },
   "keywords": [

package/src/close.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import WebSocket from "ws";
+import { DEFAULT_PORT } from "./utils.js";
+
+try {
+  // Use CDP Browser.close to actually quit the browser
+  const res = await fetch(`http://localhost:${DEFAULT_PORT}/json/version`);
+  const { webSocketDebuggerUrl } = await res.json();
+
+  const socket = new WebSocket(webSocketDebuggerUrl);
+
+  await new Promise((resolve, reject) => {
+    socket.on("open", () => {
+      socket.send(JSON.stringify({ id: 1, method: "Browser.close" }));
+    });
+    socket.on("message", () => {
+      resolve();
+    });
+    socket.on("error", reject);
+    setTimeout(() => resolve(), 2000); // Browser closes before responding
+  });
+
+  console.log("Browser closed");
+} catch (err) {
+  if (err.cause?.code === "ECONNREFUSED" || err.message?.includes("ECONNREFUSED")) {
+    console.log("No browser running on port", DEFAULT_PORT);
+  } else {
+    throw err;
+  }
+}

package/src/console.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage, formatTime, levelColors, resetColor } from "./utils.js";
+
+const args = process.argv.slice(2);
+const duration = args.find((a) => a.startsWith("--duration="));
+const durationMs = duration ? parseInt(duration.split("=")[1]) * 1000 : null;
+const shouldReload = args.includes("--reload") || args.includes("-r");
+const showHelp = args.includes("--help") || args.includes("-h");
+
+if (showHelp) {
+  console.log("Usage: console.js [options]");
+  console.log("\nCapture browser console output in real-time.");
+  console.log("\nOptions:");
+  console.log("  --duration=N  Stop after N seconds (default: run until Ctrl+C)");
+  console.log("  --reload, -r  Reload the page before capturing");
+  console.log("\nExamples:");
+  console.log("  console.js              # Stream console logs until Ctrl+C");
+  console.log("  console.js --duration=5 # Capture for 5 seconds");
+  console.log("  console.js --reload     # Reload page and capture logs");
+  process.exit(0);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+console.error(`Connected to: ${page.url()}`);
+
+// Use CDP directly for Log domain (captures network errors, etc.)
+const cdp = await page.context().newCDPSession(page);
+await cdp.send("Log.enable");
+
+cdp.on("Log.entryAdded", ({ entry }) => {
+  const color = levelColors[entry.level] || levelColors.info;
+  const source = entry.source ? `[${entry.source}]` : "";
+  console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
+  if (entry.url) {
+    console.log(`${color}    URL: ${entry.url}${resetColor}`);
+  }
+});
+
+// Also capture runtime exceptions
+await cdp.send("Runtime.enable");
+cdp.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
+  const text = exceptionDetails.exception?.description || exceptionDetails.text;
+  console.log(`\x1b[31m[${formatTime()}] [EXCEPTION] ${text}${resetColor}`);
+});
+
+// Capture network failures (ERR_BLOCKED_BY_CLIENT, etc.)
+await cdp.send("Network.enable");
+cdp.on("Network.loadingFailed", ({ requestId, errorText, blockedReason }) => {
+  const reason = blockedReason ? ` (${blockedReason})` : "";
+  console.log(`\x1b[31m[${formatTime()}] [NETWORK ERROR] ${errorText}${reason}${resetColor}`);
+});
+
+// Keep Playwright listeners for console.log() calls
+page.on("console", (msg) => {
+  const type = msg.type();
+  const color = levelColors[type] || levelColors.info;
+  const text = msg.text();
+  console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${text}${resetColor}`);
+});
+
+page.on("pageerror", (error) => {
+  console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
+});
+
+if (shouldReload) {
+  console.error("Reloading page...");
+  await page.reload();
+}
+
+console.error(`Listening for console output... (Ctrl+C to stop)`);
+
+if (durationMs) {
+  await new Promise((r) => setTimeout(r, durationMs));
+  await browser.close();
+} else {
+  // Keep running until interrupted
+  process.on("SIGINT", async () => {
+    console.error("\nStopping...");
+    await browser.close();
+    process.exit(0);
+  });
+
+  // Keep the process alive
+  await new Promise(() => {});
+}

package/src/dom.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const html = await page.content();
+console.log(html);
+
+await browser.close();

package/src/eval.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage, formatTime, levelColors, resetColor } from "./utils.js";
+
+const args = process.argv.slice(2);
+const showHelp = args.includes("--help") || args.includes("-h");
+const captureConsole = args.includes("--console");
+const durationArg = args.find((a) => a.startsWith("--duration="));
+const durationMs = durationArg ? parseInt(durationArg.split("=")[1]) * 1000 : 3000;
+const code = args.filter((a) => !a.startsWith("--")).join(" ");
+
+if (showHelp || !code) {
+  console.log("Usage: eval.js '<code>' [options]");
+  console.log("\nOptions:");
+  console.log("  --console        Capture console output during evaluation");
+  console.log("  --duration=N     With --console, capture for N seconds (default: 3)");
+  console.log("\nExamples:");
+  console.log('  eval.js "document.title"');
+  console.log("  eval.js \"document.querySelectorAll('a').length\"");
+  console.log("  eval.js \"fetch('/api/data')\" --console");
+  process.exit(showHelp ? 0 : 1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+if (captureConsole) {
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send("Log.enable");
+  await cdp.send("Runtime.enable");
+  await cdp.send("Network.enable");
+
+  cdp.on("Log.entryAdded", ({ entry }) => {
+    const color = levelColors[entry.level] || levelColors.info;
+    const source = entry.source ? `[${entry.source}]` : "";
+    console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
+    if (entry.url) {
+      console.log(`${color}    URL: ${entry.url}${resetColor}`);
+    }
+  });
+
+  cdp.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
+    const text = exceptionDetails.exception?.description || exceptionDetails.text;
+    console.log(`\x1b[31m[${formatTime()}] [EXCEPTION] ${text}${resetColor}`);
+  });
+
+  cdp.on("Network.loadingFailed", ({ requestId, errorText, blockedReason }) => {
+    const reason = blockedReason ? ` (${blockedReason})` : "";
+    console.log(`\x1b[31m[${formatTime()}] [NETWORK ERROR] ${errorText}${reason}${resetColor}`);
+  });
+
+  page.on("console", (msg) => {
+    const type = msg.type();
+    const color = levelColors[type] || levelColors.info;
+    console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${msg.text()}${resetColor}`);
+  });
+
+  page.on("pageerror", (error) => {
+    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
+  });
+}
+
+let result;
+
+try {
+  result = await page.evaluate((c) => {
+    const AsyncFunction = (async () => {}).constructor;
+    return new AsyncFunction(`return (${c})`)();
+  }, code);
+} catch (e) {
+  console.log("Failed to evaluate expression");
+  console.log(`  Expression: ${code}`);
+  console.log(e);
+  process.exit(1);
+}
+
+if (Array.isArray(result)) {
+  for (let i = 0; i < result.length; i++) {
+    if (i > 0) console.log("");
+    for (const [key, value] of Object.entries(result[i])) {
+      console.log(`${key}: ${value}`);
+    }
+  }
+} else if (typeof result === "object" && result !== null) {
+  for (const [key, value] of Object.entries(result)) {
+    console.log(`${key}: ${value}`);
+  }
+} else {
+  console.log(result);
+}
+
+if (captureConsole) {
+  console.error(`\nListening for ${durationMs / 1000}s...`);
+  await new Promise((r) => setTimeout(r, durationMs));
+}
+
+await browser.close();

package/{insights.js → src/insights.js}

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
 import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
 
 const args = process.argv.slice(2);
 const showHelp = args.includes("--help") || args.includes("-h");
@@ -31,7 +30,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-const page = pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");

package/src/lighthouse.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import lighthouse from "lighthouse";
+import { chromium } from "playwright";
+import { DEFAULT_PORT } from "./utils.js";
+
+const args = process.argv.slice(2);
+const showHelp = args.includes("--help") || args.includes("-h");
+const jsonOutput = args.includes("--json");
+const category = args.find((a) => a.startsWith("--category="))?.split("=")[1];
+
+if (showHelp) {
+  console.log("Usage: lighthouse.js [--json] [--category=NAME]");
+  console.log("\nRun Lighthouse audit on the current page.");
+  console.log("\nOptions:");
+  console.log("  --json              Output full JSON report");
+  console.log("  --category=NAME     Run specific category only");
+  console.log("                      (performance, accessibility, best-practices, seo)");
+  console.log("\nExamples:");
+  console.log("  lighthouse.js                        # Full audit");
+  console.log("  lighthouse.js --category=performance # Performance only");
+  console.log("  lighthouse.js --json                 # JSON output");
+  process.exit(0);
+}
+
+// Get current page URL and check for DevTools
+const targetsRes = await fetch(`http://localhost:${DEFAULT_PORT}/json`);
+const targets = await targetsRes.json();
+
+const httpPages = targets.filter(t =>
+  t.type === "page" && (t.url.startsWith("http://") || t.url.startsWith("https://"))
+);
+const devtoolsPages = targets.filter(t =>
+  t.type === "page" && t.url.startsWith("devtools://")
+);
+
+if (httpPages.length === 0) {
+  console.error("No HTTP page found to audit");
+  process.exit(1);
+}
+
+const targetPage = httpPages[0];
+const url = targetPage.url;
+
+// Check if DevTools is open (it will block Lighthouse)
+if (devtoolsPages.length > 0) {
+  console.error("⚠️  DevTools is open - please close it first (Cmd+Option+I)");
+  console.error("   Lighthouse needs exclusive debugger access to run audits.");
+  process.exit(1);
+}
+
+if (!url.startsWith("http")) {
+  console.error(`Cannot audit non-HTTP URL: ${url}`);
+  process.exit(1);
+}
+
+console.error(`Running Lighthouse audit on ${url}...`);
+
+// Navigate existing same-origin pages away to prevent conflicts
+// Lighthouse creates a new tab, and existing same-origin tabs block debugger access
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const pages = browser.contexts()[0]?.pages() || [];
+for (const page of pages) {
+  const pageUrl = page.url();
+  if (pageUrl.startsWith("http") && new URL(pageUrl).origin === new URL(url).origin) {
+    console.error("(Navigating existing tab away to avoid conflicts)");
+    await page.goto("about:blank");
+  }
+}
+await browser.close();
+
+let result;
+try {
+  result = await lighthouse(
+    url,
+    {
+      port: DEFAULT_PORT,
+      output: "json",
+      logLevel: "error",
+    }
+  );
+} catch (err) {
+  if (err.message?.includes("Script execution is prohibited")) {
+    console.error("\n❌ Lighthouse failed - browser blocks debugger access");
+    console.error("\nBrave browser blocks CDP Debugger.enable. Use Chrome instead:");
+    console.error("  1. Close Brave");
+    console.error("  2. browser-cdp start chrome --isolated");
+    console.error("  3. browser-cdp nav <url>");
+    console.error("  4. browser-cdp lighthouse");
+    process.exit(1);
+  }
+  throw err;
+}
+
+if (!result) {
+  console.error("Lighthouse audit failed");
+  process.exit(1);
+}
+
+const { lhr } = result;
+
+if (jsonOutput) {
+  console.log(JSON.stringify(lhr, null, 2));
+} else {
+  console.log(`\nLighthouse Report: ${lhr.finalDisplayedUrl}\n`);
+
+  // Scores
+  console.log("Scores:");
+  for (const [key, cat] of Object.entries(lhr.categories)) {
+    const score = Math.round((cat.score || 0) * 100);
+    const bar = getScoreBar(score);
+    console.log(`  ${cat.title.padEnd(20)} ${bar} ${score}`);
+  }
+
+  // Top opportunities (performance)
+  if (lhr.categories.performance && lhr.audits) {
+    const opportunities = Object.values(lhr.audits)
+      .filter((a) => a.details?.type === "opportunity" && a.score !== null && a.score < 1)
+      .sort((a, b) => (a.score || 0) - (b.score || 0))
+      .slice(0, 5);
+
+    if (opportunities.length > 0) {
+      console.log("\nTop Opportunities:");
+      for (const opp of opportunities) {
+        const savings = opp.details?.overallSavingsMs
+          ? ` (${Math.round(opp.details.overallSavingsMs)}ms)`
+          : "";
+        console.log(`  - ${opp.title}${savings}`);
+      }
+    }
+  }
+
+  // Failed audits summary
+  const failed = Object.values(lhr.audits)
+    .filter((a) => a.score === 0)
+    .slice(0, 5);
+
+  if (failed.length > 0) {
+    console.log("\nFailed Audits:");
+    for (const audit of failed) {
+      console.log(`  ✗ ${audit.title}`);
+    }
+  }
+}
+
+function getScoreBar(score) {
+  const color = score >= 90 ? "\x1b[32m" : score >= 50 ? "\x1b[33m" : "\x1b[31m";
+  const reset = "\x1b[0m";
+  const filled = Math.round(score / 10);
+  const empty = 10 - filled;
+  return `${color}${"█".repeat(filled)}${"░".repeat(empty)}${reset}`;
+}

package/src/nav.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, normalizeUrl, getActivePage, formatTime, levelColors, resetColor } from "./utils.js";
+
+const args = process.argv.slice(2);
+const showHelp = args.includes("--help") || args.includes("-h");
+const newTab = args.includes("--new");
+const captureConsole = args.includes("--console");
+const durationArg = args.find((a) => a.startsWith("--duration="));
+const durationMs = durationArg ? parseInt(durationArg.split("=")[1]) * 1000 : 5000;
+
+// Get URL (first arg that doesn't start with --)
+let url = args.find((a) => !a.startsWith("--"));
+
+if (showHelp || !url) {
+  console.log("Usage: nav.js <url> [options]");
+  console.log("\nOptions:");
+  console.log("  --new            Open in new tab");
+  console.log("  --console        Capture console output during navigation");
+  console.log("  --duration=N     With --console, capture for N seconds (default: 5)");
+  console.log("\nExamples:");
+  console.log("  nav.js example.com              # Navigate current tab");
+  console.log("  nav.js example.com --new        # Open in new tab");
+  console.log("  nav.js example.com --console    # Navigate and capture console");
+  process.exit(showHelp ? 0 : 1);
+}
+
+url = normalizeUrl(url);
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0] || await browser.newContext();
+
+let page;
+if (newTab) {
+  page = await context.newPage();
+} else {
+  const pages = context.pages();
+  const realPages = pages.filter(p => {
+    const u = p.url();
+    return u.startsWith("http://") || u.startsWith("https://") || u === "about:blank";
+  });
+  page = realPages[realPages.length - 1] || pages[pages.length - 1] || await context.newPage();
+}
+
+if (captureConsole) {
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send("Log.enable");
+  await cdp.send("Runtime.enable");
+  await cdp.send("Network.enable");
+
+  cdp.on("Log.entryAdded", ({ entry }) => {
+    const color = levelColors[entry.level] || levelColors.info;
+    const source = entry.source ? `[${entry.source}]` : "";
+    console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
+    if (entry.url) {
+      console.log(`${color}    URL: ${entry.url}${resetColor}`);
+    }
+  });
+
+  cdp.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
+    const text = exceptionDetails.exception?.description || exceptionDetails.text;
+    console.log(`\x1b[31m[${formatTime()}] [EXCEPTION] ${text}${resetColor}`);
+  });
+
+  cdp.on("Network.loadingFailed", ({ requestId, errorText, blockedReason }) => {
+    const reason = blockedReason ? ` (${blockedReason})` : "";
+    console.log(`\x1b[31m[${formatTime()}] [NETWORK ERROR] ${errorText}${reason}${resetColor}`);
+  });
+
+  page.on("console", (msg) => {
+    const type = msg.type();
+    const color = levelColors[type] || levelColors.info;
+    console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${msg.text()}${resetColor}`);
+  });
+
+  page.on("pageerror", (error) => {
+    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
+  });
+
+  console.error(`Navigating to ${url} (capturing console for ${durationMs / 1000}s)...`);
+}
+
+await page.goto(url, { waitUntil: "domcontentloaded" });
+
+if (captureConsole) {
+  console.error(`Loaded: ${url}`);
+  await new Promise((r) => setTimeout(r, durationMs));
+  console.error("Done.");
+} else {
+  console.log(newTab ? "Opened:" : "Navigated to:", url);
+}
+
+await browser.close();

package/src/pdf.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log("Usage: pdf [options]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --path <file>       Output path (default: temp dir with timestamp)");
+  console.log("  --format <format>   Paper size: A4, Letter, Legal, Tabloid (default: Letter)");
+  console.log("  --landscape         Landscape orientation (default: portrait)");
+  console.log("");
+  console.log("Examples:");
+  console.log("  pdf");
+  console.log("  pdf --path output.pdf");
+  console.log("  pdf --format A4 --landscape");
+  process.exit(0);
+}
+
+const PAPER_FORMATS = {
+  A4: { width: 8.27, height: 11.69 },
+  LETTER: { width: 8.5, height: 11 },
+  LEGAL: { width: 8.5, height: 14 },
+  TABLOID: { width: 11, height: 17 },
+};
+
+const pathIdx = args.findIndex((a) => a === "--path");
+const formatIdx = args.findIndex((a) => a === "--format");
+const landscape = args.includes("--landscape");
+
+const customPath = pathIdx !== -1 ? args[pathIdx + 1] : null;
+const format = formatIdx !== -1 ? args[formatIdx + 1]?.toUpperCase() : "LETTER";
+const paperSize = PAPER_FORMATS[format] || PAPER_FORMATS.LETTER;
+
+const outputPath =
+  customPath ||
+  join(tmpdir(), `pdf-${new Date().toISOString().replace(/[:.]/g, "-")}.pdf`);
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const cdp = await context.newCDPSession(page);
+const { data } = await cdp.send("Page.printToPDF", {
+  printBackground: true,
+  paperWidth: paperSize.width,
+  paperHeight: paperSize.height,
+  landscape,
+  marginTop: 0.4,
+  marginBottom: 0.4,
+  marginLeft: 0.4,
+  marginRight: 0.4,
+});
+
+writeFileSync(outputPath, Buffer.from(data, "base64"));
+
+console.log(outputPath);
+
+await browser.close();

package/{pick.js → src/pick.js}

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
 import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
 
 const message = process.argv.slice(2).join(" ");
 if (!message) {
@@ -22,7 +21,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-const page = pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");

package/{screenshot.js → src/screenshot.js}

@@ -3,8 +3,7 @@
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
 
 const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
 const contexts = browser.contexts();
@@ -16,7 +15,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-const page = pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");

package/{start.js → src/start.js}

@@ -2,80 +2,45 @@
 
 import { spawn, execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { platform } from "node:os";
 import { chromium } from "playwright";
-
-const isMac = platform() === "darwin";
-const isLinux = platform() === "linux";
-
-// Browser configurations per platform
-const BROWSERS = {
-  chrome: {
-    name: "Google Chrome",
-    path: isMac
-      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
-      : "/usr/bin/google-chrome",
-    process: "Google Chrome",
-    profileSource: isMac
-      ? `${process.env.HOME}/Library/Application Support/Google/Chrome/`
-      : `${process.env.HOME}/.config/google-chrome/`,
-  },
-  brave: {
-    name: "Brave",
-    path: isMac
-      ? "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
-      : "/usr/bin/brave-browser",
-    process: "Brave Browser",
-    profileSource: isMac
-      ? `${process.env.HOME}/Library/Application Support/BraveSoftware/Brave-Browser/`
-      : `${process.env.HOME}/.config/BraveSoftware/Brave-Browser/`,
-  },
-  edge: {
-    name: "Microsoft Edge",
-    path: isMac
-      ? "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
-      : "/usr/bin/microsoft-edge",
-    process: "Microsoft Edge",
-    profileSource: isMac
-      ? `${process.env.HOME}/Library/Application Support/Microsoft Edge/`
-      : `${process.env.HOME}/.config/microsoft-edge/`,
-  },
-};
-
-const DEFAULT_PORT = 9222;
+import { BROWSERS, DEFAULT_PORT, isMac, resolveProfileDir } from "./utils.js";
 
 function printUsage() {
-  console.log("Usage: start.js [browser] [--isolated] [--port=PORT]");
+  console.log("Usage: start.js [browser] [--profile=NAME] [--isolated] [--port=PORT]");
   console.log("\nBrowsers:");
   console.log("  chrome  - Google Chrome (default)");
   console.log("  brave   - Brave Browser");
   console.log("  edge    - Microsoft Edge");
   console.log("\nOptions:");
-  console.log("  --isolated  Use isolated profile (default: real profile)");
-  console.log("  --port=N    Use custom debugging port (default: 9222)");
+  console.log("  --profile=NAME  Use specific profile by name or directory");
+  console.log("  --isolated      Use isolated profile (default: real profile)");
+  console.log("  --port=N        Use custom debugging port (default: 9222)");
   console.log("\nEnvironment variables:");
   console.log("  BROWSER       Default browser (chrome, brave, edge)");
   console.log("  BROWSER_PATH  Custom browser executable path");
   console.log("  DEBUG_PORT    Custom debugging port");
   console.log("\nExamples:");
-  console.log("  start.js                    # Start Chrome with real profile");
-  console.log("  start.js brave              # Start Brave with real profile");
-  console.log("  start.js edge --isolated    # Start Edge with isolated profile");
-  console.log("  start.js --port=9333        # Start Chrome on port 9333");
+  console.log("  start.js                           # Start Chrome with default profile");
+  console.log("  start.js brave                     # Start Brave with default profile");
+  console.log("  start.js brave --profile=Work      # Start Brave with 'Work' profile");
+  console.log("  start.js edge --isolated           # Start Edge with isolated profile");
+  console.log("  start.js --port=9333               # Start Chrome on port 9333");
   process.exit(1);
 }
 
-// Parse arguments
 const args = process.argv.slice(2);
 let browserName = process.env.BROWSER || "chrome";
 let isolated = false;
-let port = parseInt(process.env.DEBUG_PORT) || DEFAULT_PORT;
+let profile = null;
+let port = DEFAULT_PORT;
 
 for (const arg of args) {
   if (arg === "--help" || arg === "-h") {
     printUsage();
   } else if (arg === "--isolated") {
     isolated = true;
+  } else if (arg.startsWith("--profile=")) {
+    profile = arg.split("=")[1];
   } else if (arg.startsWith("--port=")) {
     port = parseInt(arg.split("=")[1]);
   } else if (BROWSERS[arg]) {
@@ -87,7 +52,6 @@ for (const arg of args) {
   }
 }
 
-// Resolve browser config
 const browserPath = process.env.BROWSER_PATH || BROWSERS[browserName]?.path;
 const browserConfig = BROWSERS[browserName] || {
   name: "Custom",
@@ -154,8 +118,11 @@ if (!isolated && browserConfig.process) {
   }
 }
 
-// Build browser arguments
-const browserArgs = [`--remote-debugging-port=${port}`];
+const browserArgs = [
+  `--remote-debugging-port=${port}`,
+  // Required for Lighthouse/CDP debugger access (prevents bfcache blocking)
+  "--disable-features=ProcessPerSiteUpToMainFrameThreshold",
+];
 
 if (isolated) {
   const cacheBase = isMac
@@ -164,17 +131,20 @@ if (isolated) {
   const profileDir = `${cacheBase}/browser-cdp/${browserName}`;
   execFileSync("mkdir", ["-p", profileDir], { stdio: "ignore" });
   browserArgs.push(`--user-data-dir=${profileDir}`);
+} else if (profile) {
+  // Resolve profile name to directory if needed
+  const profileDir = resolveProfileDir(browserConfig.profileSource, profile);
+  browserArgs.push(`--profile-directory=${profileDir}`);
 }
 
-// Start browser
-console.log(`Starting ${browserConfig.name} on port ${port}${isolated ? " (isolated)" : ""}...`);
+const profileInfo = isolated ? " (isolated)" : profile ? ` (${profile})` : "";
+console.log(`Starting ${browserConfig.name} on port ${port}${profileInfo}...`);
 
 spawn(browserPath, browserArgs, {
   detached: true,
   stdio: "ignore",
 }).unref();
 
-// Wait for browser to be ready
 let connected = false;
 for (let i = 0; i < 30; i++) {
   try {
@@ -192,4 +162,4 @@ if (!connected) {
   process.exit(1);
 }
 
-console.log(`${browserConfig.name} started on :${port}${isolated ? " (isolated)" : ""}`);
+console.log(`${browserConfig.name} started on :${port}${profileInfo}`);

package/src/utils.js

@@ -0,0 +1,118 @@
+import { readFileSync } from "node:fs";
+import { platform } from "node:os";
+
+export const isMac = platform() === "darwin";
+export const isLinux = platform() === "linux";
+
+export const DEFAULT_PORT = parseInt(process.env.DEBUG_PORT) || 9222;
+
+// Browser configurations per platform
+export const BROWSERS = {
+  chrome: {
+    name: "Google Chrome",
+    path: isMac
+      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      : "/usr/bin/google-chrome",
+    process: "Google Chrome",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/Google/Chrome/`
+      : `${process.env.HOME}/.config/google-chrome/`,
+  },
+  brave: {
+    name: "Brave",
+    path: isMac
+      ? "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+      : "/usr/bin/brave-browser",
+    process: "Brave Browser",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/BraveSoftware/Brave-Browser/`
+      : `${process.env.HOME}/.config/BraveSoftware/Brave-Browser/`,
+  },
+  edge: {
+    name: "Microsoft Edge",
+    path: isMac
+      ? "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+      : "/usr/bin/microsoft-edge",
+    process: "Microsoft Edge",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/Microsoft Edge/`
+      : `${process.env.HOME}/.config/microsoft-edge/`,
+  },
+};
+
+export function resolveProfileDir(profileSource, profileName) {
+  // If it looks like a directory name already, use it
+  if (profileName === "Default" || profileName.startsWith("Profile ")) {
+    return profileName;
+  }
+
+  // Try to find profile by name in Local State
+  if (profileSource) {
+    try {
+      const localStatePath = `${profileSource}Local State`;
+      const localState = JSON.parse(readFileSync(localStatePath, "utf8"));
+      const profiles = localState.profile?.info_cache || {};
+
+      for (const [dir, info] of Object.entries(profiles)) {
+        if (info.name?.toLowerCase() === profileName.toLowerCase()) {
+          return dir;
+        }
+      }
+    } catch {
+      // Fall through to return original name
+    }
+  }
+
+  return profileName;
+}
+
+export function parseProfileName(localState, profileName) {
+  const profiles = localState.profile?.info_cache || {};
+
+  for (const [dir, info] of Object.entries(profiles)) {
+    if (info.name?.toLowerCase() === profileName.toLowerCase()) {
+      return dir;
+    }
+  }
+
+  return null;
+}
+
+export function normalizeUrl(url) {
+  if (!url.match(/^https?:\/\//i)) {
+    return "https://" + url;
+  }
+  return url;
+}
+
+export function filterRealPages(pages) {
+  return pages.filter((p) => {
+    const url = p.url();
+    return url.startsWith("http://") || url.startsWith("https://");
+  });
+}
+
+export function getActivePage(pages) {
+  const realPages = filterRealPages(pages);
+  return realPages[realPages.length - 1] || pages[pages.length - 1] || null;
+}
+
+export function formatTime() {
+  return new Date().toISOString().split("T")[1].slice(0, 12);
+}
+
+// Console output colors
+export const levelColors = {
+  verbose: "\x1b[90m", // gray
+  info: "\x1b[36m", // cyan
+  warning: "\x1b[33m", // yellow
+  error: "\x1b[31m", // red
+};
+
+export const resetColor = "\x1b[0m";
+
+export function formatLogEntry(level, source, text) {
+  const color = levelColors[level] || levelColors.info;
+  const sourceTag = source ? `[${source}]` : "";
+  return `${color}[${formatTime()}] [${level.toUpperCase()}]${sourceTag} ${text}${resetColor}`;
+}

package/console.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-
-import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
-
-const args = process.argv.slice(2);
-const duration = args.find((a) => a.startsWith("--duration="));
-const durationMs = duration ? parseInt(duration.split("=")[1]) * 1000 : null;
-const showHelp = args.includes("--help") || args.includes("-h");
-
-if (showHelp) {
-  console.log("Usage: console.js [--duration=SECONDS]");
-  console.log("\nCapture browser console output in real-time.");
-  console.log("\nOptions:");
-  console.log("  --duration=N  Stop after N seconds (default: run until Ctrl+C)");
-  console.log("\nExamples:");
-  console.log("  console.js              # Stream console logs until Ctrl+C");
-  console.log("  console.js --duration=5 # Capture for 5 seconds");
-  process.exit(0);
-}
-
-const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
-const contexts = browser.contexts();
-const context = contexts[0];
-
-if (!context) {
-  console.error("No browser context found");
-  process.exit(1);
-}
-
-const pages = context.pages();
-const page = pages[pages.length - 1];
-
-if (!page) {
-  console.error("No active tab found");
-  process.exit(1);
-}
-
-const formatTime = () => new Date().toISOString().split("T")[1].slice(0, 12);
-
-const typeColors = {
-  log: "\x1b[0m",      // default
-  info: "\x1b[36m",    // cyan
-  warn: "\x1b[33m",    // yellow
-  error: "\x1b[31m",   // red
-  debug: "\x1b[90m",   // gray
-};
-const reset = "\x1b[0m";
-
-page.on("console", (msg) => {
-  const type = msg.type();
-  const color = typeColors[type] || typeColors.log;
-  const text = msg.text();
-  console.log(`${color}[${formatTime()}] [${type.toUpperCase()}] ${text}${reset}`);
-});
-
-page.on("pageerror", (error) => {
-  console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${reset}`);
-});
-
-console.error(`Listening for console output... (Ctrl+C to stop)`);
-
-if (durationMs) {
-  await new Promise((r) => setTimeout(r, durationMs));
-  await browser.close();
-} else {
-  // Keep running until interrupted
-  process.on("SIGINT", async () => {
-    console.error("\nStopping...");
-    await browser.close();
-    process.exit(0);
-  });
-
-  // Keep the process alive
-  await new Promise(() => {});
-}

package/eval.js

@@ -1,62 +0,0 @@
-#!/usr/bin/env node
-
-import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
-
-const code = process.argv.slice(2).join(" ");
-if (!code) {
-  console.log("Usage: eval.js 'code'");
-  console.log("\nExamples:");
-  console.log('  eval.js "document.title"');
-  console.log("  eval.js \"document.querySelectorAll('a').length\"");
-  process.exit(1);
-}
-
-const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
-const contexts = browser.contexts();
-const context = contexts[0];
-
-if (!context) {
-  console.error("No browser context found");
-  process.exit(1);
-}
-
-const pages = context.pages();
-const page = pages[pages.length - 1];
-
-if (!page) {
-  console.error("No active tab found");
-  process.exit(1);
-}
-
-let result;
-
-try {
-  result = await page.evaluate((c) => {
-    const AsyncFunction = (async () => {}).constructor;
-    return new AsyncFunction(`return (${c})`)();
-  }, code);
-} catch (e) {
-  console.log("Failed to evaluate expression");
-  console.log(`  Expression: ${code}`);
-  console.log(e);
-  process.exit(1);
-}
-
-if (Array.isArray(result)) {
-  for (let i = 0; i < result.length; i++) {
-    if (i > 0) console.log("");
-    for (const [key, value] of Object.entries(result[i])) {
-      console.log(`${key}: ${value}`);
-    }
-  }
-} else if (typeof result === "object" && result !== null) {
-  for (const [key, value] of Object.entries(result)) {
-    console.log(`${key}: ${value}`);
-  }
-} else {
-  console.log(result);
-}
-
-await browser.close();

package/nav.js

@@ -1,38 +0,0 @@
-#!/usr/bin/env node
-
-import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
-
-let url = process.argv[2];
-const newTab = process.argv[3] === "--new";
-
-// Add protocol if missing
-if (url && !url.match(/^https?:\/\//i)) {
-  url = "https://" + url;
-}
-
-if (!url) {
-  console.log("Usage: nav.js <url> [--new]");
-  console.log("\nExamples:");
-  console.log("  nav.js example.com       # Navigate current tab");
-  console.log("  nav.js example.com --new # Open in new tab");
-  process.exit(1);
-}
-
-const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
-const contexts = browser.contexts();
-const context = contexts[0] || await browser.newContext();
-
-if (newTab) {
-  const page = await context.newPage();
-  await page.goto(url, { waitUntil: "domcontentloaded" });
-  console.log("Opened:", url);
-} else {
-  const pages = context.pages();
-  const page = pages[pages.length - 1] || await context.newPage();
-  await page.goto(url, { waitUntil: "domcontentloaded" });
-  console.log("Navigated to:", url);
-}
-
-await browser.close();