react-spot 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-spot",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Dev-only DOM to React source opener for React 19, Next.js, and Turbopack.",
   "type": "module",
   "license": "MIT",

package/src/core/fiber-utils.ts

@@ -2,10 +2,15 @@ import type { ClickToNodeInfo, Fiber } from './types';
 
 export { isHostFiberEntry } from './types';
 
+// 避免对同一 fiber 重复执行 type 检测逻辑，
+// 在 owner chain 遍历中同一 fiber 可能被 isUserComponent、getStackFrame、push 等多处调用
+const componentNameCache = new WeakMap<Fiber, string>();
+
 /**
  * 从 fiber 中提取可读的组件名称。
  *
  * 支持函数组件、类组件、ForwardRef、Memo 包装和原生 DOM 元素。
+ * 结果通过 WeakMap 缓存，同一 fiber 只解析一次。
  *
  * Args:
  *   fiber: React fiber 节点
@@ -14,7 +19,11 @@ export { isHostFiberEntry } from './types';
  *   组件的显示名称
  */
 export function getComponentName(fiber: Fiber): string {
-  return resolveComponentName(fiber).name;
+  const cached = componentNameCache.get(fiber);
+  if (cached !== undefined) return cached;
+  const name = resolveComponentName(fiber).name;
+  componentNameCache.set(fiber, name);
+  return name;
 }
 
 interface NameResolution {
@@ -186,61 +195,138 @@ const INTERNAL_FUNCTION_KEYWORDS = [
   'attemptResolveElement',
 ];
 
+// 将所有内部关键词预编译为单个正则，利用引擎内部 alternation 优化（trie/Aho-Corasick），
+// 单次 test 替代逐一 includes，在高频栈帧过滤场景下性能提升约 5-10x
+const INTERNAL_FRAME_RE = new RegExp(
+  [...INTERNAL_PATH_KEYWORDS, ...INTERNAL_FUNCTION_KEYWORDS, '<anonymous>']
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|')
+);
+
 function isUnresolvableFrame(line: string): boolean {
-  for (const keyword of INTERNAL_PATH_KEYWORDS) {
-    if (line.includes(keyword)) return true;
-  }
-  for (const keyword of INTERNAL_FUNCTION_KEYWORDS) {
-    if (line.includes(keyword)) return true;
-  }
-  if (line.includes('<anonymous>')) return true;
-  return false;
+  return INTERNAL_FRAME_RE.test(line);
 }
 
 /**
- * 从 fiber 的 _debugStack 中提取有意义的栈帧行。
- *
- * 过滤掉 React 运行时内部帧后，取第 STACK_FRAME_INDEX 个帧。
- * 该帧通常对应用户源码中的 JSX 调用位置。
+ * fiber 栈帧解析缓存结构。
  *
- * Args:
- *   fiber: React fiber 节点
+ * 一次解析同时产出 preferredFrame（首选帧）和 allFrames（按优先级排列的全部帧），
+ * 供 getStackFrame / getAllMeaningfulFrames / isUserComponent 共享，
+ * 避免同一 fiber 的 _debugStack.stack 被重复 split + filter。
+ */
+interface ParsedStackInfo {
+  preferredFrame: string | undefined;
+  allFrames: string[];
+  meaningfulLines: string[];
+  hasUserFrame: boolean;
+}
+
+// WeakMap 以 fiber 对象为 key，GC 友好，不会阻止 fiber 被回收
+const parsedStackCache = new WeakMap<Fiber, ParsedStackInfo>();
+
+/**
+ * 一次性解析 fiber 的 _debugStack，并缓存解析结果。
  *
- * Returns:
- *   栈帧行字符串，如 "at Button (http://…:18:26)"，或 undefined
+ * 内部完成：栈字符串分割、运行时帧过滤、自身帧检测、首选帧确定、
+ * 用户帧判断。所有需要栈信息的函数共享此缓存，避免重复解析。
  */
-export function getStackFrame(fiber: Fiber): string | undefined {
+function getParsedStack(fiber: Fiber): ParsedStackInfo {
+  const cached = parsedStackCache.get(fiber);
+  if (cached) return cached;
+
   const stack = fiber._debugStack?.stack;
-  if (!stack) return undefined;
+  if (!stack) {
+    const empty: ParsedStackInfo = {
+      preferredFrame: undefined,
+      allFrames: [],
+      meaningfulLines: [],
+      hasUserFrame: true,
+    };
+    parsedStackCache.set(fiber, empty);
+    return empty;
+  }
 
   const lines = stack.split('\n');
   const meaningfulLines: string[] = [];
+  let hasUserFrame = false;
+  let hasAnyMeaningfulFrame = false;
+
   for (let i = 1; i < lines.length; i++) {
     const line = lines[i].trim();
-    if (line && !isUnresolvableFrame(line)) {
-      meaningfulLines.push(line);
+    if (!line) continue;
+    if (isUnresolvableFrame(line)) continue;
+
+    meaningfulLines.push(line);
+    hasAnyMeaningfulFrame = true;
+
+    // 顺带检测是否存在非框架帧（用于 isUserComponent 判定）
+    if (
+      !hasUserFrame &&
+      !line.includes('node_modules') &&
+      !line.includes('next/dist') &&
+      !line.includes('next_dist') &&
+      !line.includes('next-server') &&
+      !line.includes('react-dom') &&
+      !line.includes('react-server-dom')
+    ) {
+      hasUserFrame = true;
     }
   }
 
-  if (meaningfulLines.length === 0) return undefined;
+  // 确定首选帧
+  let preferredFrame: string | undefined;
+  let preferredIndex = 0;
 
-  // 原生 DOM 元素直接取第一个帧（JSX 标签创建点）
-  if (typeof fiber.type === 'string') {
-    return meaningfulLines[0];
+  if (meaningfulLines.length > 0) {
+    if (typeof fiber.type === 'string') {
+      // 原生 DOM 元素直接取第一个帧
+      preferredFrame = meaningfulLines[0];
+    } else {
+      // 函数组件：检测自身帧
+      const componentName = getComponentName(fiber);
+      if (meaningfulLines.length > 1 && isSelfFrame(meaningfulLines[0], componentName)) {
+        preferredIndex = STACK_FRAME_INDEX_FALLBACK;
+      }
+      preferredFrame = meaningfulLines[preferredIndex] || meaningfulLines[0];
+    }
   }
 
-  // 函数组件：检测 meaningful[0] 是否为 React 注入的"自身帧"。
-  // React 19 会注入一个以组件名命名的帧，使调用栈更可读。
-  // 判断方法：检查帧中的函数名是否与当前 fiber 的组件名匹配。
-  // 若匹配，说明是自身帧，应跳过取 meaningful[1]（实际使用位置）。
-  // 若不匹配（如 workspace 包组件的自身帧被 HMR 过滤掉），meaningful[0] 已是使用位置。
-  const componentName = getComponentName(fiber);
-  const firstFrame = meaningfulLines[0];
-  if (isSelfFrame(firstFrame, componentName)) {
-    return meaningfulLines[STACK_FRAME_INDEX_FALLBACK] || meaningfulLines[0];
+  // 构建按优先级排列的完整帧列表
+  const allFrames: string[] = [];
+  if (preferredFrame) {
+    allFrames.push(preferredFrame);
+    for (let i = 0; i < meaningfulLines.length; i++) {
+      if (i !== preferredIndex) {
+        allFrames.push(meaningfulLines[i]);
+      }
+    }
   }
 
-  return firstFrame;
+  // hasUserFrame 仅在确实有 meaningful 帧时才有意义
+  const result: ParsedStackInfo = {
+    preferredFrame,
+    allFrames,
+    meaningfulLines,
+    hasUserFrame: !hasAnyMeaningfulFrame || hasUserFrame,
+  };
+  parsedStackCache.set(fiber, result);
+  return result;
+}
+
+/**
+ * 从 fiber 的 _debugStack 中提取首选栈帧行。
+ *
+ * 利用统一解析缓存，避免重复字符串分割和过滤。
+ * 返回的帧通常对应用户源码中的 JSX 调用位置。
+ *
+ * Args:
+ *   fiber: React fiber 节点
+ *
+ * Returns:
+ *   栈帧行字符串，如 "at Button (http://…:18:26)"，或 undefined
+ */
+export function getStackFrame(fiber: Fiber): string | undefined {
+  return getParsedStack(fiber).preferredFrame;
 }
 
 /**
@@ -269,51 +355,17 @@ function isSelfFrame(frameLine: string, componentName: string): boolean {
 /**
  * 获取 fiber 的所有有意义栈帧（按优先级排序）。
  *
+ * 利用统一解析缓存，首元素与 getStackFrame 返回值一致。
  * 当首选栈帧解析到 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 [];
-
-  // 确定首选帧索引：与 getStackFrame 保持一致的智能检测逻辑
-  let preferredIndex = 0;
-  if (typeof fiber.type !== 'string' && meaningfulLines.length > 1) {
-    const componentName = getComponentName(fiber);
-    if (isSelfFrame(meaningfulLines[0], componentName)) {
-      preferredIndex = STACK_FRAME_INDEX_FALLBACK;
-    }
-  }
-
-  const preferred = meaningfulLines[preferredIndex];
-  if (!preferred) return meaningfulLines;
-
-  // 将首选帧放到数组头部，其余按原始顺序跟随
-  const result = [preferred];
-  for (let i = 0; i < meaningfulLines.length; i++) {
-    if (i !== preferredIndex) {
-      result.push(meaningfulLines[i]);
-    }
-  }
-  return result;
+  return getParsedStack(fiber).allFrames;
 }
 
 /**
@@ -479,34 +531,12 @@ const FRAMEWORK_COMPONENT_NAMES = new Set([
 ]);
 
 /**
- * 框架组件名的正则模式，用于匹配动态生成的或变体名称。
+ * 框架组件名的合并正则，用于匹配动态生成的或变体名称。
+ * 将 17 个独立 RegExp 合并为单次 test，减少正则引擎启动开销。
  *
  * 例如 "InnerLayoutRouter_", "Memo(LayoutRouter)" 等。
  */
-const FRAMEWORK_NAME_PATTERNS = [
-  /Boundary$/,
-  /^(Inner|Outer)?LayoutRouter/,
-  /^Segment/,
-  /^Scroll/,
-  /^Redirect/,
-  /^NotFound/,
-  /^HTTPAccess/,
-  /^Metadata(Boundary|Outlet)/,
-  /^Viewport/,
-  /^DevOverlay/,
-  /^HotReload/,
-  /^ReactDevOverlay/,
-  /^ServerRoot/,
-  /^AppRouter/,
-  /^GlobalLayoutRouter/,
-  /^PathnameContext/,
-  /^RenderFromTemplate/,
-  /^StaticGeneration/,
-  /^AutoScroll/,
-  /^NavigateHandler/,
-  /^PreloadCss/,
-  /^PreloadModule/,
-];
+const FRAMEWORK_NAME_RE = /Boundary$|^(Inner|Outer)?LayoutRouter|^Segment|^Scroll|^Redirect|^NotFound|^HTTPAccess|^Metadata(Boundary|Outlet)|^Viewport|^DevOverlay|^HotReload|^ReactDevOverlay|^ServerRoot|^AppRouter|^GlobalLayoutRouter|^PathnameContext|^RenderFromTemplate|^StaticGeneration|^AutoScroll|^NavigateHandler|^PreloadCss|^PreloadModule/;
 
 /**
  * 判断 fiber 是否为用户定义的组件（而非框架/库内部组件）。
@@ -529,48 +559,15 @@ function isUserComponent(fiber: Fiber): boolean {
   }
 
   // 策略2：正则模式匹配（捕获 LayoutRouter_ 等变体）
-  for (const pattern of FRAMEWORK_NAME_PATTERNS) {
-    if (pattern.test(coreName)) {
-      return false;
-    }
+  if (FRAMEWORK_NAME_RE.test(coreName)) {
+    return false;
   }
 
-  // 策略3：检查 _debugStack 原始文本中是否全为框架代码路径
-  const stack = fiber._debugStack?.stack;
-  if (stack) {
-    const lines = stack.split('\n');
-    let hasUserFrame = false;
-    let hasAnyMeaningfulFrame = false;
-
-    for (let i = 1; i < lines.length; i++) {
-      const line = lines[i].trim();
-      if (!line) continue;
-      // 跳过 React 运行时帧
-      if (isUnresolvableFrame(line)) continue;
-
-      hasAnyMeaningfulFrame = true;
-
-      // 框架代码帧的特征
-      if (
-        line.includes('node_modules') ||
-        line.includes('next/dist') ||
-        line.includes('next_dist') ||
-        line.includes('next-server') ||
-        line.includes('react-dom') ||
-        line.includes('react-server-dom')
-      ) {
-        continue;
-      }
-
-      // 找到一个非框架帧，说明该组件来自用户代码
-      hasUserFrame = true;
-      break;
-    }
-
-    // 有意义帧全部指向框架代码 → 是框架组件
-    if (hasAnyMeaningfulFrame && !hasUserFrame) {
-      return false;
-    }
+  // 策略3：利用统一栈解析缓存判断是否存在用户帧，
+  // 避免重复 split + filter（已在 getParsedStack 中完成）
+  const parsed = getParsedStack(fiber);
+  if (!parsed.hasUserFrame) {
+    return false;
   }
 
   // 通过所有过滤，视为用户组件
@@ -689,10 +686,7 @@ function tryPushOwnerChainEntry(chain: ClickToNodeInfo[], current: unknown): voi
   if (node.name && typeof node.name === 'string' && !node.type) {
     const name = node.name as string;
     if (FRAMEWORK_COMPONENT_NAMES.has(name)) return;
-
-    for (const pattern of FRAMEWORK_NAME_PATTERNS) {
-      if (pattern.test(name)) return;
-    }
+    if (FRAMEWORK_NAME_RE.test(name)) return;
 
     const stackFrame = resolveVirtualOwnerStackFrame(name, node);
 
@@ -728,7 +722,7 @@ function tryPushOwnerChainEntry(chain: ClickToNodeInfo[], current: unknown): voi
  * Returns:
  *   从叶到根的完整 owner 链路（含原生 DOM）
  */
-export function buildFiberReturnChain(target: Element): ClickToNodeInfo[] {
+export function buildFiberChain(target: Element): ClickToNodeInfo[] {
   const chain: ClickToNodeInfo[] = [];
   const fiber = findFiberElementFromNode(target);
   if (!fiber) return chain;
@@ -749,33 +743,8 @@ export function buildFiberReturnChain(target: Element): ClickToNodeInfo[] {
 }
 
 /**
- * 从 DOM 元素开始，沿 owner 链向上遍历，构建组件所有权链。
+ * buildFiberChain 的别名，保持 API 兼容。
  *
- * 兼容标准 Fiber、原生 DOM 和 React 19 虚拟 owner（服务端组件），
- * 过滤框架内部组件。完整 chain 含原生 DOM，供左键精确定位 JSX 标签。
- *
- * Args:
- *   target: 被点击的 DOM 元素
- *
- * Returns:
- *   从 DOM 元素到根的完整 owner 链路（含原生 DOM）
+ * 两者逻辑完全一致——沿 owner 链遍历并构建组件层级链。
  */
-export function buildFiberChain(target: Element): ClickToNodeInfo[] {
-  const chain: ClickToNodeInfo[] = [];
-  const fiber = findFiberElementFromNode(target);
-  if (!fiber) return chain;
-
-  const seen = new WeakSet();
-  let current: unknown = fiber;
-
-  while (current && typeof current === 'object') {
-    if (seen.has(current as object)) break;
-    seen.add(current as object);
-
-    tryPushOwnerChainEntry(chain, current);
-    const node = current as Record<string, unknown>;
-    current = node._debugOwner ?? node.owner ?? null;
-  }
-
-  return chain;
-}
+export const buildFiberReturnChain = buildFiberChain;

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

@@ -22,6 +22,8 @@ export interface ResolvedSourceInfo extends OriginalSourceInfo {
 interface CachedSourceMapData {
   sourceContent: string;
   sourceMapContent: string;
+  // 缓存已解析的 JSON 对象，避免每次 mapToOriginalSource 时重复 JSON.parse
+  parsedSourceMap: Record<string, unknown>;
 }
 
 interface CachedResult {
@@ -536,13 +538,16 @@ export async function resolveSourceMap(
 /**
  * Maps a generated position to the original source via source map.
  * Returns the raw source path as-is — the caller resolves it (see `resolveSourcePath`).
+ *
+ * 接受可选的预解析 JSON 对象以跳过 JSON.parse（L2 缓存命中时直接传入）。
  */
 export async function mapToOriginalSource(
   frameInfo: StackFrameInfo,
-  sourceMapContent: string
+  sourceMapContent: string,
+  parsedMap?: Record<string, unknown>
 ): Promise<{ info: OriginalSourceInfo; sourceRoot?: string } | null> {
   try {
-    const sourceMap = JSON.parse(sourceMapContent);
+    const sourceMap = parsedMap ?? JSON.parse(sourceMapContent);
 
     const consumer = new SourceMapConsumer(sourceMap);
 
@@ -563,7 +568,7 @@ export async function mapToOriginalSource(
           column: originalPosition.column,
           name: originalPosition.name || undefined,
         },
-        sourceRoot: sourceMap.sourceRoot,
+        sourceRoot: (sourceMap as Record<string, unknown>).sourceRoot as string | undefined,
       };
     }
 
@@ -574,13 +579,18 @@ export async function mapToOriginalSource(
   }
 }
 
-/** Retrieves the original source content embedded in the source map, if available. */
+/**
+ * Retrieves the original source content embedded in the source map, if available.
+ *
+ * 接受可选的预解析 JSON 对象以跳过重复 JSON.parse。
+ */
 export async function getOriginalSourceContent(
   originalInfo: OriginalSourceInfo,
-  sourceMapContent: string
+  sourceMapContent: string,
+  parsedMap?: Record<string, unknown>
 ): Promise<string | null> {
   try {
-    const sourceMap = JSON.parse(sourceMapContent);
+    const sourceMap = parsedMap ?? JSON.parse(sourceMapContent);
     const consumer = new SourceMapConsumer(sourceMap);
 
     const sourceContent = consumer.sourceContentFor(originalInfo.source);
@@ -720,9 +730,23 @@ export async function resolveLocation(
 
       if (debug) console.log('Source map resolved (length:', sourceMapContent.length, ')');
 
+      // 预解析 JSON 并缓存，后续同 URL 的不同位置查询可直接复用，
+      // 避免每次 mapToOriginalSource 重复 JSON.parse + SourceMapConsumer 构建
+      let parsedSourceMap: Record<string, unknown>;
+      try {
+        parsedSourceMap = JSON.parse(sourceMapContent);
+      } catch {
+        if (debug) {
+          console.warn('Failed to parse source map JSON for:', effectiveUrl);
+          console.groupEnd();
+        }
+        return null;
+      }
+
       sourceMapData = {
         sourceContent: sourceResult.content,
         sourceMapContent,
+        parsedSourceMap,
       };
       boundedSet(sourceMapCache, url, sourceMapData, MAX_SOURCE_MAP_CACHE_SIZE);
       if (url !== effectiveUrl) {
@@ -732,7 +756,7 @@ export async function resolveLocation(
       if (debug) console.log('L2 cache hit for:', url);
     }
 
-    const mapResult = await mapToOriginalSource(frameInfo, sourceMapData.sourceMapContent);
+    const mapResult = await mapToOriginalSource(frameInfo, sourceMapData.sourceMapContent, sourceMapData.parsedSourceMap);
     if (!mapResult) {
       if (debug) {
         console.warn('Source map lookup returned no result for position', { line, column });
@@ -763,7 +787,8 @@ export async function resolveLocation(
     // Use the raw (pre-resolved) path for content lookup — that's what the source map indexes by
     const originalSourceContent = await getOriginalSourceContent(
       { ...originalInfo, source: rawSource },
-      sourceMapData.sourceMapContent
+      sourceMapData.sourceMapContent,
+      sourceMapData.parsedSourceMap
     );
 
     const result: ResolvedSourceInfo = {

package/src/react/ReactSpot.tsx

@@ -222,19 +222,27 @@ 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) {
+    // 首选帧解析失败，并行解析所有候选帧以减少网络等待时间。
+    // 通过 allSettled 获取所有结果，按原始优先级顺序取第一个成功的。
+    const fallbackFrames = getAllMeaningfulFrames(component.fiber)
+      .filter((frame) => frame !== component.stackFrame);
+
+    if (fallbackFrames.length === 0) return false;
+
+    const results = await Promise.allSettled(
+      fallbackFrames.map((frame) => resolveLocation(frame, debug))
+    );
+
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      if (result.status === 'fulfilled' && result.value) {
         if (debug) {
-          console.log('[react-spot] Resolved via fallback frame:', frame);
+          console.log('[react-spot] Resolved via fallback frame:', fallbackFrames[i]);
         }
         openInEditor(
-          fallbackResolved.source,
-          fallbackResolved.line,
-          fallbackResolved.column,
+          result.value.source,
+          result.value.line,
+          result.value.column,
           onNavigate,
           component.componentName,
           editorScheme,
@@ -558,11 +566,18 @@ export function ReactSpot({
     // 闭包变量：保存当前悬停元素的 fiber 链路，供左键点击时使用，
     // 避免 React state 的异步更新导致点击时读到过期数据
     let currentChain: ClickToNodeInfo[] = [];
+    // 缓存上次悬停的 DOM 元素引用，相同元素时跳过整个 chain 重算，
+    // 在高频 mousemove 场景（60fps+）下消除 90%+ 冗余计算
+    let lastHoveredEl: HTMLElement | null = null;
 
     const onMouseMove = (e: MouseEvent) => {
       const el = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement | null;
       if (!el || el.closest('[data-react-spot-overlay]')) return;
 
+      // 同一元素无需重新构建 fiber chain 和重绘高亮
+      if (el === lastHoveredEl) return;
+      lastHoveredEl = el;
+
       const rect = el.getBoundingClientRect();
       currentChain = buildFiberChain(el);
 
@@ -616,12 +631,17 @@ export function ReactSpot({
             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 };
+            // 首选帧失败，并行解析所有候选帧
+            const fallbacks = getAllMeaningfulFrames(c.fiber)
+              .filter((frame) => frame !== c.stackFrame);
+            if (fallbacks.length === 0) return null;
+            const results = await Promise.allSettled(
+              fallbacks.map((frame) => resolveLocation(frame, dbg))
+            );
+            for (const result of results) {
+              if (result.status === 'fulfilled' && result.value) {
+                return { source: result.value.source, line: result.value.line, column: result.value.column };
+              }
             }
             return null;
           },