@treelocator/runtime 0.1.8 → 0.2.0

package/dist/adapters/phoenix/parsePhoenixComments.js

@@ -0,0 +1,131 @@
+/**
+ * Regex patterns for Phoenix LiveView debug annotations.
+ *
+ * These comments are added by Phoenix LiveView when configured with:
+ * config :phoenix_live_view, debug_heex_annotations: true
+ *
+ * Pattern 1 (Caller): <!-- @caller lib/app_web/home_live.ex:20 -->
+ * Pattern 2 (Component): <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+ * Pattern 3 (Closing): <!-- </AppWeb.CoreComponents.header> -->
+ */
+const PHOENIX_CALLER_PATTERN = /^@caller\s+(.+):(\d+)$/;
+const PHOENIX_COMPONENT_PATTERN = /^<([^>]+)>\s+(.+):(\d+)$/;
+const PHOENIX_CLOSING_PATTERN = /^<\/([^>]+)>$/;
+
+/**
+ * Parse a single HTML comment node for Phoenix debug annotations.
+ * Returns null if the comment doesn't match Phoenix patterns.
+ */
+function parseCommentNode(commentNode) {
+  const text = commentNode.textContent?.trim();
+  if (!text) return null;
+
+  // Check for @caller pattern: <!-- @caller lib/app_web/home_live.ex:20 -->
+  const callerMatch = text.match(PHOENIX_CALLER_PATTERN);
+  if (callerMatch && callerMatch[1] && callerMatch[2]) {
+    return {
+      commentNode,
+      name: "@caller",
+      filePath: callerMatch[1],
+      line: parseInt(callerMatch[2], 10),
+      type: "caller"
+    };
+  }
+
+  // Check for component opening pattern: <!-- <AppWeb.CoreComponents.header> lib/app_web/core_components.ex:123 -->
+  const componentMatch = text.match(PHOENIX_COMPONENT_PATTERN);
+  if (componentMatch && componentMatch[1] && componentMatch[2] && componentMatch[3]) {
+    return {
+      commentNode,
+      name: componentMatch[1],
+      filePath: componentMatch[2],
+      line: parseInt(componentMatch[3], 10),
+      type: "component"
+    };
+  }
+
+  // Closing tags are ignored (we only care about opening tags)
+  // Example: <!-- </AppWeb.CoreComponents.header> -->
+  if (text.match(PHOENIX_CLOSING_PATTERN)) {
+    return null;
+  }
+
+  // Not a Phoenix comment
+  return null;
+}
+
+/**
+ * Find all Phoenix comment annotations immediately preceding an element.
+ * Walks backward through previous siblings until hitting a non-comment node.
+ *
+ * Returns array ordered from outermost to innermost (matching Phoenix nesting order).
+ * Example: [@caller, CoreComponents.button] where @caller is outermost.
+ *
+ * Example DOM structure:
+ * ```html
+ * <!-- @caller lib/app_web/home_live.ex:48 -->
+ * <!-- <AppWeb.CoreComponents.button> lib/app_web/core_components.ex:456 -->
+ * <button>Click Me</button>
+ * ```
+ *
+ * Would return: [
+ *   { name: "@caller", filePath: "lib/app_web/home_live.ex", line: 48, type: "caller" },
+ *   { name: "AppWeb.CoreComponents.button", filePath: "lib/app_web/core_components.ex", line: 456, type: "component" }
+ * ]
+ */
+export function findPrecedingPhoenixComments(element) {
+  const matches = [];
+  let node = element.previousSibling;
+
+  // Walk backward through siblings, collecting comment nodes
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const match = parseCommentNode(node);
+      if (match) {
+        matches.push(match);
+      }
+      // Continue even if this comment didn't match - keep looking for more Phoenix comments
+    } else if (node.nodeType === Node.TEXT_NODE) {
+      // Skip whitespace text nodes
+      const text = node.textContent?.trim();
+      if (text && text.length > 0) {
+        // Hit non-whitespace text, stop searching
+        break;
+      }
+    } else {
+      // Hit another element, stop searching
+      break;
+    }
+    node = node.previousSibling;
+  }
+
+  // Reverse so outermost comes first (matches Phoenix nesting order)
+  // This makes the array order match the visual hierarchy: [@caller, Component]
+  return matches.reverse();
+}
+
+/**
+ * Convert PhoenixCommentMatch[] to ServerComponentInfo[].
+ * Filters and transforms matches into the format expected by AncestryItem.
+ */
+export function phoenixMatchesToServerComponents(matches) {
+  return matches.map(match => ({
+    name: match.name,
+    filePath: match.filePath,
+    line: match.line,
+    type: match.type
+  }));
+}
+
+/**
+ * Main entry point: extract server component info from element.
+ * Returns null if no Phoenix annotations found.
+ *
+ * This function is called during ancestry collection to enrich each AncestryItem
+ * with server-side component information.
+ */
+export function parsePhoenixServerComponents(element) {
+  const matches = findPrecedingPhoenixComments(element);
+  if (matches.length === 0) return null;
+  return phoenixMatchesToServerComponents(matches);
+}

package/dist/adapters/phoenix/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Represents a parsed Phoenix LiveView debug annotation HTML comment.
+ * Phoenix LiveView adds these comments when debug_heex_annotations: true is configured.
+ */
+export interface PhoenixCommentMatch {
+    /** The actual HTML Comment node from the DOM */
+    commentNode: Comment;
+    /** Component name (e.g., "AppWeb.CoreComponents.button") or "@caller" */
+    name: string;
+    /** File path (e.g., "lib/app_web/core_components.ex") */
+    filePath: string;
+    /** Line number */
+    line: number;
+    /** Type of annotation */
+    type: "component" | "caller";
+}

package/dist/adapters/phoenix/types.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/react/getFiberLabel.js

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

package/dist/components/MaybeOutline.js

@@ -1,14 +1,35 @@
 import { template as _$template } from "solid-js/web";
 import { effect as _$effect } from "solid-js/web";
+import { insert as _$insert } from "solid-js/web";
 import { setStyleProperty as _$setStyleProperty } from "solid-js/web";
 import { createComponent as _$createComponent } from "solid-js/web";
 import { memo as _$memo } from "solid-js/web";
-var _tmpl$ = /*#__PURE__*/_$template(`<div><div class="fixed rounded border border-solid border-amber-500"style=z-index:2></div><div class="fixed text-xs font-medium rounded-md"style="z-index:3;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">No source found`);
+var _tmpl$ = /*#__PURE__*/_$template(`<div><div class="fixed rounded border border-solid border-amber-500"style=z-index:2></div><div class="fixed text-xs font-medium rounded-md"style="z-index:3;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">`),
+  _tmpl$2 = /*#__PURE__*/_$template(`<div><div class="fixed rounded border border-solid border-gray-500"style=z-index:2></div><div class="fixed text-xs font-medium rounded-md"style="z-index:3;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">`);
 import { createMemo } from "solid-js";
 import { getElementInfo } from "../adapters/getElementInfo";
 import { Outline } from "./Outline";
+import { parsePhoenixServerComponents } from "../adapters/phoenix/parsePhoenixComments";
 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 _$memo(() => _$memo(() => !!elInfo())() ? _$createComponent(Outline, {
     get element() {
@@ -17,14 +38,15 @@ export function MaybeOutline(props) {
     get targets() {
       return props.targets;
     }
-  }) : (() => {
+  }) : _$memo(() => !!phoenixInfo())() ? (() => {
     var _el$ = _tmpl$(),
       _el$2 = _el$.firstChild,
       _el$3 = _el$2.nextSibling;
     _$setStyleProperty(_el$3, "padding", "4px 10px");
-    _$setStyleProperty(_el$3, "background", "rgba(120, 53, 15, 0.85)");
+    _$setStyleProperty(_el$3, "background", "rgba(79, 70, 229, 0.85)");
     _$setStyleProperty(_el$3, "color", "#fff");
     _$setStyleProperty(_el$3, "border", "1px solid rgba(255, 255, 255, 0.15)");
+    _$insert(_el$3, () => phoenixInfo().filter(sc => sc.type === "component").map(sc => sc.name.split(".").pop()).join(" > "));
     _$effect(_p$ => {
       var _v$ = box().x + "px",
         _v$2 = box().y + "px",
@@ -48,5 +70,45 @@ export function MaybeOutline(props) {
       n: undefined
     });
     return _el$;
+  })() : (() => {
+    var _el$4 = _tmpl$2(),
+      _el$5 = _el$4.firstChild,
+      _el$6 = _el$5.nextSibling;
+    _$setStyleProperty(_el$6, "padding", "4px 10px");
+    _$setStyleProperty(_el$6, "background", "rgba(75, 85, 99, 0.85)");
+    _$setStyleProperty(_el$6, "color", "#fff");
+    _$setStyleProperty(_el$6, "border", "1px solid rgba(255, 255, 255, 0.15)");
+    _$insert(_el$6, () => props.currentElement.tagName.toLowerCase(), null);
+    _$insert(_el$6, (() => {
+      var _c$ = _$memo(() => !!props.currentElement.id);
+      return () => _c$() ? `#${props.currentElement.id}` : "";
+    })(), null);
+    _$insert(_el$6, (() => {
+      var _c$2 = _$memo(() => !!props.currentElement.className);
+      return () => _c$2() ? `.${props.currentElement.className.split(" ")[0]}` : "";
+    })(), null);
+    _$effect(_p$ => {
+      var _v$7 = box().x + "px",
+        _v$8 = box().y + "px",
+        _v$9 = box().width + "px",
+        _v$0 = box().height + "px",
+        _v$1 = box().x + 4 + "px",
+        _v$10 = box().y + 4 + "px";
+      _v$7 !== _p$.e && _$setStyleProperty(_el$5, "left", _p$.e = _v$7);
+      _v$8 !== _p$.t && _$setStyleProperty(_el$5, "top", _p$.t = _v$8);
+      _v$9 !== _p$.a && _$setStyleProperty(_el$5, "width", _p$.a = _v$9);
+      _v$0 !== _p$.o && _$setStyleProperty(_el$5, "height", _p$.o = _v$0);
+      _v$1 !== _p$.i && _$setStyleProperty(_el$6, "left", _p$.i = _v$1);
+      _v$10 !== _p$.n && _$setStyleProperty(_el$6, "top", _p$.n = _v$10);
+      return _p$;
+    }, {
+      e: undefined,
+      t: undefined,
+      a: undefined,
+      o: undefined,
+      i: undefined,
+      n: undefined
+    });
+    return _el$4;
   })());
 }

package/dist/functions/formatAncestryChain.d.ts

@@ -1,4 +1,5 @@
 import { TreeNode } from "../types/TreeNode";
+import { ServerComponentInfo } from "../types/ServerComponentInfo";
 export interface OwnerComponentInfo {
     name: string;
     filePath?: string;
@@ -13,6 +14,8 @@ export interface AncestryItem {
     nthChild?: number;
     /** All owner components from outermost (Sidebar) to innermost (GlassPanel) */
     ownerComponents?: OwnerComponentInfo[];
+    /** Server-side components (Phoenix LiveView, Rails, Next.js RSC, etc.) */
+    serverComponents?: ServerComponentInfo[];
 }
 export declare function collectAncestry(node: TreeNode): AncestryItem[];
 export declare function formatAncestryChain(items: AncestryItem[]): string;

package/dist/functions/formatAncestryChain.js

@@ -1,3 +1,6 @@
+import { parsePhoenixServerComponents } from "../adapters/phoenix/parsePhoenixComments";
+import { parseNextjsServerComponents } from "../adapters/nextjs/parseNextjsDataAttributes";
+import { normalizeFilePath } from "./normalizeFilePath";
 // Elements to exclude from ancestry (not useful for debugging)
 const EXCLUDED_ELEMENTS = new Set(["html", "body", "head"]);
 function isTreeNodeElement(node) {
@@ -22,7 +25,7 @@ function getNthChildIfAmbiguous(element) {
 function treeNodeComponentToOwnerInfo(comp) {
   return {
     name: comp.label,
-    filePath: comp.callLink?.fileName,
+    filePath: comp.callLink?.fileName ? normalizeFilePath(comp.callLink.fileName) : undefined,
     line: comp.callLink?.lineNumber
   };
 }
@@ -51,6 +54,19 @@ export function collectAncestry(node) {
         if (nthChild !== undefined) {
           item.nthChild = nthChild;
         }
+
+        // Parse server components from various sources
+        // 1. Phoenix LiveView (HTML comments)
+        const phoenixComponents = parsePhoenixServerComponents(element);
+
+        // 2. Next.js Server Components (data-locatorjs attributes)
+        const nextjsComponents = parseNextjsServerComponents(element);
+
+        // Combine all server components
+        const allServerComponents = [...(phoenixComponents || []), ...(nextjsComponents || [])];
+        if (allServerComponents.length > 0) {
+          item.serverComponents = allServerComponents;
+        }
       }
     }
 
@@ -62,7 +78,7 @@ export function collectAncestry(node) {
       // Use outermost component as the primary component name
       item.componentName = outermost.label;
       if (outermost.callLink) {
-        item.filePath = outermost.callLink.fileName;
+        item.filePath = normalizeFilePath(outermost.callLink.fileName);
         item.line = outermost.callLink.lineNumber;
       }
     } else {
@@ -71,18 +87,18 @@ export function collectAncestry(node) {
       if (component) {
         item.componentName = component.label;
         if (component.callLink) {
-          item.filePath = component.callLink.fileName;
+          item.filePath = normalizeFilePath(component.callLink.fileName);
           item.line = component.callLink.lineNumber;
         }
       }
     }
     if (!item.filePath && source) {
-      item.filePath = source.fileName;
+      item.filePath = normalizeFilePath(source.fileName);
       item.line = source.lineNumber;
     }
 
-    // Only include items that have useful info (component name or file path)
-    if (item.componentName || item.filePath) {
+    // Only include items that have useful info (component name, file path, or server components)
+    if (item.componentName || item.filePath || item.serverComponents) {
       items.push(item);
     }
     current = current.getParent();
@@ -101,8 +117,35 @@ export function formatAncestryChain(items) {
     const indent = "    ".repeat(index);
     const prefix = index === 0 ? "" : "└─ ";
 
-    // Build element selector: elementName:nth-child(n)#id
-    let selector = item.elementName;
+    // Get the previous item's component to detect component boundaries
+    const prevItem = index > 0 ? reversed[index - 1] : null;
+    const prevComponentName = prevItem?.componentName || prevItem?.ownerComponents?.[prevItem.ownerComponents.length - 1]?.name;
+
+    // Get current item's innermost component
+    const currentComponentName = item.ownerComponents?.[item.ownerComponents.length - 1]?.name || item.componentName;
+
+    // Determine the display name for the element
+    // Use component name ONLY when crossing a component boundary (root element of a component)
+    // This prevents "App -> App:nth-child(5)" when both are just elements inside App
+    let displayName = item.elementName;
+    let outerComponents = [];
+    const isComponentBoundary = currentComponentName && currentComponentName !== prevComponentName;
+    if (isComponentBoundary) {
+      if (item.ownerComponents && item.ownerComponents.length > 0) {
+        // Use innermost component as display name, show outer ones in "in X > Y"
+        const innermost = item.ownerComponents[item.ownerComponents.length - 1];
+        if (innermost) {
+          displayName = innermost.name;
+          // Outer components (excluding innermost)
+          outerComponents = item.ownerComponents.slice(0, -1).map(c => c.name);
+        }
+      } else if (item.componentName) {
+        displayName = item.componentName;
+      }
+    }
+
+    // Build element selector: displayName:nth-child(n)#id
+    let selector = displayName;
     if (item.nthChild !== undefined) {
       selector += `:nth-child(${item.nthChild})`;
     }
@@ -111,14 +154,60 @@ export function formatAncestryChain(items) {
     }
     let description = selector;
 
-    // Show all owner components if available (Sidebar > GlassPanel)
-    if (item.ownerComponents && item.ownerComponents.length > 0) {
-      const componentChain = item.ownerComponents.map(c => c.name).join(" > ");
-      description = `${selector} in ${componentChain}`;
-    } else if (item.componentName) {
-      description = `${selector} in ${item.componentName}`;
+    // Build component description parts
+    const parts = [];
+
+    // Server components (Phoenix/Next.js/Rails/etc.)
+    if (item.serverComponents && item.serverComponents.length > 0) {
+      // Group server components by framework (detected by file extension)
+      const phoenixComponents = item.serverComponents.filter(sc => sc.filePath.match(/\.(ex|exs|heex)$/));
+      const nextjsComponents = item.serverComponents.filter(sc => sc.filePath.match(/\.(tsx?|jsx?)$/));
+
+      // Format Phoenix components
+      if (phoenixComponents.length > 0) {
+        const names = phoenixComponents.filter(sc => sc.type === "component").map(sc => sc.name);
+        if (names.length > 0) {
+          parts.push(`[Phoenix: ${names.join(" > ")}]`);
+        }
+      }
+
+      // Format Next.js components
+      if (nextjsComponents.length > 0) {
+        const names = nextjsComponents.filter(sc => sc.type === "component").map(sc => sc.name);
+        if (names.length > 0) {
+          parts.push(`[Next.js: ${names.join(" > ")}]`);
+        }
+      }
+    }
+
+    // Client components - show outer components for context (if any)
+    if (outerComponents.length > 0) {
+      parts.push(`in ${outerComponents.join(" > ")}`);
+    }
+    if (parts.length > 0) {
+      description = `${selector} ${parts.join(" ")}`;
+    }
+
+    // Build location string
+    const locationParts = [];
+
+    // Server component locations
+    if (item.serverComponents && item.serverComponents.length > 0) {
+      item.serverComponents.forEach(sc => {
+        const prefix = sc.type === "caller" ? " (called from)" : "";
+        locationParts.push(`${sc.filePath}:${sc.line}${prefix}`);
+      });
+    }
+
+    // Client component location (only add if different from server components)
+    if (item.filePath) {
+      const clientLocation = `${item.filePath}:${item.line}`;
+      // Only add if this location isn't already in the list
+      if (!locationParts.includes(clientLocation)) {
+        locationParts.push(clientLocation);
+      }
     }
-    const location = item.filePath ? ` at ${item.filePath}:${item.line}` : "";
+    const location = locationParts.length > 0 ? ` at ${locationParts.join(", ")}` : "";
     lines.push(`${indent}${prefix}${description}${location}`);
   });
   return lines.join("\n");

package/dist/functions/formatAncestryChain.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { formatAncestryChain } from "./formatAncestryChain";
 describe("formatAncestryChain", () => {
-  it("formats basic ancestry without ID or nth-child", () => {
+  it("uses component name only at component boundaries", () => {
     const items = [{
       elementName: "button",
       componentName: "Button"
@@ -10,23 +10,25 @@ describe("formatAncestryChain", () => {
       componentName: "App"
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe(`div in App
-    └─ button in Button`);
+    // App is root (component boundary), Button is different component (boundary)
+    expect(result).toBe(`App
+    └─ Button`);
   });
-  it("includes ID when present", () => {
+  it("shows element name when same component as parent", () => {
     const items = [{
       elementName: "button",
-      componentName: "Button",
+      componentName: "App",
       id: "submit-btn"
     }, {
       elementName: "div",
       componentName: "App"
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe(`div in App
-    └─ button#submit-btn in Button`);
+    // Both are in App, so second item shows element name not component name
+    expect(result).toBe(`App
+    └─ button#submit-btn`);
   });
-  it("includes nth-child when present", () => {
+  it("includes nth-child with component name at boundary", () => {
     const items = [{
       elementName: "li",
       componentName: "ListItem",
@@ -36,10 +38,11 @@ describe("formatAncestryChain", () => {
       componentName: "List"
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe(`ul in List
-    └─ li:nth-child(3) in ListItem`);
+    // Different components = boundaries
+    expect(result).toBe(`List
+    └─ ListItem:nth-child(3)`);
   });
-  it("includes both nth-child and ID when present", () => {
+  it("includes both nth-child and ID at component boundary", () => {
     const items = [{
       elementName: "li",
       componentName: "ListItem",
@@ -50,10 +53,10 @@ describe("formatAncestryChain", () => {
       componentName: "List"
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe(`ul in List
-    └─ li:nth-child(2)#special-item in ListItem`);
+    expect(result).toBe(`List
+    └─ ListItem:nth-child(2)#special-item`);
   });
-  it("includes file location when present", () => {
+  it("includes file location at component boundary", () => {
     const items = [{
       elementName: "button",
       componentName: "Button",
@@ -62,7 +65,8 @@ describe("formatAncestryChain", () => {
       line: 42
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe("button#save in Button at src/Button.tsx:42");
+    // First item is always a boundary (no previous item)
+    expect(result).toBe("Button#save at src/Button.tsx:42");
   });
   it("formats element without component name", () => {
     const items = [{
@@ -78,7 +82,7 @@ describe("formatAncestryChain", () => {
     const result = formatAncestryChain([]);
     expect(result).toBe("");
   });
-  it("shows all owner components when ownerComponents is provided", () => {
+  it("uses innermost component as display name with outer components in chain", () => {
     const items = [{
       elementName: "div",
       id: "sidebar-panel",
@@ -101,10 +105,11 @@ describe("formatAncestryChain", () => {
       line: 104
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe(`div in App at src/App.jsx:104
-    └─ div#sidebar-panel in Sidebar > GlassPanel at src/components/game/Sidebar.jsx:78`);
+    // GlassPanel (innermost) is the display name, Sidebar (outer) shown in "in"
+    expect(result).toBe(`App at src/App.jsx:104
+    └─ GlassPanel#sidebar-panel in Sidebar at src/components/game/Sidebar.jsx:78`);
   });
-  it("shows single owner component without arrow when only one in chain", () => {
+  it("uses component name as display name when only one in chain", () => {
     const items = [{
       elementName: "button",
       componentName: "Button",
@@ -117,6 +122,7 @@ describe("formatAncestryChain", () => {
       line: 10
     }];
     const result = formatAncestryChain(items);
-    expect(result).toBe("button in Button at src/Button.tsx:10");
+    // Single component becomes the display name, no "in X" needed
+    expect(result).toBe("Button at src/Button.tsx:10");
   });
 });

package/dist/functions/normalizeFilePath.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert absolute file paths to relative paths for display.
+ *
+ * This ensures consistent path display across different sources:
+ * - React _debugSource may provide absolute paths
+ * - Next.js data-locatorjs attributes may have absolute paths
+ * - Phoenix comments use relative paths
+ *
+ * Examples:
+ *   - "/Users/name/project/src/App.tsx" → "src/App.tsx"
+ *   - "/workspace/apps/next-16/app/page.tsx" → "app/page.tsx"
+ *   - "src/components/Button.tsx" → "src/components/Button.tsx" (unchanged)
+ */
+export declare function normalizeFilePath(filePath: string): string;

package/dist/functions/normalizeFilePath.js

@@ -0,0 +1,40 @@
+/**
+ * Convert absolute file paths to relative paths for display.
+ *
+ * This ensures consistent path display across different sources:
+ * - React _debugSource may provide absolute paths
+ * - Next.js data-locatorjs attributes may have absolute paths
+ * - Phoenix comments use relative paths
+ *
+ * Examples:
+ *   - "/Users/name/project/src/App.tsx" → "src/App.tsx"
+ *   - "/workspace/apps/next-16/app/page.tsx" → "app/page.tsx"
+ *   - "src/components/Button.tsx" → "src/components/Button.tsx" (unchanged)
+ */
+export function normalizeFilePath(filePath) {
+  // If it's already relative (doesn't start with /), return as-is
+  if (!filePath.startsWith("/")) {
+    return filePath;
+  }
+
+  // Find common project indicators to trim the path
+  const indicators = ["/app/", "/src/", "/pages/", "/components/", "/lib/"];
+  for (const indicator of indicators) {
+    const index = filePath.indexOf(indicator);
+    if (index !== -1) {
+      // Return from the indicator onwards (remove leading slash)
+      return filePath.substring(index + 1);
+    }
+  }
+
+  // If no indicator found, try to get just the last few path segments
+  const parts = filePath.split("/");
+
+  // Return last 3-4 segments if available (e.g., "apps/next-16/app/page.tsx")
+  if (parts.length > 3) {
+    return parts.slice(-4).join("/");
+  }
+
+  // Last resort: return as-is
+  return filePath;
+}