Merge pull request #37 from freema/fix/snapshot-visibility-and-error-handling

fix: Improve snapshot visibility checking and error handling

Author: freema

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.6.1] - 2026-02-04
+
+### Added
+- **Enhanced Vue/Livewire/Alpine.js support**: New snapshot options for modern JavaScript frameworks
+  - `includeAll` parameter: Include all visible elements without relevance filtering
+  - `selector` parameter: Scope snapshot to specific DOM subtree using CSS selector
+  - Fixes [#36](https://github.com/freema/firefox-devtools-mcp/issues/36) - DOM filtering problem with Vue and Livewire applications
+- **Test fixtures**: Added new HTML fixtures for testing visibility edge cases (`visibility.html`, `selector.html`)
+
+### Changed
+- **Improved element relevance detection**:
+  - Fixed text content checking to use direct text only (excluding descendants)
+  - Added check for interactive descendants to include wrapper elements
+  - Implemented "bubble-up" pattern in tree walker to preserve nested interactive elements
+  - Elements with `v-*`, `wire:*`, `x-*` attributes and custom components are now properly captured with `includeAll=true`
+
+### Fixed
+- **Visibility checking now considers ancestor elements**: Elements inside hidden parents (e.g., `display:none`, `visibility:hidden`) are now correctly excluded from snapshots, even in `includeAll` mode
+- **Opacity parsing improved**: Fixed opacity check to properly handle various numeric formats (`0`, `0.0`, `0.00`) by parsing as float instead of string comparison
+- **CSS selector error handling**: Invalid CSS selectors now return clear error messages (`"Invalid selector syntax"`) instead of generic `"Unknown error"`
+- Interactive elements deeply nested in non-relevant wrapper divs are now correctly captured
+- Container elements with large descendant text content no longer incorrectly filtered out
+- Custom HTML elements (Vue/Livewire components) are now visible in snapshots with `includeAll=true`
+
+## [0.6.0] - 2025-12-01
+
+Released on npm, see GitHub releases for details.
+
 ## [0.5.3] - 2025-01-30
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firefox-devtools-mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Model Context Protocol (MCP) server for Firefox DevTools automation",
   "author": "freema",
   "license": "MIT",

src/firefox/index.ts

@@ -7,7 +7,7 @@ import { FirefoxCore } from './core.js';
 import { ConsoleEvents, NetworkEvents } from './events/index.js';
 import { DomInteractions } from './dom.js';
 import { PageManagement } from './pages.js';
-import { SnapshotManager, type Snapshot } from './snapshot/index.js';
+import { SnapshotManager, type Snapshot, type SnapshotOptions } from './snapshot/index.js';
 
 /**
  * Main Firefox Client facade
@@ -315,11 +315,11 @@ export class FirefoxClient {
   // Snapshot
   // ============================================================================
 
-  async takeSnapshot(): Promise<Snapshot> {
+  async takeSnapshot(options?: SnapshotOptions): Promise<Snapshot> {
     if (!this.snapshot) {
       throw new Error('Not connected');
     }
-    return await this.snapshot.takeSnapshot();
+    return await this.snapshot.takeSnapshot(options);
   }
 
   resolveUidToSelector(uid: string): string {

src/firefox/snapshot/index.ts

@@ -2,7 +2,7 @@
  * Snapshot module exports
  */
 
-export { SnapshotManager } from './manager.js';
+export { SnapshotManager, type SnapshotOptions } from './manager.js';
 export type {
   Snapshot,
   SnapshotNode,

src/firefox/snapshot/injected/attributeCollector.ts

@@ -146,8 +146,10 @@ export function getComputedProperties(el: Element): ComputedProperties {
   // Visible
   try {
     const style = window.getComputedStyle(el);
+    // Parse opacity as number to handle '0', '0.0', '0.00', etc.
+    const opacity = parseFloat(style.opacity);
     computed.visible =
-      style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+      style.display !== 'none' && style.visibility !== 'hidden' && opacity !== 0 && !isNaN(opacity);
   } catch (e) {
     computed.visible = false;
   }

src/firefox/snapshot/injected/elementCollector.ts

@@ -28,9 +28,72 @@ const SEMANTIC_TAGS = ['nav', 'main', 'section', 'article', 'header', 'footer',
 const CONTAINER_TAGS = ['div', 'span', 'p', 'li', 'ul', 'ol'];
 
 /**
- * Max text content length for containers
+ * Max direct text content length for containers
  */
-const MAX_TEXT_CONTENT = 500;
+const MAX_DIRECT_TEXT_CONTENT = 500;
+
+/**
+ * Check if element is visible
+ * Checks current element and all ancestors up to documentElement
+ */
+export function isVisible(el: Element): boolean {
+  if (!el || el.nodeType !== Node.ELEMENT_NODE) {
+    return false;
+  }
+
+  // Check current element and all ancestors
+  let current: Element | null = el;
+  while (current && current !== document.documentElement) {
+    try {
+      const style = window.getComputedStyle(current);
+      // Parse opacity as number to handle '0', '0.0', '0.00', etc.
+      const opacity = parseFloat(style.opacity);
+      if (
+        style.display === 'none' ||
+        style.visibility === 'hidden' ||
+        opacity === 0 ||
+        isNaN(opacity)
+      ) {
+        return false;
+      }
+    } catch (e) {
+      return false;
+    }
+    current = current.parentElement;
+  }
+
+  return true;
+}
+
+/**
+ * Get direct text content (not including descendants)
+ */
+function getDirectTextContent(el: Element): string {
+  let text = '';
+  for (let i = 0; i < el.childNodes.length; i++) {
+    const node = el.childNodes[i];
+    if (node && node.nodeType === Node.TEXT_NODE) {
+      text += node.textContent || '';
+    }
+  }
+  return text.trim();
+}
+
+/**
+ * Check if element has interactive descendants
+ */
+function hasInteractiveDescendant(el: Element): boolean {
+  for (let i = 0; i < el.children.length; i++) {
+    const child = el.children[i];
+    if (child) {
+      const tag = child.tagName.toLowerCase();
+      if (INTERACTIVE_TAGS.indexOf(tag) !== -1 || child.hasAttribute('role')) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 /**
  * Check if element is relevant for snapshot
@@ -42,12 +105,7 @@ export function isRelevant(el: Element): boolean {
   }
 
   // Check visibility
-  try {
-    const style = window.getComputedStyle(el);
-    if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
-      return false;
-    }
-  } catch (e) {
+  if (!isVisible(el)) {
     return false;
   }
 
@@ -80,15 +138,19 @@ export function isRelevant(el: Element): boolean {
 
   // Common containers - need additional checks
   if (CONTAINER_TAGS.indexOf(tag) !== -1) {
-    // Has meaningful text?
-    const textContent = (el.textContent || '').trim();
-    if (textContent.length > 0 && textContent.length < MAX_TEXT_CONTENT) {
+    // Has meaningful direct text (not from descendants)?
+    const directText = getDirectTextContent(el);
+    if (directText.length > 0 && directText.length < MAX_DIRECT_TEXT_CONTENT) {
       return true;
     }
     // Has id or class?
     if (el.id || el.className) {
       return true;
     }
+    // Has interactive descendants?
+    if (hasInteractiveDescendant(el)) {
+      return true;
+    }
   }
 
   return false;

src/firefox/snapshot/injected/snapshot.injected.ts

@@ -3,17 +3,65 @@
  * This gets bundled and injected into browser context
  */
 
-import { walkTree } from './treeWalker.js';
+import { walkTree, type TreeWalkerOptions } from './treeWalker.js';
 import type { TreeWalkerResult } from './treeWalker.js';
 
+/**
+ * Options for snapshot creation
+ */
+export interface CreateSnapshotOptions extends TreeWalkerOptions {
+  selector?: string;
+}
+
+/**
+ * Result from snapshot creation
+ */
+export interface CreateSnapshotResult extends TreeWalkerResult {
+  selectorError?: string;
+}
+
 /**
  * Create snapshot of current page
  * This function is called from executeScript
  */
-export function createSnapshot(snapshotId: number): TreeWalkerResult {
+export function createSnapshot(
+  snapshotId: number,
+  options?: CreateSnapshotOptions
+): CreateSnapshotResult {
   try {
-    // Walk from body
-    const result = walkTree(document.body, snapshotId, true);
+    // Determine root element
+    let rootElement: Element = document.body;
+
+    if (options?.selector) {
+      try {
+        const selected = document.querySelector(options.selector);
+        if (!selected) {
+          return {
+            tree: null,
+            uidMap: [],
+            truncated: false,
+            selectorError: `Selector "${options.selector}" not found`,
+          };
+        }
+        rootElement = selected;
+      } catch (error: any) {
+        return {
+          tree: null,
+          uidMap: [],
+          truncated: false,
+          selectorError: `Invalid selector syntax: "${options.selector}"`,
+        };
+      }
+    }
+
+    // Walk from root element
+    const treeOptions: TreeWalkerOptions = {
+      includeIframes: options?.includeIframes ?? true,
+    };
+    if (options?.includeAll !== undefined) {
+      treeOptions.includeAll = options.includeAll;
+    }
+    const result = walkTree(rootElement, snapshotId, treeOptions);
 
     if (!result.tree) {
       throw new Error('Failed to generate tree');