@treelocator/runtime 0.1.8 → 0.3.0

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

package/src/functions/formatAncestryChain.test.ts

@@ -6,46 +6,49 @@ import {
 } from "./formatAncestryChain";
 
 describe("formatAncestryChain", () => {
-  it("formats basic ancestry without ID or nth-child", () => {
+  it("uses component name only at component boundaries", () => {
     const items: AncestryItem[] = [
       { elementName: "button", componentName: "Button" },
       { elementName: "div", componentName: "App" },
     ];
 
     const result = formatAncestryChain(items);
+    // App is root (component boundary), Button is different component (boundary)
     expect(result).toBe(
-      `div in App
-    └─ button in Button`
+      `App
+    └─ Button`
     );
   });
 
-  it("includes ID when present", () => {
+  it("shows element name when same component as parent", () => {
     const items: AncestryItem[] = [
-      { elementName: "button", componentName: "Button", id: "submit-btn" },
+      { elementName: "button", componentName: "App", id: "submit-btn" },
       { elementName: "div", componentName: "App" },
     ];
 
     const result = formatAncestryChain(items);
+    // Both are in App, so second item shows element name not component name
     expect(result).toBe(
-      `div in App
-    └─ button#submit-btn in Button`
+      `App
+    └─ button#submit-btn`
     );
   });
 
-  it("includes nth-child when present", () => {
+  it("includes nth-child with component name at boundary", () => {
     const items: AncestryItem[] = [
       { elementName: "li", componentName: "ListItem", nthChild: 3 },
       { elementName: "ul", componentName: "List" },
     ];
 
     const result = formatAncestryChain(items);
+    // Different components = boundaries
     expect(result).toBe(
-      `ul in List
-    └─ li:nth-child(3) in ListItem`
+      `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: AncestryItem[] = [
       {
         elementName: "li",
@@ -58,12 +61,12 @@ describe("formatAncestryChain", () => {
 
     const result = formatAncestryChain(items);
     expect(result).toBe(
-      `ul in List
-    └─ li:nth-child(2)#special-item in ListItem`
+      `List
+    └─ ListItem:nth-child(2)#special-item`
     );
   });
 
-  it("includes file location when present", () => {
+  it("includes file location at component boundary", () => {
     const items: AncestryItem[] = [
       {
         elementName: "button",
@@ -75,7 +78,8 @@ describe("formatAncestryChain", () => {
     ];
 
     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", () => {
@@ -92,7 +96,7 @@ describe("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: AncestryItem[] = [
       {
         elementName: "div",
@@ -117,13 +121,14 @@ describe("formatAncestryChain", () => {
     ];
 
     const result = formatAncestryChain(items);
+    // GlassPanel (innermost) is the display name, Sidebar (outer) shown in "in"
     expect(result).toBe(
-      `div in App at src/App.jsx:104
-    └─ div#sidebar-panel in Sidebar > GlassPanel at src/components/game/Sidebar.jsx:78`
+      `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: AncestryItem[] = [
       {
         elementName: "button",
@@ -135,6 +140,7 @@ describe("formatAncestryChain", () => {
     ];
 
     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/src/functions/formatAncestryChain.ts

@@ -1,4 +1,8 @@
 import { TreeNode, TreeNodeComponent, TreeNodeElement } from "../types/TreeNode";
+import { ServerComponentInfo } from "../types/ServerComponentInfo";
+import { parsePhoenixServerComponents } from "../adapters/phoenix/parsePhoenixComments";
+import { parseNextjsServerComponents } from "../adapters/nextjs/parseNextjsDataAttributes";
+import { normalizeFilePath } from "./normalizeFilePath";
 
 export interface OwnerComponentInfo {
   name: string;
@@ -15,6 +19,8 @@ export interface AncestryItem {
   nthChild?: number; // 1-indexed, only set when there are ambiguous siblings
   /** All owner components from outermost (Sidebar) to innermost (GlassPanel) */
   ownerComponents?: OwnerComponentInfo[];
+  /** Server-side components (Phoenix LiveView, Rails, Next.js RSC, etc.) */
+  serverComponents?: ServerComponentInfo[];
 }
 
 // Elements to exclude from ancestry (not useful for debugging)
@@ -49,7 +55,7 @@ function treeNodeComponentToOwnerInfo(
 ): OwnerComponentInfo {
   return {
     name: comp.label,
-    filePath: comp.callLink?.fileName,
+    filePath: comp.callLink?.fileName ? normalizeFilePath(comp.callLink.fileName) : undefined,
     line: comp.callLink?.lineNumber,
   };
 }
@@ -82,6 +88,23 @@ export function collectAncestry(node: TreeNode): AncestryItem[] {
         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;
+        }
       }
     }
 
@@ -93,7 +116,7 @@ export function collectAncestry(node: TreeNode): AncestryItem[] {
       // 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 {
@@ -102,19 +125,19 @@ export function collectAncestry(node: TreeNode): AncestryItem[] {
       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);
     }
 
@@ -138,8 +161,36 @@ export function formatAncestryChain(items: AncestryItem[]): string {
     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: string[] = [];
+    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})`;
     }
@@ -149,15 +200,70 @@ export function formatAncestryChain(items: AncestryItem[]): string {
 
     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: string[] = [];
+
+    // 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: string[] = [];
+
+    // 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}`);
   });

package/src/functions/normalizeFilePath.ts

@@ -0,0 +1,41 @@
+/**
+ * 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: string): string {
+  // 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;
+}

package/src/types/ServerComponentInfo.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents a server-side component in the ancestry chain.
+ * Used for Phoenix LiveView, Rails ViewComponents, Next.js RSC, etc.
+ */
+export interface ServerComponentInfo {
+  /** Component name (e.g., "AppWeb.CoreComponents.button") or "@caller" for call site */
+  name: string;
+  /** File path (e.g., "lib/app_web/core_components.ex") */
+  filePath: string;
+  /** Line number in the source file */
+  line: number;
+  /** Type of server component annotation */
+  type: "component" | "caller";
+}

package/.turbo/turbo-build.log

@@ -1,30 +0,0 @@
-
-> @treelocator/runtime@0.1.8 build /Users/wende/projects/locatorjs/packages/runtime
-> concurrently pnpm:build:*
-
-[tailwind] 
-[tailwind] > @treelocator/runtime@0.1.8 build:tailwind /Users/wende/projects/locatorjs/packages/runtime
-[tailwind] > tailwindcss -i ./src/main.css -o ./dist/output.css
-[tailwind] 
-[babel] 
-[babel] > @treelocator/runtime@0.1.8 build:babel /Users/wende/projects/locatorjs/packages/runtime
-[babel] > babel src --out-dir dist --extensions .js,.jsx,.ts,.tsx
-[babel] 
-[ts] 
-[ts] > @treelocator/runtime@0.1.8 build:ts /Users/wende/projects/locatorjs/packages/runtime
-[ts] > tsc --declaration --emitDeclarationOnly --noEmit false --outDir dist
-[ts] 
-[wrapImage] 
-[wrapImage] > @treelocator/runtime@0.1.8 build:wrapImage /Users/wende/projects/locatorjs/packages/runtime
-[wrapImage] > node ./scripts/wrapImage.js
-[wrapImage] 
-[wrapImage] Tree icon file generated
-[wrapImage] pnpm run build:wrapImage exited with code 0
-[tailwind] 
-[tailwind] Rebuilding...
-[tailwind] 
-[tailwind] Done in 164ms.
-[tailwind] pnpm run build:tailwind exited with code 0
-[babel] Successfully compiled 72 files with Babel (409ms).
-[babel] pnpm run build:babel exited with code 0
-[ts] pnpm run build:ts exited with code 0

package/.turbo/turbo-test.log

@@ -1,19 +0,0 @@
-
-> @treelocator/runtime@0.1.5 test /Users/wende/projects/locatorjs/packages/runtime
-> vitest run
-
-
- RUN  v2.1.9 /Users/wende/projects/locatorjs/packages/runtime
-
- ✓ src/functions/mergeRects.test.ts (1 test) 2ms
- ✓ src/functions/evalTemplate.test.ts (1 test) 2ms
- ✓ src/functions/transformPath.test.ts (3 tests) 3ms
- ✓ src/functions/getUsableFileName.test.tsx (4 tests) 3ms
- ✓ src/functions/formatAncestryChain.test.ts (7 tests) 2ms
- ✓ src/functions/cropPath.test.ts (2 tests) 2ms
-
- Test Files  6 passed (6)
-      Tests  18 passed (18)
-   Start at  17:17:22
-   Duration  718ms (transform 282ms, setup 0ms, collect 336ms, tests 14ms, environment 1ms, prepare 463ms)
-

package/.turbo/turbo-ts.log

@@ -1,4 +0,0 @@
-
-> @locator/runtime@0.5.1 ts /Users/wende/projects/locatorjs/packages/runtime
-> tsc --noEmit
-

package/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Krzysztof Wende
-Copyright (c) 2023 Michael Musil (original LocatorJS)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.