browsertrack 0.2.0 → 0.2.2

package/AGENTS.md

@@ -33,6 +33,7 @@ graph TD
 
 1. **Find open notes:** Call `list_notes({ status: "OPEN" })`.
 2. **Inspect note context:** Call `get_note({ noteId: "note_xxx" })`.
+   - **Check `elementContext.componentSource`**: In React, Vue, or Svelte apps, this gives you the exact component name, source file (`sourceFile`), and line number (`sourceLine`). Open that file directly!
    - Review the target selector (`target.selector`), viewport dimensions, bounding box (`boundingRect`), and screenshot path.
    - Check if layout overflow (`overflow-x`, min-width, flex wrapping) is causing the issue.
 3. **Apply the fix:** Edit the corresponding CSS, style rules, or component markup.
@@ -49,6 +50,7 @@ When an error or unexpected behavior occurs in the frontend:
 1. **List open incidents:** Call `list_incidents({ status: "OPEN" })`.
 2. **Retrieve incident details:** Call `get_incident({ incidentId: "inc_xxx" })`.
    - Inspect stack traces, exact source line/column, last user interactions, and failing network calls.
+   - **Check `lastInteractedElement.componentSource`** to see which React/Vue component and source file was clicked right before the crash.
 3. **Inspect interaction timeline (if needed):** Call `get_breadcrumbs({ incidentId: "inc_xxx" })` to see what clicks, inputs, or navigations led to the failure.
 4. **Inspect failed network requests (if needed):** Call `get_network_failures()` to examine 4xx/5xx status codes, request URLs, and response details.
 5. **Apply code fix:** Edit the source file causing the bug.
@@ -97,10 +99,9 @@ When an error or unexpected behavior occurs in the frontend:
 
 If BrowserTrack is not yet active in your project:
 
-### 1. Ensure Daemon is Running
-```bash
-browsertrack start
-```
+### 1. Zero-Config Daemon Auto-Boot (Singleton Daemon)
+You do **not** need to manually run `browsertrack start`! When your IDE connects to BrowserTrack via MCP (`browsertrack mcp`), the background HTTP/WebSocket server is launched **automatically** on `http://127.0.0.1:7331` as a **singleton daemon**. Multiple windows, workspaces, or sub-agent sessions seamlessly share this single daemon without spawning duplicates or conflicting on ports.
+*(You can still manually run `browsertrack start` or `browsertrack stop` if you want a standalone terminal process).*
 
 ### 2. Connect the Browser Client
 - **Via HTML script tag:**
@@ -114,17 +115,21 @@ browsertrack start
 
 ### 3. MCP Configuration
 Ensure BrowserTrack MCP is configured in your editor:
+
 ```json
 {
   "mcpServers": {
     "browsertrack": {
-      "command": "browsertrack",
-      "args": ["mcp"]
+      "command": "npx",
+      "args": ["-y", "browsertrack@latest", "mcp"]
     }
   }
 }
 ```
 
+> **Note on PATH errors (`executable file not found in $PATH`):**
+> If your IDE cannot find `npx` or `browsertrack` in `$PATH` (common in GUI apps on macOS using NVM or Homebrew), provide the absolute path to `npx` (e.g. `~/.nvm/versions/node/v20.x.x/bin/npx`) along with `PATH` in the `env` object.
+
 ---
 
 ## 💡 Best Practices for AI Agents

package/README.md

@@ -17,6 +17,8 @@ browsertrack start
 
 This starts the local diagnostics server at `http://127.0.0.1:7331` (WebSocket at `ws://127.0.0.1:7331`).
 
+> **⚡ Zero-Config Auto-Start**: If you configure BrowserTrack via MCP in your AI editor (Cursor, Antigravity, Claude Code), you do **not** need to manually run `browsertrack start`! The MCP server automatically launches and manages a **single background daemon (singleton)** on port `7331`. Multiple windows or sessions share this single daemon without duplicate processes or port conflicts.
+
 ### 2. Connect Your Web Project
 
 #### Option A: Zero-install script tag (Plain HTML / Vite / Next.js)