chrometools-mcp 3.1.6 → 3.2.4

package/pom/apom-tree-converter.js

@@ -43,6 +43,11 @@ function buildAPOMTree(interactiveOnly = true) {
   // Build tree from body
   result.tree = buildNode(document.body, null, 0, []);
 
+  // Prune empty branches (containers without interactive elements)
+  if (interactiveOnly && result.tree) {
+    result.tree = pruneEmptyBranches(result.tree);
+  }
+
   // Collect radio and checkbox groups for easier agent access
   result.groups = collectInputGroups(result.tree);
 
@@ -102,29 +107,109 @@ function buildAPOMTree(interactiveOnly = true) {
   }
 
   /**
-   * Mark interactive elements and their ancestors
+   * Prune empty branches (containers without interactive elements)
+   * Bottom-up traversal: remove container branches that don't end with interactive leaves
    */
-  function markInteractiveElements(root) {
-    const interactiveTags = new Set([
-      'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'LABEL', 'FORM'
-    ]);
+  function pruneEmptyBranches(node) {
+    if (!node) return null;
+
+    // Handle compact format containers
+    if (typeof node === 'object' && !node.id && !node.tag) {
+      // Compact format: { "tag_id": [children] }
+      const keys = Object.keys(node);
+      if (keys.length === 1 && Array.isArray(node[keys[0]])) {
+        const key = keys[0];
+        const prunedChildren = node[key]
+          .map(child => pruneEmptyBranches(child))
+          .filter(child => child !== null);
+
+        // If no children left after pruning, remove this container
+        if (prunedChildren.length === 0) {
+          return null;
+        }
 
-    const interactiveRoles = new Set([
-      'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox', 'listbox',
-      'menuitem', 'tab', 'switch', 'slider', 'searchbox'
-    ]);
+        return { [key]: prunedChildren };
+      }
+    }
 
-    // Find all interactive elements
+    // Handle regular format (interactive elements or full-mode containers)
+    if (node.children && Array.isArray(node.children)) {
+      // Prune children recursively
+      node.children = node.children
+        .map(child => pruneEmptyBranches(child))
+        .filter(child => child !== null);
+    }
+
+    // If this is a container (no type = not interactive) with no children, remove it
+    if (!node.type && node.children && node.children.length === 0) {
+      return null;
+    }
+
+    return node;
+  }
+
+  /**
+   * Check if cursor:pointer is explicitly set (not inherited)
+   */
+  function hasCursorPointerExplicit(element) {
+    const computedStyle = window.getComputedStyle(element);
+    if (computedStyle.cursor !== 'pointer') {
+      return false;
+    }
+
+    // Check if cursor is set via inline style
+    if (element.style.cursor === 'pointer') {
+      return true;
+    }
+
+    // Check if cursor is set via CSS class or direct CSS rule (not inherited)
+    // If parent also has cursor:pointer computed, then it's likely inherited
+    const parent = element.parentElement;
+    if (parent) {
+      const parentStyle = window.getComputedStyle(parent);
+      if (parentStyle.cursor === 'pointer') {
+        // Parent has cursor:pointer, so this is inherited
+        return false;
+      }
+    }
+
+    // Element has cursor:pointer but parent doesn't - it's explicitly set
+    return true;
+  }
+
+  /**
+   * Mark interactive elements and their ancestors
+   * NOTE: This function is defined before checkInteractivity,
+   * so we need to inline the checks or move function definitions
+   */
+  function markInteractiveElements(root) {
+    // Find all interactive elements using the same logic as checkInteractivity
     const elements = root.querySelectorAll('*');
     const interactiveList = [];
 
     elements.forEach(el => {
-      const isInteractive =
-        interactiveTags.has(el.tagName) ||
-        interactiveRoles.has(el.getAttribute('role')) ||
+      // Use inline checks (same logic as checkInteractivity)
+      const tag = el.tagName.toLowerCase();
+      const role = el.getAttribute('role');
+
+      const isInteractive = (
+        // Native HTML interactive elements
+        ['a', 'button', 'input', 'select', 'textarea', 'label', 'form'].includes(tag) ||
+        // Interactive ARIA roles
+        (role && ['button', 'link', 'checkbox', 'radio', 'tab', 'menuitem', 'option', 'switch', 'textbox'].includes(role)) ||
+        // onclick attribute
         el.hasAttribute('onclick') ||
-        el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1' ||
-        (el.tagName === 'DIV' && el.getAttribute('contenteditable') === 'true');
+        // onclick property
+        (el.onclick !== null && el.onclick !== undefined) ||
+        // cursor: pointer (only if explicitly set, not inherited)
+        hasCursorPointerExplicit(el) ||
+        // tabindex (except -1)
+        (el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1') ||
+        // contenteditable
+        el.getAttribute('contenteditable') === 'true'
+        // Note: We skip event listener check here for performance
+        // as querySelectorAll can return thousands of elements
+      );
 
       if (isInteractive && isVisible(el)) {
         interactiveList.push(el);
@@ -169,10 +254,17 @@ function buildAPOMTree(interactiveOnly = true) {
       return null;
     }
 
-    // Generate unique ID
+    // Generate unique ID and CSS selector
     const id = generateElementId(element);
+    const selector = generateSelector(element);
     elementIds.set(element, id);
 
+    // Register element in selector resolver (internal only)
+    if (typeof window !== 'undefined' && typeof window.registerElement === 'function') {
+      const tag = element.tagName.toLowerCase();
+      window.registerElement(id, selector, { tag, depth });
+    }
+
     const currentPath = [...path, id];
 
     // Get positioning info
@@ -184,26 +276,47 @@ function buildAPOMTree(interactiveOnly = true) {
     // Build node - minimize non-interactive parents
     const isInteractive = elementType.isInteractive;
 
-    const node = {
-      id,
-      tag: element.tagName.toLowerCase(),
-      selector: generateSelector(element),
-      position,
-      children: []
-    };
+    // Build node structure based on mode
+    let node;
 
-    // Add full info only for interactive elements
     if (isInteractive) {
-      node.type = elementType.type;
-      node.bounds = getBounds(element);
+      // Interactive elements: full structure without selector (unless includeAll)
+      node = {
+        id,
+        tag: element.tagName.toLowerCase(),
+        position,
+        type: elementType.type,
+        children: []
+      };
 
-      // Add metadata based on element type
+      // Add selector only in includeAll mode
+      if (!interactiveOnly) {
+        node.selector = selector;
+      }
+
+      // Add metadata for interactive elements
       if (elementType.metadata) {
         node.metadata = elementType.metadata;
       }
     } else {
-      // For containers (parents), keep it minimal
-      node.type = elementType.type;
+      // Containers: compact format "tag_id": [children] when interactiveOnly
+      // or full format when includeAll
+      if (interactiveOnly) {
+        // Compact format - will be converted after processing children
+        node = {
+          _compact: true,
+          _key: `${element.tagName.toLowerCase()}_${id}`,
+          children: []
+        };
+      } else {
+        // Full format with selector
+        node = {
+          id,
+          tag: element.tagName.toLowerCase(),
+          selector,
+          children: []
+        };
+      }
     }
 
     // Update metadata counters
@@ -231,6 +344,14 @@ function buildAPOMTree(interactiveOnly = true) {
       }
     }
 
+    // Convert compact containers to final format
+    if (node._compact) {
+      // Return compact format: { "tag_id": [children] }
+      const compactNode = {};
+      compactNode[node._key] = node.children;
+      return compactNode;
+    }
+
     return node;
   }
 
@@ -291,6 +412,87 @@ function buildAPOMTree(interactiveOnly = true) {
     };
   }
 
+  /**
+   * Check if element has click event listeners
+   */
+  function hasClickListener(element) {
+    try {
+      // Check for getEventListeners (available in Chrome DevTools context)
+      if (typeof getEventListeners === 'function') {
+        const listeners = getEventListeners(element);
+        return listeners && listeners.click && listeners.click.length > 0;
+      }
+
+      // Fallback: check for common event listener markers
+      // Note: This is not 100% reliable but catches common cases
+      return element._events?.click ||
+             element.__listeners?.click ||
+             element.__eventListeners?.click;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /**
+   * Check if element is interactive based on various signals
+   */
+  function checkInteractivity(element) {
+    const tag = element.tagName.toLowerCase();
+    const role = element.getAttribute('role');
+
+    // 1. Standard interactive HTML elements
+    const interactiveTags = ['a', 'button', 'input', 'select', 'textarea'];
+    if (interactiveTags.includes(tag)) {
+      return { isInteractive: true, reason: 'native-html' };
+    }
+
+    // 2. Interactive ARIA roles
+    const interactiveRoles = [
+      'button', 'link', 'checkbox', 'radio', 'tab',
+      'menuitem', 'option', 'switch', 'textbox'
+    ];
+    if (role && interactiveRoles.includes(role)) {
+      return { isInteractive: true, reason: 'aria-role' };
+    }
+
+    // 3. Elements with onclick attribute
+    if (element.hasAttribute('onclick')) {
+      return { isInteractive: true, reason: 'onclick-attr' };
+    }
+
+    // 4. Elements with onclick property set via JavaScript
+    if (element.onclick !== null && element.onclick !== undefined) {
+      return { isInteractive: true, reason: 'onclick-prop' };
+    }
+
+    // 5. Elements with cursor: pointer (only if explicitly set, not inherited)
+    if (hasCursorPointerExplicit(element)) {
+      return { isInteractive: true, reason: 'cursor-pointer' };
+    }
+
+    // 6. Elements with click event listeners
+    if (hasClickListener(element)) {
+      return { isInteractive: true, reason: 'event-listener' };
+    }
+
+    // 7. Elements with tabindex (except -1)
+    const tabindex = element.getAttribute('tabindex');
+    if (tabindex !== null && tabindex !== '-1') {
+      return { isInteractive: true, reason: 'tabindex' };
+    }
+
+    // 8. Contenteditable elements
+    if (element.getAttribute('contenteditable') === 'true') {
+      return { isInteractive: true, reason: 'contenteditable' };
+    }
+
+    return { isInteractive: false, reason: null };
+  }
+
+  /**
+   * Detect framework-specific attributes on element
+   * Returns framework info or null
+   */
   /**
    * Determine element type and metadata
    */
@@ -301,14 +503,16 @@ function buildAPOMTree(interactiveOnly = true) {
 
     // Form
     if (tag === 'form') {
+      const metadata = {
+        method: element.method?.toUpperCase() || 'GET',
+        action: element.action || '',
+        name: element.name || null
+      };
+
       return {
         type: 'form',
         isInteractive: true,
-        metadata: {
-          method: element.method?.toUpperCase() || 'GET',
-          action: element.action || '',
-          name: element.name || null
-        }
+        metadata
       };
     }
 
@@ -450,25 +654,32 @@ function buildAPOMTree(interactiveOnly = true) {
 
     // Container with semantic role
     if (role) {
+      const interactivityCheck = checkInteractivity(element);
       return {
         type: role,
-        isInteractive: false,
+        isInteractive: interactivityCheck.isInteractive,
         metadata: {
-          ariaLabel: element.getAttribute('aria-label') || null
+          ariaLabel: element.getAttribute('aria-label') || null,
+          interactivityReason: interactivityCheck.reason || undefined
         }
       };
     }
 
-    // Generic container
+    // Generic container - check for JavaScript interactivity
+    const interactivityCheck = checkInteractivity(element);
     return {
       type: 'container',
-      isInteractive: false,
-      metadata: null
+      isInteractive: interactivityCheck.isInteractive,
+      metadata: interactivityCheck.isInteractive ? {
+        text: element.textContent?.trim().substring(0, 100) || '',
+        interactivityReason: interactivityCheck.reason
+      } : null
     };
   }
 
   /**
    * Generate unique CSS selector
+   * Excludes framework-specific dynamic attributes (React, Vue, Angular)
    */
   function generateSelector(element) {
     // Use ID if available and unique
@@ -476,6 +687,19 @@ function buildAPOMTree(interactiveOnly = true) {
       return `#${element.id}`;
     }
 
+    // Try to find stable class name (excluding framework-specific dynamic classes)
+    const stableClass = getStableClassName(element);
+    if (stableClass) {
+      const classSelector = `.${stableClass}`;
+      // Verify it's unique within parent context
+      if (element.parentElement) {
+        const matches = element.parentElement.querySelectorAll(classSelector);
+        if (matches.length === 1 && matches[0] === element) {
+          return classSelector;
+        }
+      }
+    }
+
     // Build path from parent
     const path = [];
     let current = element;
@@ -483,6 +707,12 @@ function buildAPOMTree(interactiveOnly = true) {
     while (current && current !== document.body) {
       let selector = current.tagName.toLowerCase();
 
+      // Add stable class if available
+      const stableClass = getStableClassName(current);
+      if (stableClass) {
+        selector += `.${stableClass}`;
+      }
+
       // Add nth-of-type if needed
       if (current.parentElement) {
         const siblings = Array.from(current.parentElement.children).filter(
@@ -500,6 +730,39 @@ function buildAPOMTree(interactiveOnly = true) {
 
     return path.join(' > ');
   }
+
+  /**
+   * Get stable class name excluding framework-specific dynamic classes
+   * Returns first stable class or null
+   */
+  function getStableClassName(element) {
+    if (!element.className || typeof element.className !== 'string') {
+      return null;
+    }
+
+    const classes = element.className.split(/\s+/).filter(c => c);
+
+    // Filter out framework-specific classes
+    const stableClasses = classes.filter(className => {
+      // React: CSS Modules, Styled Components, Emotion
+      if (/^[a-zA-Z0-9_-]+-[a-zA-Z0-9_-]{5,}$/.test(className)) return false;
+      if (/^css-[a-z0-9]+(-[a-z0-9]+)?$/i.test(className)) return false;
+      if (/^sc-[a-z0-9]+-[a-z0-9]+$/i.test(className)) return false;
+
+      // Vue: scoped styles
+      if (/^data-v-[a-f0-9]{8}$/i.test(className)) return false;
+
+      // Angular: component styles (no classes starting with _ng)
+      if (/^_ng/.test(className)) return false;
+
+      // Generic hash patterns
+      if (/^[a-z0-9]{32,}$/i.test(className)) return false;
+
+      return true;
+    });
+
+    return stableClasses.length > 0 ? stableClasses[0] : null;
+  }
 }
 
 // Export for use in both Node.js and browser context

package/server/tool-definitions.js

@@ -28,7 +28,7 @@ export const toolDefinitions = [
       },
       {
         name: "click",
-        description: "PRIMARY tool for clicking elements. PREFERRED: Use APOM ID (e.g., id: 'button_45') from analyzePage for reliable element targeting. ALTERNATIVE: CSS selector for ad-hoc usage. Works correctly with React/Vue/Angular synthetic events. DO NOT use executeScript for clicks - use this tool instead. Waits for animations and navigation.",
+        description: "Click element by APOM ID (preferred) or CSS selector. Handles React/Vue/Angular events, waits for navigation.",
         inputSchema: {
           type: "object",
           properties: {
@@ -42,7 +42,7 @@ export const toolDefinitions = [
       },
       {
         name: "type",
-        description: "PRIMARY tool for filling input fields. PREFERRED: Use APOM ID (e.g., id: 'input_20') from analyzePage for reliable element targeting. ALTERNATIVE: CSS selector for ad-hoc usage. Works correctly with React/Vue/Angular state management. DO NOT use executeScript for typing - use this tool instead. Automatically updates framework state (React hooks, Vue reactive data).",
+        description: "Type text into input by APOM ID (preferred) or CSS selector. Updates React/Vue/Angular state automatically.",
         inputSchema: {
           type: "object",
           properties: {
@@ -55,16 +55,6 @@ export const toolDefinitions = [
           required: ["text"],
         },
       },
-      {
-        name: "getElement",
-        description: "Get HTML markup of element. Prefer analyzePage for better efficiency.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            selector: { type: "string", description: "CSS selector (default: body)" },
-          },
-        },
-      },
       {
         name: "getComputedCss",
         description: "Get computed CSS styles for element. For layout debugging and responsive design.",
@@ -102,7 +92,7 @@ export const toolDefinitions = [
       },
       {
         name: "screenshot",
-        description: "Capture element image (15-25k tokens). For visual comparison. Use analyzePage for form data/validation (2-5k tokens).",
+        description: "Capture element image (15-25k tokens). Use analyzePage for form data/validation (8-10k tokens).",
         inputSchema: {
           type: "object",
           properties: {
@@ -223,7 +213,7 @@ export const toolDefinitions = [
       },
       {
         name: "hover",
-        description: "Hover over element. PREFERRED: Use APOM ID from analyzePage. ALTERNATIVE: CSS selector. For testing hover effects, tooltips, and CSS :hover states.",
+        description: "Hover over element by APOM ID or CSS selector. For hover effects, tooltips, :hover states.",
         inputSchema: {
           type: "object",
           properties: {
@@ -234,7 +224,7 @@ export const toolDefinitions = [
       },
       {
         name: "selectOption",
-        description: "Select option in dropdown. PREFERRED: Use APOM ID from analyzePage. ALTERNATIVE: CSS selector. Works with HTML select elements. Specify value, text, or index to choose option.",
+        description: "Select dropdown option by APOM ID or CSS selector. Specify value, text, or index.",
         inputSchema: {
           type: "object",
           properties: {
@@ -248,7 +238,7 @@ export const toolDefinitions = [
       },
       {
         name: "drag",
-        description: "Drag element by mouse (click-hold-move-release). Simulates real mouse drag in any direction. Works with interactive maps, Gantt charts, SVG diagrams, canvas, sliders. Does NOT work with standard overflow scrollbars - use scrollTo/scrollHorizontal instead.",
+        description: "Drag element in any direction. For maps, charts, SVG, canvas, sliders. Use scrollHorizontal for scrollbars.",
         inputSchema: {
           type: "object",
           properties: {
@@ -262,7 +252,7 @@ export const toolDefinitions = [
       },
       {
         name: "scrollHorizontal",
-        description: "Scroll element horizontally. For tables, carousels, and horizontally scrollable containers. Can scroll by pixels or to the end.",
+        description: "Scroll element horizontally by pixels or to end. For tables, carousels, scrollable containers.",
         inputSchema: {
           type: "object",
           properties: {
@@ -487,12 +477,12 @@ export const toolDefinitions = [
       },
       {
         name: "analyzePage",
-        description: "PRIMARY tool for reading page state. Returns APOM (Agent Page Object Model) format by default with unique element IDs. Use element IDs with click/type tools instead of CSS selectors. Use refresh:true after clicks/submissions to see updated state. Efficient: 2-5k tokens vs screenshot 15-25k. Set useLegacyFormat:true for old format.",
+        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k.",
         inputSchema: {
           type: "object",
           properties: {
             refresh: { type: "boolean", description: "Refresh cache (default: false)" },
-            includeAll: { type: "boolean", description: "Include all elements on page, not just interactive ones (default: false)" },
+            includeAll: { type: "boolean", description: "Include all elements with selectors - full debug format (default: false for compact format)" },
             useLegacyFormat: { type: "boolean", description: "Return legacy format instead of APOM (default: false - APOM is now default)" },
             registerElements: { type: "boolean", description: "Auto-register elements in selector resolver (default: true)" },
             groupBy: { type: "string", description: "Group elements: 'type' or 'flat' (default: 'type')", enum: ["type", "flat"] },
@@ -500,12 +490,15 @@ export const toolDefinitions = [
         },
       },
       {
-        name: "getElementByApomId",
-        description: "Get detailed information about element by its APOM ID from analyzePage. Returns full element details including bounds, position, attributes, computed styles. Use this to inspect specific elements without re-analyzing entire page.",
+        name: "getElementDetails",
+        description: "Get detailed information about element by its APOM ID. Returns full element details including bounds, CSS selector, position, attributes, and computed styles. Can also analyze children elements tree structure. Use this when analyzePage output was simplified and you need complete information about specific element or analyze specific sections in detail.",
         inputSchema: {
           type: "object",
           properties: {
             id: { type: "string", description: "APOM element ID (e.g., 'input_20', 'button_45') from analyzePage result" },
+            analyzeChildren: { type: "boolean", description: "Analyze children elements tree structure (default: false)" },
+            includeAll: { type: "boolean", description: "When analyzing children, include all elements, not just interactive ones (default: false)" },
+            refresh: { type: "boolean", description: "Force refresh of cached analysis (default: false)" },
           },
           required: ["id"],
         },
@@ -564,7 +557,7 @@ export const toolDefinitions = [
       },
       {
         name: "enableRecorder",
-        description: "Check ChromeTools Extension connection status for scenario recording. Recording is now handled via Chrome Extension popup (click CT icon in Chrome toolbar). Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/.",
+        description: "Check ChromeTools Extension connection for scenario recording. Use Chrome Extension popup (CT icon) for recording.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -572,7 +565,7 @@ export const toolDefinitions = [
       },
       {
         name: "startRecording",
-        description: "Start recording user actions into a scenario. Recording follows the active tab automatically. Use stopRecording to finish and save the scenario.",
+        description: "Start recording user actions. Follows active tab automatically. Use stopRecording to finish.",
         inputSchema: {
           type: "object",
           properties: {
@@ -641,7 +634,7 @@ export const toolDefinitions = [
       },
       {
         name: "executeScenario",
-        description: "Execute recorded scenario by name. Runs actions with dependency resolution. Scenarios are organized by domain in ~/.config/chrometools-mcp/projects/{domain}/scenarios/. If multiple scenarios have the same name across different domains, specify projectId to disambiguate.",
+        description: "Execute scenario by name with dependency resolution. Use projectId to disambiguate duplicate names.",
         inputSchema: {
           type: "object",
           properties: {
@@ -655,7 +648,7 @@ export const toolDefinitions = [
       },
       {
         name: "listScenarios",
-        description: "List all scenarios with metadata. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "List all scenarios with metadata.",
         inputSchema: {
           type: "object",
           properties: {
@@ -665,7 +658,7 @@ export const toolDefinitions = [
       },
       {
         name: "searchScenarios",
-        description: "Search scenarios by text or tags. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Search scenarios by text or tags.",
         inputSchema: {
           type: "object",
           properties: {
@@ -677,7 +670,7 @@ export const toolDefinitions = [
       },
       {
         name: "getScenarioInfo",
-        description: "Get scenario details: actions, parameters, dependencies. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Get scenario details: actions, parameters, dependencies.",
         inputSchema: {
           type: "object",
           properties: {
@@ -689,7 +682,7 @@ export const toolDefinitions = [
       },
       {
         name: "deleteScenario",
-        description: "Delete scenario and secrets. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Delete scenario and secrets.",
         inputSchema: {
           type: "object",
           properties: {
@@ -700,7 +693,7 @@ export const toolDefinitions = [
       },
       {
         name: "exportScenarioAsCode",
-        description: "Export recorded scenario as executable test code for creating a NEW test file. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to EXISTING files, use 'appendScenarioToFile' instead. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Export scenario as test code for NEW file. Cleans unstable selectors, optionally generates Page Object. Use appendScenarioToFile for existing files.",
         inputSchema: {
           type: "object",
           properties: {
@@ -735,7 +728,7 @@ export const toolDefinitions = [
       },
       {
         name: "appendScenarioToFile",
-        description: "Append recorded scenario as test code to an EXISTING test file. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class. Returns JSON with test code and target file - Claude Code will append to the file without overwriting existing tests. To create NEW test files, use 'exportScenarioAsCode' instead. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Append scenario as test code to EXISTING file. Cleans unstable selectors, optionally generates Page Object. Use exportScenarioAsCode for new files.",
         inputSchema: {
           type: "object",
           properties: {

package/server/tool-schemas.js

@@ -35,10 +35,6 @@ export const TypeSchema = z.object({
   message: "Either 'id' or 'selector' must be provided, but not both"
 });
 
-export const GetElementSchema = z.object({
-  selector: z.string().optional().describe("CSS selector (optional, defaults to body)"),
-});
-
 export const HoverSchema = z.object({
   id: z.string().optional().describe("APOM element ID from analyzePage. Mutually exclusive with selector."),
   selector: z.string().optional().describe("CSS selector for element to hover. Mutually exclusive with id."),
@@ -260,14 +256,17 @@ export const SmartFindElementSchema = z.object({
 
 export const AnalyzePageSchema = z.object({
   refresh: z.boolean().optional().describe("Force refresh of cached analysis (default: false)"),
-  includeAll: z.boolean().optional().describe("Include all elements on page, not just interactive ones (default: false). Useful for layout work and finding non-interactive elements to style."),
+  includeAll: z.boolean().optional().describe("Include all elements on page, not just interactive ones (default: false). When false (default), returns compact format: containers as \"tag_id\":[children], interactive elements without selectors. When true, returns full format with selectors for debugging."),
   useLegacyFormat: z.boolean().optional().describe("Return legacy format instead of APOM (default: false - APOM is now the default format)"),
   registerElements: z.boolean().optional().describe("Automatically register elements in selector resolver (default: true)"),
   groupBy: z.enum(['type', 'flat']).optional().describe("Group elements by type or return flat structure (default: 'type')"),
 });
 
-export const GetElementByApomIdSchema = z.object({
+export const GetElementDetailsSchema = z.object({
   id: z.string().describe("APOM element ID (e.g., 'input_20', 'button_45') from analyzePage result"),
+  analyzeChildren: z.boolean().optional().describe("Analyze children elements tree structure (default: false)"),
+  includeAll: z.boolean().optional().describe("When analyzing children, include all elements, not just interactive ones (default: false)"),
+  refresh: z.boolean().optional().describe("Force refresh of cached analysis (default: false)"),
 });
 
 export const GetAllInteractiveElementsSchema = z.object({