browsertrack 0.1.2 → 0.2.0

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

@@ -73,6 +73,9 @@ export interface VisualNote {
   region?: RegionContext;
   status: NoteStatus;
   incidentId?: string;
+  scenarioId?: string;
+  stepNumber?: number;
+  scenarioTitle?: string;
   screenshots?: {
     original?: string;
     after?: string;
@@ -82,6 +85,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

@@ -252,6 +252,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 +264,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 +276,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 +340,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,

package/packages/mcp/src/tools.ts

@@ -156,6 +156,7 @@ export const TOOLS: Tool[] = [
       type: 'object',
       properties: {
         projectId: { type: 'string', description: 'Filter notes by project ID or name' },
+        scenarioId: { type: 'string', description: 'Filter notes by scenario / flow ID' },
         status: {
           type: 'string',
           enum: ['OPEN', 'IN_PROGRESS', 'VERIFYING', 'RESOLVED', 'FAILED', 'INCONCLUSIVE'],
@@ -165,6 +166,33 @@ export const TOOLS: Tool[] = [
       },
     },
   },
+  {
+    name: 'list_scenarios',
+    description: 'List recorded reproduction scenarios and multi-step user interaction flows',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Filter scenarios by project ID or name' },
+        status: {
+          type: 'string',
+          enum: ['OPEN', 'RESOLVED'],
+          description: 'Filter by scenario status',
+        },
+        limit: { type: 'number', description: 'Maximum number of scenarios to return (default: 20)' },
+      },
+    },
+  },
+  {
+    name: 'get_scenario',
+    description: 'Retrieve full chronological step-by-step reproduction flow with selectors, route, screenshots, and action details',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scenarioId: { type: 'string', description: 'The unique ID of the scenario / flow (e.g. scen_123)' },
+      },
+      required: ['scenarioId'],
+    },
+  },
   {
     name: 'get_note',
     description: 'Retrieve full debugging context for a visual note (message, route, viewport dimensions, target element selector, DOM context, screenshot file path, project path)',

package/test/client/interceptors.test.ts

@@ -127,4 +127,68 @@ describe('Client Interceptors & Utilities', () => {
 
     inspector.destroy();
   });
+
+  it('should support multi-step scenario recording flow in NoteInspector', async () => {
+    const mockTransport = { send: vi.fn(), getSessionId: () => 'sess_123', onMessage: vi.fn(() => () => {}) } as any;
+    const mockDriver = { captureElement: vi.fn().mockResolvedValue({ ok: false }) } as any;
+
+    const inspector = new NoteInspector(mockTransport, mockDriver, {
+      showToolbar: true,
+    });
+
+    inspector.init();
+
+    inspector.startScenario('Checkout Journey');
+    expect((inspector as any).activeScenario).not.toBeNull();
+    expect((inspector as any).activeScenario.title).toBe('Checkout Journey');
+    expect((inspector as any).activeScenario.stepNumber).toBe(1);
+    expect((inspector as any).activeMode).toBe('element');
+
+    const fakeElement = {
+      tagName: 'BUTTON',
+      id: 'checkout-button',
+      getAttribute: () => null,
+      attributes: [],
+      classList: [],
+      getBoundingClientRect: () => ({ x: 10, y: 20, width: 100, height: 40, top: 20, left: 10, bottom: 60, right: 110 }),
+    } as any;
+
+    await inspector.saveVisualNote(fakeElement, 'Click checkout', 'element', {
+      scenarioId: (inspector as any).activeScenario.id,
+      stepNumber: 1,
+      scenarioTitle: 'Checkout Journey',
+    });
+
+    expect(mockTransport.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'create_note',
+        scenarioId: expect.any(String),
+        stepNumber: 1,
+        scenarioTitle: 'Checkout Journey',
+      })
+    );
+
+    inspector.finishScenario();
+    expect((inspector as any).activeScenario).toBeNull();
+    expect((inspector as any).activeMode).toBe('idle');
+
+    inspector.destroy();
+  });
+
+  it('should support toast notifications in NoteInspector', () => {
+    const mockTransport = { send: vi.fn(), getSessionId: () => 'sess_123', onMessage: vi.fn(() => () => {}) } as any;
+    const mockDriver = { captureElement: vi.fn() } as any;
+
+    const inspector = new NoteInspector(mockTransport, mockDriver, {
+      showToolbar: true,
+    });
+
+    inspector.init();
+    // Test showing toast without errors
+    expect(() => {
+      inspector.showToast('Test Toast Notification', '✨');
+    }).not.toThrow();
+
+    inspector.destroy();
+  });
 });

package/test/daemon/scenario-storage.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { StorageDB } from '../../packages/daemon/src/storage/db.js';
+import { handleToolCall } from '../../packages/mcp/src/handlers.js';
+import type { VisualNote } from '../../packages/core/src/index.js';
+
+const TEST_DB = path.join(process.cwd(), 'tmp', 'test-scenario.db');
+
+describe('Scenario & Multi-Step Flow Storage', () => {
+  let db: StorageDB;
+
+  beforeEach(() => {
+    if (fs.existsSync(TEST_DB)) fs.unlinkSync(TEST_DB);
+    db = new StorageDB(TEST_DB);
+    db.upsertProject({
+      id: 'proj_e2e',
+      name: 'E2E App',
+      origin: 'http://localhost:3000',
+    });
+  });
+
+  afterEach(() => {
+    db.close();
+    if (fs.existsSync(TEST_DB)) fs.unlinkSync(TEST_DB);
+  });
+
+  it('should store sequential scenario steps and retrieve scenario summary and detail', () => {
+    const scenarioId = 'scen_checkout_123';
+    const title = 'Checkout Promo Flow';
+
+    const step1: VisualNote = {
+      id: 'note_s1',
+      projectId: 'proj_e2e',
+      sessionId: 'sess_1',
+      type: 'element',
+      message: '1. Click on Cart button',
+      route: '/shop',
+      url: 'http://localhost:3000/shop',
+      viewport: { width: 1280, height: 800, devicePixelRatio: 1 },
+      scroll: { scrollX: 0, scrollY: 0 },
+      target: {
+        selector: '#btn-cart',
+        boundingRect: { x: 10, y: 10, width: 50, height: 30, top: 10, left: 10, bottom: 40, right: 60 },
+        visible: true,
+      },
+      scenarioId,
+      stepNumber: 1,
+      scenarioTitle: title,
+      status: 'OPEN',
+      createdAt: '2026-09-01T10:00:00.000Z',
+      updatedAt: '2026-09-01T10:00:00.000Z',
+    };
+
+    const step2: VisualNote = {
+      id: 'note_s2',
+      projectId: 'proj_e2e',
+      sessionId: 'sess_1',
+      type: 'element',
+      message: '2. Enter coupon code PROMO2026',
+      route: '/cart',
+      url: 'http://localhost:3000/cart',
+      viewport: { width: 1280, height: 800, devicePixelRatio: 1 },
+      scroll: { scrollX: 0, scrollY: 0 },
+      target: {
+        selector: '#input-coupon',
+        boundingRect: { x: 50, y: 100, width: 200, height: 40, top: 100, left: 50, bottom: 140, right: 250 },
+        visible: true,
+      },
+      scenarioId,
+      stepNumber: 2,
+      scenarioTitle: title,
+      status: 'OPEN',
+      createdAt: '2026-09-01T10:01:00.000Z',
+      updatedAt: '2026-09-01T10:01:00.000Z',
+    };
+
+    const step3: VisualNote = {
+      id: 'note_s3',
+      projectId: 'proj_e2e',
+      sessionId: 'sess_1',
+      type: 'region',
+      message: '3. Total price did not calculate discount',
+      route: '/cart',
+      url: 'http://localhost:3000/cart',
+      viewport: { width: 1280, height: 800, devicePixelRatio: 1 },
+      scroll: { scrollX: 0, scrollY: 0 },
+      region: { x: 50, y: 200, width: 300, height: 100 },
+      scenarioId,
+      stepNumber: 3,
+      scenarioTitle: title,
+      status: 'OPEN',
+      createdAt: '2026-09-01T10:02:00.000Z',
+      updatedAt: '2026-09-01T10:02:00.000Z',
+    };
+
+    db.insertNote(step1);
+    db.insertNote(step2);
+    db.insertNote(step3);
+
+    // Test listScenarios
+    const scenarios = db.listScenarios();
+    expect(scenarios.length).toBe(1);
+    expect(scenarios[0].id).toBe(scenarioId);
+    expect(scenarios[0].title).toBe(title);
+    expect(scenarios[0].stepsCount).toBe(3);
+    expect(scenarios[0].status).toBe('OPEN');
+
+    // Test getScenario
+    const detail = db.getScenario(scenarioId);
+    expect(detail).not.toBeNull();
+    expect(detail!.stepsCount).toBe(3);
+    expect(detail!.steps[0].id).toBe('note_s1');
+    expect(detail!.steps[0].stepNumber).toBe(1);
+    expect(detail!.steps[1].id).toBe('note_s2');
+    expect(detail!.steps[1].stepNumber).toBe(2);
+    expect(detail!.steps[2].id).toBe('note_s3');
+    expect(detail!.steps[2].stepNumber).toBe(3);
+  });
+
+  it('should handle list_scenarios and get_scenario MCP tool calls', async () => {
+    const scenarioId = 'scen_login_bug';
+    const note1: VisualNote = {
+      id: 'note_step_1',
+      projectId: 'proj_e2e',
+      sessionId: 'sess_1',
+      type: 'element',
+      message: 'Click Sign In',
+      route: '/login',
+      url: 'http://localhost:3000/login',
+      viewport: { width: 1280, height: 800, devicePixelRatio: 1 },
+      scroll: { scrollX: 0, scrollY: 0 },
+      scenarioId,
+      stepNumber: 1,
+      scenarioTitle: 'Auth Flow',
+      status: 'OPEN',
+      createdAt: '2026-09-01T10:00:00.000Z',
+      updatedAt: '2026-09-01T10:00:00.000Z',
+    };
+
+    db.insertNote(note1);
+
+    const listRes = await handleToolCall('list_scenarios', {}, { db });
+    expect(listRes.total).toBe(1);
+    expect(listRes.scenarios[0].id).toBe(scenarioId);
+
+    const getRes = await handleToolCall('get_scenario', { scenarioId }, { db });
+    expect(getRes.id).toBe(scenarioId);
+    expect(getRes.title).toBe('Auth Flow');
+    expect(getRes.steps.length).toBe(1);
+    expect(getRes.steps[0].stepNumber).toBe(1);
+
+    // Delete scenario
+    db.deleteScenario(scenarioId);
+    const afterDelete = db.listScenarios();
+    expect(afterDelete.length).toBe(0);
+  });
+});