@treelocator/runtime 0.2.0 → 0.3.1

package/src/browserApi.ts

@@ -5,6 +5,7 @@ import {
   formatAncestryChain,
   AncestryItem,
 } from "./functions/formatAncestryChain";
+import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
 
 export interface LocatorJSAPI {
   /**
@@ -33,7 +34,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.
@@ -61,7 +62,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.
@@ -88,7 +89,7 @@ export interface LocatorJSAPI {
    */
   getPathData(
     elementOrSelector: HTMLElement | string
-  ): { path: string; ancestry: AncestryItem[] } | null;
+  ): Promise<{ path: string; ancestry: AncestryItem[] } | null>;
 
   /**
    * Display help information about the LocatorJS API.
@@ -128,6 +129,14 @@ function getAncestryForElement(element: HTMLElement): AncestryItem[] | null {
   return collectAncestry(treeNode);
 }
 
+async function getEnrichedAncestryForElement(
+  element: HTMLElement
+): Promise<AncestryItem[] | null> {
+  const ancestry = getAncestryForElement(element);
+  if (!ancestry) return null;
+  return enrichAncestryWithSourceMaps(ancestry, element);
+}
+
 const HELP_TEXT = `
 ╔═══════════════════════════════════════════════════════════════════════════╗
 ║                        TreeLocatorJS Browser API                          ║
@@ -233,46 +242,39 @@ export function createBrowserAPI(
   adapterId = adapterIdParam;
 
   return {
-    getPath(elementOrSelector: HTMLElement | string): string | null {
+    getPath(elementOrSelector: HTMLElement | string): Promise<string | null> {
       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: HTMLElement | string): AncestryItem[] | null {
+    getAncestry(
+      elementOrSelector: HTMLElement | string
+    ): Promise<AncestryItem[] | null> {
       const element = resolveElement(elementOrSelector);
       if (!element) {
-        return null;
+        return Promise.resolve(null);
       }
 
-      return getAncestryForElement(element);
+      return getEnrichedAncestryForElement(element);
     },
 
     getPathData(
       elementOrSelector: HTMLElement | string
-    ): { path: string; ancestry: AncestryItem[] } | null {
+    ): Promise<{ path: string; ancestry: AncestryItem[] } | null> {
       const element = resolveElement(elementOrSelector);
       if (!element) {
-        return null;
-      }
-
-      const ancestry = getAncestryForElement(element);
-      if (!ancestry) {
-        return null;
+        return Promise.resolve(null);
       }
 
-      return {
-        path: formatAncestryChain(ancestry),
-        ancestry,
-      };
+      return getEnrichedAncestryForElement(element).then((ancestry) =>
+        ancestry ? { path: formatAncestryChain(ancestry), ancestry } : null
+      );
     },
 
     help(): string {

package/src/components/MaybeOutline.tsx

@@ -108,7 +108,7 @@ export function MaybeOutline(props: {
           >
             {props.currentElement.tagName.toLowerCase()}
             {props.currentElement.id ? `#${props.currentElement.id}` : ""}
-            {props.currentElement.className ? `.${props.currentElement.className.split(" ")[0]}` : ""}
+            {props.currentElement.getAttribute('class') ? `.${props.currentElement.getAttribute('class')!.split(" ")[0]}` : ""}
           </div>
         </div>
       )}

package/src/components/Runtime.tsx

@@ -8,6 +8,7 @@ import { MaybeOutline } from "./MaybeOutline";
 import { isLocatorsOwnElement } from "../functions/isLocatorsOwnElement";
 import { Toast } from "./Toast";
 import { collectAncestry, formatAncestryChain } from "../functions/formatAncestryChain";
+import { enrichAncestryWithSourceMaps } from "../functions/enrichAncestrySourceMaps";
 import { createTreeNode } from "../adapters/createTreeNode";
 import treeIconUrl from "../_generated_tree_icon";
 
@@ -153,10 +154,24 @@ function Runtime(props: RuntimeProps) {
     const treeNode = createTreeNode(element as HTMLElement, props.adapterId);
     if (treeNode) {
       const ancestry = collectAncestry(treeNode);
+
+      // Write immediately with component names (preserves user gesture for clipboard API)
       const formatted = formatAncestryChain(ancestry);
       navigator.clipboard.writeText(formatted).then(() => {
         setToastMessage("Copied to clipboard");
       });
+
+      // For React 19+: try to enrich with source map file paths and re-copy
+      enrichAncestryWithSourceMaps(ancestry, element as HTMLElement).then(
+        (enriched) => {
+          const enrichedFormatted = formatAncestryChain(enriched);
+          if (enrichedFormatted !== formatted) {
+            navigator.clipboard.writeText(enrichedFormatted).then(() => {
+              setToastMessage("Copied to clipboard");
+            });
+          }
+        }
+      );
     }
 
     // Deactivate toggle after click

package/src/functions/enrichAncestrySourceMaps.ts

@@ -0,0 +1,103 @@
+import { AncestryItem } from "./formatAncestryChain";
+import { resolveSourceLocation, parseDebugStack } from "../adapters/react/resolveSourceMap";
+import { normalizeFilePath } from "./normalizeFilePath";
+
+/**
+ * Check if any DOM element has React 19 fibers (with _debugStack instead of _debugSource).
+ */
+function isReact19Environment(): boolean {
+  const el = document.querySelector("[class]") || document.body;
+  if (!el) return false;
+
+  const fiberKey = Object.keys(el).find((k) => k.startsWith("__reactFiber$"));
+  if (!fiberKey) return false;
+
+  const fiber = (el as any)[fiberKey];
+  return !fiber?._debugSource && !!(fiber as any)?._debugStack;
+}
+
+/**
+ * Walk a fiber's _debugOwner chain and collect _debugStack stack traces for each component.
+ * Returns a map from component name to its parsed stack location.
+ */
+function collectFiberStacks(
+  element: HTMLElement
+): Map<string, { url: string; line: number; column: number }> {
+  const stacks = new Map<string, { url: string; line: number; column: number }>();
+
+  const fiberKey = Object.keys(element).find((k) =>
+    k.startsWith("__reactFiber$")
+  );
+  if (!fiberKey) return stacks;
+
+  let fiber = (element as any)[fiberKey];
+
+  // Collect stacks from the fiber itself and its _debugOwner chain
+  while (fiber) {
+    const debugStack = fiber._debugStack;
+    if (debugStack?.stack) {
+      const parsed = parseDebugStack(debugStack.stack);
+      if (parsed) {
+        const name =
+          fiber.type?.name || fiber.type?.displayName || fiber.type;
+        if (typeof name === "string") {
+          stacks.set(name, parsed);
+        }
+      }
+    }
+    fiber = fiber._debugOwner || null;
+  }
+
+  return stacks;
+}
+
+/**
+ * Enrich ancestry items that are missing filePath by resolving via source maps.
+ * This is an async operation that fetches source maps for React 19 environments.
+ * For React 18 (where _debugSource exists), this is a no-op.
+ */
+export async function enrichAncestryWithSourceMaps(
+  items: AncestryItem[],
+  element?: HTMLElement
+): Promise<AncestryItem[]> {
+  // Skip if all items already have file paths, or not React 19
+  const needsEnrichment = items.some((item) => item.componentName && !item.filePath);
+  if (!needsEnrichment || !isReact19Environment()) {
+    return items;
+  }
+
+  // Collect _debugStack info from the DOM element's fiber chain
+  const stacks = element ? collectFiberStacks(element) : new Map();
+
+  // Resolve source maps in parallel for items missing filePath
+  const enriched = await Promise.all(
+    items.map(async (item) => {
+      if (item.filePath || !item.componentName) return item;
+
+      // Find the stack trace for this component
+      const stack = stacks.get(item.componentName);
+      if (!stack) return item;
+
+      try {
+        const source = await resolveSourceLocation(
+          stack.url,
+          stack.line,
+          stack.column
+        );
+        if (source) {
+          return {
+            ...item,
+            filePath: normalizeFilePath(source.fileName),
+            line: source.lineNumber,
+          };
+        }
+      } catch {
+        // Source map resolution failed — keep item as-is
+      }
+
+      return item;
+    })
+  );
+
+  return enriched;
+}