browsertrack 0.2.1 → 0.2.3

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/selector.ts

@@ -6,23 +6,26 @@ export interface SelectorOptions {
   maxClasses?: number;
   maxOuterHTMLLength?: number;
   maxInnerTextLength?: number;
+  maxParentDepth?: 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.
+ * Prioritizes data-testid/data-component, id, semantic tag + curated class, aria/role, or concise unique parent path.
  */
 export function getSemanticSelector(element: HTMLElement | Element, options: SelectorOptions = {}): string {
   if (!element || !element.tagName) return 'unknown';
 
   const maxClasses = options.maxClasses ?? 2;
+  const maxParentDepth = options.maxParentDepth ?? 3;
 
-  // 1. Check for standard test attributes
+  // 1. Check for standard test or component attributes
   const testId =
     element.getAttribute('data-testid') ||
     element.getAttribute('data-test') ||
     element.getAttribute('data-cy') ||
-    element.getAttribute('data-qa');
+    element.getAttribute('data-qa') ||
+    element.getAttribute('data-component');
 
   if (testId) {
     return `[data-testid="${testId}"]`;
@@ -34,21 +37,43 @@ export function getSemanticSelector(element: HTMLElement | Element, options: Sel
     return `#${id}`;
   }
 
-  // 3. Check for aria-label or name on buttons/inputs
+  const tag = element.tagName.toLowerCase();
+
+  // 3. Check for aria-label, role, title or name on interactive elements
   const ariaLabel = element.getAttribute('aria-label');
-  if (ariaLabel && ariaLabel.length < 30) {
-    return `${element.tagName.toLowerCase()}[aria-label="${ariaLabel}"]`;
+  if (ariaLabel && ariaLabel.length < 40) {
+    return `${tag}[aria-label="${ariaLabel}"]`;
+  }
+
+  const role = element.getAttribute('role');
+  if (role && !['presentation', 'none'].includes(role)) {
+    const roleSelector = `${tag}[role="${role}"]`;
+    if (tag === 'button' || tag === 'a' || tag === 'nav' || tag === 'dialog') {
+      return roleSelector;
+    }
   }
 
   const nameAttr = element.getAttribute('name');
   if (nameAttr) {
-    return `${element.tagName.toLowerCase()}[name="${nameAttr}"]`;
+    return `${tag}[name="${nameAttr}"]`;
+  }
+
+  const titleAttr = element.getAttribute('title');
+  if (titleAttr && titleAttr.length < 30) {
+    return `${tag}[title="${titleAttr}"]`;
   }
 
   // 4. Tag + curated classes
-  const tag = element.tagName.toLowerCase();
-  const classList = Array.from(element.classList || [])
-    .filter((c) => !c.startsWith('css-') && !c.startsWith('_') && !/^[a-z0-9]{5,}$/i.test(c)) // filter hashed utility classes
+  const rawClassList = Array.from(element.classList || []);
+  const classList = rawClassList
+    .filter(
+      (c) =>
+        !c.startsWith('css-') &&
+        !c.startsWith('_') &&
+        !/^[a-z0-9]{5,}$/i.test(c) && // filter dynamic hashed utility classes
+        !c.includes(':') && // Tailwind pseudo-class prefixes (hover:, md:, etc.)
+        !c.includes('[') // Tailwind arbitrary value classes
+    )
     .slice(0, maxClasses);
 
   if (classList.length > 0) {
@@ -56,17 +81,87 @@ export function getSemanticSelector(element: HTMLElement | Element, options: Sel
     return `${tag}${classStr}`;
   }
 
-  // 5. If generic element (div, span, p) without attributes, try parent context
-  if (element.parentElement && element.parentElement !== document.body && element.parentElement !== document.documentElement) {
-    const parentSelector = getSemanticSelector(element.parentElement, { maxClasses: 1 });
-    if (parentSelector && parentSelector !== 'unknown' && !parentSelector.includes('>')) {
-      return `${parentSelector} > ${tag}`;
+  // 5. If generic element (div, span, p, li) without attributes, try parent context & nth-of-type
+  const hasParent =
+    element.parentElement &&
+    (typeof document === 'undefined' ||
+      (element.parentElement !== document.body && element.parentElement !== document.documentElement));
+
+  if (hasParent) {
+    let suffix = '';
+    // Calculate nth-of-type if siblings of same tag exist
+    if (element.parentElement.children && element.parentElement.children.length > 1) {
+      const sameTagSiblings = Array.from(element.parentElement.children).filter(
+        (child: any) => child.tagName && child.tagName.toLowerCase() === tag
+      );
+      if (sameTagSiblings.length > 1) {
+        const index = sameTagSiblings.indexOf(element) + 1;
+        if (index > 0) {
+          suffix = `:nth-of-type(${index})`;
+        }
+      }
+    }
+
+    if (maxParentDepth > 0) {
+      const parentSelector = getSemanticSelector(element.parentElement, {
+        maxClasses: 1,
+        maxParentDepth: maxParentDepth - 1,
+      });
+      if (parentSelector && parentSelector !== 'unknown' && parentSelector !== 'body' && parentSelector !== 'html') {
+        return `${parentSelector} > ${tag}${suffix}`;
+      }
+    }
+
+    if (suffix) {
+      return `${tag}${suffix}`;
     }
   }
 
   return tag;
 }
 
+/**
+ * If an element under the cursor is an inline or leaf formatting element
+ * (e.g. svg, path, i, b, strong, or an inner span without attributes)
+ * inside an interactive container or component, resolves to the parent container.
+ */
+export function resolveMeaningfulTarget(element: HTMLElement | Element): HTMLElement {
+  if (!element || typeof element !== 'object') {
+    return element as HTMLElement;
+  }
+
+  const el = element as HTMLElement;
+
+  // 1. If element is inside an SVG or is an SVG child (path, circle, rect, g, svg)
+  const isSvg = el.tagName.toLowerCase() === 'svg' || el.namespaceURI?.includes('svg');
+  if (isSvg || el.closest?.('svg')) {
+    const interactiveParent = el.closest?.(
+      'button, a, [role="button"], [role="link"], [role="tab"], summary, label, [data-testid], [data-component]'
+    ) as HTMLElement | null;
+    if (interactiveParent) return interactiveParent;
+    const svgEl = isSvg ? el : (el.closest?.('svg') as HTMLElement | null);
+    if (svgEl) return svgEl;
+  }
+
+  // 2. Minor leaf tags (span, i, em, b, strong, small) with no distinct attributes inside interactive element
+  const leafTags = ['span', 'i', 'em', 'b', 'strong', 'small', 'mark', 'code'];
+  const tag = el.tagName.toLowerCase();
+  if (
+    leafTags.includes(tag) &&
+    !el.id &&
+    !el.getAttribute('data-testid') &&
+    !el.getAttribute('data-component') &&
+    !el.getAttribute('aria-label')
+  ) {
+    const interactiveParent = el.closest?.(
+      'button, a, [role="button"], [role="link"], [role="tab"], [role="menuitem"], summary, label, [data-testid], [data-component]'
+    ) as HTMLElement | null;
+    if (interactiveParent) return interactiveParent;
+  }
+
+  return el;
+}
+
 /**
  * Truncates string to specified max length with ellipsis
  */

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 {}
+    }
+  }
+};
 }

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

@@ -1,11 +1,23 @@
 import crypto from 'node:crypto';
 import type { WebSocket, WebSocketServer } from 'ws';
 import type { ClientEventMessage, CommandResponse, HelloMessage } from '../../../core/src/index.js';
+import { safeJsonStringify } from '../../../core/src/index.js';
 import type { IncidentEngine } from '../incidents/engine.js';
 import type { NotesEngine } from '../notes/engine.js';
 import type { SessionManager } from '../session/manager.js';
 import type { StorageDB } from '../storage/db.js';
 
+function safeWsSend(ws: WebSocket, payload: any): boolean {
+  if (ws.readyState !== 1 /* WebSocket.OPEN */) return false;
+  try {
+    const raw = typeof payload === 'string' ? payload : safeJsonStringify(payload);
+    ws.send(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function setupWebSocketServer(
   wss: WebSocketServer,
   db: StorageDB,
@@ -65,23 +77,19 @@ export function setupWebSocketServer(
 
           sessionManager.registerSocket(sessionId, ws, hello.origin || '', project.id);
 
-          ws.send(
-            JSON.stringify({
-              type: 'hello_ack',
-              sessionId,
-              projectId: project.id,
-              projectName: project.name,
-            })
-          );
+          safeWsSend(ws, {
+            type: 'hello_ack',
+            sessionId,
+            projectId: project.id,
+            projectName: project.name,
+          });
 
           // Sync existing notes for this project on load
           const existingNotes = db.listNotes({ projectId: project.id, limit: 100 });
-          ws.send(
-            JSON.stringify({
-              type: 'notes_sync',
-              notes: existingNotes,
-            })
-          );
+          safeWsSend(ws, {
+            type: 'notes_sync',
+            notes: existingNotes,
+          });
 
           if (verbose) {
             console.log(`[BrowserTrack] New session connected: ${sessionId} (${project.name} @ ${hello.origin})`);
@@ -147,15 +155,13 @@ export function setupWebSocketServer(
             );
           }
 
-          ws.send(
-            JSON.stringify({
-              type: 'note_created_ack',
-              noteId: note.id,
-              status: note.status,
-              scenarioId: note.scenarioId,
-              stepNumber: note.stepNumber,
-            })
-          );
+          safeWsSend(ws, {
+            type: 'note_created_ack',
+            noteId: note.id,
+            status: note.status,
+            scenarioId: note.scenarioId,
+            stepNumber: note.stepNumber,
+          });
 
           // Broadcast updated notes to all active browser tabs in this project
           const allNotes = db.listNotes({ projectId: note.projectId, limit: 100 });
@@ -224,12 +230,10 @@ export function setupWebSocketServer(
           const projectId = data.projectId || session?.projectId;
           if (projectId) {
             const allNotes = db.listNotes({ projectId, limit: 100 });
-            ws.send(
-              JSON.stringify({
-                type: 'notes_sync',
-                notes: allNotes,
-              })
-            );
+            safeWsSend(ws, {
+              type: 'notes_sync',
+              notes: allNotes,
+            });
           }
           return;
         }