@treelocator/runtime 0.1.8 → 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/getFiberLabel.ts

@@ -1,6 +1,7 @@
 import { Fiber, Source } from "@locator/shared";
 import { LabelData } from "../../types/LabelData";
 import { getUsableName } from "../../functions/getUsableName";
+import { normalizeFilePath } from "../../functions/normalizeFilePath";
 
 export function getFiberLabel(fiber: Fiber, source?: Source): LabelData {
   const name = getUsableName(fiber);
@@ -9,7 +10,7 @@ export function getFiberLabel(fiber: Fiber, source?: Source): LabelData {
     label: name,
     link: source
       ? {
-          filePath: source.fileName,
+          filePath: normalizeFilePath(source.fileName),
           projectPath: "",
           line: source.lineNumber,
           column: source.columnNumber || 0,

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

@@ -3,6 +3,7 @@ import { createMemo } from "solid-js";
 import { AdapterId } from "../consts";
 import { getElementInfo } from "../adapters/getElementInfo";
 import { Outline } from "./Outline";
+import { parsePhoenixServerComponents } from "../adapters/phoenix/parsePhoenixComments";
 
 export function MaybeOutline(props: {
   currentElement: HTMLElement;
@@ -12,7 +13,28 @@ export function MaybeOutline(props: {
   const elInfo = createMemo(() =>
     getElementInfo(props.currentElement, props.adapterId)
   );
+
+  // Check for Phoenix server components when client framework data is not available
+  const phoenixInfo = createMemo(() => {
+    if (elInfo()) return null; // Client framework takes precedence
+
+    // Try current element first
+    let serverComponents = parsePhoenixServerComponents(props.currentElement);
+    if (serverComponents) return serverComponents;
+
+    // Walk up the tree to find the nearest parent with Phoenix components
+    let parent = props.currentElement.parentElement;
+    while (parent && parent !== document.body) {
+      serverComponents = parsePhoenixServerComponents(parent);
+      if (serverComponents) return serverComponents;
+      parent = parent.parentElement;
+    }
+
+    return null;
+  });
+
   const box = () => props.currentElement.getBoundingClientRect();
+
   return (
     <>
       {elInfo() ? (
@@ -20,7 +42,7 @@ export function MaybeOutline(props: {
           element={elInfo()!}
           targets={props.targets}
         />
-      ) : (
+      ) : phoenixInfo() ? (
         <div>
           {/* Element outline box */}
           <div
@@ -33,7 +55,42 @@ export function MaybeOutline(props: {
               height: box().height + "px",
             }}
           />
-          {/* Glass morphism label */}
+          {/* Phoenix component label */}
+          <div
+            class="fixed text-xs font-medium rounded-md"
+            style={{
+              "z-index": 3,
+              left: box().x + 4 + "px",
+              top: box().y + 4 + "px",
+              padding: "4px 10px",
+              background: "rgba(79, 70, 229, 0.85)",
+              color: "#fff",
+              border: "1px solid rgba(255, 255, 255, 0.15)",
+              "box-shadow": "0 4px 16px rgba(0, 0, 0, 0.2)",
+              "font-family": "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace",
+              "letter-spacing": "0.01em",
+            }}
+          >
+            {phoenixInfo()!
+              .filter((sc) => sc.type === "component")
+              .map((sc) => sc.name.split(".").pop())
+              .join(" > ")}
+          </div>
+        </div>
+      ) : (
+        <div>
+          {/* Element outline box */}
+          <div
+            class="fixed rounded border border-solid border-gray-500"
+            style={{
+              "z-index": 2,
+              left: box().x + "px",
+              top: box().y + "px",
+              width: box().width + "px",
+              height: box().height + "px",
+            }}
+          />
+          {/* DOM element label */}
           <div
             class="fixed text-xs font-medium rounded-md"
             style={{
@@ -41,7 +98,7 @@ export function MaybeOutline(props: {
               left: box().x + 4 + "px",
               top: box().y + 4 + "px",
               padding: "4px 10px",
-              background: "rgba(120, 53, 15, 0.85)",
+              background: "rgba(75, 85, 99, 0.85)",
               color: "#fff",
               border: "1px solid rgba(255, 255, 255, 0.15)",
               "box-shadow": "0 4px 16px rgba(0, 0, 0, 0.2)",
@@ -49,7 +106,9 @@ export function MaybeOutline(props: {
               "letter-spacing": "0.01em",
             }}
           >
-            No source found
+            {props.currentElement.tagName.toLowerCase()}
+            {props.currentElement.id ? `#${props.currentElement.id}` : ""}
+            {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