browsertrack 0.2.0 → 0.2.1

package/dist/{notes-BMnonq46.d.ts → commands-fjuqKzkm.d.ts}

@@ -1,3 +1,126 @@
+type NoteType = 'element' | 'region' | 'page';
+type NoteStatus = 'OPEN' | 'IN_PROGRESS' | 'VERIFYING' | 'READY_FOR_REVIEW' | 'VERIFIED' | 'RESOLVED' | 'FAILED' | 'INCONCLUSIVE';
+interface ViewportContext {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+}
+interface ScrollContext {
+    scrollX: number;
+    scrollY: number;
+}
+interface DOMRectJson {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+interface NoteTarget {
+    selector: string;
+    boundingRect: DOMRectJson;
+    visible: boolean;
+    confidence?: 'high' | 'medium' | 'low';
+}
+interface ComponentSourceInfo {
+    framework?: 'react' | 'vue' | 'svelte' | 'web-component' | 'vanilla';
+    componentName?: string;
+    sourceFile?: string;
+    sourceLine?: number;
+    sourceColumn?: number;
+    hierarchy?: string[];
+    props?: Record<string, any>;
+}
+interface ElementContext {
+    selector: string;
+    tag: string;
+    attributes?: Record<string, string>;
+    outerHTML?: string;
+    innerText?: string;
+    componentSource?: ComponentSourceInfo;
+    parent?: {
+        selector: string;
+        tag: string;
+    };
+}
+interface RegionContext {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface VisualNote {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    type: NoteType;
+    message: string;
+    route: string;
+    url: string;
+    viewport: ViewportContext;
+    scroll: ScrollContext;
+    target?: NoteTarget;
+    elementContext?: ElementContext;
+    region?: RegionContext;
+    status: NoteStatus;
+    incidentId?: string;
+    scenarioId?: string;
+    stepNumber?: number;
+    scenarioTitle?: string;
+    screenshots?: {
+        original?: string;
+        after?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+interface ScenarioOverview {
+    id: string;
+    projectId: string;
+    title: string;
+    stepsCount: number;
+    status: NoteStatus;
+    route: string;
+    firstStepAt: string;
+    lastStepAt: string;
+}
+interface ScenarioDetail {
+    id: string;
+    projectId: string;
+    title: string;
+    stepsCount: number;
+    status: NoteStatus;
+    steps: VisualNote[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface NoteVerificationResult {
+    noteId: string;
+    status: NoteStatus;
+    checks: Array<{
+        type: string;
+        passed: boolean;
+        details?: string;
+    }>;
+    geometryDiff?: {
+        before?: DOMRectJson;
+        current?: DOMRectJson;
+        viewportWidth?: number;
+        overflowFixed?: boolean;
+        overflowPx?: number;
+    };
+    screenshots?: {
+        before?: string;
+        after?: string;
+    };
+    timestamp: string;
+    message?: string;
+}
+
 type EventType = 'runtime_error' | 'unhandled_rejection' | 'console' | 'fetch' | 'xhr' | 'navigation' | 'interaction';
 type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
 interface ElementSummary {
@@ -8,6 +131,7 @@ interface ElementSummary {
     attributes?: Record<string, string>;
     outerHTML?: string;
     innerText?: string;
+    componentSource?: ComponentSourceInfo;
     boundingRect?: {
         x: number;
         y: number;
@@ -167,117 +291,4 @@ interface CommandResponse<T = any> {
     reason?: string;
 }
 
-type NoteType = 'element' | 'region' | 'page';
-type NoteStatus = 'OPEN' | 'IN_PROGRESS' | 'VERIFYING' | 'READY_FOR_REVIEW' | 'VERIFIED' | 'RESOLVED' | 'FAILED' | 'INCONCLUSIVE';
-interface ViewportContext {
-    width: number;
-    height: number;
-    devicePixelRatio: number;
-}
-interface ScrollContext {
-    scrollX: number;
-    scrollY: number;
-}
-interface DOMRectJson {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    top: number;
-    left: number;
-    bottom: number;
-    right: number;
-}
-interface NoteTarget {
-    selector: string;
-    boundingRect: DOMRectJson;
-    visible: boolean;
-    confidence?: 'high' | 'medium' | 'low';
-}
-interface ElementContext {
-    selector: string;
-    tag: string;
-    attributes?: Record<string, string>;
-    outerHTML?: string;
-    innerText?: string;
-    parent?: {
-        selector: string;
-        tag: string;
-    };
-}
-interface RegionContext {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-interface VisualNote {
-    id: string;
-    projectId: string;
-    sessionId: string;
-    type: NoteType;
-    message: string;
-    route: string;
-    url: string;
-    viewport: ViewportContext;
-    scroll: ScrollContext;
-    target?: NoteTarget;
-    elementContext?: ElementContext;
-    region?: RegionContext;
-    status: NoteStatus;
-    incidentId?: string;
-    scenarioId?: string;
-    stepNumber?: number;
-    scenarioTitle?: string;
-    screenshots?: {
-        original?: string;
-        after?: string;
-    };
-    createdAt: string;
-    updatedAt: string;
-    resolvedAt?: string;
-}
-interface ScenarioOverview {
-    id: string;
-    projectId: string;
-    title: string;
-    stepsCount: number;
-    status: NoteStatus;
-    route: string;
-    firstStepAt: string;
-    lastStepAt: string;
-}
-interface ScenarioDetail {
-    id: string;
-    projectId: string;
-    title: string;
-    stepsCount: number;
-    status: NoteStatus;
-    steps: VisualNote[];
-    createdAt: string;
-    updatedAt: string;
-}
-interface NoteVerificationResult {
-    noteId: string;
-    status: NoteStatus;
-    checks: Array<{
-        type: string;
-        passed: boolean;
-        details?: string;
-    }>;
-    geometryDiff?: {
-        before?: DOMRectJson;
-        current?: DOMRectJson;
-        viewportWidth?: number;
-        overflowFixed?: boolean;
-        overflowPx?: number;
-    };
-    screenshots?: {
-        before?: string;
-        after?: string;
-    };
-    timestamp: string;
-    message?: string;
-}
-
-export type { Breadcrumb as B, CaptureElementParams as C, DOMRectJson as D, ElementContext as E, HelloMessage as H, NavigateParams as N, OverflowCheckResult as O, PageStateResult as P, QueryElementParams as Q, RegionContext as R, ScenarioDetail as S, ViewportContext as V, CaptureElementResult as a, ClientCommand as b, ClientEventMessage as c, CommandResponse as d, CommandType as e, ConsoleEvent as f, ConsoleLevel as g, ElementStyleResult as h, ElementSummary as i, EventType as j, NavigationEvent as k, NetworkEvent as l, NoteStatus as m, NoteTarget as n, NoteType as o, NoteVerificationResult as p, QueryElementResult as q, ReloadParams as r, RuntimeErrorEvent as s, ScenarioOverview as t, ScrollContext as u, VisualNote as v };
+export type { Breadcrumb as B, CaptureElementParams as C, DOMRectJson as D, ElementContext as E, HelloMessage as H, NavigateParams as N, OverflowCheckResult as O, PageStateResult as P, QueryElementParams as Q, RegionContext as R, ScenarioDetail as S, ViewportContext as V, CaptureElementResult as a, ClientCommand as b, ClientEventMessage as c, CommandResponse as d, CommandType as e, ComponentSourceInfo as f, ConsoleEvent as g, ConsoleLevel as h, ElementStyleResult as i, ElementSummary as j, EventType as k, NavigationEvent as l, NetworkEvent as m, NoteStatus as n, NoteTarget as o, NoteType as p, NoteVerificationResult as q, QueryElementResult as r, ReloadParams as s, RuntimeErrorEvent as t, ScenarioOverview as u, ScrollContext as v, VisualNote as w };

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
-export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScenarioDetail, t as ScenarioOverview, u as ScrollContext, V as ViewportContext, v as VisualNote } from '../notes-BMnonq46.js';
-export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from '../projects-D5J-egVN.js';
+export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ComponentSourceInfo, g as ConsoleEvent, h as ConsoleLevel, D as DOMRectJson, E as ElementContext, i as ElementStyleResult, j as ElementSummary, k as EventType, H as HelloMessage, N as NavigateParams, l as NavigationEvent, m as NetworkEvent, n as NoteStatus, o as NoteTarget, p as NoteType, q as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, r as QueryElementResult, R as RegionContext, s as ReloadParams, t as RuntimeErrorEvent, S as ScenarioDetail, u as ScenarioOverview, v as ScrollContext, V as ViewportContext, w as VisualNote } from '../commands-fjuqKzkm.js';
+export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from '../projects-DB7S312i.js';
 import { Rules } from '@visulima/redact';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
 

package/dist/daemon/index.d.ts

@@ -1,6 +1,6 @@
-import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-B43IohQY.js';
-import { c as ClientEventMessage } from '../notes-BMnonq46.js';
-import { I as Incident } from '../projects-D5J-egVN.js';
+import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-CmchnMDq.js';
+import { c as ClientEventMessage } from '../commands-fjuqKzkm.js';
+import { I as Incident } from '../projects-DB7S312i.js';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
 

package/dist/{engine-B43IohQY.d.ts → engine-CmchnMDq.d.ts}

@@ -1,5 +1,5 @@
-import { B as Breadcrumb, i as ElementSummary, v as VisualNote, m as NoteStatus, t as ScenarioOverview, S as ScenarioDetail, p as NoteVerificationResult, d as CommandResponse, b as ClientCommand } from './notes-BMnonq46.js';
-import { f as Project, S as Session, I as Incident, d as IncidentStatus, b as IncidentSeverity, a as IncidentOccurrence, h as VerificationResult, g as VerificationRecipe } from './projects-D5J-egVN.js';
+import { B as Breadcrumb, j as ElementSummary, w as VisualNote, n as NoteStatus, u as ScenarioOverview, S as ScenarioDetail, q as NoteVerificationResult, d as CommandResponse, b as ClientCommand } from './commands-fjuqKzkm.js';
+import { f as Project, S as Session, I as Incident, d as IncidentStatus, b as IncidentSeverity, a as IncidentOccurrence, h as VerificationResult, g as VerificationRecipe } from './projects-DB7S312i.js';
 import { WebSocket } from 'ws';
 
 declare class StorageDB {

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScenarioDetail, t as ScenarioOverview, u as ScrollContext, V as ViewportContext, v as VisualNote } from './notes-BMnonq46.js';
-export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-D5J-egVN.js';
+export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ComponentSourceInfo, g as ConsoleEvent, h as ConsoleLevel, D as DOMRectJson, E as ElementContext, i as ElementStyleResult, j as ElementSummary, k as EventType, H as HelloMessage, N as NavigateParams, l as NavigationEvent, m as NetworkEvent, n as NoteStatus, o as NoteTarget, p as NoteType, q as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, r as QueryElementResult, R as RegionContext, s as ReloadParams, t as RuntimeErrorEvent, S as ScenarioDetail, u as ScenarioOverview, v as ScrollContext, V as ViewportContext, w as VisualNote } from './commands-fjuqKzkm.js';
+export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-DB7S312i.js';
 export { BROWSER_SECURITY_RULES, FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate } from './core/index.js';
 export { BrowserTrackClient, getClient, init as initClient } from './client/index.js';
 export { BrowserTrackDaemon, createDaemon } from './daemon/index.js';
-export { c as createMcpServer } from './server-BztYp1Zc.js';
+export { c as createMcpServer } from './server-DiVmTrIR.js';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
-import './engine-B43IohQY.js';
+import './engine-CmchnMDq.js';
 import 'ws';
 import 'node:http';
 import '@modelcontextprotocol/sdk/server/index.js';

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   BrowserTrackClient,
   getClient,
   init
-} from "./chunk-WB7ZKWK7.js";
+} from "./chunk-INXDWPJW.js";
 import {
   BrowserTrackDaemon,
   createDaemon
@@ -27,7 +27,7 @@ import {
 } from "./chunk-6VA7GBAO.js";
 import {
   createMcpServer
-} from "./chunk-UP5JKCFY.js";
+} from "./chunk-464D4U2U.js";
 import "./chunk-3HOXPTM2.js";
 export {
   BROWSER_SECURITY_RULES,

package/dist/mcp/index.d.ts

@@ -1,9 +1,9 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-BztYp1Zc.js';
+export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-DiVmTrIR.js';
 import '@modelcontextprotocol/sdk/server/index.js';
-import '../engine-B43IohQY.js';
-import '../notes-BMnonq46.js';
-import '../projects-D5J-egVN.js';
+import '../engine-CmchnMDq.js';
+import '../commands-fjuqKzkm.js';
+import '../projects-DB7S312i.js';
 import 'ws';
 
 declare const TOOLS: Tool[];

package/dist/mcp/index.js

@@ -2,7 +2,7 @@ import {
   TOOLS,
   createMcpServer,
   handleToolCall
-} from "../chunk-UP5JKCFY.js";
+} from "../chunk-464D4U2U.js";
 import "../chunk-3HOXPTM2.js";
 export {
   TOOLS,

package/dist/{projects-D5J-egVN.d.ts → projects-DB7S312i.d.ts}

@@ -1,4 +1,4 @@
-import { B as Breadcrumb, l as NetworkEvent, i as ElementSummary } from './notes-BMnonq46.js';
+import { B as Breadcrumb, m as NetworkEvent, j as ElementSummary } from './commands-fjuqKzkm.js';
 
 type IncidentStatus = 'OPEN' | 'FIX_ATTEMPTED' | 'VERIFYING' | 'VERIFIED' | 'FAILED' | 'INCONCLUSIVE';
 type IncidentSeverity = 'error' | 'warn' | 'fatal';

package/dist/{server-BztYp1Zc.d.ts → server-DiVmTrIR.d.ts}

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-B43IohQY.js';
+import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CmchnMDq.js';
 
 interface McpContext {
     db: StorageDB;

package/docs/component-resolver.md

@@ -0,0 +1,108 @@
+---
+title: Component & Source Resolver
+description: Map live browser DOM elements to React Fiber, Vue VNode, Svelte metadata, and exact source file locations for AI coding agents
+order: 5
+---
+
+# Component & Source-Map Resolver 🧬
+
+A core challenge for AI coding agents during frontend debugging is bridging the gap between what the browser renders (e.g., `<button class="sc-bdVaJa bDwzTH">`) and the actual source code file in the repository (e.g., `src/components/CheckoutButton.tsx:42`).
+
+BrowserTrack includes an automated **Component & Source-Map Resolver** that inspects internal framework virtual DOM instances in real time and attaches exact component and source locations to visual notes, user interaction breadcrumbs, and error incidents.
+
+---
+
+## ⚡ Supported Frameworks
+
+| Framework | Inspection Technique | Resolved Metadata |
+| :--- | :--- | :--- |
+| **React (v16–19)** | `__reactFiber$`, `_debugSource`, `_debugOwner` | Component Name, Source File, Line, Column, Component Hierarchy, Props |
+| **Vue 3** | `__vueParentComponent`, `__vnode` | Component Name (`__name`), SFC File (`__file`), Hierarchy, Props |
+| **Vue 2** | `__vue__.$options` | Component Tag, SFC File (`__file`) |
+| **Svelte** | `__svelte_meta.loc` | Svelte Component Name, File Path, Line, Column |
+| **Web Components** | Hyphenated custom element tags | Custom Element Tag Name |
+| **Generic / Vanilla** | `data-component`, `data-source-file`, `data-source-line` | Explicit Component & File Annotation |
+
+---
+
+## 🔍 How It Works
+
+```mermaid
+graph LR
+    A[Target DOM Element] --> B[BrowserTrack Resolver]
+    B -->|React Fiber| C[Extract _debugSource & _debugOwner]
+    B -->|Vue VNode| D[Extract __file & type.__name]
+    B -->|Svelte Meta| E[Extract loc.file & loc.line]
+    C & D & E --> F[ComponentSourceInfo]
+    F --> G[Visual Notes, Breadcrumbs & Incidents]
+    G --> H[AI Agent opens exact file:line via MCP]
+```
+
+### Development Mode Source Maps
+Modern bundlers (Vite, Next.js, Create React App, Nuxt, SvelteKit) automatically populate `_debugSource` and `__file` on virtual DOM nodes during local development. BrowserTrack reads this data directly without requiring additional build plugins.
+
+---
+
+## 📦 Resolved Metadata Structure
+
+Whenever a visual note is taken, or when user interactions precede a crash:
+
+```typescript
+export interface ComponentSourceInfo {
+  framework?: 'react' | 'vue' | 'svelte' | 'web-component' | 'vanilla';
+  componentName?: string;     // e.g. "CheckoutButton"
+  sourceFile?: string;        // e.g. "src/components/CheckoutButton.tsx"
+  sourceLine?: number;        // e.g. 42
+  sourceColumn?: number;      // e.g. 8
+  hierarchy?: string[];       // e.g. ["App", "ShopLayout", "CartDrawer", "CheckoutButton"]
+  props?: Record<string, any>;// Sanitized component props
+}
+```
+
+---
+
+## 🤖 AI Agent MCP Usage
+
+When an agent retrieves an incident or visual note:
+
+### In `get_incident`:
+The `lastInteractedElement` provides direct source coordinates:
+```json
+{
+  "lastInteractedElement": {
+    "selector": "button#checkout-btn",
+    "tag": "button",
+    "componentSource": {
+      "framework": "react",
+      "componentName": "CheckoutButton",
+      "sourceFile": "src/components/CheckoutButton.tsx",
+      "sourceLine": 42,
+      "hierarchy": ["App", "ShopLayout", "CheckoutButton"]
+    }
+  }
+}
+```
+
+### In `get_note`:
+```json
+{
+  "elementContext": {
+    "selector": ".user-profile-card",
+    "componentSource": {
+      "framework": "vue",
+      "componentName": "UserProfileCard",
+      "sourceFile": "src/components/UserProfileCard.vue"
+    }
+  }
+}
+```
+
+The AI agent can immediately edit the exact file and line without running codebase searches or guessing CSS selectors!
+
+---
+
+## 🎨 Interactive Visual Badges in Browser
+
+When inspecting elements or viewing saved notes on screen:
+- The Note Editor modal displays a purple pill: `🧬 <CheckoutButton> (src/components/CheckoutButton.tsx:42)`.
+- The Note Details Card popover displays the component badge and framework tag (`REACT`, `VUE`, `SVELTE`).

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

@@ -24,7 +24,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 +84,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.

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.1",
   "description": "Local browser diagnostics + MCP bridge for coding agents",
   "type": "module",
   "main": "./dist/index.js",

package/packages/client/src/client.ts

@@ -22,7 +22,10 @@ import { WebSocketTransport } from './transport/websocket.js';
 import { NoteInspector } from './notes/inspector.js';
 
 export class BrowserTrackClient {
-  public options: Required<Omit<BrowserDiagClientOptions, 'notes'>> & { notes: Required<NonNullable<BrowserDiagClientOptions['notes']>> };
+  public options: Required<Omit<BrowserDiagClientOptions, 'notes' | 'hideQueryParam'>> & {
+    hideQueryParam?: string | string[];
+    notes: Required<NonNullable<BrowserDiagClientOptions['notes']>>;
+  };
   private breadcrumbs: BreadcrumbBuffer;
   private transport: WebSocketTransport;
   private screenshotDriver: ScreenshotDriver;
@@ -56,6 +59,10 @@ export class BrowserTrackClient {
       this.inspector = new NoteInspector(this.transport, this.screenshotDriver, {
         shortcut: this.options.notes.shortcut,
         maskSelectors: this.options.notes.maskSelectors,
+        showToolbar: this.options.notes.showToolbar,
+        showBadges: this.options.notes.showBadges,
+        hidden: this.options.hidden,
+        hideQueryParam: this.options.hideQueryParam,
       });
     }
   }
@@ -142,6 +149,16 @@ export class BrowserTrackClient {
     }
   }
 
+  public isUIVisible(): boolean {
+    return this.inspector ? this.inspector.isVisible() : false;
+  }
+
+  public setUIVisible(visible: boolean): void {
+    if (this.inspector) {
+      this.inspector.setVisible(visible);
+    }
+  }
+
   public setInspectMode(mode: 'element' | 'region' | 'page' | 'idle'): void {
     if (this.inspector) {
       this.inspector.setMode(mode);