browsertrack 0.2.0 → 0.2.2

package/dist/{notes-BMnonq46.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,117 +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;
-    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;
-}
-
-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, 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, ScenarioOverview as t, ScrollContext as u, VisualNote as v };
+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 ScenarioDetail, t as ScenarioOverview, u as ScrollContext, V as ViewportContext, v as VisualNote } from '../notes-BMnonq46.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-D5J-egVN.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';
 
@@ -83,4 +83,27 @@ declare function getSemanticSelector(element: HTMLElement | Element, options?: S
  */
 declare function truncate(str: string | undefined | null, maxLength?: number): string;
 
-export { BROWSER_SECURITY_RULES, type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate };
+/**
+ * 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.
+ */
+declare function safeJsonParse<T>(raw: any, fallback: T): T;
+/**
+ * Safely serializes an object to JSON, handling circular references and non-serializable values.
+ * Never throws "TypeError: Converting circular structure to JSON".
+ */
+declare function safeJsonStringify(val: any, fallback?: string): string;
+/**
+ * Executes a synchronous function within an isolated try/catch block.
+ * Returns the function result, or fallback if an exception was thrown.
+ */
+declare function safeExecute<T>(fn: () => T, fallback: T, onError?: (err: any) => void): T;
+/**
+ * Executes an asynchronous promise or async function safely without unhandled rejection.
+ */
+declare function safeAsync<T>(action: Promise<T> | (() => Promise<T>), fallback: T, onError?: (err: any) => void): Promise<T>;
+
+export { BROWSER_SECURITY_RULES, type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, safeAsync, safeExecute, safeJsonParse, safeJsonStringify, truncate };

package/dist/core/index.js

@@ -12,10 +12,14 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact
-} from "../chunk-6VA7GBAO.js";
+} from "../chunk-QRZ57ME3.js";
 export {
   BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
@@ -30,6 +34,10 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact

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-B43IohQY.js';
-import { c as ClientEventMessage } from '../notes-BMnonq46.js';
-import { I as Incident } from '../projects-D5J-egVN.js';
+import { S as StorageDB, b as ScreenshotStore, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine, c as NotesEngine } 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';
 
@@ -25,7 +25,7 @@ declare class IncidentEngine {
     private handleErrorEvent;
 }
 
-declare function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+declare function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string, verificationEngine?: VerificationEngine, noteVerificationEngine?: NoteVerificationEngine): (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
 
 declare function setupWebSocketServer(wss: WebSocketServer, db: StorageDB, sessionManager: SessionManager, incidentEngine: IncidentEngine, notesEngine?: NotesEngine, maxEventsPerSession?: number, verbose?: boolean): void;
 

package/dist/daemon/index.js

@@ -1,20 +1,18 @@
 import {
   BrowserTrackDaemon,
   IncidentEngine,
-  createDaemon,
-  createHttpHandler,
-  setupWebSocketServer
-} from "../chunk-7OCOQGDN.js";
-import "../chunk-6VA7GBAO.js";
-import {
   NoteVerificationEngine,
   NotesEngine,
   ScreenshotStore,
   SessionManager,
   StorageDB,
   VerificationEngine,
-  getDaemonConfig
-} from "../chunk-3HOXPTM2.js";
+  createDaemon,
+  createHttpHandler,
+  getDaemonConfig,
+  setupWebSocketServer
+} from "../chunk-AYSVE6NG.js";
+import "../chunk-QRZ57ME3.js";
 export {
   BrowserTrackDaemon,
   IncidentEngine,

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

@@ -1,5 +1,5 @@
-import { B as Breadcrumb, i as ElementSummary, v as VisualNote, m as NoteStatus, t as ScenarioOverview, S as ScenarioDetail, p as NoteVerificationResult, d as CommandResponse, b as ClientCommand } from './notes-BMnonq46.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-D5J-egVN.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 {

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 ScenarioDetail, t as ScenarioOverview, u as ScrollContext, V as ViewportContext, v as VisualNote } from './notes-BMnonq46.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-D5J-egVN.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 { 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, safeAsync, safeExecute, safeJsonParse, safeJsonStringify, 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-BztYp1Zc.js';
+export { c as createMcpServer } from './server-DjV7RWQM.js';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
-import './engine-B43IohQY.js';
+import './engine-CmchnMDq.js';
 import 'ws';
 import 'node:http';
 import '@modelcontextprotocol/sdk/server/index.js';

package/dist/index.js

@@ -2,11 +2,14 @@ import {
   BrowserTrackClient,
   getClient,
   init
-} from "./chunk-WB7ZKWK7.js";
+} from "./chunk-4HRLW6YF.js";
+import {
+  createMcpServer
+} from "./chunk-TWEYRBDU.js";
 import {
   BrowserTrackDaemon,
   createDaemon
-} from "./chunk-7OCOQGDN.js";
+} from "./chunk-AYSVE6NG.js";
 import {
   BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
@@ -21,14 +24,14 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact
-} from "./chunk-6VA7GBAO.js";
-import {
-  createMcpServer
-} from "./chunk-UP5JKCFY.js";
-import "./chunk-3HOXPTM2.js";
+} from "./chunk-QRZ57ME3.js";
 export {
   BROWSER_SECURITY_RULES,
   BrowserTrackClient,
@@ -49,6 +52,10 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact

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-BztYp1Zc.js';
+export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall, i as isDaemonRunning } from '../server-DjV7RWQM.js';
 import '@modelcontextprotocol/sdk/server/index.js';
-import '../engine-B43IohQY.js';
-import '../notes-BMnonq46.js';
-import '../projects-D5J-egVN.js';
+import '../engine-CmchnMDq.js';
+import '../commands-fjuqKzkm.js';
+import '../projects-DB7S312i.js';
 import 'ws';
 
 declare const TOOLS: Tool[];

package/dist/mcp/index.js

@@ -1,12 +1,15 @@
 import {
   TOOLS,
   createMcpServer,
-  handleToolCall
-} from "../chunk-UP5JKCFY.js";
-import "../chunk-3HOXPTM2.js";
+  handleToolCall,
+  isDaemonRunning
+} from "../chunk-TWEYRBDU.js";
+import "../chunk-AYSVE6NG.js";
+import "../chunk-QRZ57ME3.js";
 export {
   TOOLS,
   createMcpServer,
-  handleToolCall
+  handleToolCall,
+  isDaemonRunning
 };
 //# sourceMappingURL=index.js.map

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

@@ -1,4 +1,4 @@
-import { B as Breadcrumb, l as NetworkEvent, i as ElementSummary } from './notes-BMnonq46.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-BztYp1Zc.d.ts → server-DjV7RWQM.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-B43IohQY.js';
+import { S as StorageDB, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine } from './engine-CmchnMDq.js';
 
 interface McpContext {
     db: StorageDB;
@@ -10,9 +10,14 @@ interface McpContext {
 }
 declare function handleToolCall(name: string, args: any, ctx: McpContext): Promise<any>;
 
+declare function isDaemonRunning(host: string, port: number): Promise<boolean>;
 interface McpServerOptions {
     dbPath?: string;
     context?: Partial<McpContext>;
+    autoStartDaemon?: boolean;
+    port?: number;
+    host?: string;
+    detached?: boolean;
 }
 declare function createMcpServer(options?: McpServerOptions): {
     server: Server<{
@@ -49,7 +54,10 @@ declare function createMcpServer(options?: McpServerOptions): {
             } | undefined;
         } | undefined;
     }>;
+    ctx: McpContext;
+    ensureDaemon: () => Promise<void>;
+    stopDaemon(): Promise<void>;
     startStdio(): Promise<void>;
 };
 
-export { type McpContext as M, type McpServerOptions as a, createMcpServer as c, handleToolCall as h };
+export { type McpContext as M, type McpServerOptions as a, createMcpServer as c, handleToolCall as h, isDaemonRunning as i };

package/docs/cli.md

@@ -35,9 +35,12 @@ browsertrack clear             # Wipe stored logs, screenshots, and incidents
 
 ### MCP Integration
 ```bash
-browsertrack mcp               # Start Model Context Protocol server over stdio
+browsertrack mcp               # Start Model Context Protocol server over stdio (auto-boots singleton daemon if offline)
+browsertrack mcp --no-daemon   # Start MCP server without auto-booting background daemon
 ```
 
+> **⚡ Singleton Daemon Lifecycle**: When starting `browsertrack mcp`, BrowserTrack automatically checks if the daemon is already running. If offline, it starts a single, persistent background daemon on `http://127.0.0.1:7331`. All IDE windows, workspaces, and sub-sessions share this single daemon without spawning duplicates or conflicting on ports.
+
 ---
 
 ## 📖 Documentation Commands (Docboot)

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`).