browser-flow-tracker 0.1.0 → 0.2.0

package/README.md

@@ -77,8 +77,11 @@ Here's a taste of what ends up in your `.md` file:
 …plus the full request and response details for each call. 🎉
 
 It's smart, too: it **throws away the boring noise** (images, fonts, styling,
-tracking/analytics pixels) and keeps only the meaningful stuff. And it **hides your
-passwords and login tokens** by default so you can share the doc safely.
+tracking/analytics pixels) and keeps only the meaningful stuff. It **hides your
+secrets** by default — auth headers and cookies, *plus* password/token-style fields
+inside request & response bodies and URLs — so you can share the doc safely. And if
+your flow **opens a popup or a new tab** (an OAuth login, a payment window), that
+tab's API calls are captured too, in the same recording.
 
 ---
 
@@ -229,10 +232,39 @@ node bin/bft.js record --launch --browser brave \
 
 ## 🤖 Connecting to Claude / Cursor
 
-You give Claude/Cursor a tiny **settings snippet** that tells them how to run the tool.
-There's nothing to download — it runs straight from npm with `npx`.
+### ✅ Recommended: one-line install (no Node, works on macOS, Windows & Linux)
 
-### The one snippet you need
+The most reliable way — **no Node.js required** — and it avoids the `spawn npx ENOENT`
+PATH problems that trip up GUI apps. It installs a standalone binary and prints the exact
+MCP config to paste.
+
+**macOS & Linux** — in Terminal:
+
+```bash
+curl -fsSL https://apiflowtracker.com/install.sh | sh
+```
+Then your MCP config command is (same path on every Mac/Linux machine):
+```json
+{ "mcpServers": { "browser-flow-tracker": { "command": "/usr/local/bin/browser-flow-tracker" } } }
+```
+
+**Windows** — in PowerShell:
+
+```powershell
+irm https://apiflowtracker.com/install.ps1 | iex
+```
+Then your MCP config command is the path the installer prints, e.g.:
+```json
+{ "mcpServers": { "browser-flow-tracker": { "command": "C:\\Users\\you\\AppData\\Local\\browser-flow-tracker\\browser-flow-tracker.exe" } } }
+```
+
+> The installer downloads the right build for your CPU automatically (Apple Silicon or
+> Intel Mac, x64 or arm64 Linux, x64 Windows). Restart your AI app after adding the config.
+
+### Alternative: via npx (only if you already have Node.js)
+
+If Node 18+ is installed *and* on your app's PATH, you can skip the install and run it
+straight from npm:
 
 ```json
 {
@@ -245,30 +277,21 @@ There's nothing to download — it runs straight from npm with `npx`.
 }
 ```
 
-That's it — `npx` fetches and runs the tool automatically. It uses the browsers already
-installed on your computer; nothing extra to install.
-
-### Where to put it
-
-- **Claude Code (easiest):** run this one command and it's added everywhere:
+Claude Code shortcut: `claude mcp add browser-flow-tracker -- npx -y browser-flow-tracker@latest`
 
-  ```bash
-  claude mcp add browser-flow-tracker -- npx -y browser-flow-tracker@latest
-  ```
+> If you hit `spawn npx ENOENT`, your app can't see `npx` on its PATH — use the one-line
+> installer above instead; it sidesteps the whole issue.
 
-  (Or paste the snippet into a project's `.mcp.json`.)
+### Where the config file lives
 
-- **Cursor:** open your MCP settings file and add the `browser-flow-tracker` block, then
-  restart Cursor and enable it in **Settings → MCP**. Your config lives at
-  `.cursor/mcp.json` (per project) or `~/.cursor/mcp.json` (global, all projects).
+- **Claude Code:** `.mcp.json` in a project, or your user config (managed by `claude mcp`).
+- **Cursor:** `.cursor/mcp.json` (per project) or `~/.cursor/mcp.json` (global).
 
 > ⚠️ **Already using other MCP tools?** Don't replace your file — **add** the
 > `browser-flow-tracker` block *inside* your existing `mcpServers`, with a **comma** after
-> your previous tool. Valid JSON = matching `{ }` and commas between entries but not after
-> the last one. The `claude mcp add` command above does this merge for you automatically.
+> your previous tool. Keep it valid JSON (commas between entries, none after the last).
 
-Ready-made copies of the snippet are in this repo as `.mcp.json.example` and
-`.cursor/mcp.json.example`.
+Ready-made copies are in this repo as `.mcp.json.example` and `.cursor/mcp.json.example`.
 
 ### Prefer to run from source? (for the CLI or development)
 
@@ -279,6 +302,7 @@ want to hack on the code:
 git clone https://github.com/devggaurav/web-Api-scrapper.git
 cd web-Api-scrapper
 npm install
+npm test   # unit tests (redaction, filtering, exporters)
 # MCP: point your config's command at "node" with args ["<full-path>/mcp/server.js"]
 # CLI: node bin/bft.js record --launch --browser brave --url https://example.com
 ```
@@ -365,8 +389,19 @@ Not yet 😔 — Safari and Firefox work differently under the hood. For now use
 Chrome, Arc, or Edge. (Safari support is on the roadmap.)
 
 **"Is it safe to share the document?"**
-By default, **yes** — passwords, cookies, and login tokens are automatically hidden.
-Only if you used `--no-redact` should you be careful.
+By default, **yes**. The tool redacts secrets in all three places they show up:
+auth/cookie headers, token-style URL parameters (`?token=…`, `?api_key=…`), and
+password/token-style fields inside JSON & form request/response bodies
+(`password`, `access_token`, `client_secret`, `otp`, card numbers, …). Field names
+it doesn't recognize as secrets are kept — so if an app uses an unusual name for a
+secret, skim the doc once before sharing. Only if you used `--no-redact` should you
+be careful.
+
+**"My flow opens a popup / new tab — is that captured?"**
+Yes. OAuth windows, payment popups, and "open in new tab" links are attached to
+automatically (they're even paused for a split second at birth so their very first
+request isn't missed). Their calls appear in the same document, marked with the tab
+they came from.
 
 ---
 
@@ -383,7 +418,6 @@ can actually read. That's it. 🎩
 ## 🗺️ Roadmap (coming later)
 
 - 🧭 Safari & Firefox support (via a different listening method)
-- 🪟 Watch multiple browser tabs at once
 - 🔀 "Diff" mode — compare two recordings to see what changed
 - 🧩 Auto-group calls into logical steps in the doc
 

package/mcp/server.js

@@ -12,6 +12,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { TrackingSession } from '../src/session.js';
 import { detectInstalled } from '../src/browsers.js';
+import { VERSION } from '../src/version.js';
 
 let current = null; // the single active TrackingSession
 
@@ -23,7 +24,7 @@ function err(message) {
 }
 
 const server = new McpServer(
-  { name: 'browser-flow-tracker', version: '0.1.0' },
+  { name: 'browser-flow-tracker', version: VERSION },
   {
     instructions: [
       'Use these tools whenever the user wants to record, analyze, or document the',
@@ -124,7 +125,17 @@ server.registerTool(
     }
     if (!current?.active) return err('No active tracking session. Call start_tracking first.');
     const snap = current.snapshot();
-    if (full) return json(snap);
+    if (full) {
+      // Cap bodies so a long recording can't blow past MCP result limits —
+      // the complete detail always lands in the .flow.json on stop.
+      const MAX_INLINE_BODY = 4000;
+      const clip = (b) => {
+        const s = typeof b === 'string' ? b : b == null ? b : JSON.stringify(b);
+        return s && s.length > MAX_INLINE_BODY ? s.slice(0, MAX_INLINE_BODY) + '… [truncated]' : b;
+      };
+      snap.flow = snap.flow.map((e) => ({ ...e, requestBody: clip(e.requestBody), responseBody: clip(e.responseBody) }));
+      return json(snap);
+    }
     const summary = snap.flow
       .filter((e) => e.category !== 'document')
       .map((e) => ({ i: e.index, method: e.method, url: `${e.host}${e.path}`, status: e.status, ms: e.durationMs }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-flow-tracker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Record and document the API flow of any Chromium browser page (Brave, Chrome, Arc, Edge) via the Chrome DevTools Protocol. Ships as a local MCP server for Claude/Cursor and a CLI. Emits structured JSON + HAR + a Markdown flow-doc.",
   "type": "module",
   "bin": {
@@ -16,7 +16,14 @@
   ],
   "scripts": {
     "start": "node bin/bft.js",
-    "mcp": "node mcp/server.js"
+    "mcp": "node mcp/server.js",
+    "test": "node --test",
+    "build:darwin-arm64": "bun build ./mcp/server.js --compile --target=bun-darwin-arm64 --outfile dist/browser-flow-tracker-darwin-arm64",
+    "build:darwin-x64": "bun build ./mcp/server.js --compile --target=bun-darwin-x64 --outfile dist/browser-flow-tracker-darwin-x64",
+    "build:linux-x64": "bun build ./mcp/server.js --compile --target=bun-linux-x64 --outfile dist/browser-flow-tracker-linux-x64",
+    "build:linux-arm64": "bun build ./mcp/server.js --compile --target=bun-linux-arm64 --outfile dist/browser-flow-tracker-linux-arm64",
+    "build:windows-x64": "bun build ./mcp/server.js --compile --target=bun-windows-x64 --outfile dist/browser-flow-tracker-windows-x64.exe",
+    "build:all": "npm run build:darwin-arm64 && npm run build:darwin-x64 && npm run build:linux-x64 && npm run build:linux-arm64 && npm run build:windows-x64"
   },
   "engines": {
     "node": ">=18"
@@ -41,14 +48,17 @@
   "bugs": {
     "url": "https://github.com/devggaurav/web-Api-scrapper/issues"
   },
-  "homepage": "https://github.com/devggaurav/web-Api-scrapper#readme",
+  "homepage": "https://apiflowtracker.com/",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "chrome-remote-interface": "^0.33.3",
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "chrome-remote-interface": "^0.33.3",
     "zod": "^4.4.3"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "bun": "^1.3.14"
+  }
 }

package/src/browsers.js

@@ -30,16 +30,29 @@ const BINARIES = {
     opera: ['/usr/bin/opera'],
     chromium: ['/usr/bin/chromium', '/usr/bin/chromium-browser'],
   },
-  win32: {
-    brave: ['C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe'],
-    chrome: [
-      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
-      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
-    ],
-    edge: ['C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe'],
-  },
+  win32: winPaths(),
 };
 
+// Windows installs land in three different roots depending on the installer:
+// per-machine (Program Files), 32-bit legacy (Program Files (x86)), or
+// per-user (%LOCALAPPDATA%) — the per-user one is the most common for Chrome.
+function winPaths() {
+  const roots = [
+    process.env.PROGRAMFILES || 'C:\\Program Files',
+    process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)',
+    process.env.LOCALAPPDATA || '',
+  ].filter(Boolean);
+  const under = (suffix) => roots.map((r) => `${r}\\${suffix}`);
+  return {
+    brave: under('BraveSoftware\\Brave-Browser\\Application\\brave.exe'),
+    chrome: under('Google\\Chrome\\Application\\chrome.exe'),
+    edge: under('Microsoft\\Edge\\Application\\msedge.exe'),
+    vivaldi: under('Vivaldi\\Application\\vivaldi.exe'),
+    opera: under('Opera\\opera.exe').concat(under('Programs\\Opera\\opera.exe')),
+    chromium: under('Chromium\\Application\\chrome.exe'),
+  };
+}
+
 // Browsers that are Chromium-based but not covered here (Safari/WebKit,
 // Firefox/Gecko) do not expose CDP and need the proxy engine instead.
 export const UNSUPPORTED_CDP = {

package/src/cdpRecorder.js

@@ -1,10 +1,18 @@
-// Core capture engine. Attaches to a running Chromium browser over the
-// Chrome DevTools Protocol and records the network flow of a page target in
-// order, with request/response metadata and (bounded) bodies.
+// Core capture engine. Connects to a Chromium browser over the Chrome
+// DevTools Protocol and records the network flow of page targets in order,
+// with request/response metadata and (bounded) bodies.
+//
+// Multi-tab aware, race-free: a single browser-level CDP connection uses
+// Target.setAutoAttach with waitForDebuggerOnStart, so every new tab/popup
+// (OAuth windows, payment redirects, "open in new tab") is PAUSED at creation
+// until Network capture is enabled — no requests are missed, and the whole
+// flow lands in one recording. Tabs are multiplexed over one socket via flat
+// CDP sessions.
 
 import CDP from 'chrome-remote-interface';
 
 const DEFAULT_MAX_BODY = 512 * 1024; // 512 KB per body, to stay sane
+const STOP_BODY_GRACE_MS = 1500; // max wait for in-flight body fetches on stop
 
 // Wait until the CDP endpoint is reachable (a freshly launched browser needs
 // a moment to open its debugging port).
@@ -26,74 +34,163 @@ async function waitForEndpoint(port, host, timeoutMs = 15000) {
   );
 }
 
+function isRecordablePage(info) {
+  const url = info.url || '';
+  return info.type === 'page' && !url.startsWith('devtools://');
+}
+
 export class CdpRecorder {
-  constructor({ port = 9222, host = 'localhost', maxBodyBytes = DEFAULT_MAX_BODY, targetFilter } = {}) {
+  /**
+   * @param {object} opts
+   *   port, host      - CDP endpoint
+   *   maxBodyBytes    - per-body capture cap
+   *   targetFilter    - optional (target) => boolean to pick initial tab(s)
+   *   attachAll       - record ALL page targets, incl. any new tab that
+   *                     appears (launch mode: the whole window is ours).
+   *                     When false (attach mode), only the filtered/first tab
+   *                     plus popups OPENED BY a recorded tab are captured.
+   */
+  constructor({ port = 9222, host = 'localhost', maxBodyBytes = DEFAULT_MAX_BODY, targetFilter, attachAll = false } = {}) {
     this.port = port;
     this.host = host;
     this.maxBodyBytes = maxBodyBytes;
-    this.targetFilter = targetFilter; // optional (target) => boolean to pick a tab
-    this.client = null;
+    this.targetFilter = targetFilter;
+    this.attachAll = attachAll;
+    this.client = null; // single browser-level connection
+    this.sessions = new Map(); // sessionId -> tab {index, targetId, url}
+    this.tabTargetIds = new Set(); // targetIds we record (for openerId checks)
+    this.wantedTargetIds = new Set(); // initial tabs chosen at start()
+    this.tabSeq = 0;
     this.seq = 0;
-    this.startWall = null;
     this.startedAt = null;
-    // requestId -> record
-    this.records = new Map();
-    // preserve emission order
+    this.records = new Map(); // `${sessionId}:${requestId}` -> record
     this.order = [];
-    this.target = null;
+    this.pendingBodies = new Set(); // in-flight getResponseBody promises
+    this.target = null; // main (first) target info, for the doc header
+    this.mainSessionId = null;
+    this.stopping = false;
+    this.everAttached = false;
   }
 
   async start() {
     const targets = await waitForEndpoint(this.port, this.host);
-    const pages = targets.filter((t) => t.type === 'page' && !t.url.startsWith('devtools://'));
-    let chosen = pages;
-    if (this.targetFilter) chosen = pages.filter(this.targetFilter);
-    const target = chosen[0] || pages[0];
-    if (!target) throw new Error('No suitable page target to attach to.');
-    this.target = target;
-
-    this.client = await CDP({ port: this.port, host: this.host, target });
-    const { Network, Page } = this.client;
-
-    await Network.enable({ maxTotalBufferSize: 100_000_000, maxResourceBufferSize: 20_000_000 });
-    try { await Page.enable(); } catch { /* Page domain optional */ }
+    const pages = targets.filter((t) => isRecordablePage({ type: t.type, url: t.url }));
+    let chosen = this.targetFilter ? pages.filter(this.targetFilter) : pages;
+    if (!this.attachAll && !this.targetFilter) chosen = pages.slice(0, 1);
+    if (!chosen.length) chosen = pages.slice(0, 1);
+    if (!chosen.length) throw new Error('No suitable page target to attach to.');
+    for (const t of chosen) this.wantedTargetIds.add(t.id);
 
+    const version = await CDP.Version({ port: this.port, host: this.host });
+    if (!version.webSocketDebuggerUrl) {
+      throw new Error('Browser exposes no webSocketDebuggerUrl; a Chromium >= 63 is required.');
+    }
+    const client = await CDP({ target: version.webSocketDebuggerUrl });
+    this.client = client;
     this.startedAt = new Date().toISOString();
 
-    Network.requestWillBeSent((p) => this._onRequest(p));
-    Network.responseReceived((p) => this._onResponse(p));
-    Network.loadingFinished((p) => this._onFinished(p));
-    Network.loadingFailed((p) => this._onFailed(p));
-    Network.webSocketCreated((p) => this._onWebSocket(p));
-
-    // Fires when the browser/tab is closed by the user (the CDP socket drops).
-    // Lets the session auto-finalize and write files on browser close.
-    this.client.on('disconnect', () => {
+    client.on('disconnect', () => {
       if (!this.stopping) this.onDisconnect?.();
     });
 
-    return { target: { id: target.id, url: target.url, title: target.title } };
+    // Route network events to the owning tab via the flat-session id.
+    client.on('Network.requestWillBeSent', (p, sid) => this._onRequest(sid, p));
+    client.on('Network.responseReceived', (p, sid) => this._onResponse(sid, p));
+    client.on('Network.loadingFinished', (p, sid) => this._onFinished(sid, p));
+    client.on('Network.loadingFailed', (p, sid) => this._onFailed(sid, p));
+    client.on('Network.webSocketCreated', (p, sid) => this._onWebSocket(sid, p));
+
+    client.on('Target.attachedToTarget', (p) => { this._onAttached(p).catch(() => {}); });
+    client.on('Target.detachedFromTarget', ({ sessionId }) => this._onDetached(sessionId));
+
+    // Pause every NEW target at creation until we've enabled Network on it.
+    await client.Target.setAutoAttach({ autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
+
+    // Existing tabs aren't covered by autoAttach — attach to the chosen ones.
+    for (const t of chosen) {
+      await client.Target.attachToTarget({ targetId: t.id, flatten: true });
+    }
+
+    // attachedToTarget events have been handled synchronously above.
+    return { target: this.target, tabs: this.sessions.size };
   }
 
-  // Navigate the attached target. Used by launch mode so the recorder is
-  // listening before the page fires its first request (avoids missing early calls).
+  async _onAttached({ sessionId, targetInfo, waitingForDebugger }) {
+    const { targetId } = targetInfo;
+    const wanted = this.wantedTargetIds.has(targetId);
+    const openedByUs = targetInfo.openerId && this.tabTargetIds.has(targetInfo.openerId);
+    const record =
+      !this.stopping &&
+      isRecordablePage(targetInfo) &&
+      (wanted || this.attachAll || openedByUs);
+
+    if (!record) {
+      // Not ours: resume it (it may be paused) and let it go.
+      try { await this.client.Runtime.runIfWaitingForDebugger(sessionId); } catch { /* ignore */ }
+      try { await this.client.Target.detachFromTarget({ sessionId }); } catch { /* ignore */ }
+      return;
+    }
+
+    const tab = { index: this.tabSeq++, targetId, url: targetInfo.url || '' };
+    this.sessions.set(sessionId, tab);
+    this.tabTargetIds.add(targetId);
+    this.everAttached = true;
+    if (this.mainSessionId == null) {
+      this.mainSessionId = sessionId;
+      this.target = { id: targetId, url: targetInfo.url, title: targetInfo.title };
+    }
+
+    try {
+      await this.client.Network.enable(
+        { maxTotalBufferSize: 100_000_000, maxResourceBufferSize: 20_000_000 },
+        sessionId,
+      );
+      try { await this.client.Page.enable(sessionId); } catch { /* Page domain optional */ }
+    } finally {
+      // Only resume the page once capture is on — this is what makes new
+      // tabs/popups lose zero requests.
+      if (waitingForDebugger) {
+        try { await this.client.Runtime.runIfWaitingForDebugger(sessionId); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  // A recorded tab went away (closed or crashed). When the LAST one goes,
+  // treat it like the user closing the browser: auto-finalize. (On macOS the
+  // browser process can outlive its last window, so the browser-level
+  // disconnect alone isn't enough.)
+  _onDetached(sessionId) {
+    const tab = this.sessions.get(sessionId);
+    if (!tab) return;
+    this.sessions.delete(sessionId);
+    this.tabTargetIds.delete(tab.targetId);
+    if (!this.stopping && this.everAttached && this.sessions.size === 0) {
+      this.onDisconnect?.();
+    }
+  }
+
+  // Navigate the main tab. Used by launch mode so the recorder is listening
+  // before the page fires its first request (avoids missing early calls).
   async navigate(url) {
-    if (!this.client) throw new Error('Recorder not started.');
-    await this.client.Page.navigate({ url });
+    if (!this.client || this.mainSessionId == null) throw new Error('Recorder not started.');
+    await this.client.Page.navigate({ url }, this.mainSessionId);
   }
 
-  _rec(requestId) {
-    let rec = this.records.get(requestId);
+  _rec(sessionId, requestId) {
+    const key = `${sessionId}:${requestId}`;
+    let rec = this.records.get(key);
     if (!rec) {
       rec = { requestId, index: this.seq++ };
-      this.records.set(requestId, rec);
-      this.order.push(requestId);
+      this.records.set(key, rec);
+      this.order.push(key);
     }
     return rec;
   }
 
-  _onRequest(p) {
-    const rec = this._rec(p.requestId);
+  _onRequest(sessionId, p) {
+    const tab = this.sessions.get(sessionId);
+    if (!tab) return;
+    const rec = this._rec(sessionId, p.requestId);
     const r = p.request;
     // A redirect reuses the requestId; keep the redirect chain instead of losing it.
     if (rec.method && p.redirectResponse) {
@@ -109,11 +206,15 @@ export class CdpRecorder {
     rec.wallTime = p.wallTime;
     rec.timestamp = p.timestamp;
     rec.initiator = p.initiator ? { type: p.initiator.type } : undefined;
-    if (this.startWall == null && p.wallTime) this.startWall = p.wallTime;
+    rec.tab = tab.index;
+    // A tab's first document request is its real URL (popups start blank).
+    if (p.type === 'Document') tab.url = r.url;
+    rec.tabUrl = tab.url;
   }
 
-  _onResponse(p) {
-    const rec = this._rec(p.requestId);
+  _onResponse(sessionId, p) {
+    if (!this.sessions.has(sessionId)) return;
+    const rec = this._rec(sessionId, p.requestId);
     const res = p.response;
     rec.status = res.status;
     rec.statusText = res.statusText;
@@ -128,18 +229,25 @@ export class CdpRecorder {
     }
   }
 
-  async _onFinished(p) {
-    const rec = this._rec(p.requestId);
+  _onFinished(sessionId, p) {
+    if (!this.sessions.has(sessionId)) return;
+    const rec = this._rec(sessionId, p.requestId);
     rec.encodedDataLength = p.encodedDataLength;
     rec.finishedTs = p.timestamp;
     if (rec.timestamp != null && p.timestamp != null) {
       rec.durationMs = Math.max(0, (p.timestamp - rec.timestamp) * 1000);
     }
-    await this._captureBody(rec);
+    // Track the fetch so stop() can wait for in-flight bodies instead of
+    // closing the socket under them (which silently dropped tail-end bodies).
+    const promise = this._captureBody(sessionId, rec).finally(() => {
+      this.pendingBodies.delete(promise);
+    });
+    this.pendingBodies.add(promise);
   }
 
-  _onFailed(p) {
-    const rec = this._rec(p.requestId);
+  _onFailed(sessionId, p) {
+    if (!this.sessions.has(sessionId)) return;
+    const rec = this._rec(sessionId, p.requestId);
     rec.failed = true;
     rec.errorText = p.errorText;
     rec.canceled = p.canceled;
@@ -149,19 +257,24 @@ export class CdpRecorder {
     }
   }
 
-  _onWebSocket(p) {
-    const rec = this._rec(p.requestId);
+  _onWebSocket(sessionId, p) {
+    const tab = this.sessions.get(sessionId);
+    if (!tab) return;
+    const rec = this._rec(sessionId, p.requestId);
     rec.method = 'WS';
     rec.url = p.url;
     rec.resourceType = 'WebSocket';
+    rec.tab = tab.index;
+    rec.tabUrl = tab.url;
   }
 
-  async _captureBody(rec) {
+  async _captureBody(sessionId, rec) {
     if (rec.responseBody !== undefined) return;
     try {
-      const { body, base64Encoded } = await this.client.Network.getResponseBody({
-        requestId: rec.requestId,
-      });
+      const { body, base64Encoded } = await this.client.Network.getResponseBody(
+        { requestId: rec.requestId },
+        sessionId,
+      );
       if (base64Encoded) {
         rec.responseBodyBase64 = true;
         rec.responseBody = body.length > this.maxBodyBytes ? '[binary body omitted]' : body;
@@ -172,29 +285,45 @@ export class CdpRecorder {
         rec.responseBody = body;
       }
     } catch {
-      // Body may be unavailable (evicted, 204, websocket, etc.) — that's fine.
+      // Body may be unavailable (evicted, 204, websocket, closed tab) — fine.
     }
   }
 
   // Snapshot of everything captured so far, in emission order.
   getRecords() {
-    return this.order.map((id) => this.records.get(id)).filter(Boolean);
+    return this.order.map((key) => this.records.get(key)).filter(Boolean);
   }
 
-  async stop() {
+  async stop({ closeBrowser = false } = {}) {
     this.stopping = true; // suppress the disconnect->auto-finalize path
-    // Give any in-flight loadingFinished handlers a beat to grab bodies.
-    await new Promise((r) => setTimeout(r, 200));
+    // Let in-flight loadingFinished body fetches land (bounded wait).
+    if (this.pendingBodies.size) {
+      await Promise.race([
+        Promise.allSettled([...this.pendingBodies]),
+        new Promise((r) => setTimeout(r, STOP_BODY_GRACE_MS)),
+      ]);
+    }
     const records = this.getRecords();
+    // Quit the browser via CDP while the socket is still open. Works even for
+    // a reused persistent-profile window we didn't spawn.
+    let browserClosed = false;
+    if (closeBrowser && this.client) {
+      try {
+        await this.client.Browser.close();
+        browserClosed = true;
+      } catch { /* fall back to killing the child process, if any */ }
+    }
     if (this.client) {
       try { await this.client.close(); } catch { /* ignore */ }
       this.client = null;
     }
+    this.sessions.clear();
     return {
       startedAt: this.startedAt,
       stoppedAt: new Date().toISOString(),
-      target: this.target ? { id: this.target.id, url: this.target.url, title: this.target.title } : null,
+      target: this.target,
       records,
+      browserClosed,
     };
   }
 }

package/src/exporters/har.js

@@ -1,6 +1,8 @@
 // Minimal HAR 1.2 exporter so recordings can be opened in Chrome DevTools,
 // Charles, Insomnia, Postman, etc.
 
+import { VERSION } from '../version.js';
+
 function headerArray(headers) {
   return Object.entries(headers || {}).map(([name, value]) => ({ name, value: String(value) }));
 }
@@ -16,7 +18,9 @@ export function toHar(records, meta = {}) {
       const reqBody = r.requestBody;
       const resBody = r.responseBody;
       return {
-        startedDateTime: meta.startedAt || new Date(0).toISOString(),
+        // Per-request wall time so DevTools/Charles render a real waterfall
+        // instead of stacking everything at the session start.
+        startedDateTime: r.startedAt || meta.startedAt || new Date(0).toISOString(),
         time: r.durationMs || 0,
         request: {
           method: r.method || 'GET',
@@ -54,7 +58,7 @@ export function toHar(records, meta = {}) {
   return {
     log: {
       version: '1.2',
-      creator: { name: 'browser-flow-tracker', version: '0.1.0' },
+      creator: { name: 'browser-flow-tracker', version: VERSION },
       pages: [],
       entries,
     },

package/src/exporters/markdown.js

@@ -79,6 +79,7 @@ export function toMarkdown(session, options = {}) {
     lines.push(`### ${i + 1}. ${e.method} ${e.path}`);
     lines.push('');
     lines.push(`- **URL:** \`${e.url}\``);
+    if (e.tab > 0) lines.push(`- **Tab:** popup/new tab #${e.tab}${e.tabUrl ? ` (\`${e.tabUrl}\`)` : ''}`);
     lines.push(`- **Status:** ${e.failed ? `✗ ${e.errorText}` : `${e.status || ''} ${e.statusText || ''}`}`);
     if (e.durationMs != null) lines.push(`- **Duration:** ${e.durationMs}ms`);
     if (e.initiator) lines.push(`- **Initiated by:** ${e.initiator}`);

package/src/normalize.js

@@ -1,20 +1,7 @@
 // Turns raw CDP records into a clean, ordered, API-focused flow.
 
 import { classify } from './filter.js';
-
-const SENSITIVE_HEADERS = new Set([
-  'authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token',
-  'proxy-authorization', 'x-csrf-token',
-]);
-
-function redactHeaders(headers, redact) {
-  if (!headers) return {};
-  const out = {};
-  for (const [k, v] of Object.entries(headers)) {
-    out[k] = redact && SENSITIVE_HEADERS.has(k.toLowerCase()) ? '[redacted]' : v;
-  }
-  return out;
-}
+import { redactHeaders, redactQuery, redactBody } from './redact.js';
 
 function tryParseJson(body) {
   if (typeof body !== 'string') return undefined;
@@ -54,10 +41,11 @@ export function normalize(records, { includeNoise = false, redact = true } = {})
       url: rec.url,
       host,
       path,
-      query,
+      query: query ? redactQuery(query, redact) : undefined,
       resourceType: rec.resourceType,
       status: rec.status,
       statusText: rec.statusText,
+      startedAt: rec.wallTime ? new Date(rec.wallTime * 1000).toISOString() : undefined,
       durationMs: rec.durationMs != null ? Math.round(rec.durationMs) : undefined,
       sizeBytes: rec.encodedDataLength,
       fromCache: rec.fromCache || undefined,
@@ -65,17 +53,19 @@ export function normalize(records, { includeNoise = false, redact = true } = {})
       errorText: rec.errorText,
       initiator: rec.initiator?.type,
       redirects: rec.redirects,
+      tab: rec.tab, // 0-based tab index; >0 means a popup / new tab in the flow
+      tabUrl: rec.tab > 0 ? rec.tabUrl : undefined,
       requestHeaders: redactHeaders(rec.requestHeaders, redact),
       responseHeaders: redactHeaders(rec.responseHeaders, redact),
     };
 
     const reqJson = tryParseJson(rec.requestBody);
-    entry.requestBody = reqJson !== undefined ? reqJson : rec.requestBody;
+    entry.requestBody = redactBody(reqJson !== undefined ? reqJson : rec.requestBody, redact);
     entry.requestBodyIsJson = reqJson !== undefined;
 
     if (!rec.responseBodyBase64) {
       const resJson = tryParseJson(rec.responseBody);
-      entry.responseBody = resJson !== undefined ? resJson : rec.responseBody;
+      entry.responseBody = redactBody(resJson !== undefined ? resJson : rec.responseBody, redact);
       entry.responseBodyIsJson = resJson !== undefined;
       entry.responseBodyTruncated = rec.responseBodyTruncated || undefined;
     } else {

package/src/redact.js

@@ -0,0 +1,101 @@
+// Redaction of secrets so recordings are safe to share by default.
+// Covers three places secrets actually show up:
+//   1. headers (Authorization, Cookie, ...)
+//   2. URL query params (?token=..., ?api_key=...)
+//   3. JSON / form-encoded request & response bodies ({"password": ...},
+//      login responses returning {"access_token": ...}, etc.)
+
+export const SENSITIVE_HEADERS = new Set([
+  'authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token',
+  'proxy-authorization', 'x-csrf-token', 'x-xsrf-token', 'x-session-token',
+  'x-access-token', 'x-refresh-token', 'api-key', 'apikey',
+]);
+
+// Key names (matched case-insensitively, ignoring -_ separators) whose VALUES
+// are secrets wherever they appear: query params, JSON bodies, form bodies.
+const SENSITIVE_KEY_RE = new RegExp(
+  '^(' + [
+    'password', 'passwd', 'pwd', 'passphrase', 'currentpassword', 'newpassword',
+    'oldpassword', 'confirmpassword', 'secret', 'clientsecret', 'appsecret',
+    'token', 'accesstoken', 'refreshtoken', 'idtoken', 'authtoken', 'apitoken',
+    'sessiontoken', 'bearertoken', 'csrftoken', 'xsrftoken',
+    'apikey', 'apisecret', 'privatekey', 'secretkey', 'encryptionkey',
+    'auth', 'authorization', 'credential', 'credentials',
+    'sessionid', 'sid', 'jsessionid', 'phpsessid',
+    'otp', 'totp', 'mfacode', 'pin', 'securitycode', 'verificationcode',
+    'cardnumber', 'ccnumber', 'cvv', 'cvc', 'ssn',
+  ].join('|') + ')$',
+  'i',
+);
+
+const REDACTED = '[redacted]';
+const MAX_DEPTH = 12;
+
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY_RE.test(String(key).replace(/[-_.]/g, ''));
+}
+
+export function redactHeaders(headers, redact = true) {
+  if (!headers) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = redact && SENSITIVE_HEADERS.has(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+}
+
+// Flat object of query params ({token: 'abc'} -> {token: '[redacted]'}).
+export function redactQuery(query, redact = true) {
+  if (!query || !redact) return query;
+  const out = {};
+  for (const [k, v] of Object.entries(query)) {
+    out[k] = isSensitiveKey(k) ? REDACTED : v;
+  }
+  return out;
+}
+
+// Deep-walk parsed JSON, replacing values of sensitive keys.
+export function redactJson(value, depth = 0) {
+  if (value == null || depth > MAX_DEPTH) return value;
+  if (Array.isArray(value)) return value.map((v) => redactJson(v, depth + 1));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = isSensitiveKey(k) ? REDACTED : redactJson(v, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+// application/x-www-form-urlencoded bodies ("user=a&password=b").
+function looksLikeFormBody(s) {
+  return /^[^=\s&]+=[^&\n]*(&[^=\s&]+=[^&\n]*)*$/.test(s) && s.includes('=');
+}
+
+function redactFormBody(s) {
+  return s
+    .split('&')
+    .map((pair) => {
+      const eq = pair.indexOf('=');
+      if (eq === -1) return pair;
+      const key = pair.slice(0, eq);
+      let decoded = key;
+      try { decoded = decodeURIComponent(key); } catch { /* keep raw */ }
+      return isSensitiveKey(decoded) ? `${key}=${encodeURIComponent(REDACTED)}` : pair;
+    })
+    .join('&');
+}
+
+/**
+ * Redact a body. `body` may be a parsed JSON value (object/array) or a raw
+ * string (form-encoded or anything else). Returns the same shape.
+ */
+export function redactBody(body, redact = true) {
+  if (!redact || body == null) return body;
+  if (typeof body === 'object') return redactJson(body);
+  if (typeof body === 'string' && looksLikeFormBody(body.trim())) {
+    return redactFormBody(body.trim());
+  }
+  return body;
+}

package/src/session.js

@@ -11,6 +11,7 @@ import { launchBrowser } from './browsers.js';
 import { normalize } from './normalize.js';
 import { toHar } from './exporters/har.js';
 import { toMarkdown } from './exporters/markdown.js';
+import { VERSION } from './version.js';
 
 function stamp() {
   // Filesystem-safe timestamp without relying on locale.
@@ -93,7 +94,10 @@ export class TrackingSession {
       ? (t) => t.url && t.url.includes(urlMatch)
       : undefined;
 
-    this.recorder = new CdpRecorder({ port, host, targetFilter });
+    // Launch mode: the whole window is ours, so record every tab in it
+    // (popups, OAuth windows, new tabs). Attach mode records the chosen tab
+    // plus any popups that tab opens.
+    this.recorder = new CdpRecorder({ port, host, targetFilter, attachAll: Boolean(launch) });
     // If the user closes the browser/tab, auto-finalize and write the files.
     this.recorder.onDisconnect = () => { this._onBrowserClosed(); };
     const info = await this.recorder.start();
@@ -141,7 +145,7 @@ export class TrackingSession {
     // return that result instead of erroring on a later explicit stop.
     if (this.finalized) return this.finalized;
     if (!this.recorder) throw new Error('Session not started.');
-    const raw = await this.recorder.stop();
+    const raw = await this.recorder.stop({ closeBrowser });
     this.active = false;
 
     const norm = normalize(raw.records, {
@@ -151,7 +155,7 @@ export class TrackingSession {
 
     const session = {
       tool: 'browser-flow-tracker',
-      version: '0.1.0',
+      version: VERSION,
       startedAt: raw.startedAt,
       stoppedAt: raw.stoppedAt,
       target: raw.target,
@@ -162,9 +166,11 @@ export class TrackingSession {
 
     let files = null;
     if (write) {
-      const dir = outDir || join(process.cwd(), 'recordings');
+      // Fall back to the defaults given at start_tracking time, so an
+      // explicit stop honors them the same way auto-finalize does.
+      const dir = outDir || this.opts.outDir || join(process.cwd(), 'recordings');
       mkdirSync(dir, { recursive: true });
-      const base = name || `flow-${stamp()}`;
+      const base = name || this.opts.name || `flow-${stamp()}`;
       const jsonPath = join(dir, `${base}.flow.json`);
       const harPath = join(dir, `${base}.har`);
       const mdPath = join(dir, `${base}.md`);
@@ -174,7 +180,9 @@ export class TrackingSession {
       files = { json: jsonPath, har: harPath, markdown: mdPath };
     }
 
-    if (closeBrowser && this.launched?.child) {
+    // Browser.close via CDP is preferred (works for reused windows too);
+    // killing the child we spawned is the fallback.
+    if (closeBrowser && !raw.browserClosed && this.launched?.child) {
       try { this.launched.child.kill(); } catch { /* ignore */ }
     }
 

package/src/version.js

@@ -0,0 +1,4 @@
+// Single source of truth for the tool version (keep in sync with package.json).
+// A plain constant (not a package.json read) so the bun-compiled standalone
+// binaries don't need the file on disk at runtime.
+export const VERSION = '0.2.0';