browsertrack 0.0.1 → 0.1.0

package/packages/client/src/client.ts

@@ -0,0 +1,278 @@
+import type {
+  Breadcrumb,
+  ClientEventMessage,
+  ConsoleEvent,
+  ElementSummary,
+  NavigationEvent,
+  NetworkEvent,
+  RuntimeErrorEvent,
+} from '../../core/src/index.js';
+import { BreadcrumbBuffer } from './breadcrumbs.js';
+import { ClientCommandHandler } from './commands/handler.js';
+import type { BrowserDiagClientOptions } from './config.js';
+import { DEFAULT_OPTIONS } from './config.js';
+import { setupConsoleInterceptors } from './interceptors/console.js';
+import { setupInteractionInterceptors } from './interceptors/interaction.js';
+import { setupNavigationInterceptors } from './interceptors/navigation.js';
+import { setupNetworkInterceptors } from './interceptors/network.js';
+import { setupRuntimeInterceptors } from './interceptors/runtime.js';
+import { BrowserScriptScreenshotDriver } from './screenshot/browser-script-driver.js';
+import type { ScreenshotDriver } from './screenshot/driver.js';
+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']>> };
+  private breadcrumbs: BreadcrumbBuffer;
+  private transport: WebSocketTransport;
+  private screenshotDriver: ScreenshotDriver;
+  private commandHandler: ClientCommandHandler;
+  private inspector?: NoteInspector;
+  private lastElement: ElementSummary | undefined;
+  private currentRoute = '/';
+  private cleanups: (() => void)[] = [];
+  private isInitialized = false;
+
+  constructor(options: BrowserDiagClientOptions = {}) {
+    this.options = {
+      ...DEFAULT_OPTIONS,
+      ...options,
+      notes: {
+        ...DEFAULT_OPTIONS.notes,
+        ...(options.notes || {}),
+      },
+    };
+    this.breadcrumbs = new BreadcrumbBuffer(this.options.maxBreadcrumbs);
+    this.transport = new WebSocketTransport({
+      url: this.options.daemonUrl,
+      projectId: this.options.projectId,
+      debug: this.options.debug,
+    });
+    this.screenshotDriver = new BrowserScriptScreenshotDriver();
+    this.commandHandler = new ClientCommandHandler(this.screenshotDriver);
+    this.transport.setCommandHandler(this.commandHandler);
+
+    if (this.options.notes.enabled) {
+      this.inspector = new NoteInspector(this.transport, this.screenshotDriver, {
+        shortcut: this.options.notes.shortcut,
+        maskSelectors: this.options.notes.maskSelectors,
+      });
+    }
+  }
+
+  public init(): this {
+    if (this.isInitialized || typeof window === 'undefined') return this;
+    this.isInitialized = true;
+
+    try {
+      this.currentRoute = window.location.pathname + window.location.search;
+    } catch {
+      this.currentRoute = '/';
+    }
+
+    // 1. Connect WebSocket
+    this.transport.connect();
+
+    // 2. Setup Runtime error interceptor
+    if (this.options.captureErrors) {
+      const cleanupRuntime = setupRuntimeInterceptors(async (errEvent) => {
+        await this.handleRuntimeError(errEvent);
+      });
+      this.cleanups.push(cleanupRuntime);
+    }
+
+    // 3. Setup Console interceptor
+    if (this.options.captureConsole) {
+      const cleanupConsole = setupConsoleInterceptors(async (consoleEvent) => {
+        await this.handleConsole(consoleEvent);
+      });
+      this.cleanups.push(cleanupConsole);
+    }
+
+    // 4. Setup Network interceptor
+    if (this.options.captureNetwork) {
+      const cleanupNetwork = setupNetworkInterceptors((netEvent) => {
+        this.handleNetwork(netEvent);
+      });
+      this.cleanups.push(cleanupNetwork);
+    }
+
+    // 5. Setup Navigation interceptor
+    if (this.options.captureNavigation) {
+      const cleanupNav = setupNavigationInterceptors((navEvent) => {
+        this.handleNavigation(navEvent);
+      });
+      this.cleanups.push(cleanupNav);
+    }
+
+    // 6. Setup Interaction interceptor
+    if (this.options.captureInteractions) {
+      const cleanupInteraction = setupInteractionInterceptors((breadcrumb, elSummary) => {
+        if (elSummary) {
+          this.lastElement = elSummary;
+        }
+        this.breadcrumbs.add(breadcrumb);
+      });
+      this.cleanups.push(cleanupInteraction);
+    }
+
+    // 7. Setup Visual Note Inspector
+    if (this.inspector) {
+      this.inspector.init();
+    }
+
+    return this;
+  }
+
+  public openNoteEditor(el?: HTMLElement, noteType: 'element' | 'page' = 'element'): void {
+    if (this.inspector) {
+      this.inspector.openNoteEditor(el, noteType);
+    }
+  }
+
+  public startRegionSelection(): void {
+    if (this.inspector) {
+      this.inspector.setMode('region');
+    }
+  }
+
+  public startElementSelection(): void {
+    if (this.inspector) {
+      this.inspector.setMode('element');
+    }
+  }
+
+  public setInspectMode(mode: 'element' | 'region' | 'page' | 'idle'): void {
+    if (this.inspector) {
+      this.inspector.setMode(mode);
+    }
+  }
+
+  public async createNote(targetEl: HTMLElement, message: string, noteType: 'element' | 'page' = 'element'): Promise<void> {
+    if (this.inspector) {
+      await this.inspector.saveVisualNote(targetEl, message, noteType);
+    }
+  }
+
+  private async handleRuntimeError(errorEvent: RuntimeErrorEvent): Promise<void> {
+    // Add to breadcrumbs
+    this.breadcrumbs.add({
+      type: 'error',
+      category: 'runtime',
+      message: `${errorEvent.errorType}: ${errorEvent.message}`,
+      timestamp: errorEvent.timestamp,
+      level: 'error',
+      data: {
+        filename: errorEvent.filename,
+        lineno: errorEvent.lineno,
+        colno: errorEvent.colno,
+      },
+    });
+
+    let screenshotDataUrl: string | undefined;
+    if (this.options.onErrorScreenshot && this.lastElement?.selector) {
+      try {
+        const snap = await this.screenshotDriver.captureSelector(this.lastElement.selector);
+        if (snap.ok) {
+          screenshotDataUrl = snap.dataUrl;
+        }
+      } catch {
+        // Defensive
+      }
+    }
+
+    this.sendEvent('runtime_error', errorEvent, screenshotDataUrl);
+  }
+
+  private async handleConsole(consoleEvent: ConsoleEvent): Promise<void> {
+    this.breadcrumbs.add({
+      type: 'console',
+      category: 'console',
+      message: `console.${consoleEvent.level}: ${consoleEvent.message}`,
+      timestamp: consoleEvent.timestamp,
+      level: consoleEvent.level === 'error' ? 'error' : consoleEvent.level === 'warn' ? 'warn' : 'info',
+    });
+
+    if (consoleEvent.level === 'error' || consoleEvent.level === 'warn') {
+      this.sendEvent('console', consoleEvent);
+    }
+  }
+
+  private handleNetwork(netEvent: NetworkEvent): void {
+    const isError = (netEvent.status && netEvent.status >= 400) || !!netEvent.error;
+    const msg = `${netEvent.method} ${netEvent.url} -> ${netEvent.status || 'ERR'} (${netEvent.durationMs}ms)`;
+
+    this.breadcrumbs.add({
+      type: netEvent.id?.startsWith('xhr') ? 'xhr' : 'fetch',
+      category: 'network',
+      message: msg,
+      timestamp: netEvent.timestamp,
+      level: isError ? 'error' : 'info',
+      data: {
+        status: netEvent.status,
+        durationMs: netEvent.durationMs,
+        error: netEvent.error,
+        aborted: netEvent.aborted,
+      },
+    });
+
+    this.sendEvent('fetch', netEvent);
+  }
+
+  private handleNavigation(navEvent: NavigationEvent): void {
+    this.currentRoute = navEvent.to;
+    this.breadcrumbs.add({
+      type: 'navigation',
+      category: 'navigation',
+      message: `navigate ${navEvent.to} (${navEvent.type})`,
+      timestamp: navEvent.timestamp,
+      level: 'info',
+      data: { from: navEvent.from, to: navEvent.to, type: navEvent.type },
+    });
+
+    this.sendEvent('navigation', navEvent);
+  }
+
+  private sendEvent(eventType: any, payload: any, screenshotDataUrl?: string): void {
+    if (typeof window === 'undefined') return;
+
+    const message: ClientEventMessage & { screenshot?: string } = {
+      type: 'event',
+      sessionId: this.transport.getSessionId() || '',
+      eventType,
+      payload,
+      breadcrumbs: this.breadcrumbs.getRecent(),
+      lastElement: this.lastElement,
+      route: this.currentRoute,
+      url: window.location.href,
+      title: document.title,
+      timestamp: Date.now(),
+      screenshot: screenshotDataUrl,
+    };
+
+    this.transport.send(message);
+  }
+
+  public getBreadcrumbs(): Breadcrumb[] {
+    return this.breadcrumbs.getRecent();
+  }
+
+  public getLastElement(): ElementSummary | undefined {
+    return this.lastElement;
+  }
+
+  public destroy(): void {
+    for (const cleanup of this.cleanups) {
+      try {
+        cleanup();
+      } catch {}
+    }
+    this.cleanups = [];
+    this.transport.destroy();
+    if (this.inspector) {
+      this.inspector.destroy();
+    }
+    this.breadcrumbs.clear();
+    this.isInitialized = false;
+  }
+}

package/packages/client/src/commands/handler.ts

@@ -0,0 +1,301 @@
+import type {
+  ClientCommand,
+  CommandResponse,
+  PageStateResult,
+  QueryElementResult,
+  CaptureElementResult,
+} from '../../../core/src/index.js';
+import { truncate } from '../../../core/src/index.js';
+import { extractElementSummary } from '../interceptors/interaction.js';
+import type { ScreenshotDriver } from '../screenshot/driver.js';
+
+export class ClientCommandHandler {
+  private screenshotDriver: ScreenshotDriver;
+
+  constructor(screenshotDriver: ScreenshotDriver) {
+    this.screenshotDriver = screenshotDriver;
+  }
+
+  public async executeCommand(command: ClientCommand): Promise<CommandResponse> {
+    try {
+      switch (command.type) {
+        case 'reload':
+          return this.handleReload(command);
+
+        case 'navigate':
+          return this.handleNavigate(command);
+
+        case 'get_page_state':
+          return this.handleGetPageState(command);
+
+        case 'query_element':
+          return this.handleQueryElement(command);
+
+        case 'capture_element':
+          return await this.handleCaptureElement(command);
+
+        case 'check_overflow':
+          return this.handleCheckOverflow(command);
+
+        case 'get_element_rect':
+          return this.handleGetElementRect(command);
+
+        case 'get_element_style':
+          return this.handleGetElementStyle(command);
+
+        default:
+          return {
+            id: command.id,
+            ok: false,
+            error: `Unsupported command type: ${(command as any).type}`,
+          };
+      }
+    } catch (err: any) {
+      return {
+        id: command.id,
+        ok: false,
+        error: err?.message || 'Command execution failed',
+      };
+    }
+  }
+
+  private handleReload(command: ClientCommand): CommandResponse {
+    if (typeof window !== 'undefined' && window.location) {
+      setTimeout(() => {
+        window.location.reload();
+      }, 50);
+      return { id: command.id, ok: true, result: { message: 'Reload initiated' } };
+    }
+    return { id: command.id, ok: false, error: 'No browser window available' };
+  }
+
+  private handleNavigate(command: ClientCommand<{ url: string }>): CommandResponse {
+    const targetUrl = command.params?.url;
+    if (!targetUrl) {
+      return { id: command.id, ok: false, error: 'Missing target url parameter' };
+    }
+
+    if (typeof window !== 'undefined' && window.location) {
+      setTimeout(() => {
+        window.location.href = targetUrl;
+      }, 50);
+      return { id: command.id, ok: true, result: { message: `Navigating to ${targetUrl}` } };
+    }
+    return { id: command.id, ok: false, error: 'No browser window available' };
+  }
+
+  private handleGetPageState(command: ClientCommand): CommandResponse<PageStateResult> {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return { id: command.id, ok: false, error: 'No browser document available' };
+    }
+
+    const activeEl = document.activeElement && document.activeElement !== document.body ? extractElementSummary(document.activeElement) : undefined;
+
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        url: window.location.href,
+        route: window.location.pathname + window.location.search + window.location.hash,
+        title: document.title,
+        readyState: document.readyState,
+        activeElement: activeEl,
+      },
+    };
+  }
+
+  private handleQueryElement(command: ClientCommand<{ selector: string }>): CommandResponse<QueryElementResult> {
+    if (typeof document === 'undefined') {
+      return { id: command.id, ok: false, error: 'No browser document available' };
+    }
+
+    const selector = command.params?.selector;
+    if (!selector) {
+      return { id: command.id, ok: false, error: 'Missing selector parameter' };
+    }
+
+    const element = document.querySelector(selector);
+    if (!element) {
+      return {
+        id: command.id,
+        ok: true,
+        result: { exists: false },
+      };
+    }
+
+    const summary = extractElementSummary(element);
+
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        exists: true,
+        visible: summary.visible,
+        tag: summary.tag,
+        id: summary.id,
+        classes: summary.classes,
+        boundingRect: summary.boundingRect,
+        innerText: summary.innerText,
+        outerHTML: summary.outerHTML,
+      },
+    };
+  }
+
+  private async handleCaptureElement(command: ClientCommand<{ selector?: string }>): Promise<CommandResponse<CaptureElementResult>> {
+    const selector = command.params?.selector;
+    let targetEl: Element | null = null;
+
+    if (selector) {
+      targetEl = document.querySelector(selector);
+      if (!targetEl) {
+        return {
+          id: command.id,
+          ok: false,
+          reason: `ELEMENT_NOT_FOUND: ${selector}`,
+          error: `Element not found for selector: ${selector}`,
+        };
+      }
+    } else {
+      targetEl = document.body || document.documentElement;
+    }
+
+    const captureRes = await this.screenshotDriver.captureElement(targetEl);
+    if (!captureRes.ok) {
+      return {
+        id: command.id,
+        ok: false,
+        reason: captureRes.reason || 'CAPTURE_FAILED',
+        error: captureRes.reason || 'Failed to capture element screenshot',
+      };
+    }
+
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        dataUrl: captureRes.dataUrl,
+        format: captureRes.format,
+        width: captureRes.width,
+        height: captureRes.height,
+      },
+    };
+  }
+
+  private handleCheckOverflow(command: ClientCommand<{ selector: string }>): CommandResponse {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return { id: command.id, ok: false, error: 'No browser window available' };
+    }
+
+    const selector = command.params?.selector;
+    if (!selector) {
+      return { id: command.id, ok: false, error: 'Missing selector parameter' };
+    }
+
+    const el = document.querySelector(selector);
+    if (!el) {
+      return { id: command.id, ok: false, error: `Element not found: ${selector}` };
+    }
+
+    const rect = el.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+
+    const overflowRightPx = Math.max(0, Math.round(rect.right - vw));
+    const overflowBottomPx = Math.max(0, Math.round(rect.bottom - vh));
+    const isViewportOverflow = overflowRightPx > 0 || rect.left < 0;
+
+    let parentOverflow = false;
+    if (el.parentElement) {
+      parentOverflow = el.parentElement.scrollWidth > el.parentElement.clientWidth;
+    }
+
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        selector,
+        overflow: isViewportOverflow || parentOverflow,
+        viewportWidth: vw,
+        viewportHeight: vh,
+        rect: {
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+          top: Math.round(rect.top),
+          left: Math.round(rect.left),
+          bottom: Math.round(rect.bottom),
+          right: Math.round(rect.right),
+        },
+        overflowRightPx,
+        overflowBottomPx,
+        parentOverflow,
+      },
+    };
+  }
+
+  private handleGetElementRect(command: ClientCommand<{ selector: string }>): CommandResponse {
+    if (typeof document === 'undefined') {
+      return { id: command.id, ok: false, error: 'No browser document available' };
+    }
+
+    const selector = command.params?.selector;
+    if (!selector) {
+      return { id: command.id, ok: false, error: 'Missing selector parameter' };
+    }
+
+    const el = document.querySelector(selector);
+    if (!el) {
+      return { id: command.id, ok: false, error: `Element not found: ${selector}` };
+    }
+
+    const rect = el.getBoundingClientRect();
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        x: Math.round(rect.x),
+        y: Math.round(rect.y),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        top: Math.round(rect.top),
+        left: Math.round(rect.left),
+        bottom: Math.round(rect.bottom),
+        right: Math.round(rect.right),
+      },
+    };
+  }
+
+  private handleGetElementStyle(command: ClientCommand<{ selector: string; properties?: string[] }>): CommandResponse {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return { id: command.id, ok: false, error: 'No browser window available' };
+    }
+
+    const selector = command.params?.selector;
+    if (!selector) {
+      return { id: command.id, ok: false, error: 'Missing selector parameter' };
+    }
+
+    const el = document.querySelector(selector);
+    if (!el) {
+      return { id: command.id, ok: false, error: `Element not found: ${selector}` };
+    }
+
+    const computed = window.getComputedStyle(el);
+    const properties = command.params?.properties || ['overflow', 'overflowX', 'overflowY', 'width', 'maxWidth', 'display', 'position'];
+    const styles: Record<string, string> = {};
+
+    for (const prop of properties) {
+      styles[prop] = computed.getPropertyValue(prop) || (computed as any)[prop] || '';
+    }
+
+    return {
+      id: command.id,
+      ok: true,
+      result: {
+        selector,
+        styles,
+      },
+    };
+  }
+}

package/packages/client/src/config.ts

@@ -0,0 +1,37 @@
+export interface BrowserDiagClientOptions {
+  daemonUrl?: string;
+  projectId?: string;
+  maxBreadcrumbs?: number;
+  captureErrors?: boolean;
+  captureConsole?: boolean;
+  captureNetwork?: boolean;
+  captureNavigation?: boolean;
+  captureInteractions?: boolean;
+  onErrorScreenshot?: boolean;
+  notes?: {
+    enabled?: boolean;
+    shortcut?: string;
+    showBadges?: boolean;
+    maskSelectors?: string[];
+  };
+  debug?: boolean;
+}
+
+export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes'>> & { notes: Required<NonNullable<BrowserDiagClientOptions['notes']>> } = {
+  daemonUrl: 'ws://127.0.0.1:7331',
+  projectId: '',
+  maxBreadcrumbs: 50,
+  captureErrors: true,
+  captureConsole: true,
+  captureNetwork: true,
+  captureNavigation: true,
+  captureInteractions: true,
+  onErrorScreenshot: true,
+  notes: {
+    enabled: true,
+    shortcut: 'Alt+Click',
+    showBadges: true,
+    maskSelectors: ['input[type="password"]', '[data-sensitive]'],
+  },
+  debug: false,
+};

package/packages/client/src/index.ts

@@ -0,0 +1,50 @@
+import { BrowserTrackClient } from './client.js';
+import type { BrowserDiagClientOptions } from './config.js';
+
+export * from './client.js';
+export * from './config.js';
+export * from './breadcrumbs.js';
+export * from './screenshot/driver.js';
+export * from './screenshot/browser-script-driver.js';
+export * from './notes/inspector.js';
+
+let defaultClient: BrowserTrackClient | null = null;
+
+/**
+ * Initializes the BrowserTrack client.
+ */
+export function init(options: BrowserDiagClientOptions = {}): BrowserTrackClient {
+  if (defaultClient) {
+    return defaultClient;
+  }
+
+  defaultClient = new BrowserTrackClient(options);
+  defaultClient.init();
+  return defaultClient;
+}
+
+export function getClient(): BrowserTrackClient | null {
+  return defaultClient;
+}
+
+// Auto-initialize when injected via <script src="...">
+if (typeof window !== 'undefined') {
+  (window as any).__BROWSERTRACK__ = {
+    init,
+    getClient,
+  };
+
+  // Auto-start by default in browser if not explicitly disabled
+  try {
+    const currentScript = document.currentScript;
+    const autoInit = currentScript?.getAttribute('data-auto-init') !== 'false';
+    const daemonUrl = currentScript?.getAttribute('data-daemon-url') || undefined;
+    const projectId = currentScript?.getAttribute('data-project-id') || undefined;
+
+    if (autoInit) {
+      init({ daemonUrl, projectId });
+    }
+  } catch {
+    // If auto-start fails, don't crash
+  }
+}