browsertrack 0.1.2 → 0.2.1

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.1.2",
+  "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);

package/packages/client/src/config.ts

@@ -12,12 +12,25 @@ export interface BrowserDiagClientOptions {
     enabled?: boolean;
     shortcut?: string;
     showBadges?: boolean;
+    showToolbar?: boolean;
     maskSelectors?: string[];
   };
+  /**
+   * Hide visible BrowserTrack UI (toolbar dock, pins, hover overlay) by default.
+   */
+  hidden?: boolean;
+  /**
+   * Custom query parameter(s) used to hide the UI (e.g. 'e2e', 'no_ui', 'clean').
+   * Built-in query params like ?bt=0, ?bt=false, ?bt=hidden, ?browsertrack=false, ?no_bt are supported automatically.
+   */
+  hideQueryParam?: string | string[];
   debug?: boolean;
 }
 
-export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes'>> & { notes: Required<NonNullable<BrowserDiagClientOptions['notes']>> } = {
+export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes' | 'hideQueryParam'>> & {
+  hideQueryParam?: string | string[];
+  notes: Required<NonNullable<BrowserDiagClientOptions['notes']>>;
+} = {
   daemonUrl: 'ws://127.0.0.1:7331',
   projectId: '',
   maxBreadcrumbs: 50,
@@ -31,7 +44,77 @@ export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes'>>
     enabled: true,
     shortcut: 'Alt+Click',
     showBadges: true,
+    showToolbar: true,
     maskSelectors: ['input[type="password"]', '[data-sensitive]'],
   },
+  hidden: false,
+  hideQueryParam: undefined,
   debug: false,
 };
+
+const HIDE_VALUES = new Set(['0', 'false', 'hidden', 'hide', 'off', 'none', 'disabled', 'ui_off', 'silent']);
+
+/**
+ * Checks if the tool's visible UI should be hidden based on URL search query parameters.
+ */
+export function shouldHideUIFromUrl(customParam?: string | string[], searchString?: string): boolean {
+  let search = searchString;
+  if (search === undefined) {
+    if (typeof window === 'undefined' || !window.location) return false;
+    search = window.location.search;
+  }
+
+  if (!search) return false;
+
+  try {
+    const params = new URLSearchParams(search);
+
+    // 1. Check custom parameters if configured
+    if (customParam) {
+      const customKeys = Array.isArray(customParam) ? customParam : [customParam];
+      for (const key of customKeys) {
+        if (params.has(key)) {
+          const val = (params.get(key) || '').toLowerCase().trim();
+          if (val === '' || val === '1' || val === 'true' || HIDE_VALUES.has(val)) {
+            return true;
+          }
+        }
+      }
+    }
+
+    // 2. Boolean flags without values or with 1/true: ?no_bt, ?no_browsertrack, ?hide_bt, ?hide_browsertrack
+    for (const flag of ['no_bt', 'no_browsertrack', 'hide_bt', 'hide_browsertrack']) {
+      if (params.has(flag)) {
+        const val = (params.get(flag) || '').toLowerCase().trim();
+        if (val === '' || val === '1' || val === 'true' || val === 'yes') {
+          return true;
+        }
+      }
+    }
+
+    // 3. Value-based parameters: ?bt=false, ?bt=0, ?bt=hidden, ?bt=off
+    if (params.has('bt')) {
+      const val = (params.get('bt') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val)) return true;
+    }
+
+    if (params.has('browsertrack')) {
+      const val = (params.get('browsertrack') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val)) return true;
+    }
+
+    if (params.has('bt_ui')) {
+      const val = (params.get('bt_ui') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val) || val === '0' || val === 'false') return true;
+    }
+
+    if (params.has('bt_hide')) {
+      const val = (params.get('bt_hide') || '').toLowerCase().trim();
+      if (val === '' || val === '1' || val === 'true') return true;
+    }
+  } catch {
+    // Defensive in non-standard environments
+  }
+
+  return false;
+}

package/packages/client/src/index.ts

@@ -7,6 +7,7 @@ export * from './breadcrumbs.js';
 export * from './screenshot/driver.js';
 export * from './screenshot/browser-script-driver.js';
 export * from './notes/inspector.js';
+export * from './source/resolver.js';
 
 let defaultClient: BrowserTrackClient | null = null;
 
@@ -40,9 +41,11 @@ if (typeof window !== 'undefined') {
     const autoInit = currentScript?.getAttribute('data-auto-init') !== 'false';
     const daemonUrl = currentScript?.getAttribute('data-daemon-url') || undefined;
     const projectId = currentScript?.getAttribute('data-project-id') || undefined;
+    const hidden = currentScript?.getAttribute('data-hidden') === 'true';
+    const hideQueryParam = currentScript?.getAttribute('data-hide-query-param') || undefined;
 
     if (autoInit) {
-      init({ daemonUrl, projectId });
+      init({ daemonUrl, projectId, hidden, hideQueryParam });
     }
   } catch {
     // If auto-start fails, don't crash

package/packages/client/src/interceptors/interaction.ts

@@ -1,5 +1,6 @@
 import type { Breadcrumb, ElementSummary } from '../../../core/src/index.js';
 import { getSemanticSelector, truncate } from '../../../core/src/index.js';
+import { resolveComponentSource } from '../source/resolver.js';
 
 export type InteractionCallback = (breadcrumb: Breadcrumb, elementSummary?: ElementSummary) => void;
 
@@ -12,6 +13,7 @@ export function extractElementSummary(el: HTMLElement | Element): ElementSummary
   const tag = el.tagName.toLowerCase();
   const id = el.id || undefined;
   const classes = Array.from(el.classList || []);
+  const componentSource = resolveComponentSource(el as HTMLElement);
 
   let boundingRect: ElementSummary['boundingRect'] = undefined;
   let visible = true;
@@ -53,6 +55,7 @@ export function extractElementSummary(el: HTMLElement | Element): ElementSummary
     visible,
     innerText,
     outerHTML,
+    componentSource,
   };
 }