browsertrack 0.2.2 → 0.2.3

package/packages/core/src/selector.ts

@@ -6,23 +6,26 @@ export interface SelectorOptions {
   maxClasses?: number;
   maxOuterHTMLLength?: number;
   maxInnerTextLength?: number;
+  maxParentDepth?: number;
 }
 
 /**
  * Builds a clean, human-readable semantic selector for a DOM element.
- * Prioritizes data-testid/data-test, id, semantic tag + specific class, or concise parent path.
+ * Prioritizes data-testid/data-component, id, semantic tag + curated class, aria/role, or concise unique parent path.
  */
 export function getSemanticSelector(element: HTMLElement | Element, options: SelectorOptions = {}): string {
   if (!element || !element.tagName) return 'unknown';
 
   const maxClasses = options.maxClasses ?? 2;
+  const maxParentDepth = options.maxParentDepth ?? 3;
 
-  // 1. Check for standard test attributes
+  // 1. Check for standard test or component attributes
   const testId =
     element.getAttribute('data-testid') ||
     element.getAttribute('data-test') ||
     element.getAttribute('data-cy') ||
-    element.getAttribute('data-qa');
+    element.getAttribute('data-qa') ||
+    element.getAttribute('data-component');
 
   if (testId) {
     return `[data-testid="${testId}"]`;
@@ -34,21 +37,43 @@ export function getSemanticSelector(element: HTMLElement | Element, options: Sel
     return `#${id}`;
   }
 
-  // 3. Check for aria-label or name on buttons/inputs
+  const tag = element.tagName.toLowerCase();
+
+  // 3. Check for aria-label, role, title or name on interactive elements
   const ariaLabel = element.getAttribute('aria-label');
-  if (ariaLabel && ariaLabel.length < 30) {
-    return `${element.tagName.toLowerCase()}[aria-label="${ariaLabel}"]`;
+  if (ariaLabel && ariaLabel.length < 40) {
+    return `${tag}[aria-label="${ariaLabel}"]`;
+  }
+
+  const role = element.getAttribute('role');
+  if (role && !['presentation', 'none'].includes(role)) {
+    const roleSelector = `${tag}[role="${role}"]`;
+    if (tag === 'button' || tag === 'a' || tag === 'nav' || tag === 'dialog') {
+      return roleSelector;
+    }
   }
 
   const nameAttr = element.getAttribute('name');
   if (nameAttr) {
-    return `${element.tagName.toLowerCase()}[name="${nameAttr}"]`;
+    return `${tag}[name="${nameAttr}"]`;
+  }
+
+  const titleAttr = element.getAttribute('title');
+  if (titleAttr && titleAttr.length < 30) {
+    return `${tag}[title="${titleAttr}"]`;
   }
 
   // 4. Tag + curated classes
-  const tag = element.tagName.toLowerCase();
-  const classList = Array.from(element.classList || [])
-    .filter((c) => !c.startsWith('css-') && !c.startsWith('_') && !/^[a-z0-9]{5,}$/i.test(c)) // filter hashed utility classes
+  const rawClassList = Array.from(element.classList || []);
+  const classList = rawClassList
+    .filter(
+      (c) =>
+        !c.startsWith('css-') &&
+        !c.startsWith('_') &&
+        !/^[a-z0-9]{5,}$/i.test(c) && // filter dynamic hashed utility classes
+        !c.includes(':') && // Tailwind pseudo-class prefixes (hover:, md:, etc.)
+        !c.includes('[') // Tailwind arbitrary value classes
+    )
     .slice(0, maxClasses);
 
   if (classList.length > 0) {
@@ -56,17 +81,87 @@ export function getSemanticSelector(element: HTMLElement | Element, options: Sel
     return `${tag}${classStr}`;
   }
 
-  // 5. If generic element (div, span, p) without attributes, try parent context
-  if (element.parentElement && element.parentElement !== document.body && element.parentElement !== document.documentElement) {
-    const parentSelector = getSemanticSelector(element.parentElement, { maxClasses: 1 });
-    if (parentSelector && parentSelector !== 'unknown' && !parentSelector.includes('>')) {
-      return `${parentSelector} > ${tag}`;
+  // 5. If generic element (div, span, p, li) without attributes, try parent context & nth-of-type
+  const hasParent =
+    element.parentElement &&
+    (typeof document === 'undefined' ||
+      (element.parentElement !== document.body && element.parentElement !== document.documentElement));
+
+  if (hasParent) {
+    let suffix = '';
+    // Calculate nth-of-type if siblings of same tag exist
+    if (element.parentElement.children && element.parentElement.children.length > 1) {
+      const sameTagSiblings = Array.from(element.parentElement.children).filter(
+        (child: any) => child.tagName && child.tagName.toLowerCase() === tag
+      );
+      if (sameTagSiblings.length > 1) {
+        const index = sameTagSiblings.indexOf(element) + 1;
+        if (index > 0) {
+          suffix = `:nth-of-type(${index})`;
+        }
+      }
+    }
+
+    if (maxParentDepth > 0) {
+      const parentSelector = getSemanticSelector(element.parentElement, {
+        maxClasses: 1,
+        maxParentDepth: maxParentDepth - 1,
+      });
+      if (parentSelector && parentSelector !== 'unknown' && parentSelector !== 'body' && parentSelector !== 'html') {
+        return `${parentSelector} > ${tag}${suffix}`;
+      }
+    }
+
+    if (suffix) {
+      return `${tag}${suffix}`;
     }
   }
 
   return tag;
 }
 
+/**
+ * If an element under the cursor is an inline or leaf formatting element
+ * (e.g. svg, path, i, b, strong, or an inner span without attributes)
+ * inside an interactive container or component, resolves to the parent container.
+ */
+export function resolveMeaningfulTarget(element: HTMLElement | Element): HTMLElement {
+  if (!element || typeof element !== 'object') {
+    return element as HTMLElement;
+  }
+
+  const el = element as HTMLElement;
+
+  // 1. If element is inside an SVG or is an SVG child (path, circle, rect, g, svg)
+  const isSvg = el.tagName.toLowerCase() === 'svg' || el.namespaceURI?.includes('svg');
+  if (isSvg || el.closest?.('svg')) {
+    const interactiveParent = el.closest?.(
+      'button, a, [role="button"], [role="link"], [role="tab"], summary, label, [data-testid], [data-component]'
+    ) as HTMLElement | null;
+    if (interactiveParent) return interactiveParent;
+    const svgEl = isSvg ? el : (el.closest?.('svg') as HTMLElement | null);
+    if (svgEl) return svgEl;
+  }
+
+  // 2. Minor leaf tags (span, i, em, b, strong, small) with no distinct attributes inside interactive element
+  const leafTags = ['span', 'i', 'em', 'b', 'strong', 'small', 'mark', 'code'];
+  const tag = el.tagName.toLowerCase();
+  if (
+    leafTags.includes(tag) &&
+    !el.id &&
+    !el.getAttribute('data-testid') &&
+    !el.getAttribute('data-component') &&
+    !el.getAttribute('aria-label')
+  ) {
+    const interactiveParent = el.closest?.(
+      'button, a, [role="button"], [role="link"], [role="tab"], [role="menuitem"], summary, label, [data-testid], [data-component]'
+    ) as HTMLElement | null;
+    if (interactiveParent) return interactiveParent;
+  }
+
+  return el;
+}
+
 /**
  * Truncates string to specified max length with ellipsis
  */

package/packages/mcp/src/handlers.ts

@@ -9,9 +9,16 @@ export interface McpContext {
   verificationEngine?: VerificationEngine;
   noteVerificationEngine?: NoteVerificationEngine;
   daemonUrl?: string;
+  daemonInitPromise?: Promise<void>;
 }
 
 async function sendSessionCommand(ctx: McpContext, sessionId: string | undefined, command: any, timeoutMs = 5000): Promise<any> {
+  if (ctx.daemonInitPromise) {
+    try {
+      await Promise.race([ctx.daemonInitPromise, new Promise((r) => setTimeout(r, 2000))]);
+    } catch {}
+  }
+
   // 1. In-process session manager (if active sockets exist)
   if (ctx.sessionManager && ctx.sessionManager.getActiveCount() > 0) {
     const targetSession = sessionId ? ctx.db.getSession(sessionId) : ctx.sessionManager.getAnyActiveSession();

package/packages/mcp/src/server.ts

@@ -159,13 +159,21 @@ export function createMcpServer(options: McpServerOptions = {}) {
         const cliPath = resolveCliPath();
         if (cliPath && fs.existsSync(cliPath)) {
           try {
+            const nodePaths = [
+              '/usr/local/bin',
+              '/opt/homebrew/bin',
+              process.env.HOME ? `${process.env.HOME}/.nvm/versions/node/v20.19.5/bin` : '',
+              process.env.HOME ? `${process.env.HOME}/.nvm/versions/node/v23.1.0/bin` : '',
+            ].filter(Boolean);
+            const extendedPath = `${process.env.PATH || ''}:${nodePaths.join(':')}`;
+
             const child = spawn(
               process.execPath,
               [cliPath, 'start', '--port', String(config.port), '--host', config.host],
               {
                 detached: true,
                 stdio: 'ignore',
-                env: { ...process.env, BROWSERTRACK_DAEMON_DETACHED: '1' },
+                env: { ...process.env, PATH: extendedPath, BROWSERTRACK_DAEMON_DETACHED: '1' },
               }
             );
             child.unref();
@@ -245,7 +253,11 @@ export function createMcpServer(options: McpServerOptions = {}) {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-      const result = await handleToolCall(name, args || {}, ctx);
+      // 20-second safety timeout so tool execution never hangs indefinitely
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Tool execution timed out after 20s: ${name}`)), 20000)
+      );
+      const result = await Promise.race([handleToolCall(name, args || {}, ctx), timeoutPromise]);
       return {
         content: [
           {
@@ -278,9 +290,15 @@ export function createMcpServer(options: McpServerOptions = {}) {
       }
     },
     async startStdio() {
-      await ensureDaemon();
+      // Connect stdio transport immediately so client handshakes are answered instantly
       const transport = new StdioServerTransport();
       await server.connect(transport);
+
+      // Start daemon verification / auto-boot asynchronously in background so client handshakes never block
+      const daemonInitPromise = ensureDaemon().catch((err) => {
+        console.error(`[BrowserTrack MCP] Daemon background init note: ${err?.message || err}`);
+      });
+      ctx.daemonInitPromise = daemonInitPromise;
     },
   };
 }

package/test/core/selector.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+import { getSemanticSelector, resolveMeaningfulTarget } from '../../packages/core/src/index.js';
+
+function createMockElement(options: {
+  tagName: string;
+  id?: string;
+  classList?: string[];
+  attributes?: Record<string, string>;
+  parentElement?: any;
+  children?: any[];
+  closest?: (sel: string) => any;
+}): any {
+  const attrs = options.attributes || {};
+  const el: any = {
+    tagName: options.tagName.toUpperCase(),
+    id: options.id || '',
+    classList: options.classList || [],
+    parentElement: options.parentElement || null,
+    children: options.children || [],
+    getAttribute: (name: string) => attrs[name] || null,
+    closest: options.closest || (() => null),
+  };
+  return el;
+}
+
+describe('Selector & Target Resolution', () => {
+  it('prioritizes data-testid and data-component attributes', () => {
+    const el = createMockElement({
+      tagName: 'div',
+      attributes: { 'data-testid': 'submit-btn' },
+    });
+    expect(getSemanticSelector(el)).toBe('[data-testid="submit-btn"]');
+
+    const elComp = createMockElement({
+      tagName: 'div',
+      attributes: { 'data-component': 'UserProfile' },
+    });
+    expect(getSemanticSelector(elComp)).toBe('[data-testid="UserProfile"]');
+  });
+
+  it('uses clean IDs and skips uuid/numeric hashes', () => {
+    const el = createMockElement({
+      tagName: 'div',
+      id: 'navbar-header',
+    });
+    expect(getSemanticSelector(el)).toBe('#navbar-header');
+
+    const numericEl = createMockElement({
+      tagName: 'div',
+      id: '123456',
+    });
+    expect(getSemanticSelector(numericEl)).toBe('div');
+  });
+
+  it('handles aria-label, role, and title on elements', () => {
+    const btn = createMockElement({
+      tagName: 'button',
+      attributes: { 'aria-label': 'Close dialog' },
+    });
+    expect(getSemanticSelector(btn)).toBe('button[aria-label="Close dialog"]');
+
+    const nav = createMockElement({
+      tagName: 'nav',
+      attributes: { role: 'navigation' },
+    });
+    expect(getSemanticSelector(nav)).toBe('nav[role="navigation"]');
+
+    const iconBtn = createMockElement({
+      tagName: 'button',
+      attributes: { title: 'Refresh page' },
+    });
+    expect(getSemanticSelector(iconBtn)).toBe('button[title="Refresh page"]');
+  });
+
+  it('filters out dynamic hashed utility classes and retains semantic classes', () => {
+    const el = createMockElement({
+      tagName: 'div',
+      classList: ['css-98741', 'card-item', '_scoped123', 'md:flex', 'p-[12px]', 'primary-box'],
+    });
+    expect(getSemanticSelector(el)).toBe('div.card-item.primary-box');
+  });
+
+  it('generates nth-of-type for identical siblings', () => {
+    const parent = createMockElement({
+      tagName: 'div',
+      id: 'sidebar',
+    });
+    const child1 = createMockElement({
+      tagName: 'div',
+      parentElement: parent,
+    });
+    const child2 = createMockElement({
+      tagName: 'div',
+      parentElement: parent,
+    });
+    parent.children = [child1, child2];
+
+    expect(getSemanticSelector(child2)).toBe('#sidebar > div:nth-of-type(2)');
+  });
+
+  it('resolves meaningful targets from leaf SVG or formatting tags', () => {
+    const button = createMockElement({
+      tagName: 'button',
+      id: 'login-button',
+    });
+
+    const span = createMockElement({
+      tagName: 'span',
+      closest: (sel: string) => (sel.includes('button') ? button : null),
+    });
+
+    expect(resolveMeaningfulTarget(span)).toBe(button);
+
+    const link = createMockElement({
+      tagName: 'a',
+      id: 'home-link',
+    });
+
+    const svg = createMockElement({
+      tagName: 'svg',
+      closest: (sel: string) => (sel.includes('a') ? link : null),
+    });
+
+    expect(resolveMeaningfulTarget(svg)).toBe(link);
+
+    // Standalone div returns itself
+    const card = createMockElement({
+      tagName: 'div',
+      id: 'info-card',
+    });
+    expect(resolveMeaningfulTarget(card)).toBe(card);
+  });
+});