improve how source files are resolved

also compute relativePath and absolutePath

Author: buzinas

.changeset/stale-buses-cover.md

@@ -0,0 +1,9 @@
+---
+"@react-trace/plugin-copy-to-clipboard": patch
+"@react-trace/plugin-open-editor": patch
+"@react-trace/plugin-comments": patch
+"@react-trace/plugin-preview": patch
+"@react-trace/core": patch
+---
+
+Improve how source location is resolved and compute relative and absolute paths

apps/website/docs/extending/plugin-api.mdx

@@ -91,13 +91,17 @@ Returns a callback that clears the current selection. Use this when a plugin flo
 
 ### `useSelectedSource()`
 
-Returns the currently selected `ComponentSource | null`. This is a convenience for accessing just the source location.
+Returns the currently selected `ComponentSource | null`. Each source includes source-mapped file coordinates and pre-computed project-relative and absolute paths.
 
 ```ts
 interface ComponentSource {
   fileName: string
   lineNumber: number
   columnNumber: number
+  /** Path relative to the project root, e.g. "src/App.tsx" */
+  relativePath: string
+  /** Absolute filesystem path, e.g. "/Users/you/project/src/App.tsx" */
+  absolutePath: string
 }
 ```
 
@@ -121,26 +125,23 @@ function MyToolbarButton() {
 
 ## Utilities and constants
 
-| Export                            | Description                                                            |
-| --------------------------------- | ---------------------------------------------------------------------- |
-| `resolveSource(source)`           | Resolves URL-based source locations to original source-map positions.  |
-| `toAbsolutePath(fileName, root?)` | Converts a source filename or Vite URL to an absolute filesystem path. |
-| `toRelativePath(fileName, root?)` | Converts a source filename or Vite URL to a project-relative path.     |
-| `settingsPluginAtom(pluginKey)`   | Returns a writable Jotai atom for a section of `TraceSettings`.        |
-| `IS_MAC`                          | `true` on macOS/iOS user agents.                                       |
-| `MOD_KEY`                         | Platform-specific modifier key label (`⌘` on Mac, `Ctrl` elsewhere).   |
+| Export                          | Description                                                          |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `settingsPluginAtom(pluginKey)` | Returns a writable Jotai atom for a section of `TraceSettings`.      |
+| `IS_MAC`                        | `true` on macOS/iOS user agents.                                     |
+| `MOD_KEY`                       | Platform-specific modifier key label (`⌘` on Mac, `Ctrl` elsewhere). |
 
 ## Types
 
 All types are exported from `@react-trace/core`:
 
-| Type               | Description                                                                         |
-| ------------------ | ----------------------------------------------------------------------------------- |
-| `ComponentContext` | Full context of an inspected component (element, name, breadcrumb, props, sources). |
-| `ComponentSource`  | Source file location (fileName, lineNumber, columnNumber).                          |
-| `TracePlugin`      | The plugin contract (name + optional toolbar/actionPanel/settings components).      |
-| `TraceProps`       | Props accepted by the `Trace` component.                                            |
-| `TraceSettings`    | Shape of the widget settings state.                                                 |
+| Type               | Description                                                                            |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `ComponentContext` | Full context of an inspected component (element, name, breadcrumb, props, sources).    |
+| `ComponentSource`  | Source file location (fileName, lineNumber, columnNumber, relativePath, absolutePath). |
+| `TracePlugin`      | The plugin contract (name + optional toolbar/actionPanel/settings components).         |
+| `TraceProps`       | Props accepted by the `Trace` component.                                               |
+| `TraceSettings`    | Shape of the widget settings state.                                                    |
 
 ## Production stubs
 

packages/core/README.md

@@ -117,17 +117,14 @@ export function AppShell() {
 
 ## Exported utilities and constants
 
-- `resolveSource(source)` — resolves URL-based source locations back to original source-map positions when possible
-- `toAbsolutePath(fileName, root?)` — converts a source filename or Vite URL to an absolute filesystem path
-- `toRelativePath(fileName, root?)` — converts a source filename or Vite URL to a path relative to the project root when possible
 - `settingsPluginAtom(pluginKey)` — returns a writable Jotai atom for a section of `TraceSettings`
 - `IS_MAC` — `true` on macOS/iOS user agents
 - `MOD_KEY` — platform-specific modifier key label (`⌘` or `Ctrl`)
 
 ## Exported types
 
-- `ComponentContext`
-- `ComponentSource`
+- `ComponentContext` — full context of an inspected component (element, name, breadcrumb, props, sources)
+- `ComponentSource` — source file location (`fileName`, `lineNumber`, `columnNumber`, `relativePath`, `absolutePath`)
 - `TracePlugin`
 - `TraceProps`
 - `TraceSettings`

packages/core/src/components/ActionPanel.tsx

@@ -11,11 +11,11 @@ import { useCallback } from 'react'
 
 import {
   portalContainerAtom,
+  projectRootAtom,
   selectedContextAtom,
   selectedSourceAtom,
 } from '../store'
 import type { ComponentContext, ComponentSource, TracePlugin } from '../types'
-import { toRelativePath } from '../utils/path'
 import { ErrorBoundary } from './ErrorBoundary'
 
 interface ActionPanelProps {
@@ -30,14 +30,18 @@ type ChainGroup =
   | { kind: 'entry'; names: string[]; source: ComponentSource; index: number }
   | { kind: 'third-party'; names: string[][]; count: number }
 
-function groupChain(all: ComponentContext['all']): ChainGroup[] {
+function groupChain(root: string, all: ComponentContext['all']): ChainGroup[] {
   const result: ChainGroup[] = []
   let tpCount = 0
   let names: string[][] = []
 
   for (let i = 0; i < all.length; i++) {
     const entry = all[i]!
-    if (!entry.source) {
+    if (
+      !entry.source ||
+      !entry.source.absolutePath.startsWith(root) ||
+      entry.source.relativePath.startsWith('node_modules/')
+    ) {
       tpCount++
       names.push(entry.names)
     } else {
@@ -64,8 +68,7 @@ function groupChain(all: ComponentContext['all']): ChainGroup[] {
 // ---------------------------------------------------------------------------
 
 function SourceLabel({ source }: { source: ComponentSource }) {
-  const rel = toRelativePath(source.fileName)
-  const short = rel.split('/').slice(-2).join('/')
+  const short = source.relativePath.split('/').slice(-2).join('/')
 
   return (
     <span
@@ -74,7 +77,7 @@ function SourceLabel({ source }: { source: ComponentSource }) {
         fontFamily: 'ui-monospace, monospace',
         color: '#97979b',
       }}
-      title={`${rel}:${source.lineNumber}`}
+      title={`${source.relativePath}:${source.lineNumber}`}
     >
       {short}:{source.lineNumber}
     </span>
@@ -108,9 +111,12 @@ function entryStyle(active: boolean): React.CSSProperties {
 // ---------------------------------------------------------------------------
 
 export function ActionPanel({ plugins }: ActionPanelProps) {
+  const projectRoot = useAtomValue(projectRootAtom)
   const [selectedContext, setSelectedContext] = useAtom(selectedContextAtom)
   const portalContainer = useAtomValue(portalContainerAtom)
-  const groups = selectedContext ? groupChain(selectedContext.all) : []
+  const groups = selectedContext
+    ? groupChain(projectRoot, selectedContext.all)
+    : []
 
   const onClose = useCallback(
     () => setSelectedContext(null),

packages/core/src/hooks/useInspectorBehavior.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react'
 import {
   inspectorActiveAtom,
   portalContainerAtom,
+  projectRootAtom,
   selectedContextAtom,
 } from '../store'
 import type { ComponentContext } from '../types'
@@ -22,6 +23,7 @@ import { useEffectEvent } from './useEffectEvent'
 export function useInspectorBehavior() {
   const portalContainer = useAtomValue(portalContainerAtom)
   const inspectorActive = useAtomValue(inspectorActiveAtom)
+  const root = useAtomValue(projectRootAtom)
   const setInspectorActive = useSetAtom(inspectorActiveAtom)
   const [hoveredContext, setHoveredContext] = useState<ComponentContext | null>(
     null,
@@ -60,7 +62,7 @@ export function useInspectorBehavior() {
       lastHoveredElement = target
 
       try {
-        const ctx = await getComponentContext(target)
+        const ctx = await getComponentContext(target, root)
         if (lastHoveredElement !== target) return
         setHoveredContext(ctx)
       } catch {}

packages/core/src/index.prod.ts

@@ -5,7 +5,7 @@
 
 import type { WritableAtom } from 'jotai'
 
-import type { ComponentSource, TraceSettings } from './types'
+import type { TraceSettings } from './types'
 
 const NOOP = () => {}
 
@@ -19,10 +19,6 @@ export const useClearSelectedContext = () => NOOP
 export const useSelectedSource = () => null
 export const useWidgetPortalContainer = () => null
 
-export const resolveSource = async (source: ComponentSource) => source
-export const toAbsolutePath = (path: string) => path
-export const toRelativePath = (path: string) => path
-
 export { IS_MAC, MOD_KEY } from './utils/platform'
 
 export function settingsPluginAtom<K extends keyof TraceSettings>(

packages/core/src/index.tsx

@@ -8,8 +8,6 @@ export {
   useSelectedSource,
   useWidgetPortalContainer,
 } from './hooks'
-export { resolveSource } from './utils/fiber'
-export { toAbsolutePath, toRelativePath } from './utils/path'
 export { IS_MAC, MOD_KEY } from './utils/platform'
 
 export { settingsPluginAtom } from './store'

packages/core/src/types.ts

@@ -4,6 +4,10 @@ export interface ComponentSource {
   fileName: string
   lineNumber: number
   columnNumber: number
+  /** Path relative to the project root, e.g. "src/App.tsx" */
+  relativePath: string
+  /** Absolute filesystem path, e.g. "/Users/you/project/src/App.tsx" */
+  absolutePath: string
 }
 
 export interface ComponentContext {

packages/core/src/utils/fiber.ts

@@ -2,6 +2,14 @@ import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping'
 import type { EncodedSourceMap } from '@jridgewell/trace-mapping'
 
 import type { ComponentContext, ComponentSource } from '../types'
+import { toAbsolutePath, toRelativePath } from './path'
+
+/**
+ * Raw source location extracted from React fibers before path enrichment.
+ * Missing the `relativePath` and `absolutePath` fields that are computed
+ * in `getComponentContext` once the project root is known.
+ */
+type RawSource = Omit<ComponentSource, 'relativePath' | 'absolutePath'>
 
 // ---------------------------------------------------------------------------
 // Source map resolution
@@ -67,9 +75,7 @@ function loadTraceMap(fileUrl: string): Promise<TraceMap | null> {
  * so the UI updates the line number once the source map resolves (usually <50ms
  * after the first hover on a given file, instant on subsequent hovers).
  */
-export async function resolveSource(
-  source: ComponentSource,
-): Promise<ComponentSource> {
+async function resolveSource(source: RawSource): Promise<RawSource | null> {
   // Only attempt resolution for URL-form fileNames
   try {
     new URL(source.fileName)
@@ -86,7 +92,7 @@ export async function resolveSource(
     column: source.columnNumber - 1,
   })
 
-  if (original.source == null || original.line == null) return source
+  if (original.source == null || original.line == null) return null
 
   return {
     fileName: original.source,
@@ -149,7 +155,7 @@ interface ReactFiber {
   /** React 19: Error object captured at JSX creation time, stack contains the callsite */
   _debugStack: Error | null
   /** React 18: structured source object injected by Babel/SWC's JSX source transform */
-  _debugSource: ComponentSource | null
+  _debugSource: RawSource | null
   _debugOwner: ReactFiber | null
   return: ReactFiber | null
   stateNode?: HTMLElement | null
@@ -197,9 +203,7 @@ function getDisplayName(type: ComponentType): string {
  * The fileName may be a full URL in Vite dev mode (e.g. "http://localhost:5173/src/Button.tsx").
  * URL → absolute path normalization is deferred to the FileSystemService.
  */
-function parseComponentSource(
-  debugStack: Error | null,
-): ComponentSource | null {
+function parseComponentSource(debugStack: Error | null): RawSource | null {
   if (!debugStack?.stack) return null
 
   let stack = debugStack.stack
@@ -254,7 +258,7 @@ function parseComponentSource(
  * React 18 paths are absolute filesystem paths (/abs/path/to/File.tsx) so
  * resolveSource() will no-op on them — they're already at original positions.
  */
-function getSource(fiber: ReactFiber | null): ComponentSource | null {
+function getSource(fiber: ReactFiber | null): RawSource | null {
   if (!fiber) return null
   if (fiber._debugStack) return parseComponentSource(fiber._debugStack)
   if (fiber._debugSource) return fiber._debugSource
@@ -285,6 +289,7 @@ function getSource(fiber: ReactFiber | null): ComponentSource | null {
  */
 export async function getComponentContext(
   element: HTMLElement,
+  root: string,
 ): Promise<ComponentContext | null> {
   const domFiber = findFiber(element)
   if (!domFiber) return null
@@ -295,7 +300,7 @@ export async function getComponentContext(
   //   raw  → ['code', 'p', 'Card']
   //   display → ['Card', 'p', 'code']
   let fiber: ReactFiber | null = domFiber
-  const parts: Array<{ source: ComponentSource | null; names: string[] }> = [
+  const parts: Array<{ source: RawSource | null; names: string[] }> = [
     { source: getSource(fiber), names: [] },
   ]
   let i = 0
@@ -320,17 +325,28 @@ export async function getComponentContext(
     parts.map((part) => (part.source ? resolveSource(part.source) : null)),
   )
 
+  /** Enrich a raw source with computed relative and absolute paths. */
+  function enrichSource(raw: RawSource): ComponentSource {
+    return {
+      ...raw,
+      relativePath: toRelativePath(raw.fileName, root),
+      absolutePath: toAbsolutePath(raw.fileName, root) ?? raw.fileName,
+    }
+  }
+
   // parts: [hovered, …ancestors, Component] — reverse for display order
-  const all = parts.map((part, i) => ({
-    source: sources[i] ?? part.source,
-    names: part.names.reverse(),
-  }))
+  const all = parts.map((part, idx) => {
+    const resolved = sources[idx]
+    return {
+      source: resolved ? enrichSource(resolved) : null,
+      names: part.names.reverse(),
+    }
+  })
 
-  // deduplicate same files
+  // remove files without a source
   const files = all.reduce<typeof all>((acc, part) => {
     if (!part.source) return acc
-    const file = part.source.fileName
-    if (!acc.some((p) => p.source?.fileName === file)) acc.push(part)
+    acc.push(part)
     return acc
   }, [])
 

packages/plugin-comments/src/index.tsx

@@ -1,10 +1,7 @@
 import type { TracePlugin } from '@react-trace/core'
 import {
-  resolveSource,
-  toRelativePath,
   useClearSelectedContext,
   useDeactivateInspector,
-  useProjectRoot,
   useSelectedContext,
   useSelectedSource,
   useWidgetPortalContainer,
@@ -113,31 +110,24 @@ function CommentsToolbar() {
 function CommentsActionPanel() {
   const selectedContext = useSelectedContext()
   const selectedSource = useSelectedSource()
-  const root = useProjectRoot()
   const { setPending } = useCommentsActions()
   const clearSelectedContext = useClearSelectedContext()
   const deactivateInspector = useDeactivateInspector()
 
   if (!selectedContext || !selectedSource) return null
 
-  const handleAddComment = async () => {
-    const { fileName, lineNumber } = await resolveSource(selectedSource)
-    const filePath = toRelativePath(fileName, root)
-
+  const handleAddComment = () => {
     setPending({
-      filePath,
-      lineNumber,
+      filePath: selectedSource.relativePath,
+      lineNumber: selectedSource.lineNumber,
       anchorEl: selectedContext.element,
     })
     clearSelectedContext()
     deactivateInspector()
   }
 
   return (
-    <DropdownMenu.Item
-      closeOnClick
-      onClick={() => handleAddComment().catch(() => {})}
-    >
+    <DropdownMenu.Item closeOnClick onClick={handleAddComment}>
       <span style={{ display: 'flex', alignItems: 'center' }}>
         <ChatBubbleIcon />
       </span>