@treelocator/runtime 0.2.0 → 0.3.1

package/.turbo/turbo-build.log

@@ -1,32 +1,32 @@
 
-> @treelocator/runtime@0.1.8 build /Users/wende/projects/locatorjs/packages/runtime
+> @treelocator/runtime@0.3.1 build /Users/wende/projects/treelocatorjs/packages/runtime
 > concurrently pnpm:build:*
 
-[tailwind] 
-[tailwind] > @treelocator/runtime@0.1.8 build:tailwind /Users/wende/projects/locatorjs/packages/runtime
-[tailwind] > tailwindcss -i ./src/main.css -o ./dist/output.css
-[tailwind] 
-[babel] 
-[babel] > @treelocator/runtime@0.1.8 build:babel /Users/wende/projects/locatorjs/packages/runtime
-[babel] > babel src --out-dir dist --extensions .js,.jsx,.ts,.tsx
-[babel] 
 [wrapImage] 
-[wrapImage] > @treelocator/runtime@0.1.8 build:wrapImage /Users/wende/projects/locatorjs/packages/runtime
+[wrapImage] > @treelocator/runtime@0.3.1 build:wrapImage /Users/wende/projects/treelocatorjs/packages/runtime
 [wrapImage] > node ./scripts/wrapImage.js
 [wrapImage] 
 [ts] 
-[ts] > @treelocator/runtime@0.1.8 build:ts /Users/wende/projects/locatorjs/packages/runtime
+[ts] > @treelocator/runtime@0.3.1 build:ts /Users/wende/projects/treelocatorjs/packages/runtime
 [ts] > tsc --declaration --emitDeclarationOnly --noEmit false --outDir dist
 [ts] 
+[babel] 
+[babel] > @treelocator/runtime@0.3.1 build:babel /Users/wende/projects/treelocatorjs/packages/runtime
+[babel] > babel src --out-dir dist --extensions .js,.jsx,.ts,.tsx
+[babel] 
+[tailwind] 
+[tailwind] > @treelocator/runtime@0.3.1 build:tailwind /Users/wende/projects/treelocatorjs/packages/runtime
+[tailwind] > tailwindcss -i ./src/main.css -o ./dist/output.css
+[tailwind] 
 [wrapImage] Tree icon file generated
 [wrapImage] pnpm run build:wrapImage exited with code 0
+[babel] [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
 [tailwind] [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
 [tailwind] 
 [tailwind] Rebuilding...
 [tailwind] 
-[tailwind] Done in 173ms.
+[tailwind] Done in 175ms.
 [tailwind] pnpm run build:tailwind exited with code 0
-[babel] [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
-[babel] Successfully compiled 80 files with Babel (499ms).
+[babel] Successfully compiled 82 files with Babel (602ms).
 [babel] pnpm run build:babel exited with code 0
 [ts] pnpm run build:ts exited with code 0

package/.turbo/turbo-test.log

@@ -1,63 +1,14 @@
 
-> @treelocator/runtime@0.1.8 test /Users/wende/projects/locatorjs/packages/runtime
+> @treelocator/runtime@0.3.0 test /Users/wende/projects/treelocatorjs/packages/runtime
 > vitest run
 
 
- RUN  v2.1.9 /Users/wende/projects/locatorjs/packages/runtime
+ RUN  v2.1.9 /Users/wende/projects/treelocatorjs/packages/runtime
 
+ ✓ src/functions/formatAncestryChain.test.ts (9 tests) 2ms
  ✓ src/functions/evalTemplate.test.ts (1 test) 1ms
- ✓ src/functions/transformPath.test.ts (3 tests) 1ms
- ✓ src/functions/mergeRects.test.ts (1 test) 2ms
  ✓ src/functions/cropPath.test.ts (2 tests) 1ms
- ✓ src/functions/getUsableFileName.test.tsx (4 tests) 4ms
- ❯ src/functions/formatAncestryChain.test.ts (9 tests | 2 failed) 7ms
-   × formatAncestryChain > shows all owner components when ownerComponents is provided 4ms
-     → expected 'div in App at src/App.jsx:104\n    └─…' to be 'div in App at src/App.jsx:104\n    └─…' // Object.is equality
-   × formatAncestryChain > shows single owner component without arrow when only one in chain 1ms
-     → expected 'Button at src/Button.tsx:10' to be 'button in Button at src/Button.tsx:10' // Object.is equality
- ✓ src/adapters/phoenix/__tests__/parsePhoenixComments.test.ts (14 tests) 16ms
-
-⎯⎯⎯⎯⎯⎯⎯ Failed Tests 2 ⎯⎯⎯⎯⎯⎯⎯
-
- FAIL  src/functions/formatAncestryChain.test.ts > formatAncestryChain > shows all owner components when ownerComponents is provided
-AssertionError: expected 'div in App at src/App.jsx:104\n    └─…' to be 'div in App at src/App.jsx:104\n    └─…' // Object.is equality
-
-- Expected
-+ Received
-
-  div in App at src/App.jsx:104
--     └─ div#sidebar-panel in Sidebar > GlassPanel at src/components/game/Sidebar.jsx:78
-+     └─ GlassPanel#sidebar-panel in Sidebar at src/components/game/Sidebar.jsx:78
-
- ❯ src/functions/formatAncestryChain.test.ts:120:20
-    118| 
-    119|     const result = formatAncestryChain(items);
-    120|     expect(result).toBe(
-       |                    ^
-    121|       `div in App at src/App.jsx:104
-    122|     └─ div#sidebar-panel in Sidebar > GlassPanel at src/components/gam…
-
-⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/2]⎯
-
- FAIL  src/functions/formatAncestryChain.test.ts > formatAncestryChain > shows single owner component without arrow when only one in chain
-AssertionError: expected 'Button at src/Button.tsx:10' to be 'button in Button at src/Button.tsx:10' // Object.is equality
-
-Expected: "button in Button at src/Button.tsx:10"
-Received: "Button at src/Button.tsx:10"
-
- ❯ src/functions/formatAncestryChain.test.ts:138:20
-    136| 
-    137|     const result = formatAncestryChain(items);
-    138|     expect(result).toBe("button in Button at src/Button.tsx:10");
-       |                    ^
-    139|   });
-    140| });
-
-⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[2/2]⎯
-
- Test Files  1 failed | 6 passed (7)
-      Tests  2 failed | 32 passed (34)
-   Start at  11:30:22
-   Duration  904ms (transform 370ms, setup 0ms, collect 434ms, tests 32ms, environment 497ms, prepare 595ms)
-
+ ✓ src/functions/mergeRects.test.ts (1 test) 1ms
+ ✓ src/functions/getUsableFileName.test.tsx (4 tests) 2ms
+ ✓ src/functions/transformPath.test.ts (3 tests) 6ms
  ELIFECYCLE  Test failed. See above for more details.

package/dist/adapters/createTreeNode.js

@@ -4,6 +4,15 @@ import { SvelteTreeNodeElement } from "./svelte/svelteAdapter";
 import { VueTreeNodeElement } from "./vue/vueAdapter";
 import { detectJSX, detectReact, detectSvelte, detectVue } from "@locator/shared";
 import { detectPhoenix } from "./phoenix/detectPhoenix";
+
+/**
+ * Fallback React detection: check if any DOM element has __reactFiber$ keys.
+ * Works without React DevTools extension (where detectReact() fails because
+ * the renderers Map is empty).
+ */
+function hasReactFiberKeys(element) {
+  return Object.keys(element).some(k => k.startsWith("__reactFiber$"));
+}
 export function createTreeNode(element, adapterId) {
   // Check for explicit adapter ID first
   if (adapterId === "react") {
@@ -26,7 +35,7 @@ export function createTreeNode(element, adapterId) {
   if (detectVue()) {
     return new VueTreeNodeElement(element);
   }
-  if (detectReact()) {
+  if (detectReact() || hasReactFiberKeys(element)) {
     return new ReactTreeNodeElement(element);
   }
 

package/dist/adapters/react/findDebugSource.d.ts

@@ -3,3 +3,16 @@ export declare function findDebugSource(fiber: Fiber): {
     fiber: Fiber;
     source: Source;
 } | null;
+/**
+ * Async version of findDebugSource that supports React 19's _debugStack.
+ * Falls back to synchronous _debugSource check first (React 18).
+ * If that fails, parses _debugStack and resolves via source maps.
+ */
+export declare function findDebugSourceAsync(fiber: Fiber): Promise<{
+    fiber: Fiber;
+    source: Source;
+} | null>;
+/**
+ * Check if this is a React 19+ environment (has _debugStack but not _debugSource).
+ */
+export declare function isReact19Fiber(fiber: Fiber): boolean;

package/dist/adapters/react/findDebugSource.js

@@ -1,6 +1,8 @@
+import { resolveSourceFromDebugStack } from "./resolveSourceMap";
 export function findDebugSource(fiber) {
   let current = fiber;
   while (current) {
+    // React 18 and earlier: _debugSource is a structured object
     if (current._debugSource) {
       return {
         fiber: current,
@@ -10,4 +12,39 @@ export function findDebugSource(fiber) {
     current = current._debugOwner || null;
   }
   return null;
+}
+
+/**
+ * Async version of findDebugSource that supports React 19's _debugStack.
+ * Falls back to synchronous _debugSource check first (React 18).
+ * If that fails, parses _debugStack and resolves via source maps.
+ */
+export async function findDebugSourceAsync(fiber) {
+  // Try synchronous path first (React 18)
+  const syncResult = findDebugSource(fiber);
+  if (syncResult) return syncResult;
+
+  // React 19: try resolving via _debugStack + source maps
+  let current = fiber;
+  while (current) {
+    const debugStack = current._debugStack;
+    if (debugStack?.stack) {
+      const source = await resolveSourceFromDebugStack(debugStack);
+      if (source) {
+        return {
+          fiber: current,
+          source
+        };
+      }
+    }
+    current = current._debugOwner || null;
+  }
+  return null;
+}
+
+/**
+ * Check if this is a React 19+ environment (has _debugStack but not _debugSource).
+ */
+export function isReact19Fiber(fiber) {
+  return !fiber._debugSource && !!fiber._debugStack;
 }

package/dist/adapters/react/findFiberByHtmlElement.js

@@ -1,7 +1,19 @@
 import { findDebugSource } from "./findDebugSource";
+
+/**
+ * Find the React fiber key on a DOM element (e.g., "__reactFiber$abc123").
+ * Works across all React versions that attach fibers to DOM nodes.
+ */
+function findFiberFromDOMElement(element) {
+  const fiberKey = Object.keys(element).find(k => k.startsWith("__reactFiber$"));
+  if (fiberKey) {
+    return element[fiberKey];
+  }
+  return null;
+}
 export function findFiberByHtmlElement(target, shouldHaveDebugSource) {
+  // Try via DevTools renderers first (available when React DevTools extension is installed)
   const renderers = window.__REACT_DEVTOOLS_GLOBAL_HOOK__?.renderers;
-  // console.log("RENDERERS: ", renderers);
   const renderersValues = renderers?.values();
   if (renderersValues) {
     for (const renderer of Array.from(renderersValues)) {
@@ -18,5 +30,15 @@ export function findFiberByHtmlElement(target, shouldHaveDebugSource) {
       }
     }
   }
+
+  // Fallback: read fiber directly from DOM element's __reactFiber$ property.
+  // This works without the React DevTools extension and across React 16-19.
+  const fiber = findFiberFromDOMElement(target);
+  if (fiber) {
+    if (shouldHaveDebugSource) {
+      return findDebugSource(fiber)?.fiber || null;
+    }
+    return fiber;
+  }
   return null;
 }

package/dist/adapters/react/getAllParentsElementsAndRootComponent.d.ts

@@ -5,4 +5,4 @@ export declare function getAllParentsElementsAndRootComponent(fiber: Fiber): {
     component: Fiber;
     componentBox: SimpleDOMRect;
     parentElements: ElementInfo[];
-};
+} | null;

package/dist/adapters/react/getAllParentsElementsAndRootComponent.js

@@ -5,8 +5,9 @@ import { isStyledElement } from "./isStyled";
 export function getAllParentsElementsAndRootComponent(fiber) {
   const parentElements = [];
   const deepestElement = fiber.stateNode;
-  if (!deepestElement || !(deepestElement instanceof HTMLElement)) {
-    throw new Error("This functions works only for Fibres with HTMLElement stateNode");
+  if (!deepestElement || !(deepestElement instanceof Element)) {
+    console.warn("[TreeLocator] Skipping fiber with non-Element stateNode:", fiber.type, fiber.stateNode);
+    return null;
   }
   let componentBox = deepestElement.getBoundingClientRect();
 
@@ -15,7 +16,7 @@ export function getAllParentsElementsAndRootComponent(fiber) {
   while (currentFiber._debugOwner || currentFiber.return) {
     currentFiber = currentFiber._debugOwner || currentFiber.return;
     const currentElement = currentFiber.stateNode;
-    if (!currentElement || !(currentElement instanceof HTMLElement)) {
+    if (!currentElement || !(currentElement instanceof Element)) {
       return {
         component: currentFiber,
         parentElements,
@@ -30,5 +31,6 @@ export function getAllParentsElementsAndRootComponent(fiber) {
       link: null
     });
   }
-  throw new Error("Could not find root component");
+  console.warn("[TreeLocator] Could not find root component for fiber:", fiber.type);
+  return null;
 }

package/dist/adapters/react/getAllWrappingParents.js

@@ -4,7 +4,7 @@ export function getAllWrappingParents(fiber) {
   let currentFiber = fiber;
   while (currentFiber.return) {
     currentFiber = currentFiber.return;
-    if (currentFiber.stateNode && currentFiber.stateNode instanceof HTMLElement) {
+    if (currentFiber.stateNode && currentFiber.stateNode instanceof Element) {
       return parents;
     }
 

package/dist/adapters/react/reactAdapter.js

@@ -13,11 +13,15 @@ export function getElementInfo(found) {
   const labels = [];
   const fiber = findFiberByHtmlElement(found, false);
   if (fiber) {
+    const result = getAllParentsElementsAndRootComponent(fiber);
+    if (!result) {
+      return null;
+    }
     const {
       component,
       componentBox,
       parentElements
-    } = getAllParentsElementsAndRootComponent(fiber);
+    } = result;
     const allPotentialComponentFibers = getAllWrappingParents(component);
 
     // This handles a common case when the component root is basically the comopnent itself, so I want to go to usage of the component

package/dist/adapters/react/resolveSourceMap.d.ts

@@ -0,0 +1,29 @@
+import { Source } from "@locator/shared";
+/**
+ * Parse the React 19 _debugStack Error.stack to extract the caller's location.
+ *
+ * Stack format:
+ *   Error: react-stack-top-frame
+ *       at exports.jsxDEV (http://localhost:3000/_next/.../chunk.js:410:33)
+ *       at Home (http://localhost:3000/_next/.../chunk.js:8789:416)
+ *       at Object.react_stack_bottom_frame (...)
+ *
+ * The second frame (after jsxDEV/jsx) is the component that created the element.
+ */
+export declare function parseDebugStack(stack: string): {
+    url: string;
+    line: number;
+    column: number;
+} | null;
+/**
+ * Resolve a bundled location to its original source using source maps.
+ * Returns null if resolution fails.
+ */
+export declare function resolveSourceLocation(url: string, line: number, column: number): Promise<Source | null>;
+/**
+ * Given a React 19 fiber's _debugStack, resolve the source location
+ * by parsing the stack trace and looking up source maps.
+ */
+export declare function resolveSourceFromDebugStack(debugStack: {
+    stack?: string;
+}): Promise<Source | null>;

package/dist/adapters/react/resolveSourceMap.js

@@ -0,0 +1,236 @@
+// Cache: bundled script URL -> source map
+const sourceMapCache = new Map();
+
+/**
+ * Parse the React 19 _debugStack Error.stack to extract the caller's location.
+ *
+ * Stack format:
+ *   Error: react-stack-top-frame
+ *       at exports.jsxDEV (http://localhost:3000/_next/.../chunk.js:410:33)
+ *       at Home (http://localhost:3000/_next/.../chunk.js:8789:416)
+ *       at Object.react_stack_bottom_frame (...)
+ *
+ * The second frame (after jsxDEV/jsx) is the component that created the element.
+ */
+export function parseDebugStack(stack) {
+  const lines = stack.split("\n");
+
+  // Find the component caller frame (skip react-stack-top-frame and jsx factory)
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+
+    // Skip react internal frames
+    if (line.includes("react-stack-top-frame") || line.includes("react_stack_bottom_frame")) {
+      continue;
+    }
+
+    // Skip JSX factory frames (jsxDEV, jsx, jsxs)
+    if (line.includes("jsxDEV") || line.includes("exports.jsx ") || line.includes("exports.jsxs ")) {
+      continue;
+    }
+
+    // Parse "at Name (url:line:col)" or "at url:line:col"
+    const match = line.match(/at\s+(?:\S+\s+)?\(?(https?:\/\/.+?):(\d+):(\d+)\)?/) || line.match(/at\s+(https?:\/\/.+?):(\d+):(\d+)/);
+    if (match && match[1] && match[2] && match[3]) {
+      return {
+        url: match[1],
+        line: parseInt(match[2], 10),
+        column: parseInt(match[3], 10)
+      };
+    }
+  }
+  return null;
+}
+async function fetchSourceMap(scriptUrl) {
+  if (sourceMapCache.has(scriptUrl)) {
+    return sourceMapCache.get(scriptUrl);
+  }
+  const promise = (async () => {
+    try {
+      // Fetch the script to find sourceMappingURL
+      const scriptResp = await fetch(scriptUrl);
+      if (!scriptResp.ok) return null;
+      const scriptText = await scriptResp.text();
+      const match = scriptText.match(/\/\/[#@]\s*sourceMappingURL=(.+?)(?:\s|$)/);
+      if (!match || !match[1]) return null;
+
+      // Resolve the source map URL relative to the script URL
+      let mapUrl = match[1];
+      if (!mapUrl.startsWith("http")) {
+        const base = scriptUrl.substring(0, scriptUrl.lastIndexOf("/") + 1);
+        mapUrl = base + mapUrl;
+      }
+      const mapResp = await fetch(mapUrl);
+      if (!mapResp.ok) return null;
+      return await mapResp.json();
+    } catch {
+      return null;
+    }
+  })();
+  sourceMapCache.set(scriptUrl, promise);
+  return promise;
+}
+
+// Decode a single VLQ value from a mappings string, returns [value, charsConsumed]
+const VLQ_BASE_SHIFT = 5;
+const VLQ_BASE = 1 << VLQ_BASE_SHIFT; // 32
+const VLQ_BASE_MASK = VLQ_BASE - 1; // 31
+const VLQ_CONTINUATION_BIT = VLQ_BASE; // 32
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const base64Map = new Map();
+for (let i = 0; i < BASE64_CHARS.length; i++) {
+  base64Map.set(BASE64_CHARS[i], i);
+}
+function decodeVLQ(str, index) {
+  let result = 0;
+  let shift = 0;
+  let continuation;
+  let i = index;
+  do {
+    const char = str[i];
+    if (!char) return [0, i];
+    const digit = base64Map.get(char);
+    if (digit === undefined) return [0, i];
+    i++;
+    continuation = (digit & VLQ_CONTINUATION_BIT) !== 0;
+    result += (digit & VLQ_BASE_MASK) << shift;
+    shift += VLQ_BASE_SHIFT;
+  } while (continuation);
+
+  // Convert from VLQ signed
+  const isNegative = (result & 1) === 1;
+  result >>= 1;
+  return [isNegative ? -result : result, i];
+}
+
+/**
+ * Find the original source location for a generated line/column in a basic source map.
+ */
+function resolveInBasicMap(map, targetLine, targetColumn) {
+  const mappings = map.mappings;
+  if (!mappings) return null;
+  let generatedLine = 1;
+  let generatedColumn = 0;
+  let sourceIndex = 0;
+  let sourceLine = 0;
+  let sourceColumn = 0;
+  let bestSource = null;
+  let i = 0;
+  while (i < mappings.length) {
+    const char = mappings[i];
+    if (char === ";") {
+      generatedLine++;
+      generatedColumn = 0;
+      i++;
+      continue;
+    }
+    if (char === ",") {
+      i++;
+      continue;
+    }
+
+    // Decode segment
+    let colDelta;
+    [colDelta, i] = decodeVLQ(mappings, i);
+    generatedColumn += colDelta;
+
+    // Check if there's source info (segments can be 1, 4, or 5 fields)
+    if (i < mappings.length && mappings[i] !== "," && mappings[i] !== ";") {
+      let srcDelta, lineDelta, srcColDelta;
+      [srcDelta, i] = decodeVLQ(mappings, i);
+      sourceIndex += srcDelta;
+      [lineDelta, i] = decodeVLQ(mappings, i);
+      sourceLine += lineDelta;
+      [srcColDelta, i] = decodeVLQ(mappings, i);
+      sourceColumn += srcColDelta;
+
+      // Skip optional name index
+      if (i < mappings.length && mappings[i] !== "," && mappings[i] !== ";") {
+        [, i] = decodeVLQ(mappings, i);
+      }
+
+      // Check if this mapping is at or before our target
+      if (generatedLine === targetLine && generatedColumn <= targetColumn) {
+        const fileName = map.sources[sourceIndex];
+        if (fileName) {
+          bestSource = {
+            fileName: cleanSourcePath(fileName),
+            lineNumber: sourceLine + 1,
+            // source maps are 0-indexed
+            columnNumber: sourceColumn
+          };
+        }
+      }
+
+      // If we've passed the target line, we can stop
+      if (generatedLine > targetLine) {
+        break;
+      }
+    }
+  }
+  return bestSource;
+}
+
+/**
+ * Clean up source file paths from source maps.
+ * Strips file:// protocol and common project root prefixes.
+ */
+function cleanSourcePath(filePath) {
+  // Strip file:// protocol
+  let cleaned = filePath.replace(/^file:\/\//, "");
+
+  // Strip webpack/turbopack internal prefixes
+  cleaned = cleaned.replace(/^\[project\]\//, "");
+  cleaned = cleaned.replace(/^webpack:\/\/[^/]*\//, "");
+  return cleaned;
+}
+
+/**
+ * Resolve a bundled location to its original source using source maps.
+ * Returns null if resolution fails.
+ */
+export async function resolveSourceLocation(url, line, column) {
+  const sourceMap = await fetchSourceMap(url);
+  if (!sourceMap) return null;
+
+  // Handle indexed/sectioned source maps (used by Turbopack)
+  if ("sections" in sourceMap && sourceMap.sections) {
+    const sections = sourceMap.sections;
+
+    // Find the section that contains our target line
+    let targetSection = null;
+    for (let i = sections.length - 1; i >= 0; i--) {
+      const section = sections[i];
+      if (!section) continue;
+      if (section.offset.line < line) {
+        targetSection = section;
+        break;
+      }
+      if (section.offset.line === line && section.offset.column <= column) {
+        targetSection = section;
+        break;
+      }
+    }
+    if (!targetSection) return null;
+
+    // Resolve within the section's map (adjust line/column relative to section offset)
+    const relLine = line - targetSection.offset.line;
+    const relCol = line === targetSection.offset.line ? column - targetSection.offset.column : column;
+    return resolveInBasicMap(targetSection.map, relLine, relCol);
+  }
+
+  // Handle basic source maps
+  return resolveInBasicMap(sourceMap, line, column);
+}
+
+/**
+ * Given a React 19 fiber's _debugStack, resolve the source location
+ * by parsing the stack trace and looking up source maps.
+ */
+export async function resolveSourceFromDebugStack(debugStack) {
+  if (!debugStack?.stack) return null;
+  const parsed = parseDebugStack(debugStack.stack);
+  if (!parsed) return null;
+  return resolveSourceLocation(parsed.url, parsed.line, parsed.column);
+}

package/dist/browserApi.d.ts

@@ -27,7 +27,7 @@ export interface LocatorJSAPI {
      * });
      * console.log(path);
      */
-    getPath(elementOrSelector: HTMLElement | string): string | null;
+    getPath(elementOrSelector: HTMLElement | string): Promise<string | null>;
     /**
      * Get raw ancestry data for an element.
      * Returns an array of objects containing component names, file paths, and line numbers.
@@ -54,7 +54,7 @@ export interface LocatorJSAPI {
      *   return ancestry?.map(item => item.componentName).filter(Boolean);
      * });
      */
-    getAncestry(elementOrSelector: HTMLElement | string): AncestryItem[] | null;
+    getAncestry(elementOrSelector: HTMLElement | string): Promise<AncestryItem[] | null>;
     /**
      * Get both formatted path and raw ancestry data in a single call.
      * Convenience method that combines getPath() and getAncestry().
@@ -78,10 +78,10 @@ export interface LocatorJSAPI {
      *   console.log('Source files:', data.ancestry.map(a => a.filePath));
      * }
      */
-    getPathData(elementOrSelector: HTMLElement | string): {
+    getPathData(elementOrSelector: HTMLElement | string): Promise<{
         path: string;
         ancestry: AncestryItem[];
-    } | null;
+    } | null>;
     /**
      * Display help information about the LocatorJS API.
      * Shows usage examples and method descriptions for browser automation tools.

package/dist/browserApi.js

@@ -1,5 +1,6 @@
 import { createTreeNode } from "./adapters/createTreeNode";
 import { collectAncestry, formatAncestryChain } from "./functions/formatAncestryChain";
+import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
 let adapterId;
 function resolveElement(elementOrSelector) {
   if (typeof elementOrSelector === "string") {
@@ -15,6 +16,11 @@ function getAncestryForElement(element) {
   }
   return collectAncestry(treeNode);
 }
+async function getEnrichedAncestryForElement(element) {
+  const ancestry = getAncestryForElement(element);
+  if (!ancestry) return null;
+  return enrichAncestryWithSourceMaps(ancestry, element);
+}
 const HELP_TEXT = `
 ╔═══════════════════════════════════════════════════════════════════════════╗
 ║                        TreeLocatorJS Browser API                          ║
@@ -119,34 +125,26 @@ export function createBrowserAPI(adapterIdParam) {
     getPath(elementOrSelector) {
       const element = resolveElement(elementOrSelector);
       if (!element) {
-        return null;
-      }
-      const ancestry = getAncestryForElement(element);
-      if (!ancestry) {
-        return null;
+        return Promise.resolve(null);
       }
-      return formatAncestryChain(ancestry);
+      return getEnrichedAncestryForElement(element).then(ancestry => ancestry ? formatAncestryChain(ancestry) : null);
     },
     getAncestry(elementOrSelector) {
       const element = resolveElement(elementOrSelector);
       if (!element) {
-        return null;
+        return Promise.resolve(null);
       }
-      return getAncestryForElement(element);
+      return getEnrichedAncestryForElement(element);
     },
     getPathData(elementOrSelector) {
       const element = resolveElement(elementOrSelector);
       if (!element) {
-        return null;
-      }
-      const ancestry = getAncestryForElement(element);
-      if (!ancestry) {
-        return null;
+        return Promise.resolve(null);
       }
-      return {
+      return getEnrichedAncestryForElement(element).then(ancestry => ancestry ? {
         path: formatAncestryChain(ancestry),
         ancestry
-      };
+      } : null);
     },
     help() {
       return HELP_TEXT;