browser-devtools-mcp 0.1.7 → 0.2.0

package/dist/tools/react/get-element-for-component.js

@@ -1,1190 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GetElementForComponent = void 0;
-const zod_1 = require("zod");
-/**
- * -----------------------------------------------------------------------------
- * Defaults
- * -----------------------------------------------------------------------------
- *
- * Notes:
- * - Keep defaults conservative to avoid huge outputs and runaway fiber traversals.
- * - All constants are explicitly typed to match your code style.
- */
-const DEFAULT_MATCH_STRATEGY = 'contains';
-const DEFAULT_MAX_ELEMENTS = 200;
-const DEFAULT_ONLY_VISIBLE = true;
-const DEFAULT_ONLY_IN_VIEWPORT = true;
-const DEFAULT_TEXT_PREVIEW_MAX_LENGTH = 80;
-// Search / output controls
-const DEFAULT_MAX_MATCHES = 5;
-const DEFAULT_STACK_LIMIT = 50;
-// Internal safety caps (avoid runaway traversal / DOM scanning costs)
-const INTERNAL_MAX_ROOTS_SCAN = 20;
-const INTERNAL_MAX_FIBERS_VISITED = 250_000;
-class GetElementForComponent {
-    name() {
-        return 'react_get-element-for-component';
-    }
-    description() {
-        return `
-Maps a React COMPONENT INSTANCE to the DOM elements it renders (its "DOM footprint") by traversing the React Fiber graph.
-
-Selection strategy:
-- Best: provide an anchor (anchorSelector OR anchorX/anchorY) to target the correct instance near that UI.
-- Optionally provide a query (componentName and/or fileNameHint/lineNumber) to search the Fiber graph.
-- If both anchor + query are provided, we rank candidates and pick the best match near the anchor.
-
-Important behavior:
-- The React DevTools hook is helpful but NOT strictly required.
-  - If hook exists, roots are discovered reliably via getFiberRoots().
-  - If hook doesn't exist, we fall back to scanning the DOM for __reactFiber$ pointers (best-effort).
-- Query search returns multiple candidates (up to maxMatches) and ranks them.
-- Debug source information is best-effort and may be missing even in dev builds depending on bundler/build flags.
-
-Operational note for MCP users:
-- If you are using a persistent/headful browser and want more reliable root discovery and component search,
-  install the "React Developer Tools" Chrome extension in that browser profile (manual step by the user).
-        `.trim();
-    }
-    inputSchema() {
-        return {
-            anchorSelector: zod_1.z
-                .string()
-                .optional()
-                .describe('DOM CSS selector used as an anchor to pick a concrete component instance near that element.'),
-            anchorX: zod_1.z
-                .number()
-                .int()
-                .nonnegative()
-                .optional()
-                .describe('Anchor X coordinate (viewport pixels).'),
-            anchorY: zod_1.z
-                .number()
-                .int()
-                .nonnegative()
-                .optional()
-                .describe('Anchor Y coordinate (viewport pixels).'),
-            componentName: zod_1.z
-                .string()
-                .optional()
-                .describe('React component name/displayName to search in the Fiber graph.'),
-            matchStrategy: zod_1.z
-                .enum(['exact', 'contains'])
-                .optional()
-                .default(DEFAULT_MATCH_STRATEGY)
-                .describe('How to match componentName against Fiber type/displayName.'),
-            fileNameHint: zod_1.z
-                .string()
-                .optional()
-                .describe('Best-effort debug source file hint (usually endsWith match), e.g., "UserCard.tsx".'),
-            lineNumber: zod_1.z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .describe('Optional debug source line number hint (dev builds only).'),
-            maxElements: zod_1.z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .default(DEFAULT_MAX_ELEMENTS)
-                .describe('Maximum number of DOM elements to return from the selected component subtree.'),
-            onlyVisible: zod_1.z
-                .boolean()
-                .optional()
-                .default(DEFAULT_ONLY_VISIBLE)
-                .describe('If true, only visually visible elements are returned.'),
-            onlyInViewport: zod_1.z
-                .boolean()
-                .optional()
-                .default(DEFAULT_ONLY_IN_VIEWPORT)
-                .describe('If true, only elements intersecting the viewport are returned.'),
-            textPreviewMaxLength: zod_1.z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .default(DEFAULT_TEXT_PREVIEW_MAX_LENGTH)
-                .describe('Max length for per-element text preview (innerText/textContent/aria-label).'),
-            maxMatches: zod_1.z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .default(DEFAULT_MAX_MATCHES)
-                .describe('Max number of matching component candidates to return/rank.'),
-        };
-    }
-    outputSchema() {
-        return {
-            reactDetected: zod_1.z
-                .boolean()
-                .describe('True if __REACT_DEVTOOLS_GLOBAL_HOOK__ looks available.'),
-            fiberDetected: zod_1.z
-                .boolean()
-                .describe('True if DOM appears to contain React Fiber pointers (__reactFiber$...).'),
-            rootDiscovery: zod_1.z
-                .enum(['devtools-hook', 'dom-fiber-scan', 'none'])
-                .describe('How roots were discovered.'),
-            component: zod_1.z
-                .object({
-                name: zod_1.z.string().nullable(),
-                displayName: zod_1.z.string().nullable(),
-                debugSource: zod_1.z
-                    .object({
-                    fileName: zod_1.z.string().nullable(),
-                    lineNumber: zod_1.z.number().int().nullable(),
-                    columnNumber: zod_1.z.number().int().nullable(),
-                })
-                    .nullable(),
-                componentStack: zod_1.z.array(zod_1.z.string()),
-                selection: zod_1.z.enum([
-                    'anchor',
-                    'query',
-                    'query+anchor',
-                    'unknown',
-                ]),
-                scoring: zod_1.z
-                    .object({
-                    score: zod_1.z.number(),
-                    nameMatched: zod_1.z.boolean(),
-                    debugSourceMatched: zod_1.z.boolean(),
-                    anchorRelated: zod_1.z.boolean(),
-                    proximityPx: zod_1.z.number().nullable().optional(),
-                })
-                    .optional(),
-            })
-                .nullable(),
-            candidates: zod_1.z
-                .array(zod_1.z.object({
-                name: zod_1.z.string().nullable(),
-                displayName: zod_1.z.string().nullable(),
-                debugSource: zod_1.z
-                    .object({
-                    fileName: zod_1.z.string().nullable(),
-                    lineNumber: zod_1.z.number().int().nullable(),
-                    columnNumber: zod_1.z.number().int().nullable(),
-                })
-                    .nullable(),
-                componentStack: zod_1.z.array(zod_1.z.string()),
-                selection: zod_1.z.enum([
-                    'anchor',
-                    'query',
-                    'query+anchor',
-                    'unknown',
-                ]),
-                scoring: zod_1.z
-                    .object({
-                    score: zod_1.z.number(),
-                    nameMatched: zod_1.z.boolean(),
-                    debugSourceMatched: zod_1.z.boolean(),
-                    anchorRelated: zod_1.z.boolean(),
-                    proximityPx: zod_1.z.number().nullable().optional(),
-                })
-                    .optional(),
-                domFootprintCount: zod_1.z.number().int(),
-            }))
-                .describe('Ranked candidate matches (best-first).'),
-            elements: zod_1.z.array(zod_1.z.object({
-                tagName: zod_1.z.string(),
-                id: zod_1.z.string().nullable(),
-                className: zod_1.z.string().nullable(),
-                selectorHint: zod_1.z.string().nullable(),
-                textPreview: zod_1.z.string().nullable(),
-                boundingBox: zod_1.z
-                    .object({
-                    x: zod_1.z.number(),
-                    y: zod_1.z.number(),
-                    width: zod_1.z.number(),
-                    height: zod_1.z.number(),
-                })
-                    .nullable(),
-                isVisible: zod_1.z.boolean(),
-                isInViewport: zod_1.z.boolean(),
-            })),
-            notes: zod_1.z.array(zod_1.z.string()),
-        };
-    }
-    async handle(context, args) {
-        const anchorSelector = args.anchorSelector;
-        const anchorX = args.anchorX;
-        const anchorY = args.anchorY;
-        const componentName = args.componentName;
-        const matchStrategy = args.matchStrategy ?? DEFAULT_MATCH_STRATEGY;
-        const fileNameHint = args.fileNameHint;
-        const lineNumber = args.lineNumber;
-        const maxElements = args.maxElements ?? DEFAULT_MAX_ELEMENTS;
-        const onlyVisible = args.onlyVisible ?? DEFAULT_ONLY_VISIBLE;
-        const onlyInViewport = args.onlyInViewport ?? DEFAULT_ONLY_IN_VIEWPORT;
-        const textPreviewMaxLength = args.textPreviewMaxLength ?? DEFAULT_TEXT_PREVIEW_MAX_LENGTH;
-        const maxMatches = args.maxMatches ?? DEFAULT_MAX_MATCHES;
-        const hasAnchorSelector = typeof anchorSelector === 'string' &&
-            anchorSelector.trim().length > 0;
-        const hasAnchorPoint = typeof anchorX === 'number' && typeof anchorY === 'number';
-        const hasQuery = (typeof componentName === 'string' &&
-            componentName.trim().length > 0) ||
-            (typeof fileNameHint === 'string' &&
-                fileNameHint.trim().length > 0) ||
-            typeof lineNumber === 'number';
-        if (!hasAnchorSelector && !hasAnchorPoint && !hasQuery) {
-            throw new Error('Provide at least one targeting method: anchorSelector, (anchorX+anchorY), or componentName/debugSource hints.');
-        }
-        const result = await context.page.evaluate(({ anchorSelectorEval, anchorXEval, anchorYEval, componentNameEval, matchStrategyEval, fileNameHintEval, lineNumberEval, maxElementsEval, onlyVisibleEval, onlyInViewportEval, textPreviewMaxLengthEval, maxMatchesEval, maxRootsScan, maxFibersVisited, stackLimit, }) => {
-            /**
-             * -----------------------------------------------------------------
-             * Helpers (run in the browser page context)
-             * -----------------------------------------------------------------
-             */
-            const notes = [];
-            function isElement(v) {
-                return (typeof Element !== 'undefined' &&
-                    v instanceof Element);
-            }
-            function normalizeStr(v) {
-                if (typeof v !== 'string') {
-                    return null;
-                }
-                const t = v.trim();
-                if (!t) {
-                    return null;
-                }
-                return t;
-            }
-            /**
-             * React attaches internal keys like:
-             * - __reactFiber$<random>
-             * - __reactInternalInstance$<random> (older)
-             */
-            function getFiberFromDomElement(el) {
-                const anyEl = el;
-                const keys = Object.keys(anyEl);
-                for (const k of keys) {
-                    if (k.startsWith('__reactFiber$')) {
-                        const f = anyEl[k];
-                        if (f) {
-                            return f;
-                        }
-                    }
-                }
-                for (const k of keys) {
-                    if (k.startsWith('__reactInternalInstance$')) {
-                        const f = anyEl[k];
-                        if (f) {
-                            return f;
-                        }
-                    }
-                }
-                return null;
-            }
-            /**
-             * DevTools hook provides reliable Fiber roots via getFiberRoots().
-             * If it's missing, we can still try to use DOM fiber pointers (best-effort),
-             * but component search becomes less reliable.
-             */
-            function getDevtoolsHook() {
-                const g = globalThis;
-                const hook = g.__REACT_DEVTOOLS_GLOBAL_HOOK__;
-                if (!hook) {
-                    return null;
-                }
-                if (typeof hook.getFiberRoots !== 'function') {
-                    return null;
-                }
-                return hook;
-            }
-            function getAllRootsFromHook(hook) {
-                const roots = [];
-                const renderers = hook.renderers;
-                if (!renderers ||
-                    typeof renderers.forEach !== 'function') {
-                    return roots;
-                }
-                renderers.forEach((_renderer, rendererId) => {
-                    try {
-                        const set = hook.getFiberRoots(rendererId);
-                        if (set &&
-                            typeof set.forEach === 'function') {
-                            set.forEach((root) => {
-                                if (root) {
-                                    roots.push(root);
-                                }
-                            });
-                        }
-                    }
-                    catch {
-                        // ignore
-                    }
-                });
-                return roots.slice(0, maxRootsScan);
-            }
-            /**
-             * DOM-only fallback: find a few fiber pointers by scanning the DOM.
-             * This provides seed fibers even without the DevTools hook.
-             */
-            function getSeedFibersFromDomScan(maxSeeds) {
-                const out = [];
-                const els = Array.from(document.querySelectorAll('*'));
-                const step = els.length > 5000
-                    ? Math.ceil(els.length / 5000)
-                    : 1;
-                for (let i = 0; i < els.length; i += step) {
-                    const el = els[i];
-                    const f = getFiberFromDomElement(el);
-                    if (f) {
-                        out.push(f);
-                        if (out.length >= maxSeeds) {
-                            break;
-                        }
-                    }
-                }
-                return out;
-            }
-            function getFunctionDisplayName(fn) {
-                if (typeof fn !== 'function') {
-                    return null;
-                }
-                const anyFn = fn;
-                const dn = normalizeStr(anyFn.displayName);
-                if (dn) {
-                    return dn;
-                }
-                const nm = normalizeStr(anyFn.name);
-                if (nm) {
-                    return nm;
-                }
-                return null;
-            }
-            function getFiberTypeName(fiber) {
-                if (!fiber) {
-                    return null;
-                }
-                const t = fiber.type ?? fiber.elementType ?? null;
-                if (!t) {
-                    return null;
-                }
-                if (typeof t === 'function') {
-                    return getFunctionDisplayName(t);
-                }
-                if (typeof t === 'string') {
-                    return t; // host component name
-                }
-                const dn = normalizeStr(t.displayName);
-                if (dn) {
-                    return dn;
-                }
-                return normalizeStr(t.name);
-            }
-            function getDisplayName(fiber) {
-                if (!fiber) {
-                    return null;
-                }
-                const t = fiber.type ?? fiber.elementType ?? null;
-                if (!t) {
-                    return null;
-                }
-                const dn = normalizeStr(t.displayName);
-                if (dn) {
-                    return dn;
-                }
-                return getFiberTypeName(fiber);
-            }
-            /**
-             * Best-effort debug source extraction.
-             *
-             * IMPORTANT:
-             * Even when React DevTools shows "Rendered by <file>:<line>",
-             * fiber._debugSource can still be null because DevTools may derive source
-             * via stack traces + sourcemaps and keep that mapping internally.
-             */
-            function getDebugSource(fiber) {
-                const seen = new Set();
-                const queue = [];
-                const push = (x) => {
-                    if (!x) {
-                        return;
-                    }
-                    if (seen.has(x)) {
-                        return;
-                    }
-                    seen.add(x);
-                    queue.push(x);
-                };
-                push(fiber);
-                push(fiber?.alternate);
-                // Walk a few owners up (best-effort)
-                for (let i = 0; i < 8; i++) {
-                    const f = queue[i];
-                    if (!f) {
-                        break;
-                    }
-                    push(f?._debugOwner);
-                    push(f?._debugOwner?.alternate);
-                }
-                for (const f of queue) {
-                    const src = f?._debugSource ??
-                        f?._debugOwner?._debugSource ??
-                        f?.type?._debugSource ??
-                        f?.elementType?._debugSource ??
-                        null;
-                    if (!src) {
-                        continue;
-                    }
-                    const fileName = normalizeStr(src.fileName) ?? null;
-                    const lineNumber = typeof src.lineNumber === 'number'
-                        ? src.lineNumber
-                        : null;
-                    const columnNumber = typeof src.columnNumber === 'number'
-                        ? src.columnNumber
-                        : null;
-                    if (fileName ||
-                        lineNumber !== null ||
-                        columnNumber !== null) {
-                        return { fileName, lineNumber, columnNumber };
-                    }
-                }
-                return null;
-            }
-            function isHostFiber(fiber) {
-                const sn = fiber?.stateNode;
-                return isElement(sn);
-            }
-            /**
-             * Build a best-effort component stack from selected fiber up to root.
-             * We prefer non-host fibers for readability, but fall back to include hosts if needed.
-             */
-            function buildComponentStack(fiber, limit) {
-                const out = [];
-                let cur = fiber ?? null;
-                for (let i = 0; i < limit; i++) {
-                    if (!cur) {
-                        break;
-                    }
-                    const name = getDisplayName(cur);
-                    const host = isHostFiber(cur);
-                    if (name && !host) {
-                        out.push(name);
-                    }
-                    cur = cur.return ?? null;
-                }
-                if (out.length === 0) {
-                    cur = fiber ?? null;
-                    for (let i = 0; i < limit; i++) {
-                        if (!cur) {
-                            break;
-                        }
-                        const name = getDisplayName(cur);
-                        if (name) {
-                            out.push(name);
-                        }
-                        cur = cur.return ?? null;
-                    }
-                }
-                // De-dupe consecutive duplicates (wrappers can repeat)
-                const deduped = [];
-                for (const n of out) {
-                    if (deduped.length === 0) {
-                        deduped.push(n);
-                    }
-                    else {
-                        if (deduped[deduped.length - 1] !== n) {
-                            deduped.push(n);
-                        }
-                    }
-                }
-                return deduped;
-            }
-            function firstMeaningfulComponentAbove(fiber) {
-                let cur = fiber ?? null;
-                const visited = new Set();
-                while (cur) {
-                    const key = cur.alternate ?? cur;
-                    if (visited.has(key)) {
-                        break;
-                    }
-                    visited.add(key);
-                    if (!isHostFiber(cur)) {
-                        return cur;
-                    }
-                    cur = cur.return ?? null;
-                }
-                return null;
-            }
-            function matchesName(candidate, query, strategy) {
-                if (!candidate) {
-                    return false;
-                }
-                const a = candidate.trim();
-                const b = query.trim();
-                if (!a || !b) {
-                    return false;
-                }
-                if (strategy === 'exact') {
-                    return a === b;
-                }
-                return a.toLowerCase().includes(b.toLowerCase());
-            }
-            function matchesDebugSource(fiber, fileNameHint, lineNumber) {
-                const src = getDebugSource(fiber);
-                if (!src) {
-                    return false;
-                }
-                if (fileNameHint) {
-                    const hint = fileNameHint.trim();
-                    if (hint) {
-                        const fn = (src.fileName ?? '').trim();
-                        if (!fn) {
-                            return false;
-                        }
-                        const fnLower = fn.toLowerCase();
-                        const hintLower = hint.toLowerCase();
-                        const ok = fnLower.endsWith(hintLower) ||
-                            fnLower.includes(hintLower);
-                        if (!ok) {
-                            return false;
-                        }
-                    }
-                }
-                if (typeof lineNumber === 'number') {
-                    if (src.lineNumber === null) {
-                        return false;
-                    }
-                    // Allow small drift due to transforms
-                    const delta = Math.abs(src.lineNumber - lineNumber);
-                    if (delta > 3) {
-                        return false;
-                    }
-                }
-                return true;
-            }
-            /**
-             * Roots can be either:
-             * - a "root object" containing .current
-             * - a fiber itself
-             *
-             * We start from root.current.child to avoid getting stuck at the HostRoot wrapper.
-             */
-            function toStartFiber(rootOrFiber) {
-                if (!rootOrFiber) {
-                    return null;
-                }
-                const maybeCurrent = rootOrFiber.current;
-                if (maybeCurrent) {
-                    return maybeCurrent.child ?? maybeCurrent;
-                }
-                return rootOrFiber;
-            }
-            function pickAnchorElement(anchorSelector, x, y) {
-                if (anchorSelector && anchorSelector.trim()) {
-                    const el = document.querySelector(anchorSelector);
-                    if (!el) {
-                        notes.push(`anchorSelector did not match any element: ${anchorSelector}`);
-                        return null;
-                    }
-                    return el;
-                }
-                if (typeof x === 'number' && typeof y === 'number') {
-                    const el = document.elementFromPoint(x, y);
-                    if (!el) {
-                        notes.push(`anchorPoint did not hit any element: (${x}, ${y})`);
-                        return null;
-                    }
-                    return el;
-                }
-                return null;
-            }
-            function selectorHintFor(el) {
-                const dt = normalizeStr(el.getAttribute('data-testid')) ??
-                    normalizeStr(el.getAttribute('data-test-id')) ??
-                    normalizeStr(el.getAttribute('data-test')) ??
-                    null;
-                if (dt) {
-                    return `[data-testid='${dt.replace(/'/g, "\\'")}']`;
-                }
-                const ds = normalizeStr(el.getAttribute('data-selector')) ??
-                    null;
-                if (ds) {
-                    return `[data-selector='${ds.replace(/'/g, "\\'")}']`;
-                }
-                if (el.id) {
-                    try {
-                        return `#${CSS.escape(el.id)}`;
-                    }
-                    catch {
-                        return `#${el.id}`;
-                    }
-                }
-                return el.tagName.toLowerCase();
-            }
-            function textPreviewFor(el, maxLen) {
-                const aria = normalizeStr(el.getAttribute('aria-label')) ?? null;
-                if (aria) {
-                    return aria.slice(0, maxLen);
-                }
-                const txt = String(el.innerText ?? el.textContent ?? '').trim();
-                if (!txt) {
-                    return null;
-                }
-                return txt.slice(0, maxLen);
-            }
-            function computeRuntime(el) {
-                const r = el.getBoundingClientRect();
-                const s = getComputedStyle(el);
-                const isVisible = s.display !== 'none' &&
-                    s.visibility !== 'hidden' &&
-                    parseFloat(s.opacity || '1') > 0 &&
-                    r.width > 0 &&
-                    r.height > 0;
-                const vw = window.innerWidth;
-                const vh = window.innerHeight;
-                const isInViewport = r.right > 0 &&
-                    r.bottom > 0 &&
-                    r.left < vw &&
-                    r.top < vh;
-                const boundingBox = Number.isFinite(r.x) &&
-                    Number.isFinite(r.y) &&
-                    Number.isFinite(r.width) &&
-                    Number.isFinite(r.height)
-                    ? {
-                        x: r.x,
-                        y: r.y,
-                        width: r.width,
-                        height: r.height,
-                    }
-                    : null;
-                const centerX = r.left + r.width / 2;
-                const centerY = r.top + r.height / 2;
-                return {
-                    boundingBox,
-                    isVisible,
-                    isInViewport,
-                    centerX,
-                    centerY,
-                };
-            }
-            function collectDomElementsFromFiberSubtree(fiber, maxElements, onlyVisible, onlyInViewport, textPreviewMaxLength) {
-                const out = [];
-                const seen = new Set();
-                const stack = [];
-                if (fiber) {
-                    stack.push(fiber);
-                }
-                const visited = new Set();
-                while (stack.length > 0) {
-                    if (out.length >= maxElements) {
-                        break;
-                    }
-                    const f = stack.pop();
-                    if (!f) {
-                        continue;
-                    }
-                    const key = f.alternate ?? f;
-                    if (visited.has(key)) {
-                        continue;
-                    }
-                    visited.add(key);
-                    if (isHostFiber(f)) {
-                        const el = f.stateNode;
-                        if (!seen.has(el)) {
-                            seen.add(el);
-                            const rt = computeRuntime(el);
-                            if (onlyVisible && !rt.isVisible) {
-                                // skip
-                            }
-                            else {
-                                if (onlyInViewport &&
-                                    !rt.isInViewport) {
-                                    // skip
-                                }
-                                else {
-                                    const tagName = el.tagName.toLowerCase();
-                                    const id = el.id
-                                        ? String(el.id)
-                                        : null;
-                                    const classNameRaw = el.className;
-                                    const className = typeof classNameRaw === 'string'
-                                        ? classNameRaw.trim()
-                                            ? classNameRaw.trim()
-                                            : null
-                                        : null;
-                                    out.push({
-                                        tagName,
-                                        id,
-                                        className,
-                                        selectorHint: selectorHintFor(el),
-                                        textPreview: textPreviewFor(el, textPreviewMaxLength),
-                                        boundingBox: rt.boundingBox,
-                                        isVisible: rt.isVisible,
-                                        isInViewport: rt.isInViewport,
-                                    });
-                                }
-                            }
-                        }
-                    }
-                    const child = f.child ?? null;
-                    const sibling = f.sibling ?? null;
-                    if (child) {
-                        stack.push(child);
-                    }
-                    if (sibling) {
-                        stack.push(sibling);
-                    }
-                }
-                return out;
-            }
-            /**
-             * Search for matching fibers and return multiple candidates.
-             * Key fixes vs the old version:
-             * - Start traversal from root.current.child (if root object), not from root itself
-             * - Traverse a stable "current" graph; de-dupe using alternate/current pair
-             * - Collect multiple matches up to maxMatches
-             */
-            function findFibersByQuery(roots, query, maxMatches) {
-                const nameQ = query.componentName
-                    ? query.componentName.trim()
-                    : undefined;
-                const hasNameQ = Boolean(nameQ);
-                const fileQ = query.fileNameHint
-                    ? query.fileNameHint.trim()
-                    : undefined;
-                const hasFileQ = Boolean(fileQ);
-                const hasLineQ = typeof query.lineNumber === 'number';
-                const wantsAnything = hasNameQ || hasFileQ || hasLineQ;
-                if (!wantsAnything) {
-                    return [];
-                }
-                const stack = [];
-                for (const r of roots) {
-                    const start = toStartFiber(r);
-                    if (start) {
-                        stack.push(start);
-                    }
-                }
-                const visited = new Set();
-                const matches = [];
-                let visitedCount = 0;
-                while (stack.length > 0) {
-                    if (matches.length >= maxMatches) {
-                        break;
-                    }
-                    const f = stack.pop();
-                    if (!f) {
-                        continue;
-                    }
-                    const key = f.alternate ?? f;
-                    if (visited.has(key)) {
-                        continue;
-                    }
-                    visited.add(key);
-                    visitedCount++;
-                    if (visitedCount > maxFibersVisited) {
-                        notes.push(`Fiber traversal safety cap reached (${maxFibersVisited}). Results may be incomplete.`);
-                        break;
-                    }
-                    const dn = getDisplayName(f);
-                    const tn = getFiberTypeName(f);
-                    const nameMatches = hasNameQ
-                        ? matchesName(dn, nameQ, query.matchStrategy) ||
-                            matchesName(tn, nameQ, query.matchStrategy)
-                        : true;
-                    const srcMatches = hasFileQ || hasLineQ
-                        ? matchesDebugSource(f, fileQ, query.lineNumber)
-                        : true;
-                    if (nameMatches && srcMatches) {
-                        matches.push(f);
-                    }
-                    const child = f.child ?? null;
-                    const sibling = f.sibling ?? null;
-                    if (child) {
-                        stack.push(child);
-                    }
-                    if (sibling) {
-                        stack.push(sibling);
-                    }
-                }
-                return matches;
-            }
-            /**
-             * Score a candidate fiber using a heuristic:
-             * - Prefer explicit name matches and debugSource matches (if provided)
-             * - Prefer candidates related to the anchor (same subtree / overlapping area)
-             * - Prefer candidates with some DOM footprint (host nodes)
-             * - Prefer candidates near anchor point (if provided)
-             */
-            function scoreCandidate(fiber, anchorEl, anchorX, anchorY, q, maxElements, onlyVisible, onlyInViewport, textPreviewMaxLength) {
-                const nameQ = q.componentName
-                    ? q.componentName.trim()
-                    : undefined;
-                const hasNameQ = Boolean(nameQ);
-                const dn = getDisplayName(fiber);
-                const tn = getFiberTypeName(fiber);
-                const nameMatched = hasNameQ
-                    ? matchesName(dn, nameQ, q.matchStrategy) ||
-                        matchesName(tn, nameQ, q.matchStrategy)
-                    : false;
-                const debugSourceMatched = Boolean(normalizeStr(q.fileNameHint)) ||
-                    typeof q.lineNumber === 'number'
-                    ? matchesDebugSource(fiber, normalizeStr(q.fileNameHint) ?? undefined, typeof q.lineNumber === 'number'
-                        ? q.lineNumber
-                        : undefined)
-                    : false;
-                const dom = collectDomElementsFromFiberSubtree(fiber, maxElements, onlyVisible, onlyInViewport, textPreviewMaxLength);
-                let anchorRelated = false;
-                let proximityPx = null;
-                if (anchorEl) {
-                    const anchorSel = selectorHintFor(anchorEl);
-                    anchorRelated =
-                        dom.some((d) => {
-                            if (!d.selectorHint || !anchorSel) {
-                                return false;
-                            }
-                            return d.selectorHint === anchorSel;
-                        }) ||
-                            dom.some((d) => {
-                                if (!d.boundingBox) {
-                                    return false;
-                                }
-                                const r = anchorEl.getBoundingClientRect();
-                                const bb = d.boundingBox;
-                                // Overlap heuristic
-                                const overlaps = r.left < bb.x + bb.width &&
-                                    r.left + r.width > bb.x &&
-                                    r.top < bb.y + bb.height &&
-                                    r.top + r.height > bb.y;
-                                return overlaps;
-                            });
-                    if (typeof anchorX === 'number' &&
-                        typeof anchorY === 'number' &&
-                        dom.length > 0) {
-                        let best = null;
-                        for (const item of dom) {
-                            if (!item.boundingBox) {
-                                continue;
-                            }
-                            const cx = item.boundingBox.x +
-                                item.boundingBox.width / 2;
-                            const cy = item.boundingBox.y +
-                                item.boundingBox.height / 2;
-                            const dx = cx - anchorX;
-                            const dy = cy - anchorY;
-                            const dist = Math.sqrt(dx * dx + dy * dy);
-                            if (best === null) {
-                                best = dist;
-                            }
-                            else {
-                                if (dist < best) {
-                                    best = dist;
-                                }
-                            }
-                        }
-                        proximityPx = best;
-                    }
-                }
-                let score = 0;
-                score += nameMatched ? 3.0 : 0;
-                score += debugSourceMatched ? 3.0 : 0;
-                score += anchorRelated ? 2.0 : 0;
-                // Favor some DOM footprint (but cap influence)
-                score += Math.min(1.5, dom.length / 25);
-                if (typeof proximityPx === 'number' &&
-                    Number.isFinite(proximityPx)) {
-                    // 0px => +1.5, 300px => ~+0.3, 1000px => tiny
-                    const p = Math.max(0, Math.min(1, 1 - proximityPx / 1000));
-                    score += 1.5 * p;
-                }
-                return {
-                    score,
-                    nameMatched,
-                    debugSourceMatched,
-                    anchorRelated,
-                    proximityPx,
-                    dom,
-                };
-            }
-            /**
-             * -----------------------------------------------------------------------------
-             * Main logic
-             * -----------------------------------------------------------------------------
-             */
-            const hook = getDevtoolsHook();
-            const reactDetected = Boolean(hook);
-            // Tell the user explicitly how to make this better
-            if (!reactDetected) {
-                notes.push('React DevTools hook was not detected (__REACT_DEVTOOLS_GLOBAL_HOOK__).');
-                notes.push('If you are using a persistent/headful browser profile, install the "React Developer Tools" Chrome extension in that profile (manual step by the user) to enable reliable root discovery and component search.');
-            }
-            else {
-                notes.push('React DevTools hook detected. Root discovery will use getFiberRoots() (more reliable).');
-            }
-            const fiberDetected = (() => {
-                const body = document.body;
-                if (!body) {
-                    return false;
-                }
-                const f = getFiberFromDomElement(body);
-                if (f) {
-                    return true;
-                }
-                const seeds = getSeedFibersFromDomScan(1);
-                if (seeds.length > 0) {
-                    return true;
-                }
-                return false;
-            })();
-            if (!fiberDetected) {
-                notes.push('No React Fiber pointers were detected on DOM nodes (__reactFiber$...). This can happen if the page is not React, React has not rendered yet, or internals are unavailable.');
-            }
-            else {
-                notes.push('React Fiber pointers detected on DOM nodes. Anchor-based mapping may still work without the DevTools hook (best-effort).');
-            }
-            const anchorEl = pickAnchorElement(anchorSelectorEval, anchorXEval, anchorYEval);
-            // 1) Anchor-based selection (works without hook if DOM fiber exists)
-            let anchorSelected = null;
-            if (anchorEl) {
-                const anchorFiber = getFiberFromDomElement(anchorEl);
-                if (anchorFiber) {
-                    const candidateA = anchorFiber;
-                    const candidateB = anchorFiber.alternate ?? null;
-                    // Prefer the side that appears more "connected"
-                    let chosen = candidateA;
-                    if (candidateB) {
-                        if ((candidateB.child || candidateB.sibling) &&
-                            !(candidateA.child || candidateA.sibling)) {
-                            chosen = candidateB;
-                        }
-                    }
-                    const nearestComponent = firstMeaningfulComponentAbove(chosen);
-                    if (nearestComponent) {
-                        anchorSelected = nearestComponent;
-                    }
-                    else {
-                        notes.push('Anchor fiber found but no meaningful component fiber was found above it.');
-                    }
-                }
-                else {
-                    notes.push('Anchor element found but React fiber was not found on it.');
-                }
-            }
-            // 2) Discover roots (hook or DOM scan)
-            let roots = [];
-            let rootDiscovery = 'none';
-            if (hook) {
-                const r = getAllRootsFromHook(hook);
-                if (r.length > 0) {
-                    roots = r;
-                    rootDiscovery = 'devtools-hook';
-                }
-            }
-            if (roots.length === 0) {
-                if (fiberDetected) {
-                    const seeds = getSeedFibersFromDomScan(10);
-                    if (seeds.length > 0) {
-                        roots = seeds;
-                        rootDiscovery = 'dom-fiber-scan';
-                        notes.push('Using DOM fiber scan as fallback root discovery (best-effort).');
-                    }
-                }
-            }
-            // 3) Query search (optional)
-            const hasQuery = Boolean(normalizeStr(componentNameEval)) ||
-                Boolean(normalizeStr(fileNameHintEval)) ||
-                typeof lineNumberEval === 'number';
-            const query = {
-                componentName: normalizeStr(componentNameEval) ?? undefined,
-                matchStrategy: matchStrategyEval,
-                fileNameHint: normalizeStr(fileNameHintEval) ?? undefined,
-                lineNumber: typeof lineNumberEval === 'number'
-                    ? lineNumberEval
-                    : undefined,
-            };
-            let queryMatches = [];
-            if (hasQuery) {
-                if (roots.length > 0) {
-                    queryMatches = findFibersByQuery(roots, query, Math.max(1, Math.floor(maxMatchesEval)));
-                }
-                else {
-                    notes.push('Query was provided but no roots could be discovered. Provide an anchorSelector/anchorX+anchorY so we can map via DOM fiber pointers.');
-                }
-            }
-            // 4) Candidate pool
-            const candidates = [];
-            if (anchorSelected) {
-                candidates.push(anchorSelected);
-            }
-            for (const f of queryMatches) {
-                candidates.push(f);
-            }
-            // De-dupe candidate pool by alternate key
-            const uniq = [];
-            const seenCand = new Set();
-            for (const f of candidates) {
-                const key = f?.alternate ?? f;
-                if (f && !seenCand.has(key)) {
-                    seenCand.add(key);
-                    uniq.push(f);
-                }
-            }
-            if (uniq.length === 0) {
-                // Hook missing should be explicit in the notes (user action)
-                if (!reactDetected) {
-                    notes.push('No candidates found. Without the DevTools hook, component search may be unreliable unless you provide a strong anchor.');
-                }
-                return {
-                    reactDetected,
-                    fiberDetected,
-                    rootDiscovery,
-                    component: null,
-                    candidates: [],
-                    elements: [],
-                    notes: [
-                        ...notes,
-                        'Failed to select a target component fiber. Provide a better anchor, or ensure React is present and render has happened.',
-                    ],
-                };
-            }
-            // 5) Score candidates and pick the best
-            const scored = [];
-            for (const f of uniq) {
-                const s = scoreCandidate(f, anchorEl, anchorXEval, anchorYEval, query, maxElementsEval, onlyVisibleEval, onlyInViewportEval, textPreviewMaxLengthEval);
-                let selection = 'unknown';
-                const isAnchor = anchorSelected
-                    ? (anchorSelected.alternate ?? anchorSelected) ===
-                        (f.alternate ?? f)
-                    : false;
-                const isQuery = queryMatches.some((qf) => (qf.alternate ?? qf) === (f.alternate ?? f));
-                if (isAnchor && isQuery) {
-                    selection = 'query+anchor';
-                }
-                else {
-                    if (isAnchor) {
-                        selection = 'anchor';
-                    }
-                    else {
-                        if (isQuery) {
-                            selection = 'query';
-                        }
-                        else {
-                            selection = 'unknown';
-                        }
-                    }
-                }
-                const name = getFiberTypeName(f);
-                const displayName = getDisplayName(f);
-                const debugSource = getDebugSource(f);
-                const componentStack = buildComponentStack(f, stackLimit);
-                const meta = {
-                    name,
-                    displayName,
-                    debugSource,
-                    componentStack,
-                    selection,
-                    scoring: {
-                        score: s.score,
-                        nameMatched: s.nameMatched,
-                        debugSourceMatched: s.debugSourceMatched,
-                        anchorRelated: s.anchorRelated,
-                        proximityPx: s.proximityPx,
-                    },
-                };
-                scored.push({
-                    fiber: f,
-                    meta,
-                    dom: s.dom,
-                    domFootprintCount: s.dom.length,
-                });
-            }
-            scored.sort((a, b) => (b.meta.scoring?.score ?? 0) -
-                (a.meta.scoring?.score ?? 0));
-            const best = scored[0];
-            const outCandidates = scored
-                .slice(0, Math.max(1, Math.floor(maxMatchesEval)))
-                .map((c) => {
-                return {
-                    ...c.meta,
-                    domFootprintCount: c.domFootprintCount,
-                };
-            });
-            const elements = best.dom;
-            // Notes about debug source / missing info
-            if (hasQuery &&
-                (query.fileNameHint ||
-                    typeof query.lineNumber === 'number')) {
-                const anyHasDebug = outCandidates.some((c) => {
-                    if (c.debugSource?.fileName) {
-                        return true;
-                    }
-                    if (c.debugSource?.lineNumber !== null) {
-                        return true;
-                    }
-                    return false;
-                });
-                if (!anyHasDebug) {
-                    notes.push('debugSource hints were provided, but no _debugSource information was found on matched fibers. This is common in production builds and some dev toolchains.');
-                    notes.push('React DevTools may still display "Rendered by <file>:<line>" using sourcemaps/stack traces even when fiber._debugSource is null.');
-                }
-            }
-            if (elements.length >= maxElementsEval) {
-                notes.push(`Element list was truncated at maxElements=${maxElementsEval}. Increase maxElements if needed.`);
-            }
-            if (elements.length === 0) {
-                notes.push('No DOM elements were returned for the selected component. It may render no host elements, or filtering (onlyVisible/onlyInViewport) removed them.');
-            }
-            // Explain hook vs fallback
-            if (!reactDetected && fiberDetected) {
-                notes.push('React DevTools hook was not detected, but DOM fiber pointers were found. Using DOM-fiber scanning and anchor-based mapping (best-effort).');
-            }
-            else {
-                if (!reactDetected && !fiberDetected) {
-                    notes.push('React DevTools hook was not detected and no DOM fiber pointers were found. Component-to-DOM mapping is unavailable on this page.');
-                }
-            }
-            return {
-                reactDetected,
-                fiberDetected,
-                rootDiscovery,
-                component: best.meta,
-                candidates: outCandidates,
-                elements,
-                notes: [
-                    ...notes,
-                    'Component metadata is best-effort. Wrappers (memo/forwardRef/HOCs), Suspense/Offscreen, and portals may make names/stacks noisy.',
-                ],
-            };
-        }, {
-            anchorSelectorEval: typeof anchorSelector === 'string' &&
-                anchorSelector.trim()
-                ? anchorSelector.trim()
-                : undefined,
-            anchorXEval: typeof anchorX === 'number' && Number.isFinite(anchorX)
-                ? Math.floor(anchorX)
-                : undefined,
-            anchorYEval: typeof anchorY === 'number' && Number.isFinite(anchorY)
-                ? Math.floor(anchorY)
-                : undefined,
-            componentNameEval: typeof componentName === 'string' &&
-                componentName.trim()
-                ? componentName.trim()
-                : undefined,
-            matchStrategyEval: matchStrategy,
-            fileNameHintEval: typeof fileNameHint === 'string' && fileNameHint.trim()
-                ? fileNameHint.trim()
-                : undefined,
-            lineNumberEval: typeof lineNumber === 'number' &&
-                Number.isFinite(lineNumber)
-                ? Math.floor(lineNumber)
-                : undefined,
-            maxElementsEval: Math.max(1, Math.floor(maxElements)),
-            onlyVisibleEval: Boolean(onlyVisible),
-            onlyInViewportEval: Boolean(onlyInViewport),
-            textPreviewMaxLengthEval: Math.max(1, Math.floor(textPreviewMaxLength)),
-            maxMatchesEval: Math.max(1, Math.floor(maxMatches)),
-            maxRootsScan: INTERNAL_MAX_ROOTS_SCAN,
-            maxFibersVisited: INTERNAL_MAX_FIBERS_VISITED,
-            stackLimit: DEFAULT_STACK_LIMIT,
-        });
-        return result;
-    }
-}
-exports.GetElementForComponent = GetElementForComponent;
-//# sourceMappingURL=get-element-for-component.js.map