@yusufffararatt/dombridge-mcp 2.7.5

package/src/tools/extract-data.js

@@ -0,0 +1,395 @@
+/**
+ * Extract Data Tool
+ * Scans embedded/SSR data and stores scraper-relevant paths in the profile.
+ */
+
+import { buildProfileEnrichment } from '../profiles/profile-enricher.js';
+import { loadProfile, saveProfile } from '../profiles/profile-manager.js';
+import { resolveActiveDomain } from '../utils/tab-resolver.js';
+import { filterNoiseSources } from '../utils/extract-density.js';
+
+export const EXTRACT_DATA_SCRIPT = `(function() {
+  var sources = [];
+
+  var propsKeys = Object.keys(window).filter(function(k) {
+    return /__PROPS$|__PROPS__$|__DATA$|__DATA__$|__STATE$|__STATE__$|__STORE$/.test(k);
+  });
+
+  propsKeys.forEach(function(key) {
+    try {
+      var val = window[key];
+      if (val && typeof val === 'object') {
+        sources.push({ key: key, type: 'window_props', data: val });
+      }
+    } catch(e) {}
+  });
+
+  if (window.__NEXT_DATA__ && window.__NEXT_DATA__.props) {
+    sources.push({ key: '__NEXT_DATA__.props', type: 'next_ssr', data: window.__NEXT_DATA__.props });
+  }
+
+  // Next.js App Router: __next_f is an array of [hash, chunk] tuples
+  // Chunks come in two formats:
+  //   1. Standard JSON: parseable directly via JSON.parse
+  //   2. RSC stream: multi-line "id:value" pairs where value may be JSON
+  // We try JSON.parse first; if it fails, we extract "id:{...}" lines as JSON objects.
+  if (Array.isArray(window.__next_f)) {
+    try {
+      var merged = {};
+      var collisionKeys = [];
+      var chunks = [];
+      var rscLines = [];
+      window.__next_f.forEach(function(item) {
+        if (Array.isArray(item) && item.length >= 2) {
+          try {
+            chunks.push(item[1]);
+            // Try 1: direct JSON.parse (standard format)
+            var parsed = JSON.parse(item[1]);
+            if (parsed && typeof parsed === 'object') {
+              Object.keys(parsed).forEach(function(k) {
+                if (merged.hasOwnProperty(k) && collisionKeys.indexOf(k) === -1) {
+                  collisionKeys.push(k);
+                }
+                merged[k] = parsed[k];
+              });
+            }
+          } catch(e) {
+            // Try 2: RSC stream format — each line is "id:value"
+            // Extract lines where value starts with '{' (JSON object)
+            var lines = item[1].split('\\n');
+            lines.forEach(function(line) {
+              var colonIdx = line.indexOf(':');
+              if (colonIdx > 0) {
+                var value = line.substring(colonIdx + 1);
+                if (value.charAt(0) === '{' || value.charAt(0) === '[') {
+                  try {
+                    var obj = JSON.parse(value);
+                    if (obj && typeof obj === 'object') {
+                      var objectsToMerge = [];
+                      var findTopLevelObjects = function(val) {
+                        if (!val || typeof val !== 'object') return;
+                        if (Array.isArray(val)) {
+                          val.forEach(findTopLevelObjects);
+                        } else {
+                          objectsToMerge.push(val);
+                        }
+                      };
+                      findTopLevelObjects(obj);
+
+                      objectsToMerge.forEach(function(targetObj) {
+                        rscLines.push({ id: line.substring(0, colonIdx), keys: Object.keys(targetObj).slice(0, 10) });
+                        Object.keys(targetObj).forEach(function(k) {
+                          if (merged.hasOwnProperty(k) && collisionKeys.indexOf(k) === -1) {
+                            collisionKeys.push(k);
+                          }
+                          merged[k] = targetObj[k];
+                        });
+                      });
+                    }
+                  } catch(e2) { /* not a JSON object/array — skip */ }
+                }
+              }
+            });
+          }
+        }
+      });
+      if (Object.keys(merged).length > 0 || chunks.length > 0) {
+        var data = Object.keys(merged).length > 0 ? merged : { __rawChunks: chunks.length, __note: 'RSC payload — use execute_js to explore individual chunks' };
+        if (collisionKeys.length > 0) {
+          data.__collisionKeys = collisionKeys;
+          data.__note = (data.__note ? data.__note + ' ' : '') + 'Overlapping keys across chunks: ' + collisionKeys.join(', ') + '. Later values win. Use execute_js to inspect individual chunks.';
+        }
+        if (rscLines.length > 0) {
+          data.__rscParseMode = 'stream';
+          data.__rscObjectCount = rscLines.length;
+        }
+        sources.push({ key: '__next_f', type: 'next_rsc', data: data });
+      }
+    } catch(e) {}
+  }
+
+  // Next.js _N_E objects (standard JSON, used by Next.js runtime)
+  if (window._N_E && typeof window._N_E === 'object') {
+    sources.push({ key: '_N_E', type: 'next_runtime', data: window._N_E });
+  }
+
+  if (window.__NUXT__ && window.__NUXT__.data) {
+    sources.push({ key: '__NUXT__.data', type: 'nuxt_ssr', data: window.__NUXT__.data });
+  }
+
+  var storeKeys = ['__REDUX_STATE__', '__INITIAL_STATE__', '__INITIAL_DATA__', '__APP_STATE__',
+                   '__STORE__', '__store__', '__STATE__', '__PRELOADED_STATE__'];
+  storeKeys.forEach(function(key) {
+    try {
+      if (window[key] && typeof window[key] === 'object' && !propsKeys.includes(key)) {
+        sources.push({ key: key, type: 'store', data: window[key] });
+      }
+    } catch(e) {}
+  });
+
+  var jsonScripts = document.querySelectorAll('script[type="application/json"]');
+  jsonScripts.forEach(function(el, i) {
+    try {
+      var parsed = JSON.parse(el.textContent);
+      if (parsed && typeof parsed === 'object') {
+        sources.push({ key: 'script[type=application/json][' + i + ']', type: 'inline_json', data: parsed });
+      }
+    } catch(e) {}
+  });
+
+  if (sources.length === 0) return { found: false, sources: [] };
+
+  var inferType = function(val) {
+    if (val === null) return 'null';
+    if (Array.isArray(val)) return 'array';
+    return typeof val;
+  };
+
+  var buildSchema = function(obj, path, depth, maxDepth) {
+    var schema = {};
+    if (depth > maxDepth) return { __truncated: true };
+    if (typeof obj !== 'object' || obj === null) return {};
+
+    var keys = Array.isArray(obj) ? [] : Object.keys(obj).slice(0, 30);
+    if (Array.isArray(obj)) {
+      if (obj.length === 0) return { __empty_array: true };
+      var firstItem = obj[0];
+      var itemSchema = (firstItem && typeof firstItem === 'object')
+        ? buildSchema(firstItem, path + '[]', depth + 1, maxDepth)
+        : { __type: inferType(firstItem), __example: String(firstItem).substring(0, 50) };
+      return { __type: 'array', __length: obj.length, __items: itemSchema };
+    }
+
+    keys.forEach(function(k) {
+      var val = obj[k];
+      var t = inferType(val);
+      if (t === 'object' || t === 'array') {
+        schema[k] = buildSchema(val, path + '.' + k, depth + 1, maxDepth);
+      } else if (t !== 'function') {
+        var example = val !== null && val !== undefined ? String(val).substring(0, 80) : null;
+        schema[k] = { __type: t, __example: example };
+      }
+    });
+
+    if (Object.keys(obj).length > 30) {
+      schema.__note = '... ' + (Object.keys(obj).length - 30) + ' more keys truncated';
+    }
+    return schema;
+  };
+
+  var collectLeafPaths = function(obj, prefix, result, depth, maxDepth) {
+    if (depth > maxDepth) return;
+    if (typeof obj !== 'object' || obj === null) return;
+
+    var keys = Array.isArray(obj)
+      ? (obj.length > 0 ? ['0'] : [])
+      : Object.keys(obj).slice(0, 20);
+
+    keys.forEach(function(k) {
+      var val = Array.isArray(obj) ? obj[0] : obj[k];
+      var path = Array.isArray(obj) ? prefix + '[]' : prefix + '.' + k;
+      var t = inferType(val);
+      if (t === 'object' || t === 'array') {
+        collectLeafPaths(val, path, result, depth + 1, maxDepth);
+      } else if (t !== 'function') {
+        var example = val !== null && val !== undefined ? String(val).substring(0, 60) : null;
+        result.push({ path: path, type: t, example: example });
+      }
+    });
+  };
+
+  var MAX_DEPTH = 5;
+  return {
+    found: true,
+    sources: sources.map(function(src) {
+      var schema = buildSchema(src.data, src.key, 0, MAX_DEPTH);
+      var leafPaths = [];
+      collectLeafPaths(src.data, src.key, leafPaths, 0, MAX_DEPTH);
+      return {
+        key: src.key,
+        type: src.type,
+        schema: schema,
+        leafPaths: leafPaths.slice(0, 50),
+        isArray: Array.isArray(src.data),
+        arrayLength: Array.isArray(src.data) ? src.data.length : null,
+        topLevelKeyCount: (src.data && typeof src.data === 'object' && !Array.isArray(src.data))
+          ? Object.keys(src.data).length
+          : null
+      };
+    })
+  };
+})()`;
+
+const TYPE_LABELS = {
+    next_ssr: 'Next.js SSR (Pages Router)',
+    next_rsc: 'Next.js RSC payload',
+    next_runtime: 'Next.js Runtime State',
+    nuxt_ssr: 'Nuxt SSR',
+    window_props: 'Window Props',
+    store: 'State Store',
+    inline_json: 'Inline JSON Script'
+};
+
+function buildSourceDiff(existingProfile, sources) {
+    const existingKeys = new Set((existingProfile?.dataSchema?.sources || []).map((source) => source.key));
+    const existingCount = existingKeys.size;
+    if (existingCount === 0) return '';
+
+    const newCount = sources.filter((source) => !existingKeys.has(source.key)).length;
+    return `${existingCount} known source${existingCount !== 1 ? 's' : ''} in profile${newCount > 0 ? `, **${newCount} new** found` : ', no new sources'}`;
+}
+
+export const extractDataTool = {
+    name: 'extract_data',
+    description: `This is a tool from the dombridge MCP server.
+Automatically scans embedded/SSR data sources on the current page and writes extraction-ready summaries into the site profile.
+
+WORKFLOW POSITION: Use after analyze_page when the site appears SSR-heavy or embeds state in window objects.
+
+MULTI-TAB: Call debug_mcp_state() first to get tab IDs, then pass tabId to extract data from a specific tab.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            verbose: {
+                type: 'boolean',
+                description: 'Return more schema/path detail (default: false)'
+            },
+            tabId: {
+                type: 'number',
+                description: 'Target tab ID (optional). Omit to use active tab.'
+            }
+        }
+    },
+    handler: async (args, bridgeClient) => {
+        if (!bridgeClient.isConnected) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: 'Error: Extension not connected.\nREQUIRED STEPS:\n1. Reload webpage\n2. Ensure the Chrome extension is active'
+                }],
+                isError: true
+            };
+        }
+
+        const { verbose = false, tabId } = args || {};
+        const requestId = `extract-data-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+        try {
+            // Queue execute-js request via bridge daemon
+            const requestPayload = {
+                code: EXTRACT_DATA_SCRIPT,
+                timeout: 10000,
+                id: requestId,
+                ...(tabId !== undefined ? { tabId } : {})
+            };
+            await bridgeClient.queueRequest('execute-js', requestPayload);
+
+            // Wait for result (15s script + 3s buffer)
+            const timeout = 15000;
+            const resultItem = await bridgeClient.waitForResult('js-execution', requestId, timeout + 3000);
+
+            if (!resultItem) {
+                return {
+                    content: [{ type: 'text', text: `Timeout: extract_data did not complete within ${timeout}ms.` }],
+                    isError: true
+                };
+            }
+
+            // CSP auto-bypass wraps result in { _cspBypassed, result }. Unwrap it.
+            let rawResult = resultItem.result;
+            if (rawResult && rawResult._cspBypassed !== undefined && rawResult.result !== undefined) {
+                rawResult = rawResult.result;
+            }
+            const result = rawResult;
+
+            if (result?.error) {
+                return {
+                    content: [{ type: 'text', text: `extract_data failed: ${result.error}` }],
+                    isError: true
+                };
+            }
+
+            if (!result || !result.found) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `No embedded data found on this page.\n\nThis page may be API-driven, use a non-standard state pattern, or require interaction before data loads.\n\nTry \`discover_apis()\` or \`get_network_trace()\` after interacting with the page.`
+                    }]
+                };
+            }
+
+            const domain = await resolveActiveDomain(bridgeClient, tabId);
+            const existingProfile = domain ? loadProfile(domain) : null;
+            const originalSourceCount = result.sources.length;
+            const diffNote = domain ? buildSourceDiff(existingProfile, result.sources) : '';
+
+            // Filter RequireJS-style noise sources (low leaf density) when source count is high
+            result.sources = filterNoiseSources(result.sources);
+            const filteredOut = originalSourceCount - result.sources.length;
+            const densityNote = filteredOut > 0
+                ? `Filtered ${filteredOut} low-density source(s) (RequireJS-style loaders). Pass verbose=true to inspect raw count.`
+                : '';
+
+            const enrichment = buildProfileEnrichment('extract_data', result);
+
+            if (domain && Object.keys(enrichment).length > 0) {
+                saveProfile(domain, enrichment);
+            }
+
+            const lines = [
+                `Embedded data sources found: ${result.sources.length}`,
+                filteredOut > 0 ? `(raw count: ${originalSourceCount}, filtered: ${filteredOut})` : '',
+                diffNote ? `Profile diff: ${diffNote}` : '',
+                densityNote,
+                ''
+            ].filter(Boolean);
+
+            result.sources.forEach((source, index) => {
+                const typeLabel = TYPE_LABELS[source.type] || source.type;
+                lines.push(`### ${index + 1}. \`${source.key}\` _(${typeLabel})_`);
+
+                if (source.isArray) {
+                    lines.push(`- Type: **Array** with ${source.arrayLength} items`);
+                } else if (source.topLevelKeyCount !== null) {
+                    lines.push(`- Type: **Object** with ${source.topLevelKeyCount} top-level keys`);
+                }
+
+                const schemaKeys = Object.keys(source.schema || {}).filter((key) => !key.startsWith('__'));
+                if (schemaKeys.length > 0) {
+                    lines.push(`- Top-level fields: \`${schemaKeys.slice(0, 10).join('`, `')}\`${schemaKeys.length > 10 ? ` ... +${schemaKeys.length - 10} more` : ''}`);
+                }
+
+                if (Array.isArray(source.leafPaths) && source.leafPaths.length > 0) {
+                    const shown = source.leafPaths.slice(0, verbose ? 15 : 7);
+                    lines.push(`- Extraction-ready paths (${source.leafPaths.length} found${!verbose && source.leafPaths.length > 7 ? ', showing top 7' : ''}):`);
+                    shown.forEach((path) => {
+                        const example = path.example ? ` -> \`${String(path.example).substring(0, verbose ? 60 : 40)}\`` : '';
+                        lines.push(`  - \`${path.path}\` _(${path.type})_${example}`);
+                    });
+                    if (!verbose && source.leafPaths.length > shown.length) {
+                        lines.push(`  - _... ${source.leafPaths.length - shown.length} more paths_`);
+                    }
+                }
+
+                lines.push('');
+            });
+
+            if (domain) {
+                lines.push(`Saved to profile: \`manage_site_profile({ action: 'load', domain: "${domain}" })\``);
+            }
+            lines.push('---');
+            lines.push('Next steps:');
+            lines.push('- Use `execute_js({ code: "JSON.stringify(window.YOUR_PATH_HERE, null, 2)" })` to inspect the real data');
+            lines.push('- Use `get_element()` + `get_network_trace()` if you need to connect DOM values to API responses');
+
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }]
+            };
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+};

package/src/tools/get-element.js

@@ -0,0 +1,281 @@
+/**
+ * Tool: get_element
+ * Unified element tool — programmatic selection (CSS/XPath) OR retrieval of manually selected element.
+ * Merges the former get_selected_element and select_element tools.
+ */
+
+import { StateValidator } from '../utils/state-validator.js';
+import { RateLimiter } from '../utils/rate-limiter.js';
+import { circuitBreakers } from '../utils/circuit-breaker.js';
+import { suggestNextTools, formatWorkflowSuggestions, formatHardGuard } from '../utils/workflow-helper.js';
+import { VALIDATION_SCRIPT, formatAlternatives } from '../utils/selector-validator.js';
+import { runScript } from '../utils/run-script.js';
+
+export const getElementTool = {
+  name: 'get_element',
+  description: `Select or retrieve a DOM element — programmatically or from user's manual selection.
+
+WORKFLOW POSITION: 🔵 First Step - Use before get_network_trace
+
+TWO MODES:
+
+1. PROGRAMMATIC (provide css/xpath/text) — NO manual browser interaction needed:
+   get_element({ css: '.product-price' })
+   get_element({ xpath: '//h1[@class="title"]' })
+   get_element({ css: 'img[src*="lock"]' })       ← attribute-based selection
+   get_element({ css: '[data-testid="product"]' }) ← data-attribute selection
+
+2. MANUAL RETRIEVAL (no selector) — retrieves element user clicked in browser:
+   get_element()
+
+PARAMETERS:
+- css (optional): CSS selector — preferred method
+- xpath (optional): XPath expression
+- text (optional): Exact visible text — last resort, unreliable on nested DOM
+- triggerNetworkTrace (optional): Auto-run network trace after selection (default: true)
+- tabId (optional): Target a specific tab by ID. Get IDs from debug_mcp_state(). Omit to use active tab.
+
+AUTONOMOUS WORKFLOW:
+1. analyze_page() → understand page structure
+2. get_element({ css: '.price' }) → select target element
+3. get_network_trace() → find matching API
+
+MANUAL WORKFLOW:
+1. User clicks element in browser extension
+2. get_element() → retrieve what was selected
+3. get_network_trace() → find matching API`,
+
+  inputSchema: {
+    type: 'object',
+    properties: {
+      css: {
+        type: 'string',
+        description: "CSS selector to programmatically find the element. E.g. \".price\", \"#title\", \"[data-testid='product']\", \"img[src*='lock']\", \"a[href^='https']\". Attribute selectors are fully supported."
+      },
+      xpath: {
+        type: 'string',
+        description: 'XPath expression to find the element. Use when CSS is insufficient.'
+      },
+      text: {
+        type: 'string',
+        description: '⚠️ Exact visible text content to find (last resort — unreliable on nested DOM).'
+      },
+      triggerNetworkTrace: {
+        type: 'boolean',
+        description: 'Auto-run network trace after programmatic selection (default: true)'
+      },
+      verbose: {
+        type: 'boolean',
+        description: 'Return full detail: xpath, all attributes, sessionInfo, pageAnalysis detail (default: false)'
+      },
+      tabId: {
+        type: 'number',
+        description: 'Target tab ID (optional). Omit to use active tab. Get IDs from debug_mcp_state().'
+      }
+    }
+  },
+
+  handler: async (args, bridgeClient) => {
+    const { css, xpath, text, triggerNetworkTrace = true, verbose = false, tabId } = args || {};
+    // Backward compat: selectorInfo object de kabul et
+    const selectorInfo = (css || xpath || text)
+      ? { css, xpath, text }
+      : (args?.selectorInfo || null);
+    const isProgrammatic = selectorInfo && (selectorInfo.css || selectorInfo.xpath || selectorInfo.text);
+
+    if (isProgrammatic) {
+      return handleProgrammaticSelection(selectorInfo, triggerNetworkTrace, verbose, bridgeClient, tabId);
+    } else {
+      return handleManualRetrieval(verbose, bridgeClient);
+    }
+  }
+};
+
+// --- Programmatic selection (formerly select_element) ---
+
+async function handleProgrammaticSelection(selectorInfo, triggerNetworkTrace, verbose, bridgeClient, tabId) {
+  // Hard guard: extension must be connected
+  if (!bridgeClient.isConnected) {
+    return formatHardGuard('get_element', {
+      missing: ['extension_connection'],
+      suggestions: ['Reload the webpage and ensure the Chrome extension is active']
+    });
+  }
+
+  // CSS selector varsa önceden validate et (execute_action ile aynı yaklaşım)
+  if (selectorInfo.css) {
+    try {
+      const v = await runScript(VALIDATION_SCRIPT(selectorInfo.css), bridgeClient, 5000, { tabId });
+      if (v && !v.found) {
+        const altLines = formatAlternatives(v.alternatives);
+
+        // Semantic alternatives for heading tags — many modern SPAs (X.com, React apps)
+        // use [role=heading], [data-testid*="title"], or styled <div> elements instead of
+        // semantic <h1>/<h2>/<h3>. Suggest these so the AI can recover without guessing.
+        const semanticAlts = [];
+        if (/^h[1-6]$/i.test(selectorInfo.css)) {
+          const headingLevel = selectorInfo.css.toLowerCase();
+          semanticAlts.push(`[role="${headingLevel}"]`);
+          semanticAlts.push(`[role="heading"][aria-level="${headingLevel[1]}"]`);
+          semanticAlts.push(`[data-testid*="title"]`);
+          semanticAlts.push(`[aria-label*="title"]`);
+          semanticAlts.push(`[class*="title"]`);
+        }
+        const semanticHint = semanticAlts.length > 0
+          ? `\n\nSemantic alternatives to try:\n${semanticAlts.map(a => `  - \`${a}\``).join('\n')}`
+          : '';
+
+        return {
+          content: [{
+            type: 'text',
+            text: `❌ Element not found: \`${selectorInfo.css}\`\n\nTROUBLESHOOTING:\n- Verify selector with execute_js: document.querySelector('${selectorInfo.css}')\n- Check that the element is visible\n- Try a different selector type (css → xpath or vice versa)${semanticHint}${altLines ? '\n\nSimilar elements on page:\n' + altLines : ''}`
+          }],
+          isError: true
+        };
+      }
+    } catch (_) { /* validation failure is non-blocking — proceed with select_element */ }
+  }
+
+  const requestId = `sel-elem-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+  try {
+    // Queue element selection request via bridge daemon
+    await circuitBreakers.selectElement.execute(() =>
+      bridgeClient.queueRequest('select-element', {
+        selectorInfo, triggerNetworkTrace, id: requestId, ...(tabId ? { tabId } : {})
+      })
+    );
+
+    // Wait for result via bridge daemon polling
+    const resultItem = await bridgeClient.waitForResult('select-element', requestId, 10000);
+
+    if (!resultItem) {
+      return {
+        content: [{ type: 'text', text: `❌ Timeout: Extension did not respond within 10s. Check if extension is active.` }],
+        isError: true
+      };
+    }
+
+    if (!resultItem.success || resultItem.error) {
+      const isXPath = !!selectorInfo.xpath;
+      const verifyHint = isXPath
+        ? `Verify selector with execute_js: const r = document.evaluate('${selectorInfo.xpath}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); r.singleNodeValue`
+        : `Verify selector with execute_js: document.querySelector('${selectorInfo.css}')`;
+      const otherSelector = isXPath ? 'css' : 'xpath';
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Element Selection Failed: ${resultItem.error || 'Unknown error'}\n\nTROUBLESHOOTING:\n- ${verifyHint}\n- Check that the element is visible\n- Try a different selector type (${isXPath ? 'xpath' : 'css'} → ${otherSelector})`
+        }],
+        isError: true
+      };
+    }
+
+    const el = resultItem.element;
+    const selectorUsed = selectorInfo.css || selectorInfo.xpath || selectorInfo.text;
+
+    let text = `✅ Element Selected: **${el?.tagName?.toLowerCase() || 'element'}**\n\n`;
+    text += `**Selector used:** \`${selectorUsed}\`\n`;
+    text += `**CSS Selector:** \`${el?.cssSelector || 'N/A'}\`\n`;
+
+    // XPath: verbose only
+    if (verbose) {
+      text += `**XPath:** \`${el?.xpath || 'N/A'}\`\n`;
+    }
+
+    if (el?.stableSelector) {
+      const meta = el?.stableSelectorMeta;
+      const conf = (verbose && meta?.confidence) ? ` _(${meta.confidence} — ${meta.reason})_` : '';
+      text += `**Stable Selector:** \`${el.stableSelector}\`${conf}\n`;
+    }
+
+    if (el?.textContent) {
+      const limit = verbose ? 200 : 100;
+      text += `**Text:** ${el.textContent.substring(0, limit)}${el.textContent.length > limit ? '...' : ''}`;
+    }
+
+    if (el?.attributes && Object.keys(el.attributes).length > 0) {
+      const attrLimit = verbose ? Object.keys(el.attributes).length : 3;
+      const attrs = Object.entries(el.attributes).slice(0, attrLimit).map(([k, v]) => `${k}="${v}"`).join(', ');
+      const extra = Object.keys(el.attributes).length > attrLimit ? ` +${Object.keys(el.attributes).length - attrLimit} more` : '';
+      text += `\n**Attributes:** ${attrs}${extra}`;
+    }
+
+    text += triggerNetworkTrace
+      ? `\n\n🔄 Network trace triggered. Call \`get_network_trace()\` to see API matches.`
+      : `\n\n💡 Next: Call \`get_network_trace()\` to find which API provides this element's data.`;
+
+    return { content: [{ type: 'text', text }] };
+  } catch (e) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `Error: ${e.message}\n\nREQUIRED STEPS:\n1. Verify selector syntax\n2. Make sure the element is present and the page is loaded`
+      }]
+    };
+  }
+}
+
+// --- Manual retrieval (formerly get_selected_element) ---
+
+async function handleManualRetrieval(verbose, bridgeClient) {
+  return await RateLimiter.executeWithRetry(
+    'get_element',
+    async () => {
+      const connValidation = StateValidator.validateConnection(bridgeClient);
+      if (!connValidation.valid) return StateValidator.formatValidationError(connValidation);
+
+      const validation = StateValidator.validateSelectedElement(bridgeClient);
+      if (!validation.valid) return StateValidator.formatValidationError(validation);
+
+      const el = validation.data;
+
+      let output = `✅ Selected Element Retrieved:\n\n`;
+      output += `📍 CSS: ${el.cssSelector}\n`;
+      if (verbose) output += `📍 XPath: ${el.xpath}\n`;
+      if (el.stableSelector) {
+        const meta = el.stableSelectorMeta;
+        const conf = (verbose && meta?.confidence) ? ` (${meta.confidence} — ${meta.reason})` : '';
+        output += `📍 Stable: ${el.stableSelector}${conf}\n`;
+      }
+      output += `🏷️  Tag: ${el.tagName}\n`;
+
+      if (Object.keys(el.attributes || {}).length > 0) {
+        const attrLimit = verbose ? Object.keys(el.attributes).length : 3;
+        output += `\n📋 Attributes:\n`;
+        Object.entries(el.attributes).slice(0, attrLimit).forEach(([key, value]) => {
+          output += `   ${key}: ${value.length > 50 ? value.substring(0, 50) + '...' : value}\n`;
+        });
+        const remaining = Object.keys(el.attributes).length - attrLimit;
+        if (remaining > 0) output += `   ... and ${remaining} more\n`;
+      }
+
+      const analysis = bridgeClient.pageAnalysis;
+      if (analysis?.timestamp) {
+        const detections = [];
+        if (analysis.ssrDetected) detections.push('SSR');
+        if (analysis.initialStateDetected) detections.push('Initial State');
+        if (analysis.embeddedDataDetected) detections.push('Embedded JSON');
+
+        output += `\n🔍 **Data Source:** ${detections.length > 0 ? detections.join(', ') : 'Dynamic API load'} | Network: ${(analysis.networkCaptureRate || 0).toFixed(0)}%\n`;
+
+        if (verbose) {
+          if (analysis.recommendation) output += `💡 ${analysis.recommendation}\n`;
+        }
+      }
+
+      // sessionInfo: verbose only
+      if (verbose && el.sessionInfo) {
+        const si = el.sessionInfo;
+        output += `\n🔐 Session: ${si.cookiesDetected} cookies (${si.hasAuthCookie ? 'auth cookie found' : 'no auth cookie'}) | ${si.botProtection}\n`;
+      }
+
+      const suggestions = suggestNextTools('get_element', bridgeClient);
+      output += formatWorkflowSuggestions(suggestions);
+
+      return { content: [{ type: 'text', text: output }] };
+    },
+    { maxRetries: 3 }
+  );
+}