browsertrack 0.2.0 → 0.2.1

package/packages/client/src/config.ts

@@ -12,12 +12,25 @@ export interface BrowserDiagClientOptions {
     enabled?: boolean;
     shortcut?: string;
     showBadges?: boolean;
+    showToolbar?: boolean;
     maskSelectors?: string[];
   };
+  /**
+   * Hide visible BrowserTrack UI (toolbar dock, pins, hover overlay) by default.
+   */
+  hidden?: boolean;
+  /**
+   * Custom query parameter(s) used to hide the UI (e.g. 'e2e', 'no_ui', 'clean').
+   * Built-in query params like ?bt=0, ?bt=false, ?bt=hidden, ?browsertrack=false, ?no_bt are supported automatically.
+   */
+  hideQueryParam?: string | string[];
   debug?: boolean;
 }
 
-export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes'>> & { notes: Required<NonNullable<BrowserDiagClientOptions['notes']>> } = {
+export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes' | 'hideQueryParam'>> & {
+  hideQueryParam?: string | string[];
+  notes: Required<NonNullable<BrowserDiagClientOptions['notes']>>;
+} = {
   daemonUrl: 'ws://127.0.0.1:7331',
   projectId: '',
   maxBreadcrumbs: 50,
@@ -31,7 +44,77 @@ export const DEFAULT_OPTIONS: Required<Omit<BrowserDiagClientOptions, 'notes'>>
     enabled: true,
     shortcut: 'Alt+Click',
     showBadges: true,
+    showToolbar: true,
     maskSelectors: ['input[type="password"]', '[data-sensitive]'],
   },
+  hidden: false,
+  hideQueryParam: undefined,
   debug: false,
 };
+
+const HIDE_VALUES = new Set(['0', 'false', 'hidden', 'hide', 'off', 'none', 'disabled', 'ui_off', 'silent']);
+
+/**
+ * Checks if the tool's visible UI should be hidden based on URL search query parameters.
+ */
+export function shouldHideUIFromUrl(customParam?: string | string[], searchString?: string): boolean {
+  let search = searchString;
+  if (search === undefined) {
+    if (typeof window === 'undefined' || !window.location) return false;
+    search = window.location.search;
+  }
+
+  if (!search) return false;
+
+  try {
+    const params = new URLSearchParams(search);
+
+    // 1. Check custom parameters if configured
+    if (customParam) {
+      const customKeys = Array.isArray(customParam) ? customParam : [customParam];
+      for (const key of customKeys) {
+        if (params.has(key)) {
+          const val = (params.get(key) || '').toLowerCase().trim();
+          if (val === '' || val === '1' || val === 'true' || HIDE_VALUES.has(val)) {
+            return true;
+          }
+        }
+      }
+    }
+
+    // 2. Boolean flags without values or with 1/true: ?no_bt, ?no_browsertrack, ?hide_bt, ?hide_browsertrack
+    for (const flag of ['no_bt', 'no_browsertrack', 'hide_bt', 'hide_browsertrack']) {
+      if (params.has(flag)) {
+        const val = (params.get(flag) || '').toLowerCase().trim();
+        if (val === '' || val === '1' || val === 'true' || val === 'yes') {
+          return true;
+        }
+      }
+    }
+
+    // 3. Value-based parameters: ?bt=false, ?bt=0, ?bt=hidden, ?bt=off
+    if (params.has('bt')) {
+      const val = (params.get('bt') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val)) return true;
+    }
+
+    if (params.has('browsertrack')) {
+      const val = (params.get('browsertrack') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val)) return true;
+    }
+
+    if (params.has('bt_ui')) {
+      const val = (params.get('bt_ui') || '').toLowerCase().trim();
+      if (HIDE_VALUES.has(val) || val === '0' || val === 'false') return true;
+    }
+
+    if (params.has('bt_hide')) {
+      const val = (params.get('bt_hide') || '').toLowerCase().trim();
+      if (val === '' || val === '1' || val === 'true') return true;
+    }
+  } catch {
+    // Defensive in non-standard environments
+  }
+
+  return false;
+}

package/packages/client/src/index.ts

@@ -7,6 +7,7 @@ export * from './breadcrumbs.js';
 export * from './screenshot/driver.js';
 export * from './screenshot/browser-script-driver.js';
 export * from './notes/inspector.js';
+export * from './source/resolver.js';
 
 let defaultClient: BrowserTrackClient | null = null;
 
@@ -40,9 +41,11 @@ if (typeof window !== 'undefined') {
     const autoInit = currentScript?.getAttribute('data-auto-init') !== 'false';
     const daemonUrl = currentScript?.getAttribute('data-daemon-url') || undefined;
     const projectId = currentScript?.getAttribute('data-project-id') || undefined;
+    const hidden = currentScript?.getAttribute('data-hidden') === 'true';
+    const hideQueryParam = currentScript?.getAttribute('data-hide-query-param') || undefined;
 
     if (autoInit) {
-      init({ daemonUrl, projectId });
+      init({ daemonUrl, projectId, hidden, hideQueryParam });
     }
   } catch {
     // If auto-start fails, don't crash

package/packages/client/src/interceptors/interaction.ts

@@ -1,5 +1,6 @@
 import type { Breadcrumb, ElementSummary } from '../../../core/src/index.js';
 import { getSemanticSelector, truncate } from '../../../core/src/index.js';
+import { resolveComponentSource } from '../source/resolver.js';
 
 export type InteractionCallback = (breadcrumb: Breadcrumb, elementSummary?: ElementSummary) => void;
 
@@ -12,6 +13,7 @@ export function extractElementSummary(el: HTMLElement | Element): ElementSummary
   const tag = el.tagName.toLowerCase();
   const id = el.id || undefined;
   const classes = Array.from(el.classList || []);
+  const componentSource = resolveComponentSource(el as HTMLElement);
 
   let boundingRect: ElementSummary['boundingRect'] = undefined;
   let visible = true;
@@ -53,6 +55,7 @@ export function extractElementSummary(el: HTMLElement | Element): ElementSummary
     visible,
     innerText,
     outerHTML,
+    componentSource,
   };
 }
 

package/packages/client/src/notes/inspector.ts

@@ -2,6 +2,8 @@ import type { ElementContext, NoteTarget, RegionContext, VisualNote } from '../.
 import { getSemanticSelector, truncate } from '../../../core/src/index.js';
 import type { ScreenshotDriver } from '../screenshot/driver.js';
 import type { WebSocketTransport } from '../transport/websocket.js';
+import { shouldHideUIFromUrl } from '../config.js';
+import { resolveComponentSource } from '../source/resolver.js';
 
 export type NoteInspectMode = 'element' | 'region' | 'page' | 'idle';
 
@@ -9,6 +11,9 @@ export interface InspectorOptions {
   shortcut?: string; // e.g. "Alt+Click"
   maskSelectors?: string[];
   showToolbar?: boolean;
+  showBadges?: boolean;
+  hidden?: boolean;
+  hideQueryParam?: string | string[];
   onNoteCreated?: (note: Partial<VisualNote>) => void;
 }
 
@@ -28,6 +33,7 @@ export interface ActiveScenarioState {
  * 5. Real-time Saved Note & Step Markers (pins with step sequencing numbers)
  * 6. Interactive Note & Step Detail Card (with previous/next step walk-through navigation)
  * 7. Floating quick dock / toolbar in bottom-right corner with Notes count and Flow controls
+ * 8. Automatic invisibility via query parameter (?bt=0, ?bt=false, ?bt=hidden, ?no_bt, custom query params)
  */
 export class NoteInspector {
   private transport: WebSocketTransport;
@@ -58,15 +64,20 @@ export class NoteInspector {
 
   private savedNotes: VisualNote[] = [];
   private showMarkers = true;
+  private isHidden = false;
   private cleanups: (() => void)[] = [];
 
   constructor(transport: WebSocketTransport, screenshotDriver: ScreenshotDriver, options: InspectorOptions = {}) {
     this.transport = transport;
     this.screenshotDriver = screenshotDriver;
+    const hiddenByQuery = shouldHideUIFromUrl(options.hideQueryParam);
+    this.isHidden = options.hidden === true || hiddenByQuery;
+    this.showMarkers = options.showBadges !== false && !this.isHidden;
     this.options = {
       shortcut: 'Alt+Click',
       maskSelectors: ['input[type="password"]', '[data-sensitive]'],
       showToolbar: true,
+      showBadges: true,
       ...options,
     };
   }
@@ -158,6 +169,44 @@ export class NoteInspector {
     }
   }
 
+  public isVisible(): boolean {
+    return !this.isHidden;
+  }
+
+  public setVisible(visible: boolean): void {
+    this.isHidden = !visible;
+    this.showMarkers = this.options.showBadges !== false && !this.isHidden;
+
+    if (this.container) {
+      this.container.style.display = this.isHidden ? 'none' : 'block';
+    }
+
+    if (this.toolbarElement) {
+      this.toolbarElement.style.display = this.isHidden ? 'none' : 'flex';
+    } else if (!this.isHidden && this.options.showToolbar !== false) {
+      this.createToolbar();
+    }
+
+    if (this.isHidden) {
+      this.hideHighlight();
+      this.hideRegionOverlay();
+      if (this.modalOverlay && this.shadowRoot) {
+        this.shadowRoot.removeChild(this.modalOverlay);
+        this.modalOverlay = null;
+      }
+      if (this.cardOverlay && this.shadowRoot) {
+        this.shadowRoot.removeChild(this.cardOverlay);
+        this.cardOverlay = null;
+      }
+      if (this.markersContainer) {
+        this.markersContainer.innerHTML = '';
+      }
+    } else {
+      this.renderMarkers();
+      this.updateToolbarCount();
+    }
+  }
+
   private ensureContainer(): ShadowRoot | null {
     if (typeof document === 'undefined') return null;
 
@@ -166,6 +215,9 @@ export class NoteInspector {
       this.container.id = 'browsertrack-inspector-host';
       this.container.style.cssText =
         'all: initial; position: fixed; top: 0; left: 0; width: 0; height: 0; z-index: 2147483647; pointer-events: none;';
+      if (this.isHidden) {
+        this.container.style.display = 'none';
+      }
 
       this.shadowRoot = this.container.attachShadow({ mode: 'open' });
 
@@ -611,6 +663,22 @@ export class NoteInspector {
           color: #cbd5e1;
         }
 
+        .bt-component-pill {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          background: rgba(15, 23, 42, 0.95);
+          border: 1px solid rgba(99, 102, 241, 0.35);
+          border-radius: 6px;
+          padding: 6px 10px;
+          font-size: 11.5px;
+          color: #c7d2fe;
+          font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+
         .bt-scenario-stepper {
           display: flex;
           align-items: center;
@@ -859,7 +927,7 @@ export class NoteInspector {
       this.shadowRoot.appendChild(this.toastContainer);
 
       // Floating Toolbar
-      if (this.options.showToolbar) {
+      if (this.options.showToolbar && !this.isHidden) {
         this.createToolbar();
       }
     }
@@ -978,7 +1046,7 @@ export class NoteInspector {
     if (!root || !this.markersContainer) return;
 
     this.markersContainer.innerHTML = '';
-    if (!this.showMarkers) return;
+    if (!this.showMarkers || this.isHidden) return;
 
     const currentPath = window.location.pathname;
     // Filter open notes on this route or global
@@ -1143,6 +1211,32 @@ export class NoteInspector {
 
         ${scenarioStepsHtml}
 
+        ${
+          note.elementContext?.componentSource?.componentName
+            ? `<div class="bt-component-pill" title="${
+                note.elementContext.componentSource.sourceFile
+                  ? note.elementContext.componentSource.sourceFile +
+                    (note.elementContext.componentSource.sourceLine ? ':' + note.elementContext.componentSource.sourceLine : '')
+                  : note.elementContext.componentSource.componentName
+              }">
+                <span>🧬</span>
+                <span style="font-weight: 600; color: #a5b4fc;">&lt;${note.elementContext.componentSource.componentName}&gt;</span>
+                ${
+                  note.elementContext.componentSource.sourceFile
+                    ? `<span style="color: #64748b; font-size: 11px; margin-left: 4px;">${note.elementContext.componentSource.sourceFile}${
+                        note.elementContext.componentSource.sourceLine ? ':' + note.elementContext.componentSource.sourceLine : ''
+                      }</span>`
+                    : ''
+                }
+                ${
+                  note.elementContext.componentSource.framework
+                    ? `<span class="bt-mode-badge" style="background: rgba(99, 102, 241, 0.15); color: #818cf8; margin-left: auto; font-size: 10px;">${note.elementContext.componentSource.framework.toUpperCase()}</span>`
+                    : ''
+                }
+              </div>`
+            : ''
+        }
+
         <div class="bt-target-pill" title="${contextText}">
           <span>🏷️</span>
           <span class="bt-pill-content">${contextText}</span>
@@ -1249,7 +1343,7 @@ export class NoteInspector {
   private setupListeners(): void {
     // 1. Mouse move: hover highlight in element mode or with Alt key
     const onMouseMove = (e: MouseEvent) => {
-      if (this.modalOverlay || this.cardOverlay || this.isDraggingRegion || this.activeMode === 'region') return;
+      if (this.isHidden || this.modalOverlay || this.cardOverlay || this.isDraggingRegion || this.activeMode === 'region') return;
 
       // Don't highlight elements if mouse is over our own inspector UI
       const path = e.composedPath ? e.composedPath() : [];
@@ -1274,7 +1368,7 @@ export class NoteInspector {
 
     // 2. Click: Alt+Click or Element mode click selects element and opens editor
     const onClick = (e: MouseEvent) => {
-      if (this.modalOverlay || this.cardOverlay) return;
+      if (this.isHidden || this.modalOverlay || this.cardOverlay) return;
 
       // If clicking inside inspector toolbar or container, do NOT intercept
       const path = e.composedPath ? e.composedPath() : [];
@@ -1505,6 +1599,11 @@ export class NoteInspector {
       this.updateHighlight(targetEl);
     }
 
+    const comp = noteType === 'element' ? resolveComponentSource(targetEl) : undefined;
+    const compPrefix = comp?.componentName
+      ? `🧬 <${comp.componentName}>${comp.sourceFile ? ' (' + comp.sourceFile + (comp.sourceLine ? ':' + comp.sourceLine : '') + ')' : ''} · `
+      : '';
+
     this.renderNoteModal({
       title: this.activeScenario
         ? `Step ${this.activeScenario.stepNumber}: ${this.activeScenario.title}`
@@ -1513,7 +1612,7 @@ export class NoteInspector {
       pillText:
         noteType === 'page'
           ? `Page Viewport: ${window.innerWidth} × ${window.innerHeight} px`
-          : `${getSemanticSelector(targetEl)} (${Math.round(targetEl.getBoundingClientRect().width)}×${Math.round(targetEl.getBoundingClientRect().height)}) · Viewport: ${window.innerWidth}×${window.innerHeight}`,
+          : `${compPrefix}${getSemanticSelector(targetEl)} (${Math.round(targetEl.getBoundingClientRect().width)}×${Math.round(targetEl.getBoundingClientRect().height)}) · Viewport: ${window.innerWidth}×${window.innerHeight}`,
       onSave: async (message, action) => {
         let scenarioParam: { scenarioId?: string; stepNumber?: number; scenarioTitle?: string } | undefined;
 
@@ -1863,12 +1962,15 @@ export class NoteInspector {
       innerText = truncate(innerText, 200);
     }
 
+    const componentSource = resolveComponentSource(el);
+
     return {
       selector,
       tag: el.tagName.toLowerCase(),
       attributes,
       outerHTML,
       innerText,
+      componentSource,
       parent: el.parentElement
         ? {
             selector: getSemanticSelector(el.parentElement),

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;

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,