react-spot 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-spot",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Dev-only DOM to React source opener for React 19, Next.js, and Turbopack.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "demo:next": "npm --prefix examples/next-turbopack run dev -- --turbo"
+    "demo:next": "pnpm --filter react-spot-next-turbopack-demo dev -- --turbo"
   },
   "dependencies": {
     "@jridgewell/source-map": "latest",

package/src/core/chain-transformer.ts

@@ -41,6 +41,8 @@ export interface ChainTransformContext {
   ) => Promise<ResolvedSourceInfo | null>;
   getComponentName: (fiber: Fiber) => string;
   getStackFrame: (fiber: Fiber) => string | undefined;
+  /** 获取 fiber 的所有候选栈帧，用于首选帧解析失败时回退 */
+  getAllMeaningfulFrames: (fiber: Fiber) => string[];
   debug?: boolean;
 }
 

package/src/core/fiber-utils.ts

@@ -219,6 +219,48 @@ export function getStackFrame(fiber: Fiber): string | undefined {
   return meaningfulLines[frameIndex] || meaningfulLines[0] || undefined;
 }
 
+/**
+ * 获取 fiber 的所有有意义栈帧（按优先级排序）。
+ *
+ * 当首选栈帧解析到 React 运行时等无效位置时，调用方可逐个尝试后续候选帧。
+ * 对于函数组件，优先返回 STACK_FRAME_INDEX 处的帧，然后是其他所有帧；
+ * 对于原生 DOM 元素，优先返回 index 0 处的帧。
+ *
+ * Args:
+ *   fiber: React fiber 节点
+ *
+ * Returns:
+ *   按优先级排列的栈帧行数组，首元素与 getStackFrame 返回值一致
+ */
+export function getAllMeaningfulFrames(fiber: Fiber): string[] {
+  const stack = fiber._debugStack?.stack;
+  if (!stack) return [];
+
+  const lines = stack.split('\n');
+  const meaningfulLines: string[] = [];
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line && !isUnresolvableFrame(line)) {
+      meaningfulLines.push(line);
+    }
+  }
+
+  if (meaningfulLines.length === 0) return [];
+
+  // 将首选帧放到数组头部，其余按原始顺序跟随
+  const frameIndex = typeof fiber.type === 'string' ? 0 : STACK_FRAME_INDEX;
+  const preferred = meaningfulLines[frameIndex];
+  if (!preferred) return meaningfulLines;
+
+  const result = [preferred];
+  for (let i = 0; i < meaningfulLines.length; i++) {
+    if (i !== frameIndex) {
+      result.push(meaningfulLines[i]);
+    }
+  }
+  return result;
+}
+
 /**
  * 在 DOM 节点上查找 React fiber 内部属性。
  *

package/src/core/source-location-resolver.ts

@@ -341,24 +341,26 @@ async function resolveViaNextDevServer(
     const { originalStackFrame } = first.value;
     let sourcePath = originalStackFrame.file || frameInfo.url;
 
-    // Next.js returns project-relative paths (e.g. "src/app/page.tsx").
-    // Convert to absolute using the configured source root so the editor
-    // can open the file directly.
-    if (
-      sourcePath &&
-      !sourcePath.startsWith('/') &&
-      !sourcePath.startsWith('file://') &&
-      !sourcePath.includes('://')
-    ) {
-      const fsRoot = getSourceRoot();
+    // Next.js/Turbopack 返回的路径有两种形式：
+    // 1. 纯相对路径："src/app/page.tsx"（无前导 /）
+    // 2. 虚拟根相对路径："/src/components/layout/AppShell.tsx"（有前导 / 但非真实绝对路径）
+    // 两种情况都需要拼接 sourceRoot 才能得到可打开的文件系统绝对路径。
+    // 真正的绝对路径特征：以 fsRoot 开头（如 /Users/...）或以 file:// 开头。
+    const fsRoot = getSourceRoot();
+    if (sourcePath && !sourcePath.includes('://')) {
       if (debug) {
-        console.log('Source path is relative, resolving with sourceRoot:', {
-          sourcePath,
-          fsRoot,
-        });
+        console.log('Resolving sourcePath with sourceRoot:', { sourcePath, fsRoot });
       }
       if (fsRoot) {
-        sourcePath = `${fsRoot}/${sourcePath}`;
+        if (sourcePath.startsWith(fsRoot)) {
+          // 已经是完整的文件系统绝对路径，无需处理
+        } else if (sourcePath.startsWith('/')) {
+          // 虚拟根相对路径（如 /src/...），拼接项目根
+          sourcePath = fsRoot + sourcePath;
+        } else {
+          // 纯相对路径（如 src/app/page.tsx），用 / 连接
+          sourcePath = `${fsRoot}/${sourcePath}`;
+        }
       }
     }
 
@@ -769,6 +771,16 @@ export async function resolveLocation(
       sourceContent: originalSourceContent || undefined,
     };
 
+    // 后验证：source map 可能错误地将 workspace 包映射到 React 运行时文件，
+    // 此时应视为解析失败，让调用方尝试其他候选栈帧
+    if (isRuntimeSource(result.source)) {
+      if (debug) {
+        console.warn('Resolved to runtime source, rejecting:', result.source);
+        console.groupEnd();
+      }
+      return null;
+    }
+
     boundedSet(resultCache, cacheKey, { originalSource: result }, MAX_RESULT_CACHE_SIZE);
 
     if (debug) {
@@ -793,6 +805,54 @@ export async function resolveLocation(
   }
 }
 
+/**
+ * 检查解析出的源码路径是否指向第三方库或框架运行时文件（非用户代码）。
+ *
+ * 这是源码导航的核心守卫：当 source map 将位置映射到 node_modules 内的
+ * 第三方包源码时（如 next/src/client/image-component.tsx），该路径通常：
+ * 1. 在磁盘上不存在（包发布时不含原始 TS 源码）
+ * 2. 不是用户想要到达的位置（用户想去"使用处"而非"定义处"）
+ *
+ * 例外：pnpm workspace 链接的包会通过 symlink 直接解析到 workspace 目录，
+ * 不经过 .pnpm/ 虚拟存储，因此不会被误判。
+ */
+export function isRuntimeSource(source: string): boolean {
+  // pnpm 虚拟存储中的包 → 一定是第三方依赖
+  if (source.includes('node_modules/.pnpm/')) return true;
+
+  // node_modules 内部的包源码（排除直接 symlink 到 workspace 的情况）
+  // 匹配模式：node_modules/<pkg>/src/ 或 node_modules/<pkg>/dist/ 等
+  if (source.includes('/node_modules/') && !isWorkspaceLinkedPath(source)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * 判断一个包含 node_modules 的路径是否指向 workspace 链接的包。
+ *
+ * workspace 包的特征：路径中 node_modules 后面紧跟包名，
+ * 且该路径最终指向项目 workspace 内部（不含 .pnpm）。
+ * 此判断确保 monorepo 中自己的 packages 仍可正常导航。
+ */
+function isWorkspaceLinkedPath(source: string): boolean {
+  const fsRoot = getSourceRoot();
+  if (!fsRoot) return false;
+
+  // workspace 链接的路径解析后应以项目根目录开头，
+  // 且不经过 .pnpm 虚拟存储
+  if (source.startsWith(fsRoot) && !source.includes('.pnpm')) {
+    // 进一步检查：node_modules 之后的路径段是否又嵌套了 node_modules
+    // 如果有多层 node_modules，通常是第三方包的依赖
+    const afterFirstNodeModules = source.split('/node_modules/').slice(1);
+    if (afterFirstNodeModules.length <= 1) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /** Clears all caches (including the Next.js dev server availability flag). */
 export function clearCaches(): void {
   resultCache.clear();

package/src/react/ReactSpot.tsx

@@ -7,7 +7,7 @@ import type {
   TransformedEntry,
 } from '../core/chain-transformer';
 import { applyTransformer } from '../core/chain-transformer';
-import { buildFiberChain, buildFiberReturnChain, getComponentName, getStackFrame, isHostFiberEntry } from '../core/fiber-utils';
+import { buildFiberChain, buildFiberReturnChain, getAllMeaningfulFrames, getComponentName, getStackFrame, isHostFiberEntry } from '../core/fiber-utils';
 import { configureSourceRoot, resolveLocation } from '../core/source-location-resolver';
 import type { ClickToNodeInfo, ComponentHandle, NavigationEvent } from '../core/types';
 import { Popover, PopoverContent, PopoverTrigger } from './components/ui/popover';
@@ -193,8 +193,11 @@ function openInEditor(
 }
 
 /**
- * Resolves the source location for a single component and opens the editor.
- * Delegates to the resolver's own two-level cache.
+ * 解析组件源码位置并跳转到编辑器。
+ *
+ * 首先尝试首选栈帧；若解析失败（如 source map 错误地映射到 React 运行时），
+ * 则从 fiber 提取所有候选帧逐个尝试，直到找到有效的用户源码位置。
+ * 此回退机制解决 monorepo workspace 包在 Turbopack 编译后 source map 链路断裂的问题。
  */
 async function resolveAndNavigate(
   component: ClickToNodeInfo,
@@ -218,12 +221,56 @@ async function resolveAndNavigate(
       );
       return true;
     }
+
+    // 首选帧解析失败，尝试 fiber 的所有候选帧
+    const fallbackFrames = getAllMeaningfulFrames(component.fiber);
+    for (const frame of fallbackFrames) {
+      if (frame === component.stackFrame) continue;
+      const fallbackResolved = await resolveLocation(frame, debug);
+      if (fallbackResolved) {
+        if (debug) {
+          console.log('[react-spot] Resolved via fallback frame:', frame);
+        }
+        openInEditor(
+          fallbackResolved.source,
+          fallbackResolved.line,
+          fallbackResolved.column,
+          onNavigate,
+          component.componentName,
+          editorScheme,
+          debug
+        );
+        return true;
+      }
+    }
+
     return false;
   } catch {
     return false;
   }
 }
 
+/**
+ * 沿 owner chain 逐个尝试解析源码位置并跳转。
+ *
+ * 解决第三方库组件（如 next/image）的场景：当用户点击由库组件渲染的 DOM 元素时，
+ * 该 DOM 的栈帧指向库内部实现（不存在或不可达），此时应沿 chain 向上
+ * 找到最近的用户代码位置（即使用该库组件的 JSX 所在行）。
+ */
+async function resolveAndNavigateWithChainFallback(
+  chain: ClickToNodeInfo[],
+  onNavigate?: ReactSpotProps['onNavigate'],
+  editorScheme?: string,
+  debug?: boolean
+): Promise<boolean> {
+  for (const entry of chain) {
+    if (!entry.stackFrame) continue;
+    const success = await resolveAndNavigate(entry, onNavigate, editorScheme, debug);
+    if (success) return true;
+  }
+  return false;
+}
+
 export function ReactSpot({
   onNavigate,
   sourceRoot,
@@ -292,6 +339,7 @@ export function ReactSpot({
       resolveLocation: (sf, dbg) => resolveLocation(sf, dbg ?? debugRef.current),
       getComponentName,
       getStackFrame,
+      getAllMeaningfulFrames,
     }),
     []
   );
@@ -564,18 +612,26 @@ export function ReactSpot({
           componentName: c.componentName,
           props: c.props,
           index: i,
-          resolveSource: () =>
-            c.stackFrame
-              ? resolveLocation(c.stackFrame, dbg).then((r) =>
-                  r ? { source: r.source, line: r.line, column: r.column } : null
-                )
-              : Promise.resolve(null),
+          resolveSource: async () => {
+            if (!c.stackFrame) return null;
+            const r = await resolveLocation(c.stackFrame, dbg);
+            if (r) return { source: r.source, line: r.line, column: r.column };
+            // 首选帧失败，尝试 fiber 的其他候选帧
+            const fallbacks = getAllMeaningfulFrames(c.fiber);
+            for (const frame of fallbacks) {
+              if (frame === c.stackFrame) continue;
+              const fr = await resolveLocation(frame, dbg);
+              if (fr) return { source: fr.source, line: fr.line, column: fr.column };
+            }
+            return null;
+          },
         }));
         Promise.resolve(getClickTargetRef.current(handles)).then((targetIndex) => {
           const idx = targetIndex ?? 0;
           if (idx >= 0 && idx < currentChain.length) {
-            resolveAndNavigate(
-              currentChain[idx],
+            // 从选中位置开始沿 chain 向上回退，处理库组件源码不可达的情况
+            resolveAndNavigateWithChainFallback(
+              currentChain.slice(idx),
               onNavigateRef.current,
               editorSchemeRef.current,
               debugRef.current
@@ -587,8 +643,10 @@ export function ReactSpot({
         const transformed = applyTransformer(currentChain, chainTransformerRef.current, ctx);
         if (transformed.length > 0) navigateFromEntry(transformed[0]);
       } else {
-        resolveAndNavigate(
-          target,
+        // 尝试解析首选目标；若失败（如第三方库组件源码不存在），
+        // 沿 owner chain 向上逐个尝试，直到找到可导航的用户代码位置
+        resolveAndNavigateWithChainFallback(
+          currentChain,
           onNavigateRef.current,
           editorSchemeRef.current,
           debugRef.current

package/src/transformers/transformer-rule.ts

@@ -122,7 +122,8 @@ function buildLabel(value: unknown, rule: TransformerRule): string {
 function buildResolveLocation(
   stackFrame: string | undefined,
   rule: TransformerRule,
-  ctx: ChainTransformContext
+  ctx: ChainTransformContext,
+  fiber?: Fiber
 ): (() => Promise<{ source: string; line: number; column: number } | null>) | undefined {
   if (!stackFrame) {
     if (ctx.debug) {
@@ -132,7 +133,23 @@ function buildResolveLocation(
   }
 
   return async () => {
-    const resolved = await ctx.resolveLocation(stackFrame);
+    let resolved = await ctx.resolveLocation(stackFrame);
+
+    // 首选帧解析失败时，尝试 fiber 的其他候选栈帧
+    if (!resolved && fiber) {
+      const fallbacks = ctx.getAllMeaningfulFrames(fiber);
+      for (const frame of fallbacks) {
+        if (frame === stackFrame) continue;
+        resolved = await ctx.resolveLocation(frame);
+        if (resolved) {
+          if (ctx.debug) {
+            console.log(LOG_PREFIX, `resolved via fallback frame for rule "${rule.name}"`);
+          }
+          break;
+        }
+      }
+    }
+
     if (!resolved) {
       if (ctx.debug) {
         console.warn(LOG_PREFIX, `source resolution returned null for rule "${rule.name}"`, {
@@ -234,7 +251,7 @@ function matchChildFiber(
     label: buildLabel(labelValue, rule),
     sourceEntry: info,
     props,
-    resolveLocation: buildResolveLocation(stackFrame, rule, ctx),
+    resolveLocation: buildResolveLocation(stackFrame, rule, ctx, matched),
   };
 }
 
@@ -292,7 +309,7 @@ function matchDirect(
     label: buildLabel(labelValue, rule),
     sourceEntry: { ...entry, stackFrame },
     props,
-    resolveLocation: buildResolveLocation(stackFrame, rule, ctx),
+    resolveLocation: buildResolveLocation(stackFrame, rule, ctx, entry.fiber),
   };
 }