@treelocator/runtime 0.2.0 → 0.3.1

package/dist/components/MaybeOutline.js

@@ -84,8 +84,8 @@ export function MaybeOutline(props) {
       return () => _c$() ? `#${props.currentElement.id}` : "";
     })(), null);
     _$insert(_el$6, (() => {
-      var _c$2 = _$memo(() => !!props.currentElement.className);
-      return () => _c$2() ? `.${props.currentElement.className.split(" ")[0]}` : "";
+      var _c$2 = _$memo(() => !!props.currentElement.getAttribute('class'));
+      return () => _c$2() ? `.${props.currentElement.getAttribute('class').split(" ")[0]}` : "";
     })(), null);
     _$effect(_p$ => {
       var _v$7 = box().x + "px",

package/dist/components/Runtime.js

@@ -13,6 +13,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";
 function Runtime(props) {
@@ -128,10 +129,22 @@ function Runtime(props) {
     const treeNode = createTreeNode(element, 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).then(enriched => {
+        const enrichedFormatted = formatAncestryChain(enriched);
+        if (enrichedFormatted !== formatted) {
+          navigator.clipboard.writeText(enrichedFormatted).then(() => {
+            setToastMessage("Copied to clipboard");
+          });
+        }
+      });
     }
 
     // Deactivate toggle after click

package/dist/functions/enrichAncestrySourceMaps.d.ts

@@ -0,0 +1,7 @@
+import { AncestryItem } from "./formatAncestryChain";
+/**
+ * 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 declare function enrichAncestryWithSourceMaps(items: AncestryItem[], element?: HTMLElement): Promise<AncestryItem[]>;

package/dist/functions/enrichAncestrySourceMaps.js

@@ -0,0 +1,80 @@
+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() {
+  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[fiberKey];
+  return !fiber?._debugSource && !!fiber?._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) {
+  const stacks = new Map();
+  const fiberKey = Object.keys(element).find(k => k.startsWith("__reactFiber$"));
+  if (!fiberKey) return stacks;
+  let fiber = element[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, element) {
+  // 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treelocator/runtime",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TreeLocatorJS runtime for component ancestry tracking. Alt+click any element to copy its component tree to clipboard. Exposes window.__treelocator__ API for browser automation (Playwright, Puppeteer, Selenium, Cypress).",
   "keywords": [
     "locator",
@@ -54,7 +54,7 @@
     "@babel/cli": "^7.25.9",
     "@babel/core": "^7.26.0",
     "@tailwindcss/forms": "^0.5.11",
-    "@treelocator/dev-config": "^0.2.0",
+    "@treelocator/dev-config": "^0.3.0",
     "@types/jsdom": "^21.1.7",
     "babel-preset-solid": "^1.9.2",
     "concurrently": "^9.1.0",
@@ -73,5 +73,5 @@
     "directory": "packages/runtime"
   },
   "license": "MIT",
-  "gitHead": "5d53daa18f4fef5e815c3fd281b899608f8673ea"
+  "gitHead": "f53c9d698aaee64837698b5c6803df5485d2a229"
 }

package/src/adapters/createTreeNode.ts

@@ -11,6 +11,15 @@ import {
 } 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: HTMLElement): boolean {
+  return Object.keys(element).some((k) => k.startsWith("__reactFiber$"));
+}
+
 export function createTreeNode(
   element: HTMLElement,
   adapterId?: string
@@ -38,7 +47,7 @@ export function createTreeNode(
     return new VueTreeNodeElement(element);
   }
 
-  if (detectReact()) {
+  if (detectReact() || hasReactFiberKeys(element)) {
     return new ReactTreeNodeElement(element);
   }
 

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/getAllParentsElementsAndRootComponent.ts

@@ -10,13 +10,12 @@ export function getAllParentsElementsAndRootComponent(fiber: Fiber): {
   component: Fiber;
   componentBox: SimpleDOMRect;
   parentElements: ElementInfo[];
-} {
+} | null {
   const parentElements: ElementInfo[] = [];
   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: SimpleDOMRect = deepestElement.getBoundingClientRect();
 
@@ -26,7 +25,7 @@ export function getAllParentsElementsAndRootComponent(fiber: 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,
@@ -48,5 +47,6 @@ export function getAllParentsElementsAndRootComponent(fiber: 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/src/adapters/react/getAllWrappingParents.ts

@@ -9,7 +9,7 @@ export function getAllWrappingParents(fiber: Fiber): Fiber[] {
     currentFiber = currentFiber.return;
     if (
       currentFiber.stateNode &&
-      currentFiber.stateNode instanceof HTMLElement
+      currentFiber.stateNode instanceof Element
     ) {
       return parents;
     }

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";
@@ -24,8 +25,11 @@ export function getElementInfo(found: HTMLElement): FullElementInfo | null {
 
   const fiber = findFiberByHtmlElement(found, false);
   if (fiber) {
-    const { component, componentBox, parentElements } =
-      getAllParentsElementsAndRootComponent(fiber);
+    const result = getAllParentsElementsAndRootComponent(fiber);
+    if (!result) {
+      return null;
+    }
+    const { component, componentBox, parentElements } = result;
 
     const allPotentialComponentFibers = getAllWrappingParents(component);
 

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