browsertrack 0.0.1 → 0.1.0

package/packages/client/src/screenshot/browser-script-driver.ts

@@ -0,0 +1,192 @@
+import { snapdom } from '@zumer/snapdom';
+import type { ScreenshotDriver, ScreenshotResult } from './driver.js';
+
+/**
+ * Modern DOM snapshot driver using @zumer/snapdom with graceful fallbacks.
+ * Converts DOM subtrees and elements into WebP / PNG data URLs.
+ */
+export class BrowserScriptScreenshotDriver implements ScreenshotDriver {
+  public name = 'BrowserScriptScreenshotDriver';
+
+  public async captureSelector(selector: string): Promise<ScreenshotResult> {
+    try {
+      if (typeof document === 'undefined') {
+        return { ok: false, reason: 'NO_DOCUMENT_ENVIRONMENT' };
+      }
+
+      const el = document.querySelector(selector);
+      if (!el) {
+        return { ok: false, reason: `ELEMENT_NOT_FOUND: ${selector}` };
+      }
+
+      return await this.captureElement(el);
+    } catch (err: any) {
+      return { ok: false, reason: err?.message || 'UNKNOWN_CAPTURE_ERROR' };
+    }
+  }
+
+  public async captureElement(element: HTMLElement | Element): Promise<ScreenshotResult> {
+    try {
+      if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return { ok: false, reason: 'NO_BROWSER_ENVIRONMENT' };
+      }
+
+      const rect = element.getBoundingClientRect();
+      const width = Math.max(Math.round(rect.width), 10);
+      const height = Math.max(Math.round(rect.height), 10);
+
+      // Attempt capture with snapdom
+      const capturePromise = (async () => {
+        try {
+          // Prefer WebP export if supported, otherwise fallback to PNG
+          let imgElement: HTMLImageElement | undefined = undefined;
+          let format: 'webp' | 'png' = 'webp';
+
+          try {
+            if (typeof snapdom === 'function') {
+              const captureRes = await snapdom(element as any, { scale: 1, embedFonts: false });
+              if (captureRes && typeof captureRes.toWebp === 'function') {
+                imgElement = await captureRes.toWebp();
+              } else if (captureRes && typeof captureRes.toPng === 'function') {
+                imgElement = await captureRes.toPng();
+                format = 'png';
+              } else if (captureRes?.url) {
+                return {
+                  ok: true,
+                  dataUrl: captureRes.url,
+                  format: 'webp' as const,
+                  width,
+                  height,
+                };
+              }
+            } else if ((snapdom as any)?.toWebp) {
+              imgElement = await (snapdom as any).toWebp(element, {
+                scale: 1,
+                embedFonts: false,
+              });
+            } else if ((snapdom as any)?.toPng) {
+              imgElement = await (snapdom as any).toPng(element, {
+                scale: 1,
+                embedFonts: false,
+              });
+              format = 'png';
+            }
+          } catch {
+            // Fall through to fallback
+          }
+
+          if (imgElement && imgElement.src) {
+            return {
+              ok: true,
+              dataUrl: imgElement.src,
+              format: imgElement.src.startsWith('data:image/webp') ? ('webp' as const) : format,
+              width: imgElement.naturalWidth || width,
+              height: imgElement.naturalHeight || height,
+            };
+          }
+        } catch (snapErr: any) {
+          const errMsg = String(snapErr?.message || snapErr);
+          if (errMsg.includes('CORS') || errMsg.includes('SecurityError') || errMsg.includes('tainted')) {
+            return { ok: false, reason: 'CROSS_ORIGIN_RESOURCE' };
+          }
+          // Fallback to minimal canvas capture below
+        }
+
+        // Fallback: minimal inline SVG ForeignObject capture
+        return await this.captureWithSvgFallback(element, width, height);
+      })();
+
+      // 3 second timeout protection
+      const timeoutPromise = new Promise<ScreenshotResult>((resolve) => {
+        setTimeout(() => resolve({ ok: false, reason: 'CAPTURE_TIMEOUT' }), 3000);
+      });
+
+      return await Promise.race([capturePromise, timeoutPromise]);
+    } catch (err: any) {
+      return { ok: false, reason: err?.message || 'CAPTURE_EXCEPTION' };
+    }
+  }
+
+  private async captureWithSvgFallback(
+    element: HTMLElement | Element,
+    width: number,
+    height: number
+  ): Promise<ScreenshotResult> {
+    try {
+      const clone = element.cloneNode(true) as HTMLElement;
+      const computed = window.getComputedStyle(element);
+      let cssText = '';
+      for (let i = 0; i < computed.length; i++) {
+        const prop = computed[i];
+        cssText += `${prop}:${computed.getPropertyValue(prop)};`;
+      }
+      clone.style.cssText = cssText;
+      clone.style.margin = '0';
+      clone.style.position = 'static';
+
+      const svg = `
+        <svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+          <foreignObject width="100%" height="100%">
+            <div xmlns="http://www.w3.org/1999/xhtml" style="width:${width}px;height:${height}px;">
+              ${clone.outerHTML}
+            </div>
+          </foreignObject>
+        </svg>
+      `.trim();
+
+      const svgBlob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+      const url = URL.createObjectURL(svgBlob);
+
+      return await new Promise<ScreenshotResult>((resolve) => {
+        const img = new Image();
+        img.onload = () => {
+          try {
+            const canvas = document.createElement('canvas');
+            canvas.width = width;
+            canvas.height = height;
+            const ctx = canvas.getContext('2d');
+            if (!ctx) {
+              URL.revokeObjectURL(url);
+              resolve({ ok: false, reason: 'CANVAS_CONTEXT_UNAVAILABLE' });
+              return;
+            }
+
+            ctx.drawImage(img, 0, 0);
+            URL.revokeObjectURL(url);
+
+            let dataUrl: string;
+            try {
+              dataUrl = canvas.toDataURL('image/webp', 0.85);
+            } catch {
+              dataUrl = canvas.toDataURL('image/png');
+            }
+
+            resolve({
+              ok: true,
+              dataUrl,
+              format: dataUrl.startsWith('data:image/webp') ? 'webp' : 'png',
+              width,
+              height,
+            });
+          } catch (e: any) {
+            URL.revokeObjectURL(url);
+            if (e?.name === 'SecurityError' || String(e).includes('tainted')) {
+              resolve({ ok: false, reason: 'CROSS_ORIGIN_RESOURCE' });
+            } else {
+              resolve({ ok: false, reason: e?.message || 'CANVAS_EXPORT_FAILED' });
+            }
+          }
+        };
+
+        img.onerror = () => {
+          URL.revokeObjectURL(url);
+          resolve({ ok: false, reason: 'IMAGE_LOAD_FAILED' });
+        };
+
+        img.src = url;
+      });
+    } catch (e: any) {
+      return { ok: false, reason: e?.message || 'FALLBACK_CAPTURE_FAILED' };
+    }
+  }
+}

package/packages/client/src/screenshot/driver.ts

@@ -0,0 +1,14 @@
+export interface ScreenshotResult {
+  ok: boolean;
+  dataUrl?: string;
+  format?: 'webp' | 'png' | 'jpeg';
+  width?: number;
+  height?: number;
+  reason?: string;
+}
+
+export interface ScreenshotDriver {
+  name: string;
+  captureElement(element: HTMLElement | Element): Promise<ScreenshotResult>;
+  captureSelector(selector: string): Promise<ScreenshotResult>;
+}

package/packages/client/src/transport/websocket.ts

@@ -0,0 +1,179 @@
+import type { HelloMessage, ClientCommand, CommandResponse } from '../../../core/src/index.js';
+import type { ClientCommandHandler } from '../commands/handler.js';
+
+export interface TransportOptions {
+  url: string;
+  projectId?: string;
+  debug?: boolean;
+}
+
+export class WebSocketTransport {
+  private wsUrl: string;
+  private projectId?: string;
+  private debug: boolean;
+  private ws: WebSocket | null = null;
+  private sessionId: string | null = null;
+  private queue: string[] = [];
+  private maxQueueSize = 50;
+  private reconnectAttempts = 0;
+  private maxReconnectDelay = 10000;
+  private reconnectTimer: any = null;
+  private commandHandler?: ClientCommandHandler;
+  private isDestroyed = false;
+
+  constructor(options: TransportOptions) {
+    this.wsUrl = options.url || 'ws://127.0.0.1:7331';
+    this.projectId = options.projectId;
+    this.debug = !!options.debug;
+  }
+
+  public setCommandHandler(handler: ClientCommandHandler): void {
+    this.commandHandler = handler;
+  }
+
+  public getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  public isConnected(): boolean {
+    return this.ws !== null && this.ws.readyState === (typeof WebSocket !== 'undefined' ? WebSocket.OPEN : 1);
+  }
+
+  public connect(): void {
+    if (this.isDestroyed || typeof WebSocket === 'undefined') return;
+    if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+      return;
+    }
+
+    try {
+      this.ws = new WebSocket(this.wsUrl);
+
+      this.ws.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.sendHello();
+        this.flushQueue();
+      };
+
+      this.ws.onmessage = async (event: MessageEvent) => {
+        try {
+          const raw = typeof event.data === 'string' ? event.data : '';
+          if (!raw) return;
+          const msg = JSON.parse(raw);
+
+          if (msg.type === 'hello_ack') {
+            this.sessionId = msg.sessionId;
+            if (this.debug) {
+              console.log('[BrowserTrack] Connected, session ID:', this.sessionId);
+            }
+            return;
+          }
+
+          if (msg.type === 'command' && this.commandHandler) {
+            const command: ClientCommand = msg.command;
+            const res: CommandResponse = await this.commandHandler.executeCommand(command);
+            this.send({
+              type: 'command_response',
+              sessionId: this.sessionId,
+              response: res,
+            });
+          }
+        } catch {
+          // Defensive
+        }
+      };
+
+      this.ws.onerror = () => {
+        // Silent fail if daemon is offline
+      };
+
+      this.ws.onclose = () => {
+        this.ws = null;
+        this.scheduleReconnect();
+      };
+    } catch {
+      this.scheduleReconnect();
+    }
+  }
+
+  public send(payload: any): void {
+    const raw = JSON.stringify(payload);
+    if (this.isConnected()) {
+      try {
+        this.ws!.send(raw);
+      } catch {
+        this.enqueue(raw);
+      }
+    } else {
+      this.enqueue(raw);
+    }
+  }
+
+  private enqueue(raw: string): void {
+    if (this.queue.length >= this.maxQueueSize) {
+      this.queue.shift();
+    }
+    this.queue.push(raw);
+  }
+
+  private flushQueue(): void {
+    if (!this.isConnected()) return;
+    while (this.queue.length > 0) {
+      const item = this.queue.shift();
+      if (item) {
+        try {
+          this.ws!.send(item);
+        } catch {
+          this.queue.unshift(item);
+          break;
+        }
+      }
+    }
+  }
+
+  private sendHello(): void {
+    if (typeof window === 'undefined') return;
+
+    const hello: HelloMessage = {
+      type: 'hello',
+      origin: window.location.origin,
+      url: window.location.href,
+      title: document.title,
+      userAgent: navigator.userAgent,
+      timestamp: Date.now(),
+      projectId: this.projectId,
+    };
+
+    try {
+      this.ws!.send(JSON.stringify(hello));
+    } catch {
+      // Defensive
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.isDestroyed || this.reconnectTimer) return;
+
+    this.reconnectAttempts++;
+    const delay = Math.min(1000 * Math.pow(1.5, this.reconnectAttempts), this.maxReconnectDelay);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+
+  public destroy(): void {
+    this.isDestroyed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+    }
+    this.queue = [];
+  }
+}

package/packages/client/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

package/packages/core/dist/index.d.ts

@@ -0,0 +1,317 @@
+type EventType = 'runtime_error' | 'unhandled_rejection' | 'console' | 'fetch' | 'xhr' | 'navigation' | 'interaction';
+type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
+interface ElementSummary {
+    selector: string;
+    tag: string;
+    id?: string;
+    classes?: string[];
+    attributes?: Record<string, string>;
+    outerHTML?: string;
+    innerText?: string;
+    boundingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    visible: boolean;
+}
+interface Breadcrumb {
+    id?: string;
+    type: 'navigation' | 'click' | 'submit' | 'fetch' | 'xhr' | 'console' | 'error';
+    category?: string;
+    message: string;
+    timestamp: number;
+    level?: 'info' | 'warn' | 'error';
+    data?: Record<string, any>;
+    element?: ElementSummary;
+}
+interface NetworkEvent {
+    id?: string;
+    url: string;
+    method: string;
+    status?: number;
+    statusText?: string;
+    durationMs: number;
+    error?: string;
+    aborted?: boolean;
+    timestamp: number;
+    requestHeaders?: Record<string, string>;
+}
+interface RuntimeErrorEvent {
+    message: string;
+    stack?: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    errorType: string;
+    timestamp: number;
+}
+interface ConsoleEvent {
+    level: ConsoleLevel;
+    message: string;
+    args?: any[];
+    stack?: string;
+    timestamp: number;
+}
+interface NavigationEvent {
+    from?: string;
+    to: string;
+    type: 'pushState' | 'replaceState' | 'popstate' | 'hashchange' | 'initial';
+    timestamp: number;
+}
+interface HelloMessage {
+    type: 'hello';
+    origin: string;
+    url: string;
+    title: string;
+    userAgent: string;
+    timestamp: number;
+    projectId?: string;
+}
+interface ClientEventMessage {
+    type: 'event';
+    sessionId: string;
+    eventType: EventType;
+    payload: RuntimeErrorEvent | ConsoleEvent | NetworkEvent | NavigationEvent | Breadcrumb;
+    breadcrumbs?: Breadcrumb[];
+    lastElement?: ElementSummary;
+    route?: string;
+    url: string;
+    title?: string;
+    timestamp: number;
+}
+
+type IncidentStatus = 'OPEN' | 'FIX_ATTEMPTED' | 'VERIFYING' | 'VERIFIED' | 'FAILED' | 'INCONCLUSIVE';
+type IncidentSeverity = 'error' | 'warn' | 'fatal';
+interface IncidentSource {
+    file: string;
+    line: number;
+    column?: number;
+}
+interface Incident {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    type: string;
+    severity: IncidentSeverity;
+    message: string;
+    source: IncidentSource;
+    fingerprint: string;
+    route: string;
+    firstSeen: string;
+    lastSeen: string;
+    occurrences: number;
+    status: IncidentStatus;
+    stack?: string;
+    breadcrumbs: Breadcrumb[];
+    networkFailures: NetworkEvent[];
+    lastElement?: ElementSummary;
+    screenshots?: {
+        error?: string;
+        before?: string;
+        after?: string;
+    };
+}
+interface IncidentOccurrence {
+    id: string;
+    incidentId: string;
+    sessionId: string;
+    timestamp: string;
+    route: string;
+    url: string;
+    stack?: string;
+    breadcrumbs: Breadcrumb[];
+    lastElement?: ElementSummary;
+}
+
+type CommandType = 'reload' | 'navigate' | 'get_page_state' | 'query_element' | 'capture_element';
+interface ClientCommand<T = any> {
+    id: string;
+    type: CommandType;
+    params?: T;
+}
+interface ReloadParams {
+    force?: boolean;
+}
+interface NavigateParams {
+    url: string;
+}
+interface QueryElementParams {
+    selector: string;
+}
+interface CaptureElementParams {
+    selector?: string;
+}
+interface QueryElementResult {
+    exists: boolean;
+    visible?: boolean;
+    tag?: string;
+    id?: string;
+    classes?: string[];
+    boundingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    innerText?: string;
+    outerHTML?: string;
+}
+interface PageStateResult {
+    url: string;
+    route: string;
+    title: string;
+    readyState: string;
+    activeElement?: ElementSummary;
+}
+interface CaptureElementResult {
+    dataUrl?: string;
+    format?: string;
+    width?: number;
+    height?: number;
+}
+interface CommandResponse<T = any> {
+    id: string;
+    ok: boolean;
+    result?: T;
+    error?: string;
+    reason?: string;
+}
+
+type ProbeType = 'element_exists' | 'element_visible' | 'text_contains' | 'route_is' | 'network_request_succeeded' | 'no_incident';
+interface VerificationProbe {
+    type: ProbeType;
+    selector?: string;
+    text?: string;
+    route?: string;
+    fingerprint?: string;
+    urlPattern?: string;
+    timeoutMs?: number;
+}
+interface VerificationRecipe {
+    route?: string;
+    targetSelector?: string;
+    expect?: VerificationProbe[];
+    observationWindowMs?: number;
+}
+interface ProbeResult {
+    type: ProbeType;
+    passed: boolean;
+    details?: string;
+}
+interface VerificationResult {
+    incidentId: string;
+    status: IncidentStatus;
+    checks: ProbeResult[];
+    screenshots?: {
+        before?: string;
+        after?: string;
+    };
+    timestamp: string;
+    message?: string;
+}
+
+interface Project {
+    id: string;
+    name: string;
+    origin: string;
+    path?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Session {
+    id: string;
+    projectId: string;
+    origin: string;
+    url: string;
+    title: string;
+    userAgent: string;
+    connectedAt: string;
+    lastSeenAt: string;
+    active: boolean;
+}
+
+/**
+ * Error fingerprinting and normalization utilities
+ */
+interface FingerprintInput {
+    type: string;
+    message: string;
+    sourceFile?: string;
+    line?: number;
+    column?: number;
+    stack?: string;
+}
+/**
+ * Normalizes error messages by stripping dynamic content like UUIDs, timestamps,
+ * hex addresses, and file timestamps.
+ */
+declare function normalizeErrorMessage(message: string): string;
+/**
+ * Normalizes source filenames by removing origin and cache-busting query strings.
+ */
+declare function normalizeSourceFile(filename?: string): string;
+/**
+ * Extracts source location from stack if not explicitly provided
+ */
+declare function extractSourceFromStack(stack?: string): {
+    file: string;
+    line: number;
+    column?: number;
+} | null;
+/**
+ * Computes a deterministic fingerprint for an error
+ */
+declare function computeFingerprint(input: FingerprintInput): string;
+
+/**
+ * Security and Redaction Utilities
+ */
+declare const SENSITIVE_KEY_PATTERNS: RegExp[];
+declare const SENSITIVE_QUERY_PARAMS: string[];
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+/**
+ * Checks if a property name matches any sensitive pattern
+ */
+declare function isSensitiveKey(key: string): boolean;
+/**
+ * Redacts sensitive query parameters from a URL string
+ */
+declare function redactUrl(rawUrl: string): string;
+/**
+ * Redacts sensitive HTTP headers
+ */
+declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Deeply redacts sensitive keys from an object or array
+ */
+declare function redactSensitiveData<T = any>(data: T, maxDepth?: number, currentDepth?: number): T;
+
+/**
+ * Semantic element selector generation and inspection
+ */
+interface SelectorOptions {
+    maxClasses?: number;
+    maxOuterHTMLLength?: number;
+    maxInnerTextLength?: number;
+}
+/**
+ * Builds a clean, human-readable semantic selector for a DOM element.
+ * Prioritizes data-testid/data-test, id, semantic tag + specific class, or concise parent path.
+ */
+declare function getSemanticSelector(element: HTMLElement | Element, options?: SelectorOptions): string;
+/**
+ * Truncates string to specified max length with ellipsis
+ */
+declare function truncate(str: string | undefined | null, maxLength?: number): string;
+
+export { type Breadcrumb, type CaptureElementParams, type CaptureElementResult, type ClientCommand, type ClientEventMessage, type CommandResponse, type CommandType, type ConsoleEvent, type ConsoleLevel, type ElementSummary, type EventType, type FingerprintInput, type HelloMessage, type Incident, type IncidentOccurrence, type IncidentSeverity, type IncidentSource, type IncidentStatus, type NavigateParams, type NavigationEvent, type NetworkEvent, type PageStateResult, type ProbeResult, type ProbeType, type Project, type QueryElementParams, type QueryElementResult, REDACTED_PLACEHOLDER, type ReloadParams, type RuntimeErrorEvent, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, type Session, type VerificationProbe, type VerificationRecipe, type VerificationResult, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate };