browsertrack 0.2.0 → 0.2.2

package/docs/getting-started.md

@@ -26,6 +26,8 @@ browsertrack start
 
 This will initialize the local server at `http://127.0.0.1:7331` (WebSocket bridge on `ws://127.0.0.1:7331`) and SQLite database at `~/.browsertrack/browsertrack.db`.
 
+> **⚡ Zero-Config Auto-Start**: If you configure BrowserTrack via MCP in your AI coding editor (Cursor, Antigravity, Claude Desktop), you do **not** need to manually run `browsertrack start`. The MCP server automatically launches and manages the HTTP and WebSocket background daemon on port `7331`!
+
 ---
 
 ## 2. Connect Your Web Application
@@ -80,25 +82,77 @@ const client = new BrowserTrackClient({
 
 Add BrowserTrack MCP server to your AI editor configuration:
 
-### Antigravity (`~/.gemini/antigravity-ide/mcp_config.json`)
+### Standard Configuration
 ```json
 {
   "mcpServers": {
     "browsertrack": {
-      "command": "browsertrack",
-      "args": ["mcp"]
+      "command": "npx",
+      "args": ["-y", "browsertrack@latest", "mcp"]
     }
   }
 }
 ```
 
-### Cursor (`~/.cursor/mcp.json`) & Claude Code
+---
+
+### ⚠️ Troubleshooting: `executable file not found in $PATH`
+
+If your editor throws an error like:
+```text
+Error: exec: "browsertrack": executable file not found in $PATH
+# or
+Error: exec: "npx": executable file not found in $PATH
+```
+
+#### Why does this happen?
+GUI applications on macOS and Linux (Antigravity, Cursor, Claude Desktop, VS Code) are launched by the desktop window manager (such as `launchd` on macOS), **not** from your terminal shell. Therefore, they do **not** automatically source your `~/.zshrc`, `~/.bashrc`, or environment managers like **NVM**, **fnm**, **asdf**, **Volta**, or **Homebrew** (`/opt/homebrew/bin`).
+
+#### Solutions:
+
+##### Option A: Use Absolute Path to `npx` with `PATH` environment (Recommended)
+Find your `npx` and `node` bin directory in your terminal:
+```bash
+which npx
+# Example output: /Users/username/.nvm/versions/node/v20.19.5/bin/npx
+```
+
+Configure your MCP config with the full path, the `-y` flag (to prevent interactive installation prompts from stalling stdio), and the `PATH` environment variable:
 ```json
 {
   "mcpServers": {
     "browsertrack": {
-      "command": "npx",
-      "args": ["browsertrack", "mcp"]
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/npx",
+      "args": ["-y", "browsertrack@latest", "mcp"],
+      "env": {
+        "PATH": "/Users/username/.nvm/versions/node/v20.19.5/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+##### Option B: Run Directly via Node (Fastest for Local Development)
+If you are developing or running BrowserTrack locally, bypass `npx` completely and execute the CLI entry script directly with `node`:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/node",
+      "args": ["/absolute/path/to/browsertrack/dist/cli/index.js", "mcp"]
+    }
+  }
+}
+```
+
+##### Option C: Wrap with Login Shell (`/bin/zsh -lc`)
+Use your interactive login shell to automatically source your `~/.zshrc` and all environment variables:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "npx -y browsertrack mcp"]
     }
   }
 }

package/docs/index.md

@@ -40,6 +40,7 @@ graph TD
 - [Getting Started](./getting-started.md) — Quick installation and setup in under 2 minutes.
 - [Visual Notes & Annotations](./visual-notes.md) — Screen notes, region selection, and persistent markers.
 - [Multi-Step Scenarios & Flows](./scenarios-flows.md) — Sequential reproduction flows, Save & Next Step, and stepper walk-throughs.
+- [Component & Source Resolver](./component-resolver.md) — Map live DOM elements to React Fiber, Vue VNode, Svelte, and exact source file locations.
 - [Incidents & Error Diagnostics](./incidents-diagnostics.md) — Ingest runtime errors, stack traces, and breadcrumbs.
 - [Closed-Loop Verification](./closed-loop-verification.md) — Automated bug-fix and layout verification.
 - [MCP Tool Reference](./mcp-reference.md) — Complete guide to all MCP tools.

package/docs/mcp-reference.md

@@ -8,6 +8,8 @@ order: 6
 
 BrowserTrack exposes 16 specialized Model Context Protocol (MCP) tools for AI agents.
 
+> **⚡ Automatic Server Lifecycle**: When your IDE starts the MCP server (`browsertrack mcp`), BrowserTrack automatically checks if the background daemon is already running. If not, it **automatically starts the HTTP (`http://127.0.0.1:7331`) and WebSocket (`ws://127.0.0.1:7331`) server** in the background, so your browser can connect immediately with zero manual terminal commands. If you already have a running daemon, MCP seamlessly connects to it.
+
 ---
 
 ## 📋 Incidents & Error Diagnostics
@@ -24,7 +26,7 @@ Lists recorded browser runtime errors, unhandled rejections, and console errors
 Retrieves compact, high-signal debugging context for an error incident.
 - **Arguments**:
   - `incidentId` (`string`, *required*): The unique ID of the incident (e.g. `inc_19a31a28`).
-- **Returns**: Stack trace, normalized error message, breadcrumbs timeline, failed network calls, last interacted element, error screenshot.
+- **Returns**: Stack trace, normalized error message, breadcrumbs timeline, failed network calls, last interacted element (with `componentSource`: component name, source file, line number, hierarchy), and error screenshot.
 
 ### `get_console`
 Fetches recent console logs, warnings, and errors from a browser session.
@@ -84,7 +86,7 @@ Retrieves full chronological step-by-step reproduction flow with selectors, rout
 Retrieves full debugging context for a visual note.
 - **Arguments**:
   - `noteId` (`string`, *required*): The unique ID of the visual note (e.g. `note_30a89599`).
-- **Returns**: Note message, route, viewport dimensions, target element selector, DOM context, screenshot file path, scenario metadata.
+- **Returns**: Note message, route, viewport dimensions, target element selector, DOM context (including `componentSource` with framework, component name, source file path, and line number), screenshot file path, scenario metadata.
 
 ### `capture_note_context`
 Inspects live DOM context, bounding box, overflow, and computed styles for a target element.
@@ -139,3 +141,43 @@ Triggers closed-loop bug fix verification (reloads browser, evaluates probes, ca
 Retrieves latest verification result and before/after screenshots for an incident.
 - **Arguments**:
   - `incidentId` (`string`, *required*): The ID of the incident.
+
+---
+
+## ⚠️ Troubleshooting MCP Client Setup
+
+If your AI editor fails to launch the MCP server with:
+```text
+Error: exec: "browsertrack": executable file not found in $PATH
+```
+
+This occurs because GUI applications (Cursor, Antigravity, VS Code, Claude Desktop) run without loading terminal shell rc files (`~/.zshrc`, `~/.bashrc`), leaving version managers like **NVM**, **fnm**, **asdf**, or **Homebrew** out of `$PATH`.
+
+### Recommended Fix
+Specify the absolute path to `npx` (find it with `which npx`), include `-y`, and explicitly set `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/npx",
+      "args": ["-y", "browsertrack@latest", "mcp"],
+      "env": {
+        "PATH": "/Users/username/.nvm/versions/node/v20.19.5/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Or run directly via `node` for local projects:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/node",
+      "args": ["/path/to/browsertrack/dist/cli/index.js", "mcp"]
+    }
+  }
+}
+```

package/docs/visual-notes.md

@@ -64,4 +64,40 @@ The bottom-right floating toolbar gives quick access:
 - **`🎯 Element`**: Toggle element inspection mode.
 - **`📐 Region`**: Activate rectangle drag mode.
 - **`📄 Page`**: Open full-page note modal.
+- **`🎬 Flow`**: Start/finish sequential scenario recording.
 - **`📌 Notes (N)`**: Toggle visibility of all note markers on screen.
+
+---
+
+## 🙈 Hiding the Tool via Query String (Headless / Clean Mode)
+
+When running automated visual regression tests, Cypress, Playwright, or giving clean demo presentations, you can hide the visible BrowserTrack UI (dock, pins, overlays) completely using URL query parameters:
+
+### 1. Built-in Query Parameters
+Simply append any of the following to your page URL:
+- `?bt=0` or `?bt=false` or `?bt=hidden` or `?bt=off`
+- `?browsertrack=false` or `?browsertrack=0` or `?browsertrack=hidden`
+- `?no_bt` / `?no_bt=1` or `?no_browsertrack=1`
+- `?hide_bt=1` or `?hide_browsertrack=1`
+
+```text
+http://localhost:3000/dashboard?bt=false
+```
+
+### 2. Custom Query Parameter Configuration
+You can also define your own custom query parameters in client options:
+```typescript
+import { init } from 'browsertrack/client';
+
+init({
+  hideQueryParam: ['cypress', 'clean_view', 'no_ui'],
+  // or hide by default in specific environments:
+  hidden: process.env.NODE_ENV === 'test',
+});
+```
+
+When hidden:
+- The floating toolbar and on-screen note pins are not displayed.
+- Alt+Click hover highlights and selection shortcuts are inactive.
+- Background diagnostics (runtime errors, console capture, network logging, MCP command execution) continue working seamlessly in headless mode.
+- Programmatic visibility can be restored anytime via `client.setUIVisible(true)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browsertrack",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local browser diagnostics + MCP bridge for coding agents",
   "type": "module",
   "main": "./dist/index.js",