browsertrack 0.2.0 → 0.2.2

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,
   };
 }
 

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

@@ -9,14 +9,18 @@ export type NavigationCallback = (event: NavigationEvent) => void;
 export function setupNavigationInterceptors(onNavigation: NavigationCallback): () => void {
   if (typeof window === 'undefined' || typeof history === 'undefined') return () => {};
 
-  let currentUrl = redactUrl(window.location.href);
-
-  // Initial navigation
-  onNavigation({
-    to: currentUrl,
-    type: 'initial',
-    timestamp: Date.now(),
-  });
+  let currentUrl = '';
+  try {
+    currentUrl = redactUrl(window.location.href);
+    // Initial navigation
+    onNavigation({
+      to: currentUrl,
+      type: 'initial',
+      timestamp: Date.now(),
+    });
+  } catch {
+    // Defensive
+  }
 
   const originalPushState = history.pushState;
   const originalReplaceState = history.replaceState;
@@ -58,27 +62,35 @@ export function setupNavigationInterceptors(onNavigation: NavigationCallback): (
   };
 
   const onPopState = () => {
-    const from = currentUrl;
-    const to = redactUrl(window.location.href);
-    currentUrl = to;
-    onNavigation({
-      from,
-      to,
-      type: 'popstate',
-      timestamp: Date.now(),
-    });
+    try {
+      const from = currentUrl;
+      const to = redactUrl(window.location.href);
+      currentUrl = to;
+      onNavigation({
+        from,
+        to,
+        type: 'popstate',
+        timestamp: Date.now(),
+      });
+    } catch {
+      // Defensive
+    }
   };
 
   const onHashChange = () => {
-    const from = currentUrl;
-    const to = redactUrl(window.location.href);
-    currentUrl = to;
-    onNavigation({
-      from,
-      to,
-      type: 'hashchange',
-      timestamp: Date.now(),
-    });
+    try {
+      const from = currentUrl;
+      const to = redactUrl(window.location.href);
+      currentUrl = to;
+      onNavigation({
+        from,
+        to,
+        type: 'hashchange',
+        timestamp: Date.now(),
+      });
+    } catch {
+      // Defensive
+    }
   };
 
   window.addEventListener('popstate', onPopState);

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

@@ -37,35 +37,40 @@ export function setupNetworkInterceptors(onNetwork: NetworkCallback): () => void
 
       const safeUrl = redactUrl(urlStr);
 
+      let response: Response;
       try {
-        const response = await originalFetch.apply(window, [input as any, init]);
-        const durationMs = Date.now() - startTime;
-
-        onNetwork({
-          url: safeUrl,
-          method,
-          status: response.status,
-          statusText: response.statusText,
-          durationMs,
-          timestamp: startTime,
-        });
-
-        return response;
+        response = await originalFetch.apply(window, [input as any, init]);
       } catch (err: any) {
         const durationMs = Date.now() - startTime;
         const isAbort = err?.name === 'AbortError';
 
+        try {
+          onNetwork({
+            url: safeUrl,
+            method,
+            durationMs,
+            error: err?.message || 'Network request failed',
+            aborted: isAbort,
+            timestamp: startTime,
+          });
+        } catch {}
+
+        throw err;
+      }
+
+      const durationMs = Date.now() - startTime;
+      try {
         onNetwork({
           url: safeUrl,
           method,
+          status: response.status,
+          statusText: response.statusText,
           durationMs,
-          error: err?.message || 'Network request failed',
-          aborted: isAbort,
           timestamp: startTime,
         });
+      } catch {}
 
-        throw err;
-      }
+      return response;
     };
 
     cleanups.push(() => {

package/packages/client/src/notes/inspector.ts

@@ -2,6 +2,8 @@ import type { ElementContext, NoteTarget, RegionContext, VisualNote } from '../.
 import { getSemanticSelector, truncate } from '../../../core/src/index.js';
 import type { ScreenshotDriver } from '../screenshot/driver.js';
 import type { WebSocketTransport } from '../transport/websocket.js';
+import { shouldHideUIFromUrl } from '../config.js';
+import { resolveComponentSource } from '../source/resolver.js';
 
 export type NoteInspectMode = 'element' | 'region' | 'page' | 'idle';
 
@@ -9,6 +11,9 @@ export interface InspectorOptions {
   shortcut?: string; // e.g. "Alt+Click"
   maskSelectors?: string[];
   showToolbar?: boolean;
+  showBadges?: boolean;
+  hidden?: boolean;
+  hideQueryParam?: string | string[];
   onNoteCreated?: (note: Partial<VisualNote>) => void;
 }
 
@@ -28,6 +33,7 @@ export interface ActiveScenarioState {
  * 5. Real-time Saved Note & Step Markers (pins with step sequencing numbers)
  * 6. Interactive Note & Step Detail Card (with previous/next step walk-through navigation)
  * 7. Floating quick dock / toolbar in bottom-right corner with Notes count and Flow controls
+ * 8. Automatic invisibility via query parameter (?bt=0, ?bt=false, ?bt=hidden, ?no_bt, custom query params)
  */
 export class NoteInspector {
   private transport: WebSocketTransport;
@@ -58,15 +64,20 @@ export class NoteInspector {
 
   private savedNotes: VisualNote[] = [];
   private showMarkers = true;
+  private isHidden = false;
   private cleanups: (() => void)[] = [];
 
   constructor(transport: WebSocketTransport, screenshotDriver: ScreenshotDriver, options: InspectorOptions = {}) {
     this.transport = transport;
     this.screenshotDriver = screenshotDriver;
+    const hiddenByQuery = shouldHideUIFromUrl(options.hideQueryParam);
+    this.isHidden = options.hidden === true || hiddenByQuery;
+    this.showMarkers = options.showBadges !== false && !this.isHidden;
     this.options = {
       shortcut: 'Alt+Click',
       maskSelectors: ['input[type="password"]', '[data-sensitive]'],
       showToolbar: true,
+      showBadges: true,
       ...options,
     };
   }
@@ -158,6 +169,44 @@ export class NoteInspector {
     }
   }
 
+  public isVisible(): boolean {
+    return !this.isHidden;
+  }
+
+  public setVisible(visible: boolean): void {
+    this.isHidden = !visible;
+    this.showMarkers = this.options.showBadges !== false && !this.isHidden;
+
+    if (this.container) {
+      this.container.style.display = this.isHidden ? 'none' : 'block';
+    }
+
+    if (this.toolbarElement) {
+      this.toolbarElement.style.display = this.isHidden ? 'none' : 'flex';
+    } else if (!this.isHidden && this.options.showToolbar !== false) {
+      this.createToolbar();
+    }
+
+    if (this.isHidden) {
+      this.hideHighlight();
+      this.hideRegionOverlay();
+      if (this.modalOverlay && this.shadowRoot) {
+        this.shadowRoot.removeChild(this.modalOverlay);
+        this.modalOverlay = null;
+      }
+      if (this.cardOverlay && this.shadowRoot) {
+        this.shadowRoot.removeChild(this.cardOverlay);
+        this.cardOverlay = null;
+      }
+      if (this.markersContainer) {
+        this.markersContainer.innerHTML = '';
+      }
+    } else {
+      this.renderMarkers();
+      this.updateToolbarCount();
+    }
+  }
+
   private ensureContainer(): ShadowRoot | null {
     if (typeof document === 'undefined') return null;
 
@@ -166,6 +215,9 @@ export class NoteInspector {
       this.container.id = 'browsertrack-inspector-host';
       this.container.style.cssText =
         'all: initial; position: fixed; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647; pointer-events: none;';
+      if (this.isHidden) {
+        this.container.style.display = 'none';
+      }
 
       this.shadowRoot = this.container.attachShadow({ mode: 'open' });
 
@@ -611,6 +663,22 @@ export class NoteInspector {
           color: #cbd5e1;
         }
 
+        .bt-component-pill {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          background: rgba(15, 23, 42, 0.95);
+          border: 1px solid rgba(99, 102, 241, 0.35);
+          border-radius: 6px;
+          padding: 6px 10px;
+          font-size: 11.5px;
+          color: #c7d2fe;
+          font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+
         .bt-scenario-stepper {
           display: flex;
           align-items: center;
@@ -859,7 +927,7 @@ export class NoteInspector {
       this.shadowRoot.appendChild(this.toastContainer);
 
       // Floating Toolbar
-      if (this.options.showToolbar) {
+      if (this.options.showToolbar && !this.isHidden) {
         this.createToolbar();
       }
     }
@@ -978,13 +1046,20 @@ export class NoteInspector {
     if (!root || !this.markersContainer) return;
 
     this.markersContainer.innerHTML = '';
-    if (!this.showMarkers) return;
+    if (!this.showMarkers || this.isHidden) return;
 
     const currentPath = window.location.pathname;
     // Filter open notes on this route or global
-    const activeNotes = this.savedNotes.filter(
-      (n) => n.status === 'OPEN' && (n.route === currentPath || !n.route || n.route === '/' || window.location.href.includes(n.route))
-    );
+    const activeNotes = this.savedNotes.filter((n) => {
+      if (n.status !== 'OPEN') return false;
+      if (!n.route) return true;
+      if (n.route === currentPath) return true;
+      // Support hash or query routes (e.g. /#modal or /?tab=settings)
+      if (n.route.includes('#') || n.route.includes('?')) {
+        return window.location.href.includes(n.route);
+      }
+      return false;
+    });
 
     const pageNotes: VisualNote[] = [];
 
@@ -1143,6 +1218,32 @@ export class NoteInspector {
 
         ${scenarioStepsHtml}
 
+        ${
+          note.elementContext?.componentSource?.componentName
+            ? `<div class="bt-component-pill" title="${
+                note.elementContext.componentSource.sourceFile
+                  ? note.elementContext.componentSource.sourceFile +
+                    (note.elementContext.componentSource.sourceLine ? ':' + note.elementContext.componentSource.sourceLine : '')
+                  : note.elementContext.componentSource.componentName
+              }">
+                <span>🧬</span>
+                <span style="font-weight: 600; color: #a5b4fc;">&lt;${note.elementContext.componentSource.componentName}&gt;</span>
+                ${
+                  note.elementContext.componentSource.sourceFile
+                    ? `<span style="color: #64748b; font-size: 11px; margin-left: 4px;">${note.elementContext.componentSource.sourceFile}${
+                        note.elementContext.componentSource.sourceLine ? ':' + note.elementContext.componentSource.sourceLine : ''
+                      }</span>`
+                    : ''
+                }
+                ${
+                  note.elementContext.componentSource.framework
+                    ? `<span class="bt-mode-badge" style="background: rgba(99, 102, 241, 0.15); color: #818cf8; margin-left: auto; font-size: 10px;">${note.elementContext.componentSource.framework.toUpperCase()}</span>`
+                    : ''
+                }
+              </div>`
+            : ''
+        }
+
         <div class="bt-target-pill" title="${contextText}">
           <span>🏷️</span>
           <span class="bt-pill-content">${contextText}</span>
@@ -1249,81 +1350,103 @@ export class NoteInspector {
   private setupListeners(): void {
     // 1. Mouse move: hover highlight in element mode or with Alt key
     const onMouseMove = (e: MouseEvent) => {
-      if (this.modalOverlay || this.cardOverlay || this.isDraggingRegion || this.activeMode === 'region') return;
-
-      // Don't highlight elements if mouse is over our own inspector UI
-      const path = e.composedPath ? e.composedPath() : [];
-      if (this.container && path.includes(this.container)) {
-        this.hideHighlight();
-        return;
-      }
+      try {
+        if (this.isHidden || this.modalOverlay || this.cardOverlay || this.isDraggingRegion || this.activeMode === 'region') return;
 
-      if (e.altKey || this.activeMode === 'element') {
-        const target = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement | null;
-        if (target && target !== this.container && !this.container?.contains(target)) {
-          this.hoveredElement = target;
-          this.updateHighlight(target);
+        // Don't highlight elements if mouse is over our own inspector UI
+        const path = e.composedPath ? e.composedPath() : [];
+        if (this.container && path.includes(this.container)) {
+          this.hideHighlight();
           return;
         }
-      }
 
-      if (!e.altKey && this.activeMode !== 'element') {
-        this.hideHighlight();
+        if (e.altKey || this.activeMode === 'element') {
+          const target = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement | null;
+          if (target && target !== this.container && !this.container?.contains(target)) {
+            this.hoveredElement = target;
+            this.updateHighlight(target);
+            return;
+          }
+        }
+
+        if (!e.altKey && this.activeMode !== 'element') {
+          this.hideHighlight();
+        }
+      } catch {
+        // Defensive: never let inspector hover crash host app
       }
     };
 
     // 2. Click: Alt+Click or Element mode click selects element and opens editor
     const onClick = (e: MouseEvent) => {
-      if (this.modalOverlay || this.cardOverlay) return;
+      try {
+        if (this.isHidden || this.modalOverlay || this.cardOverlay) return;
 
-      // If clicking inside inspector toolbar or container, do NOT intercept
-      const path = e.composedPath ? e.composedPath() : [];
-      if (this.container && path.includes(this.container)) {
-        return;
-      }
+        // If clicking inside inspector toolbar or container, do NOT intercept
+        const path = e.composedPath ? e.composedPath() : [];
+        if (this.container && path.includes(this.container)) {
+          return;
+        }
 
-      if (this.activeMode === 'region') return;
+        if (this.activeMode === 'region') return;
 
-      if (e.altKey || this.activeMode === 'element') {
-        e.preventDefault();
-        e.stopPropagation();
+        if (e.altKey || this.activeMode === 'element') {
+          e.preventDefault();
+          e.stopPropagation();
 
-        const target = (this.hoveredElement || document.elementFromPoint(e.clientX, e.clientY)) as HTMLElement | null;
-        if (target && target !== this.container && !this.container?.contains(target)) {
-          this.selectedElement = target;
-          this.openNoteEditor(target, 'element');
-          if (this.activeMode === 'element' && !this.activeScenario) {
-            this.setMode('idle');
+          const target = (this.hoveredElement || document.elementFromPoint(e.clientX, e.clientY)) as HTMLElement | null;
+          if (target && target !== this.container && !this.container?.contains(target)) {
+            this.selectedElement = target;
+            this.openNoteEditor(target, 'element');
+            if (this.activeMode === 'element' && !this.activeScenario) {
+              this.setMode('idle');
+            }
           }
         }
+      } catch {
+        // Defensive
       }
     };
 
     // 3. Key handling: Escape cancels active modes, Alt release hides highlight
     const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        if (this.cardOverlay && this.cardOverlay.parentElement && this.shadowRoot) {
-          this.shadowRoot.removeChild(this.cardOverlay);
-          this.cardOverlay = null;
-        } else if (this.activeMode === 'region' || this.activeMode === 'element') {
-          if (!this.activeScenario) {
-            this.setMode('idle');
+      try {
+        if (e.key === 'Escape') {
+          if (this.cardOverlay && this.cardOverlay.parentElement && this.shadowRoot) {
+            this.shadowRoot.removeChild(this.cardOverlay);
+            this.cardOverlay = null;
+          } else if (this.activeMode === 'region' || this.activeMode === 'element') {
+            if (!this.activeScenario) {
+              this.setMode('idle');
+            }
           }
         }
+      } catch {
+        // Defensive
       }
     };
 
     const onKeyUp = (e: KeyboardEvent) => {
-      if (e.key === 'Alt' && !this.modalOverlay && !this.cardOverlay && this.activeMode !== 'element') {
-        this.hideHighlight();
+      try {
+        if (e.key === 'Alt' && !this.modalOverlay && !this.cardOverlay && this.activeMode !== 'element') {
+          this.hideHighlight();
+        }
+      } catch {
+        // Defensive
       }
     };
 
     // 4. Scroll & resize: reposition markers accurately
     const onScrollOrResize = () => {
-      requestAnimationFrame(() => {
-        this.updateMarkerPositions();
-      });
+      try {
+        requestAnimationFrame(() => {
+          try {
+            this.updateMarkerPositions();
+          } catch {}
+        });
+      } catch {
+        // Defensive
+      }
     };
 
     window.addEventListener('mousemove', onMouseMove, { capture: true, passive: true });
@@ -1505,6 +1628,11 @@ export class NoteInspector {
       this.updateHighlight(targetEl);
     }
 
+    const comp = noteType === 'element' ? resolveComponentSource(targetEl) : undefined;
+    const compPrefix = comp?.componentName
+      ? `🧬 <${comp.componentName}>${comp.sourceFile ? ' (' + comp.sourceFile + (comp.sourceLine ? ':' + comp.sourceLine : '') + ')' : ''} · `
+      : '';
+
     this.renderNoteModal({
       title: this.activeScenario
         ? `Step ${this.activeScenario.stepNumber}: ${this.activeScenario.title}`
@@ -1513,7 +1641,7 @@ export class NoteInspector {
       pillText:
         noteType === 'page'
           ? `Page Viewport: ${window.innerWidth} × ${window.innerHeight} px`
-          : `${getSemanticSelector(targetEl)} (${Math.round(targetEl.getBoundingClientRect().width)}×${Math.round(targetEl.getBoundingClientRect().height)}) · Viewport: ${window.innerWidth}×${window.innerHeight}`,
+          : `${compPrefix}${getSemanticSelector(targetEl)} (${Math.round(targetEl.getBoundingClientRect().width)}×${Math.round(targetEl.getBoundingClientRect().height)}) · Viewport: ${window.innerWidth}×${window.innerHeight}`,
       onSave: async (message, action) => {
         let scenarioParam: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string } | undefined;
 
@@ -1863,12 +1991,15 @@ export class NoteInspector {
       innerText = truncate(innerText, 200);
     }
 
+    const componentSource = resolveComponentSource(el);
+
     return {
       selector,
       tag: el.tagName.toLowerCase(),
       attributes,
       outerHTML,
       innerText,
+      componentSource,
       parent: el.parentElement
         ? {
             selector: getSemanticSelector(el.parentElement),
@@ -1903,7 +2034,11 @@ export class NoteInspector {
           region.width,
           region.height
         );
-        resolve(canvas.toDataURL('image/png'));
+        try {
+          resolve(canvas.toDataURL('image/png'));
+        } catch {
+          resolve(dataUrl);
+        }
       };
       img.onerror = () => resolve(dataUrl);
       img.src = dataUrl;