browsertrack 0.1.2 → 0.2.1

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

@@ -0,0 +1,272 @@
+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;
+    while (curr) {
+      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;
+      while (curr) {
+        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;
+    while (curr) {
+      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/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;
@@ -73,6 +84,9 @@ export interface VisualNote {
   region?: RegionContext;
   status: NoteStatus;
   incidentId?: string;
+  scenarioId?: string;
+  stepNumber?: number;
+  scenarioTitle?: string;
   screenshots?: {
     original?: string;
     after?: string;
@@ -82,6 +96,28 @@ export interface VisualNote {
   resolvedAt?: string;
 }
 
+export interface ScenarioOverview {
+  id: string;
+  projectId: string;
+  title: string;
+  stepsCount: number;
+  status: NoteStatus;
+  route: string;
+  firstStepAt: string;
+  lastStepAt: string;
+}
+
+export interface ScenarioDetail {
+  id: string;
+  projectId: string;
+  title: string;
+  stepsCount: number;
+  status: NoteStatus;
+  steps: VisualNote[];
+  createdAt: string;
+  updatedAt: string;
+}
+
 export interface NoteVerificationResult {
   noteId: string;
   status: NoteStatus;

package/packages/daemon/src/notes/engine.ts

@@ -27,6 +27,9 @@ export class NotesEngine {
     region?: any;
     screenshot?: string;
     incidentId?: string;
+    scenarioId?: string;
+    stepNumber?: number;
+    scenarioTitle?: string;
   }): VisualNote {
     const session = this.db.getSession(payload.sessionId);
     const projectId = session?.projectId || 'default';
@@ -56,6 +59,9 @@ export class NotesEngine {
       region: payload.region,
       status: 'OPEN',
       incidentId: payload.incidentId,
+      scenarioId: payload.scenarioId,
+      stepNumber: payload.stepNumber,
+      scenarioTitle: payload.scenarioTitle,
       screenshots: screenshotPath ? { original: screenshotPath } : undefined,
       createdAt: now,
       updatedAt: now,

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

@@ -134,10 +134,17 @@ export function setupWebSocketServer(
             region: data.region,
             screenshot: data.screenshot,
             incidentId: data.incidentId,
+            scenarioId: data.scenarioId,
+            stepNumber: data.stepNumber,
+            scenarioTitle: data.scenarioTitle,
           });
 
           if (verbose) {
-            console.log(`[BrowserTrack] Visual note created: ${note.id} on ${note.route} ("${note.message}")`);
+            console.log(
+              `[BrowserTrack] Visual note created: ${note.id} on ${note.route} ("${note.message}")${
+                note.scenarioId ? ` [Scenario: ${note.scenarioTitle || note.scenarioId} Step ${note.stepNumber}]` : ''
+              }`
+            );
           }
 
           ws.send(
@@ -145,6 +152,8 @@ export function setupWebSocketServer(
               type: 'note_created_ack',
               noteId: note.id,
               status: note.status,
+              scenarioId: note.scenarioId,
+              stepNumber: note.stepNumber,
             })
           );
 
@@ -197,6 +206,19 @@ export function setupWebSocketServer(
           return;
         }
 
+        if (data.type === 'delete_scenario' && data.scenarioId) {
+          const scenario = db.getScenario(data.scenarioId);
+          if (scenario) {
+            db.deleteScenario(data.scenarioId);
+            const allNotes = db.listNotes({ projectId: scenario.projectId, limit: 100 });
+            sessionManager.broadcastToProject(scenario.projectId, {
+              type: 'notes_sync',
+              notes: allNotes,
+            });
+          }
+          return;
+        }
+
         if (data.type === 'get_notes') {
           const session = currentSessionId ? db.getSession(currentSessionId) : null;
           const projectId = data.projectId || session?.projectId;

package/packages/daemon/src/storage/db.ts

@@ -15,6 +15,8 @@ import type {
   VisualNote,
   NoteStatus,
   NoteVerificationResult,
+  ScenarioOverview,
+  ScenarioDetail,
 } from '../../../core/src/index.js';
 
 export class StorageDB {
@@ -134,6 +136,9 @@ export class StorageDB {
         region_json TEXT,
         screenshot_path TEXT,
         incident_id TEXT,
+        scenario_id TEXT,
+        step_number INTEGER,
+        scenario_title TEXT,
         status TEXT DEFAULT 'OPEN',
         created_at TEXT,
         updated_at TEXT,
@@ -156,7 +161,19 @@ export class StorageDB {
       CREATE INDEX IF NOT EXISTS idx_incidents_project ON incidents(project_id, status);
       CREATE INDEX IF NOT EXISTS idx_incidents_fp ON incidents(fingerprint);
       CREATE INDEX IF NOT EXISTS idx_notes_project ON notes(project_id, status);
+      CREATE INDEX IF NOT EXISTS idx_notes_scenario ON notes(scenario_id, step_number);
     `);
+
+    // Schema migrations for scenario fields
+    try {
+      this.db.exec('ALTER TABLE notes ADD COLUMN scenario_id TEXT;');
+    } catch {}
+    try {
+      this.db.exec('ALTER TABLE notes ADD COLUMN step_number INTEGER;');
+    } catch {}
+    try {
+      this.db.exec('ALTER TABLE notes ADD COLUMN scenario_title TEXT;');
+    } catch {}
   }
 
   // --- PROJECTS ---
@@ -539,8 +556,8 @@ export class StorageDB {
         `INSERT INTO notes (
           id, project_id, session_id, type, message, route, url,
           viewport_json, scroll_json, target_json, element_context_json, region_json,
-          screenshot_path, incident_id, status, created_at, updated_at, resolved_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          screenshot_path, incident_id, scenario_id, step_number, scenario_title, status, created_at, updated_at, resolved_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       )
       .run(
         note.id,
@@ -557,6 +574,9 @@ export class StorageDB {
         note.region ? JSON.stringify(note.region) : null,
         note.screenshots?.original || null,
         note.incidentId || null,
+        note.scenarioId || null,
+        note.stepNumber ?? null,
+        note.scenarioTitle || null,
         note.status,
         note.createdAt,
         note.updatedAt,
@@ -570,7 +590,7 @@ export class StorageDB {
     return this.mapNoteRow(row);
   }
 
-  public listNotes(options: { projectId?: string; status?: NoteStatus; route?: string; limit?: number } = {}): VisualNote[] {
+  public listNotes(options: { projectId?: string; status?: NoteStatus; route?: string; scenarioId?: string; limit?: number } = {}): VisualNote[] {
     let sql = 'SELECT * FROM notes WHERE 1=1';
     const params: any[] = [];
 
@@ -586,6 +606,10 @@ export class StorageDB {
       sql += ' AND route = ?';
       params.push(options.route);
     }
+    if (options.scenarioId) {
+      sql += ' AND scenario_id = ?';
+      params.push(options.scenarioId);
+    }
 
     sql += ' ORDER BY created_at DESC LIMIT ?';
     params.push(options.limit || 50);
@@ -599,6 +623,82 @@ export class StorageDB {
     this.db.prepare('DELETE FROM notes WHERE id = ?').run(id);
   }
 
+  // --- SCENARIOS (MULTI-STEP FLOWS) ---
+  public listScenarios(options: { projectId?: string; status?: NoteStatus; limit?: number } = {}): ScenarioOverview[] {
+    let sql = `
+      SELECT 
+        scenario_id, 
+        project_id, 
+        COALESCE(MAX(scenario_title), 'Scenario') as title,
+        COUNT(id) as steps_count,
+        CASE WHEN SUM(CASE WHEN status != 'RESOLVED' THEN 1 ELSE 0 END) = 0 THEN 'RESOLVED' ELSE 'OPEN' END as status,
+        MIN(route) as route,
+        MIN(created_at) as first_step_at,
+        MAX(created_at) as last_step_at
+      FROM notes
+      WHERE scenario_id IS NOT NULL
+    `;
+    const params: any[] = [];
+    if (options.projectId) {
+      sql += ' AND (project_id = ? OR project_id IS NULL)';
+      params.push(options.projectId);
+    }
+    sql += ' GROUP BY scenario_id';
+
+    if (options.status) {
+      if (options.status === 'RESOLVED') {
+        sql += " HAVING SUM(CASE WHEN status != 'RESOLVED' THEN 1 ELSE 0 END) = 0";
+      } else {
+        sql += " HAVING SUM(CASE WHEN status != 'RESOLVED' THEN 1 ELSE 0 END) > 0";
+      }
+    }
+
+    sql += ' ORDER BY last_step_at DESC LIMIT ?';
+    params.push(options.limit || 50);
+
+    const rows = this.db.prepare(sql).all(...params) as any[];
+    return rows.map((r) => ({
+      id: r.scenario_id,
+      projectId: r.project_id,
+      title: r.title,
+      stepsCount: Number(r.steps_count),
+      status: r.status as NoteStatus,
+      route: r.route || '/',
+      firstStepAt: r.first_step_at,
+      lastStepAt: r.last_step_at,
+    }));
+  }
+
+  public getScenario(scenarioId: string): ScenarioDetail | null {
+    const rows = this.db
+      .prepare('SELECT * FROM notes WHERE scenario_id = ? ORDER BY COALESCE(step_number, 999999) ASC, created_at ASC')
+      .all(scenarioId) as any[];
+
+    if (!rows || rows.length === 0) return null;
+
+    const steps = rows.map((r) => this.mapNoteRow(r));
+    const title = steps.find((s) => s.scenarioTitle)?.scenarioTitle || `Scenario ${scenarioId}`;
+    const allResolved = steps.every((s) => s.status === 'RESOLVED');
+
+    return {
+      id: scenarioId,
+      projectId: steps[0].projectId,
+      title,
+      stepsCount: steps.length,
+      status: allResolved ? 'RESOLVED' : 'OPEN',
+      steps,
+      createdAt: steps[0].createdAt,
+      updatedAt: steps[steps.length - 1].updatedAt,
+    };
+  }
+
+  public deleteScenario(scenarioId: string): void {
+    const notes = this.db.prepare('SELECT id FROM notes WHERE scenario_id = ?').all(scenarioId) as any[];
+    for (const n of notes) {
+      this.deleteNote(n.id);
+    }
+  }
+
   public updateNoteStatus(id: string, status: NoteStatus): void {
     const now = new Date().toISOString();
     const resolvedAt = status === 'RESOLVED' ? now : null;
@@ -725,6 +825,9 @@ export class StorageDB {
       region: row.region_json ? JSON.parse(row.region_json) : undefined,
       status: row.status as NoteStatus,
       incidentId: row.incident_id || undefined,
+      scenarioId: row.scenario_id || undefined,
+      stepNumber: row.step_number != null ? Number(row.step_number) : undefined,
+      scenarioTitle: row.scenario_title || undefined,
       screenshots: row.screenshot_path
         ? {
             original: row.screenshot_path,

package/packages/mcp/src/handlers.ts

@@ -104,6 +104,7 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
               visible: incident.lastElement.visible,
               innerText: incident.lastElement.innerText,
               outerHTML: incident.lastElement.outerHTML,
+              componentSource: incident.lastElement.componentSource,
             }
           : undefined,
         recentBreadcrumbs: breadcrumbsTimeline,
@@ -252,6 +253,7 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
     case 'list_notes': {
       const notes = db.listNotes({
         projectId: args.projectId,
+        scenarioId: args.scenarioId,
         status: args.status,
         limit: args.limit || 20,
       });
@@ -263,6 +265,9 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
           type: n.type,
           status: n.status,
           route: n.route,
+          scenarioId: n.scenarioId,
+          stepNumber: n.stepNumber,
+          scenarioTitle: n.scenarioTitle,
           viewport: `${n.viewport.width} × ${n.viewport.height}`,
           target: n.target?.selector || n.type,
           message: n.message,
@@ -272,6 +277,57 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
       };
     }
 
+    case 'list_scenarios': {
+      const scenarios = db.listScenarios({
+        projectId: args.projectId,
+        status: args.status,
+        limit: args.limit || 20,
+      });
+
+      return {
+        total: scenarios.length,
+        scenarios: scenarios.map((s) => ({
+          id: s.id,
+          title: s.title,
+          stepsCount: s.stepsCount,
+          status: s.status,
+          route: s.route,
+          firstStepAt: s.firstStepAt,
+          lastStepAt: s.lastStepAt,
+        })),
+      };
+    }
+
+    case 'get_scenario': {
+      const scenario = db.getScenario(args.scenarioId);
+      if (!scenario) {
+        throw new Error(`Scenario '${args.scenarioId}' not found.`);
+      }
+
+      return {
+        id: scenario.id,
+        title: scenario.title,
+        stepsCount: scenario.stepsCount,
+        status: scenario.status,
+        steps: scenario.steps.map((step) => ({
+          id: step.id,
+          stepNumber: step.stepNumber,
+          type: step.type,
+          message: step.message,
+          route: step.route,
+          url: step.url,
+          targetSelector: step.target?.selector,
+          boundingRect: step.target?.boundingRect || step.region,
+          elementContext: step.elementContext,
+          screenshot: step.screenshots?.original,
+          status: step.status,
+          createdAt: step.createdAt,
+        })),
+        createdAt: scenario.createdAt,
+        updatedAt: scenario.updatedAt,
+      };
+    }
+
     case 'get_note': {
       const note = db.getNote(args.noteId);
       if (!note) {
@@ -285,6 +341,9 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
         type: note.type,
         status: note.status,
         message: note.message,
+        scenarioId: note.scenarioId,
+        stepNumber: note.stepNumber,
+        scenarioTitle: note.scenarioTitle,
         route: note.route,
         url: note.url,
         viewport: note.viewport,