browsertrack 0.1.0 → 0.1.1

package/docs/mcp-reference.md

@@ -0,0 +1,128 @@
+---
+title: MCP Tool Reference
+description: Complete reference for all 16 Model Context Protocol (MCP) tools exposed to AI coding agents
+order: 6
+---
+
+# MCP Tool Reference 🛠️
+
+BrowserTrack exposes 16 specialized Model Context Protocol (MCP) tools for AI agents.
+
+---
+
+## 📋 Incidents & Error Diagnostics
+
+### `list_incidents`
+Lists recorded browser runtime errors, unhandled rejections, and console errors grouped into incidents.
+- **Arguments**:
+  - `status` (`string`): Filter by `OPEN`, `FIX_ATTEMPTED`, `VERIFYING`, `VERIFIED`, `FAILED`, `INCONCLUSIVE`.
+  - `severity` (`string`): Filter by `error`, `warn`, `fatal`.
+  - `projectId` (`string`): Filter by project ID or name.
+  - `limit` (`number`): Max number of incidents (default: 20).
+
+### `get_incident`
+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.
+
+### `get_console`
+Fetches recent console logs, warnings, and errors from a browser session.
+- **Arguments**:
+  - `sessionId` (`string`): Browser session ID (optional, defaults to active session).
+  - `limit` (`number`): Number of logs to retrieve (default: 30).
+
+### `get_network_failures`
+Retrieves recent failed HTTP requests (4xx, 5xx, timeouts, aborts).
+- **Arguments**:
+  - `sessionId` (`string`): Browser session ID (optional).
+  - `limit` (`number`): Maximum number of failed requests (default: 20).
+
+### `get_breadcrumbs`
+Retrieves the chronological user interaction timeline leading up to an error.
+- **Arguments**:
+  - `incidentId` (`string`): Associated incident ID.
+  - `sessionId` (`string`): Browser session ID.
+  - `limit` (`number`): Max breadcrumbs (default: 50).
+
+### `get_page_state`
+Queries live DOM and URL state from the connected browser tab.
+- **Arguments**:
+  - `sessionId` (`string`): Target session ID (optional).
+
+### `capture_element`
+Captures an on-demand screenshot of a specific DOM element or the entire visible page.
+- **Arguments**:
+  - `selector` (`string`): CSS selector of the target element.
+  - `sessionId` (`string`): Browser session ID (optional).
+
+---
+
+## 📝 Visual Notes & Layout Tools
+
+### `list_notes`
+Lists visual annotations left on elements, regions, or pages during development.
+- **Arguments**:
+  - `status` (`string`): `OPEN`, `IN_PROGRESS`, `VERIFYING`, `RESOLVED`, `FAILED`, `INCONCLUSIVE` (default: `OPEN`).
+  - `projectId` (`string`): Filter by project ID or name.
+  - `limit` (`number`): Max notes (default: 20).
+
+### `get_note`
+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.
+
+### `capture_note_context`
+Inspects live DOM context, bounding box, overflow, and computed styles for a target element.
+- **Arguments**:
+  - `selector` (`string`, *required*): CSS selector of target element.
+  - `sessionId` (`string`): Browser session ID (optional).
+
+### `verify_note`
+Runs closed-loop layout verification (visibility, viewport overflow, geometry delta, after-screenshot).
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note to verify.
+  - `observationWindowMs` (`number`): Observation window in ms (default: 1000).
+
+### `get_note_verification`
+Retrieves latest layout verification verdict, screenshots, and geometry diff.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+### `resolve_note`
+Marks a visual note as `RESOLVED`.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+### `reopen_note`
+Reopens a previously resolved visual note.
+- **Arguments**:
+  - `noteId` (`string`, *required*): The ID of the visual note.
+
+---
+
+## 🎛️ Session & Project Management
+
+### `list_projects`
+Lists all registered development projects and mapped filesystem paths.
+
+### `list_sessions`
+Lists active and recent browser tabs connected to the local development daemon.
+- **Arguments**:
+  - `projectId` (`string`): Filter sessions by project ID or name.
+  - `activeOnly` (`boolean`): Show only active WebSocket sessions (default: `true`).
+
+### `verify_incident`
+Triggers closed-loop bug fix verification (reloads browser, evaluates probes, captures after-screenshot).
+- **Arguments**:
+  - `incidentId` (`string`, *required*): The ID of the incident.
+  - `route` (`string`): Optional route to navigate to.
+  - `targetSelector` (`string`): Optional element selector to inspect.
+  - `expect` (`array`): Optional verification probes (`no_incident`, `element_exists`, `element_visible`, `text_contains`, `route_is`).
+  - `observationWindowMs` (`number`): Observation window in ms (default: 2000).
+
+### `get_verification`
+Retrieves latest verification result and before/after screenshots for an incident.
+- **Arguments**:
+  - `incidentId` (`string`, *required*): The ID of the incident.

package/docs/security-privacy.md

@@ -0,0 +1,32 @@
+---
+title: Security & Privacy
+description: Security architecture, localhost binding, form value exclusion, and @visulima/redact sensitive data sanitization
+order: 7
+---
+
+# Security & Privacy 🛡️
+
+BrowserTrack is built with privacy-by-design principles to ensure sensitive developer tokens, credentials, and user data never leak to AI models or external servers.
+
+---
+
+## 🔒 Core Security Principles
+
+### 1. Strictly Localhost Bound
+- The daemon binds exclusively to `127.0.0.1`.
+- It cannot be reached from the public internet or external local network devices.
+
+### 2. Comprehensive Sensitive Data Masking (@visulima/redact)
+BrowserTrack integrates `@visulima/redact` to automatically scan and sanitize payloads before saving to SQLite or returning to MCP:
+- **Authentication & Headers**: `Authorization` (Bearer tokens, Basic auth), `Cookie`, `Set-Cookie`.
+- **API Keys & Credentials**: AWS Access Keys (`AKIA...`), Slack tokens (`xoxb-...`), JWTs (`eyJ...`), `private_key`, `secret`.
+- **Financial & Personal Data**: Credit card numbers, CVV/CVD, SSN / Social Security Numbers.
+- **Sensitive URL Parameters**: Query strings containing `token`, `key`, `apiKey`, `auth`, `secret`, `password`, `signature` are converted to `[REDACTED]`.
+
+### 3. No Form Input Recording
+- Values inside `<input>` and `<textarea>` fields are never read or stored.
+- Password inputs (`<input type="password">`) in DOM snapshot clones are explicitly sanitized to `value="[REDACTED]"`.
+
+### 4. Zero Request/Response Payloads
+- Network event interceptors capture only URL endpoints, HTTP methods, status codes, and latency.
+- Request and response body payloads are disabled by default.

package/docs/visual-notes.md

@@ -0,0 +1,67 @@
+---
+title: Visual Notes & Annotations
+description: Visual annotations, element hover notes, drag-and-drop region notes, and persistent on-screen pins
+order: 3
+---
+
+# Visual Notes & Screen Annotations 📝
+
+BrowserTrack enables developers and designers to leave visual feedback directly on DOM elements, custom screen regions, or full pages without leaving the browser.
+
+---
+
+## 🎯 Annotation Modes
+
+### 1. Element Notes (Alt + Click)
+- **How to use**: Hold <kbd>Alt</kbd> and hover over any element on the page. The element will highlight with its semantic CSS selector and dimensions. Click to open the note editor.
+- Alternatively, click the **🎯 Element** button in the floating toolbar.
+- **Context captured**:
+  - Semantic CSS selector (e.g. `[data-testid="stats-banner"]` or `#user-card`)
+  - Element dimensions and bounding rectangle (`x`, `y`, `width`, `height`)
+  - Sanitized outerHTML and DOM hierarchy
+  - Viewport dimensions and scroll offsets
+  - Element screenshot snapshot
+
+### 2. Region / Area Notes (Drag & Drop)
+- **How to use**: Click the **📐 Region** button in the floating toolbar.
+- Drag a bounding rectangle over any area on the screen.
+- A top banner will appear with a **✕ Cancel (Esc)** button.
+- Releasing the mouse opens the note modal with the cropped region screenshot and coordinates.
+
+### 3. Full-Page Notes
+- **How to use**: Click the **📄 Page** button in the toolbar.
+- Captures the entire page viewport state, URL route, and document context.
+
+---
+
+## 📌 Persistent On-Screen Markers
+
+When your application loads or syncs with the daemon:
+- BrowserTrack automatically fetches all open notes for the project.
+- **Element Pins (`📝 #1`)**: Placed at the top-left of each annotated element. Hovering highlights the element.
+- **Region Outlines (`📐 #2`)**: Renders a clean dashed boundary box around the selected area.
+- **Page Notes (`📄`)**: Pinned at the top right of the viewport.
+- **Responsive Tracking**: Markers dynamically stay anchored to elements as the page scrolls or resizes.
+
+---
+
+## 🔍 Interactive Popover Details Card
+
+Clicking on any note marker opens the Note Details Card:
+
+- **Full Message**: Displays the complete text/instruction.
+- **Target Metadata**: Viewport dimensions, target selector, and creation timestamp.
+- **Action Buttons**:
+  - **`✅ Resolve Note`**: Marks the note as `RESOLVED` in real time.
+  - **`🗑️ Delete Note`**: Removes the note permanently from the database.
+  - **`✕ Close`**: Closes the popover.
+
+---
+
+## 🛠️ Toolbar Controls
+
+The bottom-right floating toolbar gives quick access:
+- **`🎯 Element`**: Toggle element inspection mode.
+- **`📐 Region`**: Activate rectangle drag mode.
+- **`📄 Page`**: Open full-page note modal.
+- **`📌 Notes (N)`**: Toggle visibility of all note markers on screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browsertrack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local browser diagnostics + MCP bridge for coding agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,10 +37,14 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist dist-docs",
+    "docs:dev": "docboot dev",
+    "docs:build": "docboot build",
+    "docs:serve": "docboot serve dist-docs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1",
+    "@visulima/redact": "^2.0.5",
     "@zumer/snapdom": "^2.24.15",
     "better-sqlite3": "^11.8.1",
     "commander": "^13.1.0",

package/packages/client/package.json

@@ -8,9 +8,9 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "scripts": {