browsertrack 0.0.1 → 0.1.1

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,194 @@
+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 messageListeners: ((msg: any) => void)[] = [];
+  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 onMessage(listener: (msg: any) => void): () => void {
+    this.messageListeners.push(listener);
+    return () => {
+      this.messageListeners = this.messageListeners.filter((l) => l !== listener);
+    };
+  }
+
+  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);
+
+          // Dispatch to subscribers (e.g. NoteInspector for notes_sync)
+          for (const listener of this.messageListeners) {
+            try {
+              listener(msg);
+            } catch {}
+          }
+
+          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/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@browserdiag/core",
+  "version": "0.1.0",
+  "description": "Core types, schemas, fingerprinting, and utilities for browserdiag",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@visulima/redact": "^4.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}

package/packages/core/src/fingerprint.ts

@@ -0,0 +1,120 @@
+/**
+ * Error fingerprinting and normalization utilities
+ */
+
+export 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.
+ */
+export function normalizeErrorMessage(message: string): string {
+  if (!message) return 'unknown_error';
+
+  return message
+    // Normalize string representation
+    .trim()
+    // Replace hex addresses (e.g. 0x7ffee4b2a8)
+    .replace(/0x[0-9a-fA-F]+/g, '0x<HEX>')
+    // Replace UUIDs
+    .replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '<UUID>')
+    // Replace timestamp query params like ?t=1719283748 or ?v=1.2.3
+    .replace(/\?[tv]=[\w.-]+/g, '')
+    // Replace ISO timestamps
+    .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?/g, '<TIMESTAMP>')
+    // Replace numbers in quotes/brackets if likely IDs (e.g., user "12345")
+    .replace(/#\d+/g, '#<ID>')
+    // Normalize whitespaces
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * Normalizes source filenames by removing origin and cache-busting query strings.
+ */
+export function normalizeSourceFile(filename?: string): string {
+  if (!filename) return 'unknown_source';
+
+  let cleaned = filename.trim();
+  // Strip protocol and origin if present (e.g. http://localhost:5173/src/App.tsx?t=123)
+  try {
+    if (cleaned.startsWith('http://') || cleaned.startsWith('https://')) {
+      const url = new URL(cleaned);
+      cleaned = url.pathname;
+    }
+  } catch {
+    // fallback string manipulation
+    cleaned = cleaned.replace(/^https?:\/\/[^/]+/, '');
+  }
+
+  // Remove query parameters
+  cleaned = cleaned.split('?')[0].split('#')[0];
+
+  // Normalize windows path separators
+  cleaned = cleaned.replace(/\\/g, '/');
+
+  return cleaned || 'unknown_source';
+}
+
+/**
+ * Extracts source location from stack if not explicitly provided
+ */
+export function extractSourceFromStack(stack?: string): { file: string; line: number; column?: number } | null {
+  if (!stack) return null;
+
+  const lines = stack.split('\n');
+  for (const line of lines) {
+    // Match standard stack line: at functionName (http://localhost:5173/src/main.tsx:15:3) or at http://...:15:3
+    const match = line.match(/(?:at\s+(?:.*?\s+\()?)?(https?:\/\/[^\s)]+|file:\/\/[^\s)]+|\/[^\s)]+):(\d+):(\d+)\)?/);
+    if (match) {
+      return {
+        file: normalizeSourceFile(match[1]),
+        line: parseInt(match[2], 10),
+        column: parseInt(match[3], 10),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Fast synchronous djb2-based hash for universal client/server runtime
+ */
+function djb2Hash(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i);
+  }
+  // Convert to unsigned 32-bit hex string
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/**
+ * Computes a deterministic fingerprint for an error
+ */
+export function computeFingerprint(input: FingerprintInput): string {
+  const normType = (input.type || 'Error').trim().toLowerCase();
+  const normMsg = normalizeErrorMessage(input.message);
+
+  let sourceFile = normalizeSourceFile(input.sourceFile);
+  let line = input.line || 0;
+
+  if ((sourceFile === 'unknown_source' || line === 0) && input.stack) {
+    const extracted = extractSourceFromStack(input.stack);
+    if (extracted) {
+      sourceFile = extracted.file;
+      line = extracted.line;
+    }
+  }
+
+  const rawKey = `${normType}::${normMsg}::${sourceFile}::${line}`;
+  const hash = djb2Hash(rawKey);
+
+  return `fp_${hash}`;
+}

package/packages/core/src/index.ts

@@ -0,0 +1,9 @@
+export * from './types/events.js';
+export * from './types/incidents.js';
+export * from './types/commands.js';
+export * from './types/probes.js';
+export * from './types/projects.js';
+export * from './types/notes.js';
+export * from './fingerprint.js';
+export * from './redaction.js';
+export * from './selector.js';