@treelocator/runtime 0.1.7 → 0.2.0

package/src/adapters/phoenix/parsePhoenixComments.ts

@@ -0,0 +1,140 @@
+import { ServerComponentInfo } from "../../types/ServerComponentInfo";
+import { PhoenixCommentMatch } from "./types";
+
+/**
+ * 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: Comment): PhoenixCommentMatch | null {
+  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: Element
+): PhoenixCommentMatch[] {
+  const matches: PhoenixCommentMatch[] = [];
+  let node: Node | null = element.previousSibling;
+
+  // Walk backward through siblings, collecting comment nodes
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const match = parseCommentNode(node as Comment);
+      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: PhoenixCommentMatch[]
+): ServerComponentInfo[] {
+  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: Element
+): ServerComponentInfo[] | null {
+  const matches = findPrecedingPhoenixComments(element);
+  if (matches.length === 0) return null;
+  return phoenixMatchesToServerComponents(matches);
+}

package/src/adapters/phoenix/types.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/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/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.className ? `.${props.currentElement.className.split(" ")[0]}` : ""}
           </div>
         </div>
       )}

package/src/components/Runtime.tsx

@@ -74,7 +74,9 @@ function Runtime(props: RuntimeProps) {
       const target = e.target;
       if (target && (target instanceof HTMLElement || target instanceof SVGElement)) {
         element = target instanceof SVGElement
-          ? (target.closest('svg') as HTMLElement | null) ?? (target as unknown as HTMLElement)
+          ? (target.closest('[data-locatorjs-id], [data-locatorjs]') as HTMLElement | null) ??
+            (target.closest('svg') as HTMLElement | null) ??
+            (target as unknown as HTMLElement)
           : target;
       }
     }

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