browser-cdp 0.5.1 → 0.6.3

package/README.md

@@ -28,12 +28,23 @@ 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 (network errors, exceptions, logs)
 browser-cdp console [--duration=SECONDS]
 
+# Stream network requests/responses
+browser-cdp network [--filter=PATTERN] [--json] [--errors] [--duration=SECONDS]
+
+# Manage cookies (export/import/clear)
+browser-cdp cookies export [--path=FILE]
+browser-cdp cookies import <file>
+browser-cdp cookies clear
+
 # Show page performance metrics
 browser-cdp insights [--json]
 
@@ -69,6 +80,13 @@ 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"
 
@@ -79,6 +97,32 @@ browser-cdp console
 # Stream console for 10 seconds
 browser-cdp console --duration=10
 
+# Stream network traffic
+browser-cdp network
+# Then navigate to see requests
+
+# Filter to API calls only
+browser-cdp network --filter=api
+
+# Only show failed requests (4xx/5xx)
+browser-cdp network --errors
+
+# JSON output for parsing
+browser-cdp network --json --duration=5 | jq '.url'
+
+# Export cookies to JSON file
+browser-cdp cookies export
+# Returns: cookies.json with all cookies
+
+# Export to custom file
+browser-cdp cookies export --path session.json
+
+# Import cookies from file
+browser-cdp cookies import session.json
+
+# Clear all cookies
+browser-cdp cookies clear
+
 # Get page performance insights
 browser-cdp insights
 # Returns: TTFB, First Paint, FCP, DOM loaded, resources, memory
@@ -93,6 +137,56 @@ browser-cdp lighthouse
 browser-cdp close
 ```
 
+## Cookies Command
+
+The `cookies` command provides session persistence for authenticated workflows:
+
+### Export Cookies
+
+Save your browser cookies to a JSON file for later use:
+
+```bash
+browser-cdp cookies export                    # Saves to cookies.json
+browser-cdp cookies export --path auth.json   # Save to specific file
+```
+
+Output format:
+```json
+[
+  {
+    "name": "session_id",
+    "value": "abc123...",
+    "domain": "example.com",
+    "path": "/",
+    "httpOnly": true,
+    "secure": true,
+    "sameSite": "Strict",
+    "expires": 1735689600
+  }
+]
+```
+
+### Import Cookies
+
+Load previously exported cookies into the browser:
+
+```bash
+browser-cdp cookies import auth.json
+```
+
+Useful for:
+- Resuming authenticated sessions across browser restarts
+- Sharing sessions across team members
+- Preserving login state for automation workflows
+
+### Clear Cookies
+
+Delete all cookies from the browser:
+
+```bash
+browser-cdp cookies clear
+```
+
 ## Pre-started Browser
 
 If you already have a browser running with CDP enabled, the CLI will connect to it:
@@ -137,6 +231,25 @@ 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

package/cli.js

@@ -11,16 +11,19 @@ const command = process.argv[2];
 const args = process.argv.slice(3);
 
 const commands = {
-  start: "./start.js",
-  close: "./close.js",
-  nav: "./nav.js",
-  eval: "./eval.js",
-  dom: "./dom.js",
-  screenshot: "./screenshot.js",
-  pick: "./pick.js",
-  console: "./console.js",
-  insights: "./insights.js",
-  lighthouse: "./lighthouse.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",
+  network: "./src/network.js",
+  cookies: "./src/cookies.js",
+  insights: "./src/insights.js",
+  lighthouse: "./src/lighthouse.js",
 };
 
 function printUsage() {
@@ -35,8 +38,11 @@ function printUsage() {
   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("  network             Stream network requests/responses");
+  console.log("  cookies             Export/import/clear browser cookies");
   console.log("  insights            Show page performance metrics");
   console.log("  lighthouse          Run Lighthouse audit");
   console.log("");
@@ -51,6 +57,8 @@ function printUsage() {
   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 network --filter=api");
+  console.log("  browser-cdp cookies export --path session.json");
   console.log("  browser-cdp insights --json");
   process.exit(0);
 }

package/package.json

@@ -1,23 +1,21 @@
 {
   "name": "browser-cdp",
-  "version": "0.5.1",
+  "version": "0.6.3",
   "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"
   ],

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/{console.js → src/console.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, formatTime, levelColors, resetColor } from "./utils.js";
 
 const args = process.argv.slice(2);
 const duration = args.find((a) => a.startsWith("--duration="));
@@ -33,12 +32,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-// Filter out devtools pages and pick a real page
-const realPages = pages.filter(p => {
-  const url = p.url();
-  return url.startsWith("http://") || url.startsWith("https://");
-});
-const page = realPages[realPages.length - 1] || pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");
@@ -47,16 +41,6 @@ if (!page) {
 
 console.error(`Connected to: ${page.url()}`);
 
-const formatTime = () => new Date().toISOString().split("T")[1].slice(0, 12);
-
-const levelColors = {
-  verbose: "\x1b[90m",  // gray
-  info: "\x1b[36m",     // cyan
-  warning: "\x1b[33m",  // yellow
-  error: "\x1b[31m",    // red
-};
-const reset = "\x1b[0m";
-
 // Use CDP directly for Log domain (captures network errors, etc.)
 const cdp = await page.context().newCDPSession(page);
 await cdp.send("Log.enable");
@@ -64,9 +48,9 @@ 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}${reset}`);
+  console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
   if (entry.url) {
-    console.log(`${color}    URL: ${entry.url}${reset}`);
+    console.log(`${color}    URL: ${entry.url}${resetColor}`);
   }
 });
 
@@ -74,14 +58,14 @@ cdp.on("Log.entryAdded", ({ entry }) => {
 await cdp.send("Runtime.enable");
 cdp.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
   const text = exceptionDetails.exception?.description || exceptionDetails.text;
-  console.log(`\x1b[31m[${formatTime()}] [EXCEPTION] ${text}${reset}`);
+  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}${reset}`);
+  console.log(`\x1b[31m[${formatTime()}] [NETWORK ERROR] ${errorText}${reason}${resetColor}`);
 });
 
 // Keep Playwright listeners for console.log() calls
@@ -89,11 +73,11 @@ 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}${reset}`);
+  console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${text}${resetColor}`);
 });
 
 page.on("pageerror", (error) => {
-  console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${reset}`);
+  console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
 });
 
 if (shouldReload) {

package/src/cookies.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+const showHelp = args.includes("--help") || args.includes("-h");
+
+function printUsage() {
+  console.log("Usage: cookies <subcommand> [options]");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  export                Export cookies to JSON file");
+  console.log("  import <file>         Import cookies from JSON file");
+  console.log("  clear                 Clear all cookies from browser");
+  console.log("");
+  console.log("Options:");
+  console.log("  --path <file>         Output file path for export (default: cookies.json)");
+  console.log("");
+  console.log("Examples:");
+  console.log("  cookies export");
+  console.log("  cookies export --path session.json");
+  console.log("  cookies import session.json");
+  console.log("  cookies clear");
+  process.exit(0);
+}
+
+if (!subcommand || showHelp) {
+  printUsage();
+}
+
+if (!["export", "import", "clear"].includes(subcommand)) {
+  console.error(`Unknown subcommand: ${subcommand}`);
+  console.log("Available: export, import, clear");
+  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 = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const cdp = await page.context().newCDPSession(page);
+
+if (subcommand === "export") {
+  const pathIdx = args.findIndex((a) => a === "--path");
+  const outputFile = pathIdx !== -1 ? args[pathIdx + 1] : "cookies.json";
+
+  const { cookies } = await cdp.send("Network.getCookies");
+  writeFileSync(outputFile, JSON.stringify(cookies, null, 2));
+  console.log(`Exported ${cookies.length} cookie(s) to ${outputFile}`);
+} else if (subcommand === "import") {
+  const importFile = args[1];
+
+  if (!importFile) {
+    console.error("Error: import requires a file path");
+    process.exit(1);
+  }
+
+  const cookies = JSON.parse(readFileSync(importFile, "utf8"));
+
+  if (!Array.isArray(cookies)) {
+    console.error("Error: Cookie file must contain a JSON array");
+    process.exit(1);
+  }
+
+  await cdp.send("Network.setCookies", { cookies });
+  console.log(`Imported ${cookies.length} cookie(s) from ${importFile}`);
+} else if (subcommand === "clear") {
+  await cdp.send("Network.clearBrowserCookies");
+  console.log("Cleared all cookies");
+}
+
+await browser.close();

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/{eval.js → src/eval.js}

@@ -1,16 +1,13 @@
 #!/usr/bin/env node
 
 import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+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;
-
-// Get code (everything that's not a flag)
 const code = args.filter((a) => !a.startsWith("--")).join(" ");
 
 if (showHelp || !code) {
@@ -35,29 +32,14 @@ if (!context) {
 }
 
 const pages = context.pages();
-// Filter out devtools pages and pick a real page
-const realPages = pages.filter(p => {
-  const url = p.url();
-  return url.startsWith("http://") || url.startsWith("https://");
-});
-const page = realPages[realPages.length - 1] || pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");
   process.exit(1);
 }
 
-// Set up console capture BEFORE evaluation
 if (captureConsole) {
-  const formatTime = () => new Date().toISOString().split("T")[1].slice(0, 12);
-  const levelColors = {
-    verbose: "\x1b[90m",
-    info: "\x1b[36m",
-    warning: "\x1b[33m",
-    error: "\x1b[31m",
-  };
-  const reset = "\x1b[0m";
-
   const cdp = await page.context().newCDPSession(page);
   await cdp.send("Log.enable");
   await cdp.send("Runtime.enable");
@@ -66,30 +48,30 @@ if (captureConsole) {
   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}${reset}`);
+    console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
     if (entry.url) {
-      console.log(`${color}    URL: ${entry.url}${reset}`);
+      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}${reset}`);
+    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}${reset}`);
+    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()}${reset}`);
+    console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${msg.text()}${resetColor}`);
   });
 
   page.on("pageerror", (error) => {
-    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${reset}`);
+    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
   });
 }
 
@@ -107,7 +89,6 @@ try {
   process.exit(1);
 }
 
-// Print result
 if (Array.isArray(result)) {
   for (let i = 0; i < result.length; i++) {
     if (i > 0) console.log("");
@@ -123,7 +104,6 @@ if (Array.isArray(result)) {
   console.log(result);
 }
 
-// Wait for async console output
 if (captureConsole) {
   console.error(`\nListening for ${durationMs / 1000}s...`);
   await new Promise((r) => setTimeout(r, durationMs));

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,12 +30,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-// Filter out devtools pages and pick a real page
-const realPages = pages.filter(p => {
-  const url = p.url();
-  return url.startsWith("http://") || url.startsWith("https://");
-});
-const page = realPages[realPages.length - 1] || 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/{nav.js → src/nav.js}

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 
 import { chromium } from "playwright";
-
-const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+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");
@@ -27,10 +26,7 @@ if (showHelp || !url) {
   process.exit(showHelp ? 0 : 1);
 }
 
-// Add protocol if missing
-if (!url.match(/^https?:\/\//i)) {
-  url = "https://" + url;
-}
+url = normalizeUrl(url);
 
 const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
 const contexts = browser.contexts();
@@ -48,17 +44,7 @@ if (newTab) {
   page = realPages[realPages.length - 1] || pages[pages.length - 1] || await context.newPage();
 }
 
-// Set up console capture BEFORE navigation
 if (captureConsole) {
-  const formatTime = () => new Date().toISOString().split("T")[1].slice(0, 12);
-  const levelColors = {
-    verbose: "\x1b[90m",
-    info: "\x1b[36m",
-    warning: "\x1b[33m",
-    error: "\x1b[31m",
-  };
-  const reset = "\x1b[0m";
-
   const cdp = await page.context().newCDPSession(page);
   await cdp.send("Log.enable");
   await cdp.send("Runtime.enable");
@@ -67,30 +53,30 @@ if (captureConsole) {
   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}${reset}`);
+    console.log(`${color}[${formatTime()}] [${entry.level.toUpperCase()}]${source} ${entry.text}${resetColor}`);
     if (entry.url) {
-      console.log(`${color}    URL: ${entry.url}${reset}`);
+      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}${reset}`);
+    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}${reset}`);
+    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()}${reset}`);
+    console.log(`${color}[${formatTime()}] [CONSOLE.${type.toUpperCase()}] ${msg.text()}${resetColor}`);
   });
 
   page.on("pageerror", (error) => {
-    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${reset}`);
+    console.log(`\x1b[31m[${formatTime()}] [PAGE ERROR] ${error.message}${resetColor}`);
   });
 
   console.error(`Navigating to ${url} (capturing console for ${durationMs / 1000}s)...`);

package/src/network.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage, formatTime, resetColor } from "./utils.js";
+
+const args = process.argv.slice(2);
+const filterPattern = args.find((a) => a.startsWith("--filter="))?.split("=")[1];
+const jsonOutput = args.includes("--json");
+const errorsOnly = args.includes("--errors");
+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: network.js [options]");
+  console.log("\nStream network requests and responses in real-time.");
+  console.log("\nOptions:");
+  console.log("  --filter=PATTERN  Filter URLs by regex pattern");
+  console.log("  --json            Output as JSON for piping");
+  console.log("  --errors          Only show failed requests (4xx/5xx)");
+  console.log("  --duration=N      Stop after N seconds (default: run until Ctrl+C)");
+  console.log("\nExamples:");
+  console.log("  network.js                      # Stream all network traffic");
+  console.log("  network.js --filter=api         # Only show URLs containing 'api'");
+  console.log("  network.js --errors             # Only show failed requests");
+  console.log("  network.js --json               # JSON output for jq/parsing");
+  console.log("  network.js --duration=10        # Capture for 10 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 = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+console.error(`Connected to: ${page.url()}`);
+
+const cdp = await page.context().newCDPSession(page);
+await cdp.send("Network.enable");
+
+const requests = new Map();
+
+const statusColors = {
+  success: "\x1b[32m", // green for 2xx
+  redirect: "\x1b[33m", // yellow for 3xx
+  error: "\x1b[31m", // red for 4xx/5xx
+  request: "\x1b[36m", // cyan for requests
+};
+
+function matchesFilter(url) {
+  if (!filterPattern) return true;
+  try {
+    return new RegExp(filterPattern).test(url);
+  } catch {
+    return url.includes(filterPattern);
+  }
+}
+
+cdp.on("Network.requestWillBeSent", ({ requestId, request, timestamp }) => {
+  requests.set(requestId, { method: request.method, url: request.url, timestamp });
+
+  if (!matchesFilter(request.url)) return;
+  if (errorsOnly) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "request",
+        timestamp: new Date(timestamp * 1000).toISOString(),
+        method: request.method,
+        url: request.url,
+        requestId,
+      })
+    );
+  } else {
+    console.log(`${statusColors.request}[${formatTime()}] → ${request.method} ${request.url}${resetColor}`);
+  }
+});
+
+cdp.on("Network.responseReceived", ({ requestId, response, timestamp, type }) => {
+  const req = requests.get(requestId);
+
+  if (!matchesFilter(response.url)) return;
+  if (errorsOnly && response.status < 400) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "response",
+        timestamp: new Date(timestamp * 1000).toISOString(),
+        status: response.status,
+        statusText: response.statusText,
+        url: response.url,
+        mimeType: response.mimeType,
+        resourceType: type,
+        requestId,
+        method: req?.method,
+      })
+    );
+  } else {
+    let color = statusColors.success;
+    if (response.status >= 400) {
+      color = statusColors.error;
+    } else if (response.status >= 300) {
+      color = statusColors.redirect;
+    }
+
+    const method = req ? `${req.method} ` : "";
+    console.log(`${color}[${formatTime()}] ← ${response.status} ${method}${response.url}${resetColor}`);
+  }
+});
+
+cdp.on("Network.loadingFailed", ({ requestId, errorText, blockedReason, canceled }) => {
+  const req = requests.get(requestId);
+
+  if (req && !matchesFilter(req.url)) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "failed",
+        timestamp: new Date().toISOString(),
+        url: req?.url,
+        method: req?.method,
+        error: errorText,
+        blockedReason,
+        canceled,
+        requestId,
+      })
+    );
+  } else {
+    const reason = blockedReason ? ` (${blockedReason})` : "";
+    const canceledStr = canceled ? " [CANCELED]" : "";
+    console.log(
+      `${statusColors.error}[${formatTime()}] ✗ ${errorText}${reason}${canceledStr} - ${req?.url || "unknown"}${resetColor}`
+    );
+  }
+
+  if (requestId) {
+    requests.delete(requestId);
+  }
+});
+
+console.error(`Listening for network activity... (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/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,12 +21,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-// Filter out devtools pages and pick a real page
-const realPages = pages.filter(p => {
-  const url = p.url();
-  return url.startsWith("http://") || url.startsWith("https://");
-});
-const page = realPages[realPages.length - 1] || 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,12 +15,7 @@ if (!context) {
 }
 
 const pages = context.pages();
-// Filter out devtools pages and pick a real page
-const realPages = pages.filter(p => {
-  const url = p.url();
-  return url.startsWith("http://") || url.startsWith("https://");
-});
-const page = realPages[realPages.length - 1] || pages[pages.length - 1];
+const page = getActivePage(pages);
 
 if (!page) {
   console.error("No active tab found");

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

@@ -1,75 +1,9 @@
 #!/usr/bin/env node
 
 import { spawn, execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { platform } from "node:os";
+import { existsSync } from "node:fs";
 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;
-
-// Resolve profile name to directory (supports both "Profile 1" and "Suppli" style names)
-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;
-}
+import { BROWSERS, DEFAULT_PORT, isMac, resolveProfileDir } from "./utils.js";
 
 function printUsage() {
   console.log("Usage: start.js [browser] [--profile=NAME] [--isolated] [--port=PORT]");
@@ -94,12 +28,11 @@ function printUsage() {
   process.exit(1);
 }
 
-// Parse arguments
 const args = process.argv.slice(2);
 let browserName = process.env.BROWSER || "chrome";
 let isolated = false;
 let profile = null;
-let port = parseInt(process.env.DEBUG_PORT) || DEFAULT_PORT;
+let port = DEFAULT_PORT;
 
 for (const arg of args) {
   if (arg === "--help" || arg === "-h") {
@@ -119,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",
@@ -186,7 +118,6 @@ if (!isolated && browserConfig.process) {
   }
 }
 
-// Build browser arguments
 const browserArgs = [
   `--remote-debugging-port=${port}`,
   // Required for Lighthouse/CDP debugger access (prevents bfcache blocking)
@@ -206,7 +137,6 @@ if (isolated) {
   browserArgs.push(`--profile-directory=${profileDir}`);
 }
 
-// Start browser
 const profileInfo = isolated ? " (isolated)" : profile ? ` (${profile})` : "";
 console.log(`Starting ${browserConfig.name} on port ${port}${profileInfo}...`);
 
@@ -215,7 +145,6 @@ spawn(browserPath, browserArgs, {
   stdio: "ignore",
 }).unref();
 
-// Wait for browser to be ready
 let connected = false;
 for (let i = 0; i < 30; i++) {
   try {

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}`;
+}