@romanmatena/browsermonitor 2.0.0

package/src/os/wsl/index.mjs

@@ -0,0 +1,45 @@
+/**
+ * WSL utilities for browsermonitor.
+ *
+ * This module provides all functionality needed for running browsermonitor
+ * from WSL2 and connecting to Chrome on Windows.
+ */
+
+// Detection utilities
+export {
+  isWsl,
+  getWslDistroName,
+  getWindowsHostForWSL,
+  wslToWindowsPath,
+} from './detect.mjs';
+
+// Chrome detection and launch
+export {
+  getLastCmdStderrAndClear,
+  getWindowsLocalAppData,
+  getWindowsProfilePath,
+  detectWindowsChromeCanaryPath,
+  detectWindowsChromePath,
+  printCanaryInstallInstructions,
+  scanChromeInstances,
+  findProjectChrome,
+  findFreeDebugPort,
+  startChromeOnWindows,
+  killPuppeteerMonitorChromes,
+  checkChromeRunning,
+  launchChromeFromWSL,
+} from './chrome.mjs';
+
+// Port proxy management
+export {
+  removePortProxyIfExists,
+  isPortBlocked,
+  setupPortProxy,
+  detectChromeBindAddress,
+  getPortProxyConfig,
+} from './port-proxy.mjs';
+
+// Diagnostics
+export {
+  runWslDiagnostics,
+} from './diagnostics.mjs';

package/src/os/wsl/port-proxy.mjs

@@ -0,0 +1,190 @@
+/**
+ * Port proxy utilities for WSL→Windows connectivity.
+ *
+ * Chrome M113+ ignores --remote-debugging-address=0.0.0.0 for security.
+ * Chrome always binds to 127.0.0.1 or ::1, so we MUST use Windows port proxy
+ * (netsh interface portproxy) to forward connections from WSL.
+ *
+ * Port proxy types:
+ * - v4tov4: forward from 0.0.0.0:PORT to 127.0.0.1:PORT (for IPv4 Chrome)
+ * - v4tov6: forward from 0.0.0.0:PORT to ::1:PORT (for IPv6 Chrome)
+ */
+
+import { execSync } from 'child_process';
+import { log } from '../../utils/colors.mjs';
+
+/**
+ * Check if port proxy exists on a given port and remove it.
+ * This is needed because old port proxy rules can block Chrome from binding.
+ *
+ * @param {number} port - Port to check
+ * @returns {boolean} true if port proxy was found and removed
+ */
+export function removePortProxyIfExists(port) {
+  try {
+    // Check v4tov4 proxy
+    const portProxyV4 = execSync(
+      'powershell.exe -NoProfile -Command "netsh interface portproxy show v4tov4"',
+      { encoding: 'utf8', timeout: 5000 }
+    );
+
+    if (portProxyV4 && portProxyV4.includes(String(port))) {
+      log.warn(`Found old v4tov4 port proxy on port ${port}, removing...`);
+      try {
+        execSync(
+          `powershell.exe -NoProfile -Command "netsh interface portproxy delete v4tov4 listenport=${port} listenaddress=0.0.0.0"`,
+          { encoding: 'utf8', timeout: 5000 }
+        );
+        log.success(`Port proxy (v4tov4) removed from port ${port}`);
+        return true;
+      } catch (e) {
+        log.warn(`Could not remove port proxy (may need admin rights): ${e.message}`);
+      }
+    }
+
+    // Check v4tov6 proxy
+    const portProxyV6 = execSync(
+      'powershell.exe -NoProfile -Command "netsh interface portproxy show v4tov6"',
+      { encoding: 'utf8', timeout: 5000 }
+    );
+
+    if (portProxyV6 && portProxyV6.includes(String(port))) {
+      log.warn(`Found old v4tov6 port proxy on port ${port}, removing...`);
+      try {
+        execSync(
+          `powershell.exe -NoProfile -Command "netsh interface portproxy delete v4tov6 listenport=${port} listenaddress=0.0.0.0"`,
+          { encoding: 'utf8', timeout: 5000 }
+        );
+        log.success(`Port proxy (v4tov6) removed from port ${port}`);
+        return true;
+      } catch (e) {
+        log.warn(`Could not remove port proxy (may need admin rights): ${e.message}`);
+      }
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a port is already in use by something other than Chrome debug.
+ *
+ * @param {number} port - Port to check
+ * @returns {boolean} true if port is blocked
+ */
+export function isPortBlocked(port) {
+  try {
+    const netstat = execSync(
+      `netstat.exe -ano 2>/dev/null | grep -E ":${port}.*LISTEN"`,
+      { encoding: 'utf8', timeout: 5000 }
+    );
+    return netstat && netstat.includes('LISTEN');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Set up port proxy for WSL access to Chrome.
+ *
+ * @param {number} port - Port to forward
+ * @param {'v4tov4'|'v4tov6'} proxyType - Proxy type based on Chrome's bind address
+ * @returns {boolean} true if setup successful
+ */
+export function setupPortProxy(port, proxyType = 'v4tov4') {
+  const connectAddress = proxyType === 'v4tov6' ? '::1' : '127.0.0.1';
+
+  try {
+    // Remove any existing proxy first
+    try {
+      execSync(
+        `powershell.exe -NoProfile -Command "netsh interface portproxy delete v4tov4 listenport=${port} listenaddress=0.0.0.0 2>\\$null; netsh interface portproxy delete v4tov6 listenport=${port} listenaddress=0.0.0.0 2>\\$null"`,
+        { encoding: 'utf8', timeout: 5000 }
+      );
+    } catch { /* ignore */ }
+
+    // Add new proxy
+    execSync(
+      `powershell.exe -NoProfile -Command "netsh interface portproxy add ${proxyType} listenport=${port} listenaddress=0.0.0.0 connectport=${port} connectaddress=${connectAddress}"`,
+      { encoding: 'utf8', timeout: 5000 }
+    );
+    log.success(`Port proxy configured: 0.0.0.0:${port} → ${connectAddress}:${port} (${proxyType})`);
+    return true;
+  } catch (e) {
+    log.warn(`Could not set up port proxy (need admin): ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Detect Chrome's bind address (IPv4 or IPv6) by checking netstat.
+ *
+ * @param {number} port - Port to check
+ * @returns {'127.0.0.1'|'::1'|null} Bind address or null if not found
+ */
+export function detectChromeBindAddress(port) {
+  try {
+    const netstatOutput = execSync(`netstat.exe -ano`, { encoding: 'utf8', timeout: 5000 });
+    const lines = netstatOutput.split('\n').filter(l => l.includes(':' + port) && l.includes('LISTEN'));
+
+    for (const line of lines) {
+      if (line.includes('127.0.0.1:' + port)) {
+        return '127.0.0.1';
+      } else if (line.includes('[::1]:' + port)) {
+        return '::1';
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get current port proxy configuration.
+ *
+ * @returns {{v4tov4: Array<{listenPort: number, connectAddress: string}>, v4tov6: Array<{listenPort: number, connectAddress: string}>}}
+ */
+export function getPortProxyConfig() {
+  const config = { v4tov4: [], v4tov6: [] };
+
+  try {
+    const v4tov4Output = execSync(
+      'powershell.exe -NoProfile -Command "netsh interface portproxy show v4tov4"',
+      { encoding: 'utf8', timeout: 5000 }
+    );
+    // Parse output - format: "0.0.0.0         9222        127.0.0.1       9222"
+    const lines = v4tov4Output.split('\n').filter(l => l.match(/\d+\.\d+\.\d+\.\d+/));
+    for (const line of lines) {
+      const match = line.match(/(\d+\.\d+\.\d+\.\d+)\s+(\d+)\s+(\d+\.\d+\.\d+\.\d+)\s+(\d+)/);
+      if (match) {
+        config.v4tov4.push({
+          listenPort: parseInt(match[2], 10),
+          connectAddress: match[3],
+        });
+      }
+    }
+  } catch { /* ignore */ }
+
+  try {
+    const v4tov6Output = execSync(
+      'powershell.exe -NoProfile -Command "netsh interface portproxy show v4tov6"',
+      { encoding: 'utf8', timeout: 5000 }
+    );
+    const lines = v4tov6Output.split('\n').filter(l => l.match(/\d+\.\d+\.\d+\.\d+/));
+    for (const line of lines) {
+      // v4tov6 format includes ::1 for IPv6
+      const match = line.match(/(\d+\.\d+\.\d+\.\d+)\s+(\d+)\s+([^\s]+)\s+(\d+)/);
+      if (match) {
+        config.v4tov6.push({
+          listenPort: parseInt(match[2], 10),
+          connectAddress: match[3],
+        });
+      }
+    }
+  } catch { /* ignore */ }
+
+  return config;
+}

package/src/settings.mjs

@@ -0,0 +1,101 @@
+/**
+ * Settings & paths module for browsermonitor.
+ * Replaces the old package.json config approach.
+ * All project-specific state lives in <projectRoot>/.browsermonitor/
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Directory and file names
+export const BROWSERMONITOR_DIR = '.browsermonitor';
+export const PUPPETEER_DIR = '.puppeteer';
+export const CHROME_PROFILE_DIR = '.chrome-profile';
+export const SETTINGS_FILE = 'settings.json';
+export const PID_FILE = 'browsermonitor.pid';
+
+/** Default settings for new projects */
+export const DEFAULT_SETTINGS = {
+  defaultUrl: 'https://localhost:4000/',
+  headless: false,
+  navigationTimeout: 60000,
+  ignorePatterns: [],
+  httpPort: 60001,
+  realtime: false,
+};
+
+/**
+ * Get all resolved paths for a given project root.
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Object} All paths used by browsermonitor
+ */
+export function getPaths(projectRoot) {
+  const bmDir = path.join(projectRoot, BROWSERMONITOR_DIR);
+  const puppeteerDir = path.join(bmDir, PUPPETEER_DIR);
+  return {
+    bmDir,
+    settingsFile: path.join(bmDir, SETTINGS_FILE),
+    puppeteerDir,
+    chromeProfileDir: path.join(bmDir, CHROME_PROFILE_DIR),
+    pidFile: path.join(bmDir, PID_FILE),
+    // Dump outputs inside .puppeteer/
+    consoleLog: path.join(puppeteerDir, 'console.log'),
+    networkLog: path.join(puppeteerDir, 'network.log'),
+    networkDir: path.join(puppeteerDir, 'network-log'),
+    cookiesDir: path.join(puppeteerDir, 'cookies'),
+    domHtml: path.join(puppeteerDir, 'dom.html'),
+    screenshot: path.join(puppeteerDir, 'screenshot.png'),
+  };
+}
+
+/**
+ * Check if .browsermonitor/ directory exists (first-run detection).
+ * @param {string} projectRoot
+ * @returns {boolean}
+ */
+export function isInitialized(projectRoot) {
+  const { bmDir } = getPaths(projectRoot);
+  return fs.existsSync(bmDir);
+}
+
+/**
+ * Load settings from .browsermonitor/settings.json, merged with defaults.
+ * @param {string} projectRoot
+ * @returns {Object} Merged settings
+ */
+export function loadSettings(projectRoot) {
+  const { settingsFile } = getPaths(projectRoot);
+  try {
+    if (fs.existsSync(settingsFile)) {
+      const raw = fs.readFileSync(settingsFile, 'utf8');
+      const saved = JSON.parse(raw);
+      return { ...DEFAULT_SETTINGS, ...saved };
+    }
+  } catch {
+    // Ignore parse errors, fall through to defaults
+  }
+  return { ...DEFAULT_SETTINGS };
+}
+
+/**
+ * Write settings to .browsermonitor/settings.json.
+ * Creates .browsermonitor/ directory if needed.
+ * @param {string} projectRoot
+ * @param {Object} settings
+ */
+export function saveSettings(projectRoot, settings) {
+  const { bmDir, settingsFile } = getPaths(projectRoot);
+  fs.mkdirSync(bmDir, { recursive: true });
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+}
+
+/**
+ * Ensure all browsermonitor directories exist.
+ * @param {string} projectRoot
+ */
+export function ensureDirectories(projectRoot) {
+  const { bmDir, puppeteerDir, chromeProfileDir } = getPaths(projectRoot);
+  fs.mkdirSync(bmDir, { recursive: true });
+  fs.mkdirSync(puppeteerDir, { recursive: true });
+  fs.mkdirSync(chromeProfileDir, { recursive: true });
+}

package/src/templates/api-help.mjs

@@ -0,0 +1,212 @@
+/**
+ * Single source of truth for HTTP API and output files reference.
+ * Renders tables via cli-table3.
+ */
+
+import { C } from '../utils/colors.mjs';
+import { printSectionHeading } from './section-heading.mjs';
+import { createTable, printTable, INDENT } from './table-helper.mjs';
+import { printInteractiveSection } from './interactive-keys.mjs';
+
+// ─── Data (edit only here) ─────────────────────────────────────────────────
+
+export const API_ENDPOINTS = [
+  { method: 'GET', path: '/dump', description: 'Dump logs, DOM, cookies, screenshot to files; response has output paths' },
+  { method: 'GET', path: '/status', description: 'Current status, monitored URLs, stats, output file paths' },
+  { method: 'GET', path: '/stop', description: 'Pause collecting (console/network)' },
+  { method: 'GET', path: '/start', description: 'Resume collecting' },
+  { method: 'GET', path: '/clear', description: 'Clear in-memory buffers' },
+  { method: 'GET', path: '/tabs', description: 'List all user tabs (index, url)' },
+  { method: 'GET', path: '/tab?index=N', description: 'Switch monitored tab (1-based index)' },
+  { method: 'GET', path: '/computed-styles?selector=...', description: 'Get computed CSS for first element matching selector (default: body)' },
+  { method: 'POST', path: '/puppeteer', description: 'Call Puppeteer page method. Body: { "method": "page.goto", "args": ["https://..."] }. Whitelist: content, click, focus, goto, hover, pdf, screenshot, select, setDefaultNavigationTimeout, setDefaultTimeout, setViewport, title, type, url' },
+];
+
+export const OUTPUT_FILES = [
+  { path: '.browsermonitor/.puppeteer/console.log', description: 'Browser console output' },
+  { path: '.browsermonitor/.puppeteer/network.log', description: 'Network requests overview (IDs)' },
+  { path: '.browsermonitor/.puppeteer/network-log/', description: 'Per-request JSON (headers, payload, response)' },
+  { path: '.browsermonitor/.puppeteer/cookies/', description: 'Cookies per domain (JSON)' },
+  { path: '.browsermonitor/.puppeteer/dom.html', description: 'Current page DOM (for LLM / structure)' },
+  { path: '.browsermonitor/.puppeteer/screenshot.png', description: 'Screenshot of current tab viewport' },
+];
+
+/** Full description for API section. */
+const API_DESCRIPTION =
+  'For LLM Coding agents: Browser Monitor captures live browser state (console, network, DOM) and writes it to files. You or an LLM read those files instead of copy-pasting from DevTools. For debugging or feeding context to AI you need the real console, DOM, and traffic—this tool gives a one-command snapshot. Frontend devs and teams using LLM agents need it; without it, a reliable live-browser snapshot is much harder. Essential for E2E and for feeding DOM and network data to LLM agents.';
+
+const API_USAGE =
+  'Use curl to communicate with the HTTP API over REST. GET for status/dump/tabs etc.; POST for /puppeteer with JSON body. Example: curl http://127.0.0.1:60001/status  curl -X POST http://127.0.0.1:60001/puppeteer -H "Content-Type: application/json" -d \'{"method":"page.goto","args":["https://example.com"]}\'';
+
+/**
+ * Print HTTP API and output files as readable tables.
+ * @param {Object} options
+ * @param {number} [options.port=60001]
+ * @param {string} [options.host='127.0.0.1']
+ * @param {boolean} [options.showApi=true]
+ * @param {boolean} [options.showInteractive=false] - Interactive help (keyboard shortcuts, human interaction)
+ * @param {boolean} [options.showOutputFiles=true]
+ * @param {Object} [options.context] - Override paths for session help: { consoleLog, networkLog, domHtml }
+ * @param {Object} [options.sessionContext] - Full help only: { currentUrl, profilePath } – copy-paste for Claude Code
+ * @param {boolean} [options.noLeadingNewline=false] - Skip blank line before first section (e.g. when right after CLI intro)
+ */
+export function printApiHelpTable(options = {}) {
+  const {
+    port = 60001,
+    host = '127.0.0.1',
+    showApi = true,
+    showInteractive = false,
+    showOutputFiles = true,
+    context = null,
+    sessionContext = null,
+    noLeadingNewline = false,
+  } = options;
+
+  const baseUrl = `http://${host}:${port}`;
+
+  if (showApi) {
+    if (!noLeadingNewline) console.log('');
+    printSectionHeading('HTTP API', INDENT);
+
+    const hasSession = sessionContext && (sessionContext.currentUrl || sessionContext.profilePath);
+    const apiTable = createTable({
+      colWidths: hasSession ? [14, 82] : [14, 60],
+      tableOpts: { wordWrap: true, maxWidth: hasSession ? 100 : 90 },
+    });
+    const methodsContent = API_ENDPOINTS.map(
+      (r) => `${C.green}${r.method}${C.reset} ${C.brightCyan}${r.path}${C.reset} ${r.description}`
+    ).join('\n');
+    const urlLabel = sessionContext ? `${C.dim}HTTP API URL${C.reset}` : `${C.dim}Default URL${C.reset}`;
+
+    const rows = [];
+    if (sessionContext && (sessionContext.currentUrl || sessionContext.profilePath)) {
+      const lines = [];
+      if (sessionContext.currentUrl) {
+        lines.push(`${C.dim}Monitored URL:${C.reset}\n${C.brightCyan}${sessionContext.currentUrl}${C.reset}`);
+      }
+      if (sessionContext.profilePath) {
+        lines.push(`${C.dim}Chrome profile:${C.reset}\n${C.brightCyan}${sessionContext.profilePath}${C.reset}`);
+      }
+      rows.push([`${C.dim}Session${C.reset}`, lines.join('\n\n')]);
+    }
+    rows.push(
+      [`${C.dim}Description${C.reset}`, API_DESCRIPTION],
+      [`${C.dim}Usage${C.reset}`, API_USAGE],
+      [urlLabel, `${C.brightCyan}${baseUrl}${C.reset}`],
+      [`${C.dim}Methods${C.reset}`, methodsContent]
+    );
+    rows.forEach((r) => apiTable.push(r));
+    printTable(apiTable);
+  }
+
+  if (showOutputFiles) {
+    const files = context
+      ? [
+          { path: context.consoleLog, description: 'Console log' },
+          { path: context.networkLog, description: 'Network log' },
+          { path: context.networkDir, description: 'Per-request JSON (headers, payload, response)' },
+          { path: context.cookiesDir, description: 'Cookies per domain (JSON)' },
+          { path: context.domHtml, description: 'Current page DOM (LLM)' },
+          { path: context.screenshot, description: 'Screenshot of current tab' },
+        ]
+      : OUTPUT_FILES;
+
+    console.log('');
+    printSectionHeading('Output files', INDENT);
+    if (context) {
+      console.log(`${INDENT}${C.dim}(this run)${C.reset}`);
+    }
+    const content = files
+      .map((f) => `${C.dim}${f.description}${C.reset}\n${C.brightCyan}${f.path}${C.reset}`)
+      .join('\n\n');
+    const ofTable = createTable({
+      colWidths: [74],
+      tableOpts: { wordWrap: true, maxWidth: 80 },
+    });
+    ofTable.push([content]);
+    printTable(ofTable);
+  }
+
+  if (showInteractive) {
+    printInteractiveSection();
+  }
+
+  // Same info without tables, structured for LLM (no box-drawing / table chars; no keyboard shortcuts)
+  if (showApi || showOutputFiles) {
+    printApiHelpForLlm({ port, host, showApi, showOutputFiles, context, sessionContext });
+  }
+
+  console.log('');
+}
+
+/**
+ * Print API, output files and keys in plain structured text for LLM consumption (no tables).
+ * Same data as printApiHelpTable, format optimized for parsing by LLM.
+ */
+function printApiHelpForLlm(options = {}) {
+  const {
+    port = 60001,
+    host = '127.0.0.1',
+    showApi = true,
+    showOutputFiles = true,
+    context = null,
+    sessionContext = null,
+  } = options;
+
+  const baseUrl = `http://${host}:${port}`;
+  const files = context
+    ? [
+        { path: context.consoleLog, description: 'Console log' },
+        { path: context.networkLog, description: 'Network log' },
+        { path: context.networkDir, description: 'Per-request JSON (headers, payload, response)' },
+        { path: context.cookiesDir, description: 'Cookies per domain (JSON)' },
+        { path: context.domHtml, description: 'Current page DOM (LLM)' },
+        { path: context.screenshot, description: 'Screenshot of current tab' },
+      ]
+    : OUTPUT_FILES;
+
+  console.log('');
+  console.log('--- LLM reference (plain text, no tables) ---');
+  console.log('');
+  console.log('Base URL: ' + baseUrl);
+  if (sessionContext?.currentUrl) {
+    console.log('Monitored URL: ' + sessionContext.currentUrl);
+  }
+  if (sessionContext?.profilePath) {
+    console.log('Chrome profile path: ' + sessionContext.profilePath);
+  }
+  if (sessionContext?.currentUrl || sessionContext?.profilePath) {
+    console.log('');
+  }
+
+  if (showApi) {
+    console.log('HTTP API endpoints:');
+    for (const e of API_ENDPOINTS) {
+      console.log('  ' + e.method + ' ' + e.path);
+      console.log('    ' + e.description);
+    }
+    console.log('');
+  }
+
+  if (showOutputFiles) {
+    console.log('Output files (paths and purpose):');
+    for (const f of files) {
+      console.log('  ' + f.path);
+      console.log('    ' + f.description);
+    }
+    console.log('');
+  }
+
+  console.log('--- end LLM reference ---');
+  console.log('');
+}
+
+/**
+ * One-line API hint (for Ready bar and intro).
+ * @param {number} port
+ * @param {string} [host='127.0.0.1']
+ */
+export function apiHintOneLine(port, host = '127.0.0.1') {
+  const base = `http://${host}:${port}`;
+  return `${C.dim}curl ${base}/dump  ${base}/status  ${base}/stop  ${base}/start${C.reset}`;
+}

package/src/templates/cli-commands.mjs

@@ -0,0 +1,51 @@
+/**
+ * Single source of truth for CLI commands and usage.
+ * Used in intro and in --help so we never duplicate.
+ */
+
+import { C } from '../utils/colors.mjs';
+import { printSectionHeading } from './section-heading.mjs';
+import { createTable, printTable, INDENT } from './table-helper.mjs';
+
+// ─── Data (edit only here) ─────────────────────────────────────────────────
+
+export const ENTRY_POINT = 'browsermonitor';
+
+export const USAGE = 'browsermonitor [url] [options]';
+
+export const CLI_EXAMPLES = [
+  { command: 'browsermonitor', description: 'Interactive menu, then o = open / j = join / q = quit' },
+  { command: 'browsermonitor --open', description: 'Launch Chrome and monitor (URL from settings or first arg)' },
+  { command: 'browsermonitor --open https://localhost:5173/', description: 'Open with URL' },
+  { command: 'browsermonitor --join=9222', description: 'Attach to Chrome with remote debugging on port 9222' },
+  { command: 'browsermonitor init', description: 'Run setup: create .browsermonitor/, settings.json, update agent files' },
+  { command: 'browsermonitor --help', description: 'Show full help (options, API table, examples)' },
+];
+
+/**
+ * Print CLI commands as a readable table (intro and --help).
+ */
+export function printCliCommandsTable(options = {}) {
+  const { showEntry = true, showUsage = true } = options;
+
+  const table = createTable({
+    colWidths: [10, 68],
+    tableOpts: { wordWrap: true, maxWidth: 90 },
+  });
+
+  if (showEntry) {
+    table.push([`${C.dim}Entry${C.reset}`, `${C.green}${ENTRY_POINT}${C.reset}`]);
+  }
+  if (showUsage) {
+    table.push([`${C.dim}Usage${C.reset}`, `${C.brightCyan}${USAGE}${C.reset}`]);
+  }
+  const examplesContent = CLI_EXAMPLES.map(
+    (ex) => `${C.brightCyan}${ex.command}${C.reset}  ${ex.description}`
+  ).join('\n');
+  table.push([`${C.dim}Examples${C.reset}`, examplesContent]);
+
+  console.log('');
+  printSectionHeading('CLI', INDENT);
+  printTable(table);
+  console.log('');
+}

package/src/templates/interactive-keys.mjs

@@ -0,0 +1,33 @@
+/**
+ * Single source of truth for keyboard shortcuts (human interaction).
+ * Own section with same box heading as CLI / HTTP API.
+ */
+
+import { C } from '../utils/colors.mjs';
+import { printSectionHeading } from './section-heading.mjs';
+import { createTable, printTable, INDENT } from './table-helper.mjs';
+
+export const KEYBOARD_KEYS = [
+  { key: 'd', action: 'dump to files' },
+  { key: 'c', action: 'clear buffer' },
+  { key: 's', action: 'status' },
+  { key: 'p', action: 'pause/resume' },
+  { key: 't', action: 'switch tab' },
+  { key: 'h', action: 'this help' },
+  { key: 'k', action: 'kill / quit' },
+  { key: 'q', action: 'quit' },
+];
+
+const DESCRIPTION = 'Human interaction: keyboard shortcuts while monitoring.';
+
+export function printInteractiveSection() {
+  console.log('');
+  printSectionHeading('Interactive', INDENT);
+  console.log(`${INDENT}${C.dim}${DESCRIPTION}${C.reset}`);
+  console.log('');
+  const table = createTable({ colWidths: [6, 22] });
+  for (const r of KEYBOARD_KEYS) {
+    table.push([`${C.green}${r.key}${C.reset}`, r.action]);
+  }
+  printTable(table);
+}

package/src/templates/ready-help.mjs

@@ -0,0 +1,33 @@
+/**
+ * Shared "Ready" help block – printed once when monitoring starts and repeated
+ * every HELP_INTERVAL (e.g. 5) lines of status/output. Used by open-mode and join-mode.
+ */
+
+import { C } from '../utils/colors.mjs';
+import { createTable, printTable } from './table-helper.mjs';
+
+/** Keys line suffix: open = k+q with Chrome stays, join = k+q disconnect */
+export const KEYS_OPEN = `${C.green}k${C.reset}=close Chrome+quit ${C.green}q${C.reset}=quit (Chrome stays)`;
+export const KEYS_JOIN = `${C.green}k${C.reset}=kill ${C.green}q${C.reset}=quit`;
+
+/**
+ * Print the Ready block (single-cell table).
+ */
+export function printReadyHelp(httpPort, keysSuffix) {
+  const content = `${C.green}Ready${C.reset} │ ${C.green}d${C.reset}=dump ${C.green}c${C.reset}=clear ${C.green}s${C.reset}=status ${C.green}p${C.reset}=stop/start ${C.green}t${C.reset}=tab ${C.green}h${C.reset}=help │ ${keysSuffix}  ${C.dim}│ full table: h${C.reset}`;
+  const table = createTable({ colWidths: [95] });
+  table.push([content]);
+  printTable(table);
+}
+
+/**
+ * Print status block (s key) – URL first, then status line. Single-cell table.
+ */
+export function printStatusBlock(stats, urlLine, tabCount, collectingPaused) {
+  const urlDisplay = `${C.dim}URL:${C.reset} ${C.cyan}${urlLine}${C.reset}`;
+  const statusDisplay = `${C.cyan}[Status]${C.reset} ${C.brightCyan}${stats.consoleEntries}${C.reset} console │ ${C.brightCyan}${stats.networkEntries}${C.reset} network │ ${C.brightCyan}${stats.requestDetails}${C.reset} requests │ ${C.brightGreen}${tabCount}${C.reset} tab(s) │ collecting: ${collectingPaused ? C.yellow + 'paused' : C.green + 'running'}${C.reset}`;
+  const content = `${urlDisplay}\n${statusDisplay}`;
+  const table = createTable({ colWidths: [95] });
+  table.push([content]);
+  printTable(table);
+}