react-spot 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-spot",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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

@@ -769,6 +769,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 +803,33 @@ export async function resolveLocation(
   }
 }
 
+/**
+ * 检查解析出的源码路径是否指向 React/框架运行时文件。
+ *
+ * 当 source map 错误地将 workspace 包的代码映射到运行时文件时，
+ * 此函数用于识别并拒绝这种无效结果，使调用方可以尝试其他候选帧。
+ */
+const RUNTIME_SOURCE_PATTERNS = [
+  'react-jsx-runtime',
+  'react-jsx-dev-runtime',
+  '/compiled/react/',
+  '/compiled/react-dom/',
+  '/compiled/react-server-dom',
+  'node_modules/react/cjs/',
+  'node_modules/react/dist/',
+  'node_modules/react-dom/cjs/',
+  'node_modules/react-dom/dist/',
+  'node_modules/next/dist/compiled/',
+  'node_modules/next/dist/server/',
+  'node_modules/next/dist/client/',
+  'react-reconciler',
+  'scheduler/',
+];
+
+export function isRuntimeSource(source: string): boolean {
+  return RUNTIME_SOURCE_PATTERNS.some((p) => source.includes(p));
+}
+
 /** 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,6 +221,29 @@ 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;
@@ -292,6 +318,7 @@ export function ReactSpot({
       resolveLocation: (sf, dbg) => resolveLocation(sf, dbg ?? debugRef.current),
       getComponentName,
       getStackFrame,
+      getAllMeaningfulFrames,
     }),
     []
   );
@@ -564,12 +591,19 @@ 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;

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),
   };
 }