react-spot 0.0.1

package/README.md

@@ -0,0 +1,115 @@
+# react-spot
+
+Dev-only DOM to source opener for React 19, Next.js, and Turbopack.
+
+It does not inject `data-*` attributes at compile time. In the browser it finds the React Fiber attached to a clicked DOM node, walks `fiber.return` and owner metadata, reads React development source hints such as `_debugSource`, `_debugStack`, `_debugInfo`, and owner stacks, then calls a local `__open-in-editor` endpoint.
+
+This intentionally depends on React private development fields. The library keeps those reads isolated and returns diagnostics when React, Next.js, or Turbopack do not expose enough metadata.
+
+## Install
+
+```bash
+npm install react-spot
+```
+
+## Next.js App Router
+
+Create the endpoint:
+
+```ts
+// app/__open-in-editor/route.ts
+export { GET, POST, runtime, dynamic } from "react-spot/next";
+```
+
+Install the click listener in a client component:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import { installReactSpot } from "react-spot";
+
+export function ReactSpotDevtools() {
+  useEffect(() => {
+    return installReactSpot({
+      trigger: "alt"
+    });
+  }, []);
+
+  return null;
+}
+```
+
+Render `ReactSpotDevtools` only in development, for example from your root layout.
+
+- Alt-clicking an element opens the closest available React source.
+- Alt-right-clicking opens a component ancestry menu so you can pick parent components.
+
+## Options
+
+```ts
+installReactSpot({
+  endpoint: "/__open-in-editor",
+  trigger: "alt", // "always" | "meta-shift" | "ctrl-shift" | function
+  menuMaxEntries: 8,
+  onOpen(target) {
+    console.log(target.source, target.componentName, target.strategy);
+  },
+  onError(error) {
+    console.warn(error);
+  }
+});
+```
+
+Set the editor with one of:
+
+```bash
+REACT_SPOT_EDITOR=code
+REACT_SPOT_EDITOR=cursor
+REACT_SPOT_EDITOR=webstorm
+```
+
+VS Code-like editors receive `-g file:line:column`. JetBrains IDEs receive `--line line file`.
+
+## Custom Next Route Options
+
+```ts
+// app/__open-in-editor/route.ts
+import { createOpenInEditorRoute } from "react-spot/next";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const GET = createOpenInEditorRoute({
+  projectRoot: process.cwd(),
+  editor: "cursor",
+  requireLocalhost: true
+});
+
+export const POST = GET;
+```
+
+## How It Resolves Source
+
+1. Finds a DOM expando like `__reactFiber$...`.
+2. Starts with that host Fiber and walks `fiber.return`.
+3. Checks direct source objects such as `_debugSource`.
+4. Parses stack metadata such as `_debugStack`, `_debugInfo`, and owner stacks.
+5. Follows owner links such as `_debugOwner`.
+6. Calls `/__open-in-editor?file=...&line=...&column=...`.
+
+Server Components and Client Component boundaries may only expose the client entry or nearest hydrated owner. When React/Turbopack do not emit source metadata, `inspectElement` returns `source: null` instead of guessing.
+
+## Public API
+
+```ts
+import {
+  installReactSpot,
+  inspectElement,
+  findFiberFromElement,
+  findSourceFromFiber,
+  parseSourceFromStack
+} from "react-spot";
+```
+
+`inspectElement(element)` is useful if you want to build your own overlay or command palette instead of opening the editor directly.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "react-spot",
+  "version": "0.0.1",
+  "description": "Dev-only DOM to React source opener for React 19, Next.js, and Turbopack.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "demo:next": "npm --prefix examples/next-turbopack run dev -- --turbo"
+  },
+  "dependencies": {
+    "@jridgewell/source-map": "latest",
+    "@radix-ui/react-popover": "latest",
+    "@uiw/react-json-view": "latest",
+    "convert-source-map": "latest"
+  },
+  "keywords": [
+    "react",
+    "nextjs",
+    "turbopack",
+    "open-in-editor",
+    "fiber"
+  ],
+  "devDependencies": {
+    "@babel/parser": "^8.0.0",
+    "@types/convert-source-map": "^2.0.3",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
+    "typescript": "^6.0.3"
+  }
+}

package/src/core/chain-transformer.ts

@@ -0,0 +1,89 @@
+import type { ResolvedSourceInfo } from './source-location-resolver';
+import type { ClickToNodeInfo, Fiber } from './types';
+
+/**
+ * 经过变换的组件链路条目，用于在弹出菜单中展示。
+ *
+ * 由 ChainTransformer 从原始 fiber 链路生成，
+ * 支持重命名、折叠、覆盖导航目标等变换操作。
+ */
+export interface TransformedEntry {
+  /** 在链路弹出菜单中显示的标签（替代原始组件名） */
+  label: string;
+  /**
+   * 原始链路条目，用于：
+   * - 当 resolveLocation 未提供时回退到默认源码解析
+   * - 当 props 未提供时回退到 fiber props
+   */
+  sourceEntry: ClickToNodeInfo;
+  /**
+   * 覆盖源码位置解析。用户点击弹出菜单条目时延迟调用。
+   * 返回 null 表示解析失败，UI 会回退到 sourceEntry 的默认解析。
+   */
+  resolveLocation?: () => Promise<{
+    source: string;
+    line: number;
+    column: number;
+  } | null>;
+  /** 覆盖 props 检查器的数据，默认取 sourceEntry.props */
+  props?: Record<string, unknown>;
+}
+
+/**
+ * 链路变换器的上下文，提供源码解析和 fiber 内省工具。
+ *
+ * 由库注入，使变换器无需直接导入内部模块。
+ */
+export interface ChainTransformContext {
+  resolveLocation: (
+    stackFrame: string,
+    debug?: boolean
+  ) => Promise<ResolvedSourceInfo | null>;
+  getComponentName: (fiber: Fiber) => string;
+  getStackFrame: (fiber: Fiber) => string | undefined;
+  debug?: boolean;
+}
+
+/**
+ * 链路变换器函数签名。
+ *
+ * 接收原始 fiber 链路（DOM 最近元素在前），返回变换后的条目数组。
+ * 必须同步执行——异步工作应延迟到 TransformedEntry.resolveLocation 闭包中。
+ */
+export type ChainTransformer = (
+  chain: ClickToNodeInfo[],
+  context: ChainTransformContext
+) => TransformedEntry[];
+
+/**
+ * 默认变换：直接将 fiber 链路映射为展示条目，不做任何折叠或重命名。
+ */
+function defaultTransform(chain: ClickToNodeInfo[]): TransformedEntry[] {
+  return chain.map((entry) => ({
+    label: entry.componentName,
+    sourceEntry: entry,
+    props: entry.props,
+  }));
+}
+
+/**
+ * 应用链路变换器。
+ *
+ * 若未配置变换器则使用默认变换（直接映射组件名）。
+ *
+ * Args:
+ *   chain: 原始 fiber 链路
+ *   transformer: 可选的自定义变换器
+ *   context: 变换上下文
+ *
+ * Returns:
+ *   变换后的展示条目数组
+ */
+export function applyTransformer(
+  chain: ClickToNodeInfo[],
+  transformer: ChainTransformer | undefined,
+  context: ChainTransformContext
+): TransformedEntry[] {
+  if (!transformer) return defaultTransform(chain);
+  return transformer(chain, context);
+}