browsertrack 0.2.0 → 0.2.2

package/packages/client/src/source/resolver.ts

@@ -0,0 +1,278 @@
+import type { ComponentSourceInfo } from '../../../core/src/index.js';
+
+/**
+ * Resolves framework component metadata, source file paths, line numbers,
+ * and component hierarchy directly from a live DOM element.
+ * Supports React (Fiber), Vue 2 & 3, Svelte, Custom Elements, and standard data attributes.
+ */
+export function resolveComponentSource(el: HTMLElement): ComponentSourceInfo | undefined {
+  if (!el || typeof el !== 'object') return undefined;
+
+  // 1. Try React Fiber Resolution
+  const reactInfo = resolveReactComponent(el);
+  if (reactInfo) return reactInfo;
+
+  // 2. Try Vue (Vue 3 / Vue 2) Resolution
+  const vueInfo = resolveVueComponent(el);
+  if (vueInfo) return vueInfo;
+
+  // 3. Try Svelte Resolution
+  const svelteInfo = resolveSvelteComponent(el);
+  if (svelteInfo) return svelteInfo;
+
+  // 4. Try Web Component / Custom Element
+  if (el.tagName && el.tagName.includes('-')) {
+    return {
+      framework: 'web-component',
+      componentName: el.tagName.toLowerCase(),
+      hierarchy: [el.tagName.toLowerCase()],
+    };
+  }
+
+  // 5. Try Data Attribute Annotations (e.g. data-component, data-source-file)
+  const attrInfo = resolveDataAttributeComponent(el);
+  if (attrInfo) return attrInfo;
+
+  return undefined;
+}
+
+/**
+ * Extracts React Fiber debug source, owner, and hierarchy
+ */
+function resolveReactComponent(el: HTMLElement): ComponentSourceInfo | undefined {
+  try {
+    const fiberKey = Object.keys(el).find(
+      (key) => key.startsWith('__reactFiber$') || key.startsWith('__reactInternalInstance$')
+    );
+    if (!fiberKey) return undefined;
+
+    const hostFiber = (el as any)[fiberKey];
+    if (!hostFiber) return undefined;
+
+    let sourceFile: string | undefined;
+    let sourceLine: number | undefined;
+    let sourceColumn: number | undefined;
+    let componentName: string | undefined;
+    const hierarchy: string[] = [];
+    let props: Record<string, any> | undefined;
+
+    // Check host fiber debugSource first (often populated by JSX transform)
+    if (hostFiber._debugSource) {
+      sourceFile = hostFiber._debugSource.fileName;
+      sourceLine = hostFiber._debugSource.lineNumber;
+      sourceColumn = hostFiber._debugSource.columnNumber;
+    }
+
+    // Check _debugOwner if available
+    if (hostFiber._debugOwner) {
+      const ownerType = hostFiber._debugOwner.type;
+      componentName = getReactComponentName(ownerType);
+      if (!sourceFile && hostFiber._debugOwner._debugSource) {
+        sourceFile = hostFiber._debugOwner._debugSource.fileName;
+        sourceLine = hostFiber._debugOwner._debugSource.lineNumber;
+        sourceColumn = hostFiber._debugOwner._debugSource.columnNumber;
+      }
+    }
+
+    // Walk up fiber return tree to discover composite components and hierarchy
+    let curr = hostFiber;
+    let depth = 0;
+    while (curr && depth < 50) {
+      depth++;
+      const type = curr.type;
+      const name = getReactComponentName(type);
+
+      if (name && !name.startsWith('html:') && name !== 'Fragment') {
+        if (!componentName) {
+          componentName = name;
+        }
+        if (!hierarchy.includes(name)) {
+          hierarchy.unshift(name);
+        }
+
+        // Check if composite component has debug source
+        if (!sourceFile && curr._debugSource) {
+          sourceFile = curr._debugSource.fileName;
+          sourceLine = curr._debugSource.lineNumber;
+          sourceColumn = curr._debugSource.columnNumber;
+        }
+
+        // Capture safe props from the nearest custom component
+        if (!props && curr.memoizedProps && typeof curr.memoizedProps === 'object') {
+          props = sanitizeProps(curr.memoizedProps);
+        }
+      }
+
+      curr = curr.return;
+    }
+
+    if (!componentName && !sourceFile) {
+      return undefined;
+    }
+
+    return {
+      framework: 'react',
+      componentName,
+      sourceFile: normalizeFilePath(sourceFile),
+      sourceLine,
+      sourceColumn,
+      hierarchy: hierarchy.length > 0 ? hierarchy : componentName ? [componentName] : undefined,
+      props,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function getReactComponentName(type: any): string | undefined {
+  if (!type) return undefined;
+  if (typeof type === 'string') return undefined; // Host DOM tag (div, span, button)
+  if (type.displayName) return type.displayName;
+  if (type.name) return type.name;
+  if (type.render?.displayName) return type.render.displayName;
+  if (type.render?.name) return type.render.name;
+  return undefined;
+}
+
+/**
+ * Extracts Vue 3 and Vue 2 component instances and file paths
+ */
+function resolveVueComponent(el: HTMLElement): ComponentSourceInfo | undefined {
+  try {
+    // Vue 3
+    const vueParent = (el as any).__vueParentComponent || (el as any).__vnode?.ctx;
+    if (vueParent) {
+      const type = vueParent.type || {};
+      const componentName = type.name || type.__name || type.displayName || 'AnonymousComponent';
+      const sourceFile = type.__file;
+      const hierarchy: string[] = [];
+
+      let curr = vueParent;
+      let depth = 0;
+      while (curr && depth < 50) {
+        depth++;
+        const cType = curr.type || {};
+        const cName = cType.name || cType.__name || cType.displayName;
+        if (cName && !hierarchy.includes(cName)) {
+          hierarchy.unshift(cName);
+        }
+        curr = curr.parent;
+      }
+
+      return {
+        framework: 'vue',
+        componentName,
+        sourceFile: normalizeFilePath(sourceFile),
+        hierarchy: hierarchy.length > 0 ? hierarchy : [componentName],
+        props: vueParent.props ? sanitizeProps(vueParent.props) : undefined,
+      };
+    }
+
+    // Vue 2
+    const vue2Instance = (el as any).__vue__;
+    if (vue2Instance) {
+      const options = vue2Instance.$options || {};
+      const componentName = options.name || options._componentTag || 'VueComponent';
+      const sourceFile = options.__file;
+
+      return {
+        framework: 'vue',
+        componentName,
+        sourceFile: normalizeFilePath(sourceFile),
+        hierarchy: [componentName],
+        props: vue2Instance.$props ? sanitizeProps(vue2Instance.$props) : undefined,
+      };
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extracts Svelte __svelte_meta debug locations
+ */
+function resolveSvelteComponent(el: HTMLElement): ComponentSourceInfo | undefined {
+  try {
+    let curr: HTMLElement | null = el;
+    let depth = 0;
+    while (curr && depth < 50) {
+      depth++;
+      const meta = (curr as any).__svelte_meta;
+      if (meta && meta.loc) {
+        return {
+          framework: 'svelte',
+          sourceFile: normalizeFilePath(meta.loc.file),
+          sourceLine: meta.loc.line,
+          sourceColumn: meta.loc.column,
+          componentName: meta.loc.file ? getBaseNameWithoutExt(meta.loc.file) : undefined,
+          hierarchy: meta.loc.file ? [getBaseNameWithoutExt(meta.loc.file)] : undefined,
+        };
+      }
+      curr = curr.parentElement;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolves components from standard data attributes (e.g. data-component="UserCard")
+ */
+function resolveDataAttributeComponent(el: HTMLElement): ComponentSourceInfo | undefined {
+  try {
+    const compEl = el.closest('[data-component], [data-component-name], [data-source-file]');
+    if (!compEl) return undefined;
+
+    const componentName =
+      compEl.getAttribute('data-component') || compEl.getAttribute('data-component-name') || undefined;
+    const sourceFile = compEl.getAttribute('data-source-file') || undefined;
+    const lineAttr = compEl.getAttribute('data-source-line');
+    const sourceLine = lineAttr ? parseInt(lineAttr, 10) : undefined;
+
+    if (!componentName && !sourceFile) return undefined;
+
+    return {
+      framework: 'vanilla',
+      componentName,
+      sourceFile: normalizeFilePath(sourceFile),
+      sourceLine: isNaN(sourceLine as number) ? undefined : sourceLine,
+      hierarchy: componentName ? [componentName] : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeFilePath(filePath?: string): string | undefined {
+  if (!filePath) return undefined;
+  // Strip query strings or vite bundle hashes (e.g. /App.tsx?t=123)
+  const cleaned = filePath.split('?')[0];
+  return cleaned;
+}
+
+function getBaseNameWithoutExt(filePath: string): string {
+  const parts = filePath.split('/');
+  const last = parts[parts.length - 1] || filePath;
+  return last.split('.')[0] || last;
+}
+
+function sanitizeProps(props: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (key.startsWith('__') || typeof value === 'function') continue;
+
+    if (value === null || value === undefined) {
+      result[key] = value;
+    } else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      result[key] = value;
+    } else if (Array.isArray(value)) {
+      result[key] = `Array(${value.length})`;
+    } else if (typeof value === 'object') {
+      result[key] = '[Object]';
+    }
+  }
+  return result;
+}

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

@@ -1,4 +1,5 @@
 import type { HelloMessage, ClientCommand, CommandResponse } from '../../../core/src/index.js';
+import { safeJsonStringify } from '../../../core/src/index.js';
 import type { ClientCommandHandler } from '../commands/handler.js';
 
 export interface TransportOptions {
@@ -111,15 +112,19 @@ export class WebSocketTransport {
   }
 
   public send(payload: any): void {
-    const raw = JSON.stringify(payload);
-    if (this.isConnected()) {
-      try {
-        this.ws!.send(raw);
-      } catch {
+    try {
+      const raw = safeJsonStringify(payload);
+      if (this.isConnected()) {
+        try {
+          this.ws!.send(raw);
+        } catch {
+          this.enqueue(raw);
+        }
+      } else {
         this.enqueue(raw);
       }
-    } else {
-      this.enqueue(raw);
+    } catch {
+      // Defensive: never let payload serialization crash caller
     }
   }
 
@@ -148,18 +153,18 @@ export class WebSocketTransport {
   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));
+      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,
+      };
+
+      this.ws!.send(safeJsonStringify(hello));
     } catch {
       // Defensive
     }

package/packages/core/src/index.ts

@@ -7,3 +7,4 @@ export * from './types/notes.js';
 export * from './fingerprint.js';
 export * from './redaction.js';
 export * from './selector.js';
+export * from './safety.js';

package/packages/core/src/safety.ts

@@ -0,0 +1,86 @@
+/**
+ * BrowserTrack Safety & Error-Resilience Utilities
+ * Provides bulletproof try/catch wrappers, circular-safe JSON serialization, and defensive helpers.
+ */
+
+/**
+ * Safely parses a JSON string with fallback. Never throws.
+ */
+export function safeJsonParse<T>(raw: any, fallback: T): T {
+  if (raw === null || raw === undefined) return fallback;
+  if (typeof raw !== 'string') return typeof raw === 'object' ? (raw as T) : fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Safely serializes an object to JSON, handling circular references and non-serializable values.
+ * Never throws "TypeError: Converting circular structure to JSON".
+ */
+export function safeJsonStringify(val: any, fallback = '{}'): string {
+  if (val === undefined) return fallback;
+  try {
+    const seen = new WeakSet();
+    return JSON.stringify(val, (key, value) => {
+      if (typeof value === 'object' && value !== null) {
+        if (seen.has(value)) {
+          return '[Circular]';
+        }
+        seen.add(value);
+      }
+      if (typeof value === 'bigint') {
+        return value.toString();
+      }
+      return value;
+    });
+  } catch {
+    try {
+      return JSON.stringify(String(val));
+    } catch {
+      return fallback;
+    }
+  }
+}
+
+/**
+ * Executes a synchronous function within an isolated try/catch block.
+ * Returns the function result, or fallback if an exception was thrown.
+ */
+export function safeExecute<T>(fn: () => T, fallback: T, onError?: (err: any) => void): T {
+  try {
+    return fn();
+  } catch (err: any) {
+    if (onError) {
+      try {
+        onError(err);
+      } catch {}
+    }
+    return fallback;
+  }
+}
+
+/**
+ * Executes an asynchronous promise or async function safely without unhandled rejection.
+ */
+export async function safeAsync<T>(
+  action: Promise<T> | (() => Promise<T>),
+  fallback: T,
+  onError?: (err: any) => void
+): Promise<T> {
+  try {
+    if (typeof action === 'function') {
+      return await action();
+    }
+    return await action;
+  } catch (err: any) {
+    if (onError) {
+      try {
+        onError(err);
+      } catch {}
+    }
+    return fallback;
+  }
+}

package/packages/core/src/types/events.ts

@@ -1,3 +1,5 @@
+import type { ComponentSourceInfo } from './notes.js';
+
 export type EventType =
   | 'runtime_error'
   | 'unhandled_rejection'
@@ -17,6 +19,7 @@ export interface ElementSummary {
   attributes?: Record<string, string>;
   outerHTML?: string;
   innerText?: string;
+  componentSource?: ComponentSourceInfo;
   boundingRect?: {
     x: number;
     y: number;

package/packages/core/src/types/notes.ts

@@ -39,12 +39,23 @@ export interface NoteTarget {
   confidence?: 'high' | 'medium' | 'low';
 }
 
+export interface ComponentSourceInfo {
+  framework?: 'react' | 'vue' | 'svelte' | 'web-component' | 'vanilla';
+  componentName?: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  sourceColumn?: number;
+  hierarchy?: string[];
+  props?: Record<string, any>;
+}
+
 export interface ElementContext {
   selector: string;
   tag: string;
   attributes?: Record<string, string>;
   outerHTML?: string;
   innerText?: string;
+  componentSource?: ComponentSourceInfo;
   parent?: {
     selector: string;
     tag: string;

package/packages/daemon/src/server/daemon.ts

@@ -40,7 +40,13 @@ export class BrowserTrackDaemon {
   public async start(): Promise<void> {
     if (this.isRunning) return;
 
-    const httpHandler = createHttpHandler(this.db, this.sessionManager, this.config.screenshotsDir);
+    const httpHandler = createHttpHandler(
+      this.db,
+      this.sessionManager,
+      this.config.screenshotsDir,
+      this.verificationEngine,
+      this.noteVerificationEngine
+    );
     this.httpServer = http.createServer(httpHandler);
 
     this.wss = new WebSocketServer({ server: this.httpServer });

package/packages/daemon/src/server/http.ts

@@ -4,11 +4,59 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { StorageDB } from '../storage/db.js';
 import type { SessionManager } from '../session/manager.js';
+import type { VerificationEngine } from '../verification/engine.js';
+import type { NoteVerificationEngine } from '../notes/verification.js';
 
-export function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string) {
-  return (req: http.IncomingMessage, res: http.ServerResponse) => {
-    const parsedUrl = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
-    const pathname = parsedUrl.pathname;
+function readJsonBody(req: http.IncomingMessage, res: http.ServerResponse, maxSizeBytes = 10 * 1024 * 1024): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    let isTooLarge = false;
+
+    req.on('data', (chunk) => {
+      if (isTooLarge) return;
+      body += chunk;
+      if (body.length > maxSizeBytes) {
+        isTooLarge = true;
+        if (!res.headersSent) {
+          res.writeHead(413, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Payload too large' }));
+        }
+        req.destroy();
+        reject(new Error('Payload too large'));
+      }
+    });
+
+    req.on('end', () => {
+      if (isTooLarge) return;
+      try {
+        const parsed = body ? JSON.parse(body) : {};
+        resolve(parsed);
+      } catch (err: any) {
+        if (!res.headersSent) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Malformed JSON payload' }));
+        }
+        reject(err);
+      }
+    });
+
+    req.on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+export function createHttpHandler(
+  db: StorageDB,
+  sessionManager: SessionManager,
+  baseScreenshotsDir: string,
+  verificationEngine?: VerificationEngine,
+  noteVerificationEngine?: NoteVerificationEngine
+) {
+  return async (req: http.IncomingMessage, res: http.ServerResponse) => {
+    try {
+      const parsedUrl = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+      const pathname = parsedUrl.pathname;
 
     // CORS headers for local development access
     res.setHeader('Access-Control-Allow-Origin', '*');
@@ -158,8 +206,80 @@ export function createHttpHandler(db: StorageDB, sessionManager: SessionManager,
       return;
     }
 
+    // 10. API - Dispatch Live Command to Browser Session
+    if (pathname === '/api/command' && req.method === 'POST') {
+      try {
+        const data = await readJsonBody(req, res);
+        const sessionId = data.sessionId || sessionManager.getAnyActiveSession()?.id;
+        if (!sessionId) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'No active browser session connected' }));
+          return;
+        }
+        const cmdRes = await sessionManager.sendCommand(sessionId, data.command, data.timeoutMs || 5000);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(cmdRes));
+      } catch (err: any) {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err?.message || String(err) }));
+        }
+      }
+      return;
+    }
+
+    // 11. API - Verify Incident
+    if (pathname === '/api/verify/incident' && req.method === 'POST') {
+      try {
+        if (!verificationEngine) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Verification engine not attached to daemon' }));
+          return;
+        }
+        const data = await readJsonBody(req, res);
+        const result = await verificationEngine.verifyIncident(data.incidentId, data.options);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, result }));
+      } catch (err: any) {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err?.message || String(err) }));
+        }
+      }
+      return;
+    }
+
+    // 12. API - Verify Note
+    if (pathname === '/api/verify/note' && req.method === 'POST') {
+      try {
+        if (!noteVerificationEngine) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Note verification engine not attached to daemon' }));
+          return;
+        }
+        const data = await readJsonBody(req, res);
+        const result = await noteVerificationEngine.verifyNote(data.noteId, data.options);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, result }));
+      } catch (err: any) {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err?.message || String(err) }));
+        }
+      }
+      return;
+    }
+
     // Not found
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ ok: false, error: 'Not found' }));
-  };
+  } catch (err: any) {
+    if (!res.headersSent) {
+      try {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err?.message || 'Internal Server Error' }));
+      } catch {}
+    }
+  }
+};
 }