browsertrack 0.1.2 → 0.2.1

package/dist/{notes-CBvN91Wf.d.ts → commands-fjuqKzkm.d.ts}

@@ -1,3 +1,126 @@
+type NoteType = 'element' | 'region' | 'page';
+type NoteStatus = 'OPEN' | 'IN_PROGRESS' | 'VERIFYING' | 'READY_FOR_REVIEW' | 'VERIFIED' | 'RESOLVED' | 'FAILED' | 'INCONCLUSIVE';
+interface ViewportContext {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+}
+interface ScrollContext {
+    scrollX: number;
+    scrollY: number;
+}
+interface DOMRectJson {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+interface NoteTarget {
+    selector: string;
+    boundingRect: DOMRectJson;
+    visible: boolean;
+    confidence?: 'high' | 'medium' | 'low';
+}
+interface ComponentSourceInfo {
+    framework?: 'react' | 'vue' | 'svelte' | 'web-component' | 'vanilla';
+    componentName?: string;
+    sourceFile?: string;
+    sourceLine?: number;
+    sourceColumn?: number;
+    hierarchy?: string[];
+    props?: Record<string, any>;
+}
+interface ElementContext {
+    selector: string;
+    tag: string;
+    attributes?: Record<string, string>;
+    outerHTML?: string;
+    innerText?: string;
+    componentSource?: ComponentSourceInfo;
+    parent?: {
+        selector: string;
+        tag: string;
+    };
+}
+interface RegionContext {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface VisualNote {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    type: NoteType;
+    message: string;
+    route: string;
+    url: string;
+    viewport: ViewportContext;
+    scroll: ScrollContext;
+    target?: NoteTarget;
+    elementContext?: ElementContext;
+    region?: RegionContext;
+    status: NoteStatus;
+    incidentId?: string;
+    scenarioId?: string;
+    stepNumber?: number;
+    scenarioTitle?: string;
+    screenshots?: {
+        original?: string;
+        after?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+interface ScenarioOverview {
+    id: string;
+    projectId: string;
+    title: string;
+    stepsCount: number;
+    status: NoteStatus;
+    route: string;
+    firstStepAt: string;
+    lastStepAt: string;
+}
+interface ScenarioDetail {
+    id: string;
+    projectId: string;
+    title: string;
+    stepsCount: number;
+    status: NoteStatus;
+    steps: VisualNote[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface NoteVerificationResult {
+    noteId: string;
+    status: NoteStatus;
+    checks: Array<{
+        type: string;
+        passed: boolean;
+        details?: string;
+    }>;
+    geometryDiff?: {
+        before?: DOMRectJson;
+        current?: DOMRectJson;
+        viewportWidth?: number;
+        overflowFixed?: boolean;
+        overflowPx?: number;
+    };
+    screenshots?: {
+        before?: string;
+        after?: string;
+    };
+    timestamp: string;
+    message?: string;
+}
+
 type EventType = 'runtime_error' | 'unhandled_rejection' | 'console' | 'fetch' | 'xhr' | 'navigation' | 'interaction';
 type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
 interface ElementSummary {
@@ -8,6 +131,7 @@ interface ElementSummary {
     attributes?: Record<string, string>;
     outerHTML?: string;
     innerText?: string;
+    componentSource?: ComponentSourceInfo;
     boundingRect?: {
         x: number;
         y: number;
@@ -167,94 +291,4 @@ interface CommandResponse<T = any> {
     reason?: string;
 }
 
-type NoteType = 'element' | 'region' | 'page';
-type NoteStatus = 'OPEN' | 'IN_PROGRESS' | 'VERIFYING' | 'READY_FOR_REVIEW' | 'VERIFIED' | 'RESOLVED' | 'FAILED' | 'INCONCLUSIVE';
-interface ViewportContext {
-    width: number;
-    height: number;
-    devicePixelRatio: number;
-}
-interface ScrollContext {
-    scrollX: number;
-    scrollY: number;
-}
-interface DOMRectJson {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    top: number;
-    left: number;
-    bottom: number;
-    right: number;
-}
-interface NoteTarget {
-    selector: string;
-    boundingRect: DOMRectJson;
-    visible: boolean;
-    confidence?: 'high' | 'medium' | 'low';
-}
-interface ElementContext {
-    selector: string;
-    tag: string;
-    attributes?: Record<string, string>;
-    outerHTML?: string;
-    innerText?: string;
-    parent?: {
-        selector: string;
-        tag: string;
-    };
-}
-interface RegionContext {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-interface VisualNote {
-    id: string;
-    projectId: string;
-    sessionId: string;
-    type: NoteType;
-    message: string;
-    route: string;
-    url: string;
-    viewport: ViewportContext;
-    scroll: ScrollContext;
-    target?: NoteTarget;
-    elementContext?: ElementContext;
-    region?: RegionContext;
-    status: NoteStatus;
-    incidentId?: string;
-    screenshots?: {
-        original?: string;
-        after?: string;
-    };
-    createdAt: string;
-    updatedAt: string;
-    resolvedAt?: string;
-}
-interface NoteVerificationResult {
-    noteId: string;
-    status: NoteStatus;
-    checks: Array<{
-        type: string;
-        passed: boolean;
-        details?: string;
-    }>;
-    geometryDiff?: {
-        before?: DOMRectJson;
-        current?: DOMRectJson;
-        viewportWidth?: number;
-        overflowFixed?: boolean;
-        overflowPx?: number;
-    };
-    screenshots?: {
-        before?: string;
-        after?: string;
-    };
-    timestamp: string;
-    message?: string;
-}
-
-export type { Breadcrumb as B, CaptureElementParams as C, DOMRectJson as D, ElementContext as E, HelloMessage as H, NavigateParams as N, OverflowCheckResult as O, PageStateResult as P, QueryElementParams as Q, RegionContext as R, ScrollContext as S, ViewportContext as V, CaptureElementResult as a, ClientCommand as b, ClientEventMessage as c, CommandResponse as d, CommandType as e, ConsoleEvent as f, ConsoleLevel as g, ElementStyleResult as h, ElementSummary as i, EventType as j, NavigationEvent as k, NetworkEvent as l, NoteStatus as m, NoteTarget as n, NoteType as o, NoteVerificationResult as p, QueryElementResult as q, ReloadParams as r, RuntimeErrorEvent as s, VisualNote as t };
+export type { Breadcrumb as B, CaptureElementParams as C, DOMRectJson as D, ElementContext as E, HelloMessage as H, NavigateParams as N, OverflowCheckResult as O, PageStateResult as P, QueryElementParams as Q, RegionContext as R, ScenarioDetail as S, ViewportContext as V, CaptureElementResult as a, ClientCommand as b, ClientEventMessage as c, CommandResponse as d, CommandType as e, ComponentSourceInfo as f, ConsoleEvent as g, ConsoleLevel as h, ElementStyleResult as i, ElementSummary as j, EventType as k, NavigationEvent as l, NetworkEvent as m, NoteStatus as n, NoteTarget as o, NoteType as p, NoteVerificationResult as q, QueryElementResult as r, ReloadParams as s, RuntimeErrorEvent as t, ScenarioOverview as u, ScrollContext as v, VisualNote as w };

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
-export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScrollContext, V as ViewportContext, t as VisualNote } from '../notes-CBvN91Wf.js';
-export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from '../projects-CY8ungMt.js';
+export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ComponentSourceInfo, g as ConsoleEvent, h as ConsoleLevel, D as DOMRectJson, E as ElementContext, i as ElementStyleResult, j as ElementSummary, k as EventType, H as HelloMessage, N as NavigateParams, l as NavigationEvent, m as NetworkEvent, n as NoteStatus, o as NoteTarget, p as NoteType, q as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, r as QueryElementResult, R as RegionContext, s as ReloadParams, t as RuntimeErrorEvent, S as ScenarioDetail, u as ScenarioOverview, v as ScrollContext, V as ViewportContext, w as VisualNote } from '../commands-fjuqKzkm.js';
+export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from '../projects-DB7S312i.js';
 import { Rules } from '@visulima/redact';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
 

package/dist/daemon/index.d.ts

@@ -1,6 +1,6 @@
-import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-CeT9URuN.js';
-import { c as ClientEventMessage } from '../notes-CBvN91Wf.js';
-import { I as Incident } from '../projects-CY8ungMt.js';
+import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-CmchnMDq.js';
+import { c as ClientEventMessage } from '../commands-fjuqKzkm.js';
+import { I as Incident } from '../projects-DB7S312i.js';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
 

package/dist/daemon/index.js

@@ -4,7 +4,7 @@ import {
   createDaemon,
   createHttpHandler,
   setupWebSocketServer
-} from "../chunk-SPCIROIU.js";
+} from "../chunk-7OCOQGDN.js";
 import "../chunk-6VA7GBAO.js";
 import {
   NoteVerificationEngine,
@@ -14,7 +14,7 @@ import {
   StorageDB,
   VerificationEngine,
   getDaemonConfig
-} from "../chunk-ILRYKMME.js";
+} from "../chunk-3HOXPTM2.js";
 export {
   BrowserTrackDaemon,
   IncidentEngine,

package/dist/{engine-CeT9URuN.d.ts → engine-CmchnMDq.d.ts}

@@ -1,5 +1,5 @@
-import { B as Breadcrumb, i as ElementSummary, t as VisualNote, m as NoteStatus, p as NoteVerificationResult, d as CommandResponse, b as ClientCommand } from './notes-CBvN91Wf.js';
-import { f as Project, S as Session, I as Incident, d as IncidentStatus, b as IncidentSeverity, a as IncidentOccurrence, h as VerificationResult, g as VerificationRecipe } from './projects-CY8ungMt.js';
+import { B as Breadcrumb, j as ElementSummary, w as VisualNote, n as NoteStatus, u as ScenarioOverview, S as ScenarioDetail, q as NoteVerificationResult, d as CommandResponse, b as ClientCommand } from './commands-fjuqKzkm.js';
+import { f as Project, S as Session, I as Incident, d as IncidentStatus, b as IncidentSeverity, a as IncidentOccurrence, h as VerificationResult, g as VerificationRecipe } from './projects-DB7S312i.js';
 import { WebSocket } from 'ws';
 
 declare class StorageDB {
@@ -71,9 +71,17 @@ declare class StorageDB {
         projectId?: string;
         status?: NoteStatus;
         route?: string;
+        scenarioId?: string;
         limit?: number;
     }): VisualNote[];
     deleteNote(id: string): void;
+    listScenarios(options?: {
+        projectId?: string;
+        status?: NoteStatus;
+        limit?: number;
+    }): ScenarioOverview[];
+    getScenario(scenarioId: string): ScenarioDetail | null;
+    deleteScenario(scenarioId: string): void;
     updateNoteStatus(id: string, status: NoteStatus): void;
     updateNote(id: string, updates: Partial<VisualNote>): void;
     insertNoteVerification(v: NoteVerificationResult): void;
@@ -133,6 +141,9 @@ declare class NotesEngine {
         region?: any;
         screenshot?: string;
         incidentId?: string;
+        scenarioId?: string;
+        stepNumber?: number;
+        scenarioTitle?: string;
     }): VisualNote;
     saveNoteScreenshot(projectId: string, noteId: string, name: string, dataUrl: string): string | null;
 }

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ConsoleEvent, g as ConsoleLevel, D as DOMRectJson, E as ElementContext, h as ElementStyleResult, i as ElementSummary, j as EventType, H as HelloMessage, N as NavigateParams, k as NavigationEvent, l as NetworkEvent, m as NoteStatus, n as NoteTarget, o as NoteType, p as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, q as QueryElementResult, R as RegionContext, r as ReloadParams, s as RuntimeErrorEvent, S as ScrollContext, V as ViewportContext, t as VisualNote } from './notes-CBvN91Wf.js';
-export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-CY8ungMt.js';
+export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ComponentSourceInfo, g as ConsoleEvent, h as ConsoleLevel, D as DOMRectJson, E as ElementContext, i as ElementStyleResult, j as ElementSummary, k as EventType, H as HelloMessage, N as NavigateParams, l as NavigationEvent, m as NetworkEvent, n as NoteStatus, o as NoteTarget, p as NoteType, q as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, r as QueryElementResult, R as RegionContext, s as ReloadParams, t as RuntimeErrorEvent, S as ScenarioDetail, u as ScenarioOverview, v as ScrollContext, V as ViewportContext, w as VisualNote } from './commands-fjuqKzkm.js';
+export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-DB7S312i.js';
 export { BROWSER_SECURITY_RULES, FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate } from './core/index.js';
 export { BrowserTrackClient, getClient, init as initClient } from './client/index.js';
 export { BrowserTrackDaemon, createDaemon } from './daemon/index.js';
-export { c as createMcpServer } from './server-Dd8NX2Mk.js';
+export { c as createMcpServer } from './server-DiVmTrIR.js';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
-import './engine-CeT9URuN.js';
+import './engine-CmchnMDq.js';
 import 'ws';
 import 'node:http';
 import '@modelcontextprotocol/sdk/server/index.js';

package/dist/index.js

@@ -2,11 +2,11 @@ import {
   BrowserTrackClient,
   getClient,
   init
-} from "./chunk-SKCMT2DE.js";
+} from "./chunk-INXDWPJW.js";
 import {
   BrowserTrackDaemon,
   createDaemon
-} from "./chunk-SPCIROIU.js";
+} from "./chunk-7OCOQGDN.js";
 import {
   BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
@@ -27,8 +27,8 @@ import {
 } from "./chunk-6VA7GBAO.js";
 import {
   createMcpServer
-} from "./chunk-G2Y3CXCY.js";
-import "./chunk-ILRYKMME.js";
+} from "./chunk-464D4U2U.js";
+import "./chunk-3HOXPTM2.js";
 export {
   BROWSER_SECURITY_RULES,
   BrowserTrackClient,

package/dist/mcp/index.d.ts

@@ -1,9 +1,9 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-Dd8NX2Mk.js';
+export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-DiVmTrIR.js';
 import '@modelcontextprotocol/sdk/server/index.js';
-import '../engine-CeT9URuN.js';
-import '../notes-CBvN91Wf.js';
-import '../projects-CY8ungMt.js';
+import '../engine-CmchnMDq.js';
+import '../commands-fjuqKzkm.js';
+import '../projects-DB7S312i.js';
 import 'ws';
 
 declare const TOOLS: Tool[];

package/dist/mcp/index.js

@@ -2,8 +2,8 @@ import {
   TOOLS,
   createMcpServer,
   handleToolCall
-} from "../chunk-G2Y3CXCY.js";
-import "../chunk-ILRYKMME.js";
+} from "../chunk-464D4U2U.js";
+import "../chunk-3HOXPTM2.js";
 export {
   TOOLS,
   createMcpServer,

package/dist/{projects-CY8ungMt.d.ts → projects-DB7S312i.d.ts}

@@ -1,4 +1,4 @@
-import { B as Breadcrumb, l as NetworkEvent, i as ElementSummary } from './notes-CBvN91Wf.js';
+import { B as Breadcrumb, m as NetworkEvent, j as ElementSummary } from './commands-fjuqKzkm.js';
 
 type IncidentStatus = 'OPEN' | 'FIX_ATTEMPTED' | 'VERIFYING' | 'VERIFIED' | 'FAILED' | 'INCONCLUSIVE';
 type IncidentSeverity = 'error' | 'warn' | 'fatal';

package/dist/{server-Dd8NX2Mk.d.ts → server-DiVmTrIR.d.ts}

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CeT9URuN.js';
+import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CmchnMDq.js';
 
 interface McpContext {
     db: StorageDB;

package/docs/component-resolver.md

@@ -0,0 +1,108 @@
+---
+title: Component & Source Resolver
+description: Map live browser DOM elements to React Fiber, Vue VNode, Svelte metadata, and exact source file locations for AI coding agents
+order: 5
+---
+
+# Component & Source-Map Resolver 🧬
+
+A core challenge for AI coding agents during frontend debugging is bridging the gap between what the browser renders (e.g., `<button class="sc-bdVaJa bDwzTH">`) and the actual source code file in the repository (e.g., `src/components/CheckoutButton.tsx:42`).
+
+BrowserTrack includes an automated **Component & Source-Map Resolver** that inspects internal framework virtual DOM instances in real time and attaches exact component and source locations to visual notes, user interaction breadcrumbs, and error incidents.
+
+---
+
+## ⚡ Supported Frameworks
+
+| Framework | Inspection Technique | Resolved Metadata |
+| :--- | :--- | :--- |
+| **React (v16–19)** | `__reactFiber$`, `_debugSource`, `_debugOwner` | Component Name, Source File, Line, Column, Component Hierarchy, Props |
+| **Vue 3** | `__vueParentComponent`, `__vnode` | Component Name (`__name`), SFC File (`__file`), Hierarchy, Props |
+| **Vue 2** | `__vue__.$options` | Component Tag, SFC File (`__file`) |
+| **Svelte** | `__svelte_meta.loc` | Svelte Component Name, File Path, Line, Column |
+| **Web Components** | Hyphenated custom element tags | Custom Element Tag Name |
+| **Generic / Vanilla** | `data-component`, `data-source-file`, `data-source-line` | Explicit Component & File Annotation |
+
+---
+
+## 🔍 How It Works
+
+```mermaid
+graph LR
+    A[Target DOM Element] --> B[BrowserTrack Resolver]
+    B -->|React Fiber| C[Extract _debugSource & _debugOwner]
+    B -->|Vue VNode| D[Extract __file & type.__name]
+    B -->|Svelte Meta| E[Extract loc.file & loc.line]
+    C & D & E --> F[ComponentSourceInfo]
+    F --> G[Visual Notes, Breadcrumbs & Incidents]
+    G --> H[AI Agent opens exact file:line via MCP]
+```
+
+### Development Mode Source Maps
+Modern bundlers (Vite, Next.js, Create React App, Nuxt, SvelteKit) automatically populate `_debugSource` and `__file` on virtual DOM nodes during local development. BrowserTrack reads this data directly without requiring additional build plugins.
+
+---
+
+## 📦 Resolved Metadata Structure
+
+Whenever a visual note is taken, or when user interactions precede a crash:
+
+```typescript
+export interface ComponentSourceInfo {
+  framework?: 'react' | 'vue' | 'svelte' | 'web-component' | 'vanilla';
+  componentName?: string;     // e.g. "CheckoutButton"
+  sourceFile?: string;        // e.g. "src/components/CheckoutButton.tsx"
+  sourceLine?: number;        // e.g. 42
+  sourceColumn?: number;      // e.g. 8
+  hierarchy?: string[];       // e.g. ["App", "ShopLayout", "CartDrawer", "CheckoutButton"]
+  props?: Record<string, any>;// Sanitized component props
+}
+```
+
+---
+
+## 🤖 AI Agent MCP Usage
+
+When an agent retrieves an incident or visual note:
+
+### In `get_incident`:
+The `lastInteractedElement` provides direct source coordinates:
+```json
+{
+  "lastInteractedElement": {
+    "selector": "button#checkout-btn",
+    "tag": "button",
+    "componentSource": {
+      "framework": "react",
+      "componentName": "CheckoutButton",
+      "sourceFile": "src/components/CheckoutButton.tsx",
+      "sourceLine": 42,
+      "hierarchy": ["App", "ShopLayout", "CheckoutButton"]
+    }
+  }
+}
+```
+
+### In `get_note`:
+```json
+{
+  "elementContext": {
+    "selector": ".user-profile-card",
+    "componentSource": {
+      "framework": "vue",
+      "componentName": "UserProfileCard",
+      "sourceFile": "src/components/UserProfileCard.vue"
+    }
+  }
+}
+```
+
+The AI agent can immediately edit the exact file and line without running codebase searches or guessing CSS selectors!
+
+---
+
+## 🎨 Interactive Visual Badges in Browser
+
+When inspecting elements or viewing saved notes on screen:
+- The Note Editor modal displays a purple pill: `🧬 <CheckoutButton> (src/components/CheckoutButton.tsx:42)`.
+- The Note Details Card popover displays the component badge and framework tag (`REACT`, `VUE`, `SVELTE`).

package/docs/index.md

@@ -39,8 +39,10 @@ graph TD
 
 - [Getting Started](./getting-started.md) — Quick installation and setup in under 2 minutes.
 - [Visual Notes & Annotations](./visual-notes.md) — Screen notes, region selection, and persistent markers.
+- [Multi-Step Scenarios & Flows](./scenarios-flows.md) — Sequential reproduction flows, Save & Next Step, and stepper walk-throughs.
+- [Component & Source Resolver](./component-resolver.md) — Map live DOM elements to React Fiber, Vue VNode, Svelte, and exact source file locations.
 - [Incidents & Error Diagnostics](./incidents-diagnostics.md) — Ingest runtime errors, stack traces, and breadcrumbs.
 - [Closed-Loop Verification](./closed-loop-verification.md) — Automated bug-fix and layout verification.
-- [MCP Tool Reference](./mcp-reference.md) — Complete guide to all 16 MCP tools.
+- [MCP Tool Reference](./mcp-reference.md) — Complete guide to all MCP tools.
 - [Security & Redaction](./security-privacy.md) — Privacy architecture and `@visulima/redact` integration.
 - [CLI Reference](./cli.md) — Command-line interface usage.

package/docs/mcp-reference.md

@@ -24,7 +24,7 @@ Lists recorded browser runtime errors, unhandled rejections, and console errors
 Retrieves compact, high-signal debugging context for an error incident.
 - **Arguments**:
   - `incidentId` (`string`, *required*): The unique ID of the incident (e.g. `inc_19a31a28`).
-- **Returns**: Stack trace, normalized error message, breadcrumbs timeline, failed network calls, last interacted element, error screenshot.
+- **Returns**: Stack trace, normalized error message, breadcrumbs timeline, failed network calls, last interacted element (with `componentSource`: component name, source file, line number, hierarchy), and error screenshot.
 
 ### `get_console`
 Fetches recent console logs, warnings, and errors from a browser session.
@@ -65,13 +65,26 @@ Lists visual annotations left on elements, regions, or pages during development.
 - **Arguments**:
   - `status` (`string`): `OPEN`, `IN_PROGRESS`, `VERIFYING`, `RESOLVED`, `FAILED`, `INCONCLUSIVE` (default: `OPEN`).
   - `projectId` (`string`): Filter by project ID or name.
+  - `scenarioId` (`string`): Filter notes by scenario / flow ID.
   - `limit` (`number`): Max notes (default: 20).
 
+### `list_scenarios`
+Lists multi-step user reproduction scenarios and sequential interaction flows.
+- **Arguments**:
+  - `projectId` (`string`): Filter scenarios by project ID or name.
+  - `status` (`string`): Filter by `OPEN` or `RESOLVED`.
+  - `limit` (`number`): Max scenarios (default: 20).
+
+### `get_scenario`
+Retrieves full chronological step-by-step reproduction flow with selectors, route, screenshots, and action details.
+- **Arguments**:
+  - `scenarioId` (`string`, *required*): The unique ID of the scenario / flow (e.g. `scen_checkout_123`).
+
 ### `get_note`
 Retrieves full debugging context for a visual note.
 - **Arguments**:
   - `noteId` (`string`, *required*): The unique ID of the visual note (e.g. `note_30a89599`).
-- **Returns**: Note message, route, viewport dimensions, target element selector, DOM context, screenshot file path.
+- **Returns**: Note message, route, viewport dimensions, target element selector, DOM context (including `componentSource` with framework, component name, source file path, and line number), screenshot file path, scenario metadata.
 
 ### `capture_note_context`
 Inspects live DOM context, bounding box, overflow, and computed styles for a target element.

package/docs/scenarios-flows.md

@@ -0,0 +1,86 @@
+---
+title: Multi-Step Scenarios & Flows
+description: Record sequential user flows, multi-step bug reproduction journeys, on-screen step pins, and MCP flow retrieval
+order: 4
+---
+
+# Multi-Step Scenarios & Flows 🎬
+
+BrowserTrack allows developers, testers, and designers to record sequential multi-step user reproduction scenarios (e.g., *"First I clicked this, then I entered this promo code, and here is where the price overflow occurred"*).
+
+---
+
+## ⚡ Continuous Recording Workflow (Save & Next Step)
+
+Instead of manually reopening tools for each step, BrowserTrack provides a continuous capture loop:
+
+```mermaid
+graph LR
+    A[🎬 Start Flow] -->|Click Element 1| B[Step 1 Modal]
+    B -->|➡️ Save & Next Step| C[Hover Element 2]
+    C -->|Click Element 2| D[Step 2 Modal]
+    D -->|➡️ Save & Next Step| E[Drag Region 3]
+    E -->|✓ Save & Finish Flow| F[Complete Multi-Step Scenario]
+```
+
+1. **Start Recording**: Click **`🎬 Flow`** in the floating bottom-right dock (or click **`➡️ Save as Step 1 (Flow)`** from any note).
+2. **Step Progression**:
+   - Hover and click the first target element (or drag a region).
+   - Enter your description/action.
+   - Click **`➡️ Save & Next Step`** (or press <kbd>⌘+Enter</kbd> / <kbd>Ctrl+Enter</kbd>).
+   - The step is saved instantly, the counter increments to Step 2, and the inspector automatically reactivates element inspection mode so you can immediately click the next element without touching the toolbar!
+3. **Finish Recording**: On the final step, click **`✓ Save & Finish Flow`** or click the active **`🎬 Step N (Finish)`** button in the dock.
+
+---
+
+## 📌 Numbered Step Markers on Screen
+
+When notes belong to a scenario:
+- **Glowing Amber/Cyan Step Pins**: Displayed on target elements with **`🎬 Step 1`**, **`🎬 Step 2`**, **`🎬 Step 3`** badges.
+- **Dynamic Anchoring**: Pins remain attached to elements during scrolling, viewport resizing, or SPA route transitions.
+
+---
+
+## 🔍 Interactive Stepper Walk-Through
+
+Clicking any step pin opens the Note & Scenario Card:
+
+- **Header**: Shows the scenario title and current step (e.g. `🎬 Step 2 of 4: Checkout Promo Flow`).
+- **Sequential Stepper Bar**:
+  - Click **`◀ Step 1`** to inspect the previous action.
+  - Click **`Step 3 ▶`** to advance to the next action.
+- **Actions**:
+  - **`✅ Resolve Note`**: Mark individual steps as resolved.
+  - **`🗑️ Delete`**: Delete single step.
+  - **`🗑️ Delete Flow`**: Wipe the entire multi-step scenario from the database.
+
+---
+
+## 🤖 AI Coding Agent MCP Integration
+
+AI agents can retrieve the full step-by-step reproduction journey using MCP tools:
+
+### 1. `list_scenarios`
+Lists all recorded scenarios for a project with total step counts and statuses.
+
+### 2. `get_scenario`
+Retrieves all ordered steps in chronological sequence with selectors, bounding boxes, routes, and screenshots.
+
+```typescript
+// Example agent query
+const scenario = await client.callTool("get_scenario", {
+  scenarioId: "scen_checkout_123"
+});
+
+// Returns:
+// {
+//   id: "scen_checkout_123",
+//   title: "Checkout Promo Flow",
+//   stepsCount: 3,
+//   steps: [
+//     { stepNumber: 1, type: "element", message: "Click Cart button", targetSelector: "#btn-cart", route: "/shop" },
+//     { stepNumber: 2, type: "element", message: "Enter coupon PROMO", targetSelector: "#input-coupon", route: "/cart" },
+//     { stepNumber: 3, type: "region", message: "Price overflow", route: "/cart", screenshot: "..." }
+//   ]
+// }
+```