@treelocator/runtime 0.2.0 → 0.3.0

package/src/adapters/react/findDebugSource.ts

@@ -1,10 +1,15 @@
 import { Fiber, Source } from "@locator/shared";
+import {
+  resolveSourceFromDebugStack,
+  parseDebugStack,
+} from "./resolveSourceMap";
 
 export function findDebugSource(
   fiber: Fiber
 ): { fiber: Fiber; source: Source } | null {
   let current: Fiber | null = fiber;
   while (current) {
+    // React 18 and earlier: _debugSource is a structured object
     if (current._debugSource) {
       return { fiber: current, source: current._debugSource };
     }
@@ -13,3 +18,38 @@ export function findDebugSource(
 
   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: Fiber
+): Promise<{ fiber: Fiber; source: Source } | null> {
+  // 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 | null = fiber;
+  while (current) {
+    const debugStack = (current as any)._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: Fiber): boolean {
+  return !fiber._debugSource && !!(fiber as any)._debugStack;
+}

package/src/adapters/react/findFiberByHtmlElement.ts

@@ -1,12 +1,26 @@
 import { Fiber, Renderer } from "@locator/shared";
 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: HTMLElement): Fiber | null {
+  const fiberKey = Object.keys(element).find((k) =>
+    k.startsWith("__reactFiber$")
+  );
+  if (fiberKey) {
+    return (element as any)[fiberKey] as Fiber;
+  }
+  return null;
+}
+
 export function findFiberByHtmlElement(
   target: HTMLElement,
   shouldHaveDebugSource: boolean
 ): Fiber | null {
+  // 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) as Renderer[]) {
@@ -23,5 +37,16 @@ export function findFiberByHtmlElement(
       }
     }
   }
+
+  // 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/src/adapters/react/reactAdapter.ts

@@ -1,5 +1,6 @@
-import { findDebugSource } from "./findDebugSource";
+import { findDebugSource, findDebugSourceAsync, isReact19Fiber } from "./findDebugSource";
 import { findFiberByHtmlElement } from "./findFiberByHtmlElement";
+import { resolveSourceFromDebugStack } from "./resolveSourceMap";
 import { getFiberLabel } from "./getFiberLabel";
 import { getAllWrappingParents } from "./getAllWrappingParents";
 import { deduplicateLabels } from "../../functions/deduplicateLabels";

package/src/adapters/react/resolveSourceMap.ts

@@ -0,0 +1,316 @@
+import { Source } from "@locator/shared";
+
+interface SourceMapSection {
+  offset: { line: number; column: number };
+  map: {
+    version: number;
+    sources: string[];
+    mappings: string;
+    sourcesContent?: (string | null)[];
+  };
+}
+
+interface IndexedSourceMap {
+  version: number;
+  sections: SourceMapSection[];
+}
+
+interface BasicSourceMap {
+  version: number;
+  sources: string[];
+  mappings: string;
+  sourcesContent?: (string | null)[];
+}
+
+type SourceMap = IndexedSourceMap | BasicSourceMap;
+
+// Cache: bundled script URL -> source map
+const sourceMapCache = new Map<string, Promise<SourceMap | null>>();
+
+/**
+ * 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: string
+): { url: string; line: number; column: number } | null {
+  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: string): Promise<SourceMap | null> {
+  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()) as SourceMap;
+    } 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<string, number>();
+for (let i = 0; i < BASE64_CHARS.length; i++) {
+  base64Map.set(BASE64_CHARS[i]!, i);
+}
+
+function decodeVLQ(str: string, index: number): [number, number] {
+  let result = 0;
+  let shift = 0;
+  let continuation: boolean;
+  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: BasicSourceMap,
+  targetLine: number,
+  targetColumn: number
+): Source | null {
+  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: Source | null = 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: number;
+    [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: number, lineDelta: number, srcColDelta: number;
+      [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: string): string {
+  // 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: string,
+  line: number,
+  column: number
+): Promise<Source | null> {
+  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: SourceMapSection | null = 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 as BasicSourceMap,
+      relLine,
+      relCol
+    );
+  }
+
+  // Handle basic source maps
+  return resolveInBasicMap(sourceMap as BasicSourceMap, 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: { stack?: string }
+): Promise<Source | null> {
+  if (!debugStack?.stack) return null;
+
+  const parsed = parseDebugStack(debugStack.stack);
+  if (!parsed) return null;
+
+  return resolveSourceLocation(parsed.url, parsed.line, parsed.column);
+}

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;
+}