@romanmatena/browsermonitor 2.0.0 → 2.1.0

package/src/monitor/shared/cleanup.mjs

@@ -0,0 +1,96 @@
+/**
+ * Cleanup function and signal handler installation.
+ */
+
+import { log } from '../../utils/colors.mjs';
+
+/**
+ * Create cleanup function and install signal/error handlers.
+ * @param {Object} deps
+ * @param {() => import('puppeteer').Browser|null} deps.getBrowser
+ * @param {() => import('http').Server|null} deps.getHttpServer
+ * @param {(browser: import('puppeteer').Browser, closeBrowser: boolean) => Promise<void>} deps.closeBrowserFn
+ * @param {() => void} [deps.afterCleanup] - e.g. PID file removal
+ * @param {number} [deps.hardTimeout=0]
+ * @returns {{ cleanup: (code?: number, closeBrowser?: boolean) => Promise<void> }}
+ */
+export function createCleanup({ getBrowser, getHttpServer, closeBrowserFn, afterCleanup, hardTimeout = 0 }) {
+  let cleanupDone = false;
+
+  async function cleanup(code = 0, closeBrowser = false) {
+    if (cleanupDone) return;
+    cleanupDone = true;
+
+    console.log('');
+    log.info(closeBrowser ? 'Cleaning up and closing Chrome...' : 'Cleaning up...');
+
+    try {
+      const httpServer = getHttpServer();
+      if (httpServer) {
+        await new Promise((resolve) => httpServer.close(resolve));
+        log.dim('HTTP server closed');
+      }
+    } catch (e) {
+      log.error(`Error closing HTTP server: ${e.message}`);
+    }
+
+    try {
+      const browser = getBrowser();
+      if (browser) {
+        await closeBrowserFn(browser, closeBrowser);
+      }
+    } catch (e) {
+      log.error(`Error closing browser: ${e.message}`);
+    }
+
+    if (afterCleanup) {
+      try { afterCleanup(); } catch {}
+    }
+
+    process.exit(code);
+  }
+
+  // Signal handlers
+  process.on('SIGINT', () => {
+    console.log('');
+    log.dim('Received SIGINT (Ctrl+C)');
+    cleanup(0, false);
+  });
+
+  process.on('SIGTERM', () => {
+    console.log('');
+    log.dim('Received SIGTERM');
+    cleanup(0, false);
+  });
+
+  process.on('uncaughtException', (e) => {
+    const msg = (e && e.message) || String(e);
+    if (/Execution context was destroyed|Target closed|Protocol error/.test(msg)) {
+      log.dim(`Navigation/context closed: ${msg.slice(0, 60)}… (continuing)`);
+      return;
+    }
+    log.error(`Uncaught exception: ${e.message}`);
+    console.error(e.stack);
+    cleanup(1);
+  });
+
+  process.on('unhandledRejection', (e) => {
+    const msg = (e && e.message) || String(e);
+    if (/Execution context was destroyed|Target closed|Protocol error/.test(msg)) {
+      log.dim(`Navigation/context closed: ${msg.slice(0, 60)}… (continuing)`);
+      return;
+    }
+    log.error(`Unhandled rejection: ${e}`);
+    cleanup(1);
+  });
+
+  // Hard timeout
+  if (hardTimeout > 0) {
+    setTimeout(() => {
+      log.error(`HARD TIMEOUT (${hardTimeout}ms) - forcing exit`);
+      cleanup(1);
+    }, hardTimeout);
+  }
+
+  return { cleanup };
+}

package/src/monitor/shared/help.mjs

@@ -0,0 +1,64 @@
+/**
+ * Help display factories: periodic help reminder + full in-session help.
+ */
+
+import { C } from '../../utils/colors.mjs';
+import { printReadyHelp } from '../../templates/ready-help.mjs';
+import { printApiHelpTable } from '../../templates/api-help.mjs';
+
+/**
+ * Create help display functions bound to session state.
+ * @param {Object} deps
+ * @param {number} deps.httpPort
+ * @param {string} deps.keysVariant - KEYS_OPEN or KEYS_JOIN constant
+ * @param {Object} deps.logBuffer
+ * @param {string} deps.outputDir
+ * @param {string} deps.modeLabel - 'Launch mode' or 'Join mode'
+ * @param {() => string} deps.getCurrentUrl
+ * @param {() => string|null} deps.getProfilePath
+ * @param {() => string|null} deps.getBrowserUrl - join shows browserURL, open null
+ * @returns {{ maybeShowHelp: () => void, printHelp: () => void }}
+ */
+export function createHelpHandlers({
+  httpPort, keysVariant, logBuffer, outputDir,
+  modeLabel, getCurrentUrl, getProfilePath, getBrowserUrl,
+}) {
+  let outputCounter = 0;
+  const HELP_INTERVAL = 5;
+
+  function maybeShowHelp() {
+    outputCounter++;
+    if (outputCounter % HELP_INTERVAL === 0) {
+      printReadyHelp(httpPort, keysVariant);
+    }
+  }
+
+  function printHelp() {
+    const currentUrl = getCurrentUrl();
+    const browserUrl = getBrowserUrl();
+    const connInfo = browserUrl
+      ? `Browser: ${C.brightGreen}${browserUrl}${C.reset}  │  Dir: ${outputDir}`
+      : `URL: ${C.brightGreen}${currentUrl}${C.reset}  │  Dir: ${outputDir}`;
+    console.log(`${C.cyan}${modeLabel}${C.reset}  ${connInfo}`);
+    printApiHelpTable({
+      port: httpPort,
+      showApi: true,
+      showInteractive: true,
+      showOutputFiles: true,
+      context: {
+        consoleLog: logBuffer.CONSOLE_LOG,
+        networkLog: logBuffer.NETWORK_LOG,
+        networkDir: logBuffer.NETWORK_DIR,
+        cookiesDir: logBuffer.COOKIES_DIR,
+        domHtml: logBuffer.DOM_HTML,
+        screenshot: logBuffer.SCREENSHOT,
+      },
+      sessionContext: {
+        currentUrl: currentUrl || undefined,
+        profilePath: getProfilePath(),
+      },
+    });
+  }
+
+  return { maybeShowHelp, printHelp };
+}

package/src/monitor/shared/http-state-setup.mjs

@@ -0,0 +1,55 @@
+/**
+ * Wire sharedHttpState callbacks to mode-local state.
+ */
+
+import { filterUserPages } from './user-page-filter.mjs';
+
+/**
+ * @param {Object} sharedHttpState - mutable state object from CLI
+ * @param {Object} deps
+ * @param {string} deps.mode - 'launch' | 'join'
+ * @param {Object} deps.logBuffer
+ * @param {() => import('puppeteer').Page[]} deps.getMonitoredPages
+ * @param {() => boolean} deps.getCollectingPaused
+ * @param {(v: boolean) => void} deps.setCollectingPaused
+ * @param {() => import('puppeteer').Browser|null} deps.getBrowser
+ * @param {(page: import('puppeteer').Page, label?: string) => void} deps.setupPageMonitoring
+ * @param {(page: import('puppeteer').Page) => void} deps.onTabSwitched - mode-specific side effect
+ */
+export function wireHttpState(sharedHttpState, {
+  mode, logBuffer, getMonitoredPages, getCollectingPaused, setCollectingPaused,
+  getBrowser, setupPageMonitoring, onTabSwitched,
+}) {
+  sharedHttpState.mode = mode;
+  sharedHttpState.logBuffer = logBuffer;
+  sharedHttpState.getPages = getMonitoredPages;
+  sharedHttpState.getCollectingPaused = getCollectingPaused;
+  sharedHttpState.setCollectingPaused = setCollectingPaused;
+
+  sharedHttpState.getAllTabs = async () => {
+    const browser = getBrowser();
+    if (!browser) return [];
+    const allPages = await browser.pages();
+    return filterUserPages(allPages).map((p, i) => ({ index: i + 1, url: p.url() }));
+  };
+
+  sharedHttpState.switchToTab = async (index) => {
+    const browser = getBrowser();
+    if (!browser) return { success: false, error: 'Browser not connected' };
+    try {
+      const allPages = await browser.pages();
+      const pages = filterUserPages(allPages);
+      if (index < 1 || index > pages.length) {
+        return { success: false, error: `Invalid index. Use 1-${pages.length}.` };
+      }
+      const selectedPage = pages[index - 1];
+      onTabSwitched(selectedPage);
+      setupPageMonitoring(selectedPage);
+      logBuffer.printConsoleSeparator('TAB SWITCHED');
+      logBuffer.printNetworkSeparator('TAB SWITCHED');
+      return { success: true, url: selectedPage.url() };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  };
+}

package/src/monitor/shared/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * Shared utilities for open-mode and join-mode.
+ */
+
+export { filterUserPages } from './user-page-filter.mjs';
+export { createSetupPageMonitoring } from './monitoring-wrapper.mjs';
+export { createHelpHandlers } from './help.mjs';
+export { wireHttpState } from './http-state-setup.mjs';
+export { createSwitchTabs } from './tab-switching.mjs';
+export { createCleanup } from './cleanup.mjs';
+export { setupKeyboardInput } from './keyboard-handler.mjs';

package/src/monitor/shared/keyboard-handler.mjs

@@ -0,0 +1,79 @@
+/**
+ * Interactive keyboard input handler (raw mode stdin).
+ * Shared between open-mode and join-mode.
+ */
+
+import readline from 'readline';
+import { log } from '../../utils/colors.mjs';
+import { printStatusBlock } from '../../templates/ready-help.mjs';
+
+/**
+ * Setup keyboard input for lazy (buffered) mode.
+ * @param {Object} deps
+ * @param {() => import('puppeteer').Page|null} deps.getActivePage
+ * @param {Object} deps.logBuffer
+ * @param {(code?: number, closeBrowser?: boolean) => Promise<void>} deps.cleanup
+ * @param {() => Promise<void>} deps.switchTabs
+ * @param {() => void} deps.printHelp
+ * @param {() => void} deps.maybeShowHelp
+ * @param {() => boolean} deps.isSelectingTab
+ * @param {() => boolean} deps.getCollectingPaused
+ * @param {(v: boolean) => void} deps.setCollectingPaused
+ * @param {() => Promise<{ currentUrl: string, tabCount: number }>} deps.getStatusInfo
+ */
+export function setupKeyboardInput({
+  getActivePage, logBuffer, cleanup, switchTabs,
+  printHelp, maybeShowHelp, isSelectingTab,
+  getCollectingPaused, setCollectingPaused, getStatusInfo,
+}) {
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+
+  process.stdin.on('keypress', async (str, key) => {
+    if (key.ctrl && key.name === 'c') {
+      cleanup(0);
+      return;
+    }
+
+    // Ignore keys during tab selection
+    if (isSelectingTab()) return;
+
+    // Shortcuts only without modifiers
+    if (key.ctrl || key.shift || key.meta) return;
+
+    if (key.name === 'd') {
+      const page = getActivePage();
+      await logBuffer.dumpBuffersToFiles({
+        dumpCookies: page ? () => logBuffer.dumpCookiesFromPage(page) : null,
+        dumpDom: page ? () => logBuffer.dumpDomFromPage(page) : null,
+        dumpScreenshot: page ? () => logBuffer.dumpScreenshotFromPage(page) : null,
+      });
+      maybeShowHelp();
+    } else if (key.name === 'c') {
+      logBuffer.clearAllBuffers();
+      maybeShowHelp();
+    } else if (key.name === 'q') {
+      cleanup(0, false);
+    } else if (key.name === 'k') {
+      log.warn('Closing Chrome and exiting...');
+      cleanup(0, true);
+    } else if (key.name === 's') {
+      const { currentUrl, tabCount } = await getStatusInfo();
+      const stats = logBuffer.getStats();
+      printStatusBlock(stats, currentUrl, tabCount, getCollectingPaused());
+      maybeShowHelp();
+    } else if (key.name === 'p') {
+      const paused = !getCollectingPaused();
+      setCollectingPaused(paused);
+      log.info(paused ? 'Collecting stopped (paused). Press p or curl .../start to resume.' : 'Collecting started (resumed).');
+      maybeShowHelp();
+    } else if (key.name === 't') {
+      await switchTabs();
+      maybeShowHelp();
+    } else if (key.name === 'h') {
+      printHelp();
+    }
+  });
+}

package/src/monitor/shared/monitoring-wrapper.mjs

@@ -0,0 +1,39 @@
+/**
+ * Factory for page monitoring setup, bound to local session state.
+ * Manages listener lifecycle: each call to setupPageMonitoring automatically
+ * cleans up listeners from the previously monitored page.
+ */
+
+import { setupPageMonitoring as setupPageMonitoringShared } from '../page-monitoring.mjs';
+
+/**
+ * Create a setupPageMonitoring function bound to the current session's state.
+ * @param {Object} deps
+ * @param {Object} deps.logBuffer
+ * @param {() => boolean} deps.getCollectingPaused
+ * @returns {{ setupPageMonitoring: (page: import('puppeteer').Page, pageLabel?: string) => void, cleanupActivePageListeners: () => void }}
+ */
+export function createSetupPageMonitoring({ logBuffer, getCollectingPaused }) {
+  let activePageCleanup = null;
+
+  function cleanupActivePageListeners() {
+    if (activePageCleanup) {
+      activePageCleanup();
+      activePageCleanup = null;
+    }
+  }
+
+  function setupPageMonitoring(targetPage, pageLabel = '') {
+    // Remove listeners from previous page before attaching to new one
+    cleanupActivePageListeners();
+
+    setupPageMonitoringShared(targetPage, {
+      logBuffer,
+      getCollectingPaused,
+      setActivePageCleanup: (fn) => { activePageCleanup = fn; },
+      pageLabel,
+    });
+  }
+
+  return { setupPageMonitoring, cleanupActivePageListeners };
+}

package/src/monitor/shared/tab-switching.mjs

@@ -0,0 +1,61 @@
+/**
+ * Interactive tab switching (t key).
+ */
+
+import { C, log } from '../../utils/colors.mjs';
+import { askUserToSelectPage } from '../tab-selection.mjs';
+import { filterUserPages } from './user-page-filter.mjs';
+
+/**
+ * Create interactive tab-switch function.
+ * @param {Object} deps
+ * @param {() => import('puppeteer').Browser|null} deps.getBrowser
+ * @param {(page: import('puppeteer').Page) => void} deps.onTabSwitched
+ * @param {(page: import('puppeteer').Page, label?: string) => void} deps.setupPageMonitoring
+ * @param {Object} deps.logBuffer
+ * @param {(v: boolean) => void} deps.setSelectingTab
+ * @returns {() => Promise<void>}
+ */
+export function createSwitchTabs({ getBrowser, onTabSwitched, setupPageMonitoring, logBuffer, setSelectingTab }) {
+  return async () => {
+    const browser = getBrowser();
+    if (!browser) {
+      log.error('Browser not connected');
+      return;
+    }
+
+    try {
+      const allPages = await browser.pages();
+      const pages = filterUserPages(allPages);
+
+      if (pages.length === 0) {
+        log.warn('No user tabs found');
+        return;
+      }
+
+      if (pages.length === 1) {
+        log.info('Only one user tab available');
+        return;
+      }
+
+      setSelectingTab(true);
+      const selectedPage = await askUserToSelectPage(pages);
+      setSelectingTab(false);
+
+      if (selectedPage === null) {
+        log.dim('Tab switch cancelled');
+        return;
+      }
+
+      onTabSwitched(selectedPage);
+      setupPageMonitoring(selectedPage);
+      log.success(`Now monitoring: ${C.brightCyan}${selectedPage.url()}${C.reset}`);
+
+      logBuffer.printConsoleSeparator('TAB SWITCHED');
+      logBuffer.printNetworkSeparator('TAB SWITCHED');
+    } catch (e) {
+      log.error(`Error switching tabs: ${e.message}`);
+      setSelectingTab(false);
+    }
+  };
+}

package/src/monitor/shared/user-page-filter.mjs

@@ -0,0 +1,28 @@
+/**
+ * Filter browser internal / devtools pages from a page list.
+ * Single source of truth for "is this a user page?" across all modes.
+ *
+ * Strips: chrome://, devtools://, chrome-extension://, moz-extension://,
+ * extension://, React/Redux devtools background pages.
+ * Also strips about:blank unless it's the only remaining page.
+ *
+ * @param {import('puppeteer').Page[]} allPages
+ * @returns {import('puppeteer').Page[]}
+ */
+export function filterUserPages(allPages) {
+  const isUserPage = (p) => {
+    const u = p.url();
+    if (u.startsWith('chrome://')) return false;
+    if (u.startsWith('devtools://')) return false;
+    if (u.startsWith('chrome-extension://')) return false;
+    if (u.startsWith('moz-extension://')) return false;
+    if (u.startsWith('extension://')) return false;
+    if (u.includes('react-devtools') || u.includes('redux-devtools')) return false;
+    if (u.includes('__react_devtools__')) return false;
+    return true;
+  };
+  let pages = allPages.filter(isUserPage);
+  const nonBlank = pages.filter(p => p.url() !== 'about:blank');
+  if (nonBlank.length > 0) pages = nonBlank;
+  return pages;
+}

package/src/os/wsl/chrome.mjs

@@ -41,7 +41,6 @@ export function getLastCmdStderrAndClear() {
   _lastCmdStderrLines = [];
   return lines;
 }
-import { getWslDistroName } from './detect.mjs';
 
 // Cache for LOCALAPPDATA path
 let _cachedLocalAppData = null;
@@ -329,12 +328,9 @@ export function startChromeOnWindows(chromePath, port, profileDir) {
       );
     } catch { /* ignore */ }
 
-    const args = [
-      `--remote-debugging-port=${port}`,
-      `--user-data-dir="${profileDir}"`,
-    ].join("','");
-
-    const psCommand = `Start-Process -FilePath '${chromePath}' -ArgumentList '${args}'`;
+    // Escape single quotes for PowerShell literal strings (double them)
+    const psEsc = (s) => s.replace(/'/g, "''");
+    const psCommand = `Start-Process -FilePath '${psEsc(chromePath)}' -ArgumentList @('--remote-debugging-port=${port}','--user-data-dir=${psEsc(profileDir)}')`;
     execSync(`powershell.exe -NoProfile -Command "${psCommand}"`, { encoding: 'utf8', timeout: 10000 });
 
     log.dim('Waiting for Chrome to start...');
@@ -472,32 +468,3 @@ export function killPuppeteerMonitorChromes(usePowerShell = false) {
   }
 }
 
-/**
- * Legacy wrapper for backward compatibility.
- */
-export function checkChromeRunning() {
-  const { instances, chromeRunning } = scanChromeInstances();
-  if (!chromeRunning) {
-    return { running: false, withDebugPort: false, debugPort: null };
-  }
-  if (instances.length === 0) {
-    return { running: true, withDebugPort: false, debugPort: null };
-  }
-  return {
-    running: true,
-    withDebugPort: true,
-    debugPort: instances[0].port,
-    instances,
-  };
-}
-
-/**
- * Legacy wrapper for backward compatibility.
- */
-export function launchChromeFromWSL(chromePath, port) {
-  const distroName = getWslDistroName();
-  const wslPath = process.cwd();
-  const winPath = wslPath.replace(/\//g, '\\');
-  const profileDir = `\\\\wsl$\\${distroName}${winPath}\\.browsermonitor-profile`;
-  return startChromeOnWindows(chromePath, port, profileDir);
-}

package/src/os/wsl/detect.mjs

@@ -54,15 +54,3 @@ export function getWindowsHostForWSL(opts = {}) {
   return 'localhost';
 }
 
-/**
- * Convert WSL path to Windows UNC path.
- * Note: UNC paths don't work well with Chrome profiles due to singleton detection.
- *
- * @param {string} wslPath - WSL path (e.g., /srv/project)
- * @returns {string} Windows UNC path (e.g., \\wsl$\Ubuntu\srv\project)
- */
-export function wslToWindowsPath(wslPath) {
-  const distroName = getWslDistroName();
-  const winPath = wslPath.replace(/\//g, '\\');
-  return `\\\\wsl$\\${distroName}${winPath}`;
-}

package/src/os/wsl/index.mjs

@@ -10,7 +10,6 @@ export {
   isWsl,
   getWslDistroName,
   getWindowsHostForWSL,
-  wslToWindowsPath,
 } from './detect.mjs';
 
 // Chrome detection and launch
@@ -26,8 +25,6 @@ export {
   findFreeDebugPort,
   startChromeOnWindows,
   killPuppeteerMonitorChromes,
-  checkChromeRunning,
-  launchChromeFromWSL,
 } from './chrome.mjs';
 
 // Port proxy management

package/src/settings.mjs

@@ -16,7 +16,7 @@ export const PID_FILE = 'browsermonitor.pid';
 
 /** Default settings for new projects */
 export const DEFAULT_SETTINGS = {
-  defaultUrl: 'https://localhost:4000/',
+  defaultUrl: 'about:blank',
   headless: false,
   navigationTimeout: 60000,
   ignorePatterns: [],
@@ -30,6 +30,7 @@ export const DEFAULT_SETTINGS = {
  * @returns {Object} All paths used by browsermonitor
  */
 export function getPaths(projectRoot) {
+  projectRoot = path.resolve(projectRoot);
   const bmDir = path.join(projectRoot, BROWSERMONITOR_DIR);
   const puppeteerDir = path.join(bmDir, PUPPETEER_DIR);
   return {
@@ -49,32 +50,33 @@ export function getPaths(projectRoot) {
 }
 
 /**
- * Check if .browsermonitor/ directory exists (first-run detection).
+ * Check if settings.json exists (first-run detection).
  * @param {string} projectRoot
  * @returns {boolean}
  */
 export function isInitialized(projectRoot) {
-  const { bmDir } = getPaths(projectRoot);
-  return fs.existsSync(bmDir);
+  const { settingsFile } = getPaths(projectRoot);
+  return fs.existsSync(settingsFile);
 }
 
 /**
- * Load settings from .browsermonitor/settings.json, merged with defaults.
+ * Load settings from .browsermonitor/settings.json.
+ * Returns only what is actually saved — no default merging.
+ * Missing keys mean "not configured yet" so the caller can prompt the user.
  * @param {string} projectRoot
- * @returns {Object} Merged settings
+ * @returns {Object} Saved settings (may be empty)
  */
 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 };
+      return JSON.parse(raw);
     }
   } catch {
-    // Ignore parse errors, fall through to defaults
+    // Ignore parse errors, fall through to empty
   }
-  return { ...DEFAULT_SETTINGS };
+  return {};
 }
 
 /**

package/src/templates/api-help.mjs

@@ -43,6 +43,7 @@ const API_USAGE =
  * @param {Object} options
  * @param {number} [options.port=60001]
  * @param {string} [options.host='127.0.0.1']
+ * @param {string} [options.url] - Browser URL being monitored (shown in header)
  * @param {boolean} [options.showApi=true]
  * @param {boolean} [options.showInteractive=false] - Interactive help (keyboard shortcuts, human interaction)
  * @param {boolean} [options.showOutputFiles=true]
@@ -54,6 +55,7 @@ export function printApiHelpTable(options = {}) {
   const {
     port = 60001,
     host = '127.0.0.1',
+    url = null,
     showApi = true,
     showInteractive = false,
     showOutputFiles = true,
@@ -66,7 +68,8 @@ export function printApiHelpTable(options = {}) {
 
   if (showApi) {
     if (!noLeadingNewline) console.log('');
-    printSectionHeading('HTTP API', INDENT);
+    const heading = url ? `HTTP API  ${C.dim}→${C.reset}  ${C.brightCyan}${url}${C.reset}` : 'HTTP API';
+    printSectionHeading(heading, INDENT);
 
     const hasSession = sessionContext && (sessionContext.currentUrl || sessionContext.profilePath);
     const apiTable = createTable({
@@ -133,7 +136,7 @@ export function printApiHelpTable(options = {}) {
 
   // 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 });
+    printApiHelpForLlm({ port, host, url, showApi, showOutputFiles, context, sessionContext });
   }
 
   console.log('');
@@ -147,6 +150,7 @@ function printApiHelpForLlm(options = {}) {
   const {
     port = 60001,
     host = '127.0.0.1',
+    url = null,
     showApi = true,
     showOutputFiles = true,
     context = null,
@@ -168,6 +172,9 @@ function printApiHelpForLlm(options = {}) {
   console.log('');
   console.log('--- LLM reference (plain text, no tables) ---');
   console.log('');
+  if (url) {
+    console.log('Browser URL: ' + url);
+  }
   console.log('Base URL: ' + baseUrl);
   if (sessionContext?.currentUrl) {
     console.log('Monitored URL: ' + sessionContext.currentUrl);
@@ -201,12 +208,3 @@ function printApiHelpForLlm(options = {}) {
   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

@@ -18,7 +18,7 @@ export const CLI_EXAMPLES = [
   { 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 init', description: 'Create .browsermonitor/, settings.json with defaults, update agent files' },
   { command: 'browsermonitor --help', description: 'Show full help (options, API table, examples)' },
 ];