rfc: Next.js and Nuxt plugins for element-to-source mapping

[coconilu]

Context

目前 PickFix 的元素点选能力主要基于 HTML 标签、class、id、selector、rect、htmlHint 等运行时 DOM 信息。

这对简单 UI 修改已经有帮助，但在真实项目中，仅靠 HTML 信息并不总是足够。为了让 AI agent 更精准地修改代码，PickFix 需要知道被点选元素对应的源码位置，例如组件文件、行列信息、组件名等。

Next.js 和 Nuxt 是当前项目已有示例支持的两个框架，因此可以优先探索对应插件能力。

Goals and non-goals

Goals:

• 提供 Next.js 插件，增强元素到源码文件的映射能力。
• 提供 Nuxt 插件，增强元素到源码文件的映射能力。
• 在点选元素时，为 agent 提供更精准上下文：
  • source file
  • line / column
  • component name
  • framework metadata
• 保持 PickFix 对目标项目尽量低侵入。

Non-goals:

• 本 Issue 不要求一次性支持所有框架。
• 本 Issue 不要求完美覆盖所有构建模式。
• 本 Issue 不直接实现 Vite / Astro 插件。

Proposed design

初步方向：

1. 为 Next.js 提供 PickFix 插件或开发期增强能力。
2. 为 Nuxt 提供 PickFix module/plugin。
3. 在开发模式下给 DOM 注入额外 metadata，例如：
   • data-pf-source-file
   • data-pf-source-line
   • data-pf-component
4. bridge 在点选元素时读取这些 metadata。
5. web UI 和 agent prompt 使用这些源码信息生成更精准上下文。

Trade-offs and risks

• 不同框架、构建工具、React/Vue 编译链路差异较大。
• Source mapping 可能受开发模式、生产构建、minify、HMR 影响。
• 插件会增加目标项目集成成本。
• 需要避免泄露敏感源码路径到不可信环境。

Affected packages

• packages/bridge
• packages/cli
• apps/web
• examples
• docs
• not sure

Rollout plan

1. 先调研 Next.js dev overlay / source metadata 可行性。
2. 设计统一 metadata schema。
3. 实现 Next.js prototype。
4. 实现 Nuxt prototype。
5. 更新 bridge element metadata。
6. 更新 agent prompt，让源码位置进入上下文。
7. 增加 examples 和文档。

[coconilu]

RFC status and next step

Current status: RFC / investigation.

This issue should not jump directly into a full Next.js + Nuxt plugin implementation. The next step is to validate the element-to-source mapping strategy, then implement the smallest prototype.

Initial research summary

What Next.js appears to support

• Next.js uses SWC and React development transforms, but relying on React __source / _debugSource is risky because React 19 removed this path from public/dev internals.
• Newer React tooling can inspect component stacks or _debugStack, but this is private React internals and not ideal as the first implementation path.
• Source maps are available in development, but resolving from a clicked DOM element to a source location without build-time metadata is significantly more complex.
• A build-time metadata injection approach is likely simpler and more reliable for PickFix MVP.

What Nuxt/Vue appears to support

• Vue/Nuxt development builds have stronger source metadata options.
• Vue components expose dev-only file metadata such as __file.
• Vue SFC compiler and Vite plugin ecosystem make template transform/source metadata injection practical.
• Existing tools like Vue inspector-style plugins commonly inject source metadata into DOM attributes during development.

Recommended MVP direction

Use explicit development-only DOM metadata attributes.

Example schema:

<button
  data-pf-source-file="src/components/Button.tsx"
  data-pf-source-line="12"
  data-pf-source-column="5"
  data-pf-component="Button"
>
  Submit
</button>

Then PickFix bridge can include this in the pick payload:

type PickSourceMetadata = {
  file?: string;
  line?: number;
  column?: number;
  component?: string;
  framework?: "next" | "nuxt" | "unknown";
};

Proposed implementation order

1. Research exact transform/plugin hooks for Next.js and Nuxt.
2. Define the shared data-pf-* metadata schema.
3. Extend packages/bridge pick payload to read source metadata from the selected element or nearest ancestor.
4. Prototype Next.js source metadata injection first.
5. Surface source context in apps/web and agent prompt.
6. Prototype Nuxt source metadata injection.
7. Document plugin setup and limitations.

Open questions

• Should PickFix use explicit plugins only, or also support a no-plugin fallback later?
• Should metadata be stored as separate attributes or a compact JSON attribute?
• How should source paths be normalized across local filesystem, Docker, and remote/self-hosted environments?
• How much source metadata is safe to expose in browser DOM for enterprise usage?