PRD: Harden selection source URL resolution and snippet boundaries

[jazelly]

Problem Statement

Developers rely on selection context capture to map a clicked DOM element back to the React component source that should be edited. The current implementation is close, but one source-resolution path can turn a Vite root-relative project path into a filesystem /@fs candidate that points outside the project-root model. That creates unnecessary source lookup ambiguity and weakens the trust boundary around source snippet capture.

Solution

Tighten source path classification and snippet resolution so browser-side and MCP-side source enrichment treat root-relative Vite paths, relative source paths, and filesystem paths as distinct cases. /@fs candidates should only be generated for real filesystem paths that are known to be inside the configured project source root. The user-facing behavior should remain the same: selecting an element still returns useful component context and snippets, but source lookups become deterministic and bounded.

User Stories

1. As a React developer, I want selected elements to resolve to the correct source file, so that I can edit the intended component quickly.
2. As an MCP client user, I want source snippets to come from the active project, so that model suggestions are grounded in the code I am viewing.
3. As a package maintainer, I want source lookup to reject paths outside the project root, so that local development does not expose unrelated files.
4. As a Vite user, I want root-relative source paths to resolve through Vite's normal module serving, so that /src paths behave predictably.
5. As a Vite user, I do not want root-relative source paths to become filesystem /@fs paths, so that accidental absolute filesystem reads are avoided.
6. As a monorepo user, I want workspace roots and package roots to be handled explicitly, so that snippet lookup is not dependent on shell cwd accidents.
7. As a Windows user, I want path normalization to handle backslashes safely, so that source capture works cross-platform.
8. As a security reviewer, I want source snippet enrichment to have a clear allowlist, so that review can prove what can and cannot be read.
9. As a test author, I want a small path-resolution interface, so that boundary cases can be tested without launching a browser.
10. As a browser runtime user, I want browser-side copy behavior to keep working when source snippets are available, so that the clipboard payload remains useful.
11. As an MCP server user, I want server-side snippet enrichment to follow the same trust model as browser-side enrichment, so that outputs are consistent.
12. As a future contributor, I want path classification rules to be centralized, so that future fixes do not drift across browser and server implementations.
13. As a user selecting generated or dependency-backed DOM, I want dependency and build-cache paths excluded, so that returned snippets prioritize authored code.
14. As a user selecting a component with missing source metadata, I want selection context to degrade gracefully, so that the tool still returns DOM and component context.
15. As a maintainer, I want this hardening to be invisible to normal happy paths, so that existing selection workflows do not regress.

Implementation Decisions

• Extract or consolidate source path classification behind a deep module with a small public interface for validating source paths and building source URL candidates.
• Keep root-relative Vite paths separate from absolute filesystem paths.
• Generate /@fs candidates only for filesystem paths that pass the configured source-root boundary.
• Keep browser-side source fetching and MCP-side snippet enrichment aligned on the same path rules.
• Preserve the existing selection context API shape and MCP tool contracts.
• Continue excluding dependencies and build-cache paths from source snippet enrichment.
• Treat source snippets as best-effort enrichment, not a reason for the whole selection context call to fail.

Testing Decisions

• Good tests should verify behavior through public source-resolution and selection-context interfaces, not private implementation details.
• Add focused tests for root-relative paths, relative paths, filesystem paths inside the project root, filesystem paths outside the project root, dependency paths, build-cache paths, null-byte paths, and non-source extensions.
• Add at least one integration-style test proving that normal playground selection still returns a source snippet after the hardening.
• Add negative-path coverage proving that an out-of-root source path does not produce a snippet.
• Reuse the existing playground selection e2e as prior art for user-visible behavior.
• Prefer a deep-module unit test for path classification because it can cover many boundary cases cheaply and deterministically.

Out of Scope

• Building a production source-map server.
• Expanding browser support beyond the existing Playwright Chromium coverage.
• Changing the public MCP tool names or response payload shape.
• Solving full Next.js server component source lookup beyond preserving existing best-effort behavior.

Further Notes

This PRD addresses the highest-priority remaining review finding. It should be implemented before further broadening source capture behavior because it defines the trust boundary other features depend on.