Summary

Map annotations to their source file so agents know exactly which file to edit, eliminating the costly "grep for matching text" step.

Problem

When an agent receives an annotation, it knows the page URL (/about) and the selected text or element selector, but has no idea which source file to edit. It must search the entire codebase for matching text — expensive, slow, and error-prone for common strings like "Learn more" or "Submit".

This is the number one pain point in the agent workflow. Every annotation, every time, agents waste cycles on file discovery.

Prior Art: Tidewave

José Valim's Tidewave solves this exact problem for Phoenix and Rails by running an MCP server inside the application runtime. When a developer inspects a DOM element, Tidewave maps it directly to the source template/component that rendered it — because the runtime knows the relationship between code and rendered output.

From Valim's vertical integration essay:

"I had to constantly translate what was on the page to source code. If I wanted to 'Add an Export to CSV button to a dropdown button', the first step was typically to find where the template or component the dropdown was defined in"

Review Loop is already in a similar position — the Vite plugin runs inside the dev server and has access to Vite's module graph, which tracks which source modules contribute to each page. We just don't exploit this yet.

See also: #72 (agent runtime architecture research)

Proposal

• Add an optional sourceHint field to annotations, populated by the Vite plugin at annotation creation time
• The Vite plugin has access to the module graph and can map rendered DOM back to source components
• The hint would contain: { filePath: "src/pages/about.astro", lineRange?: [42, 58] }
• Exposed to agents via list_annotations and start_work MCP tools
• Framework-specific implementation — start with Astro (which has clear component boundaries), then extend to SvelteKit/Nuxt

Technical approach (to investigate)

• Vite's moduleGraph tracks which modules contribute to a page — this is the same kind of runtime knowledge Tidewave exploits, just via Vite rather than Phoenix/Rails internals
• Framework-specific: Astro's injectScript context knows the page being rendered; SvelteKit/Nuxt have their own component tree metadata
• Could inject a data attribute (e.g. data-source-file) during dev builds that the client reads when creating annotations — Tidewave uses a similar approach with its element inspector
• Alternative: use Vite's source maps to reverse-map DOM positions to source locations

Tidewave comparison

Review Loop's zero-config principle suggests a lighter touch than Tidewave's deep framework integration, but the core mechanism (dev server knows which source files render each page element) is the same.

Key Constraints

• Optional field — annotations without source hints remain valid (graceful degradation for unsupported frameworks)
• Dev-only — source hints must not leak into production builds
• Start with Astro — prove the concept with the best-supported framework first, then extend
• Framework-specific implementations may vary in accuracy and coverage
• Zero-config — source mapping should work automatically when the Vite plugin is active, not require additional configuration

Complexity

High — requires framework-specific hooks and investigation into Vite's module graph capabilities.

Consensus

2/3 STRONG YES (Agent + Product ranked this #1). 1/3 MAYBE (Reviewer — neutral, doesn't directly help reviewers). High complexity but transformative impact.

Related

• Part of feature roadmap — brainstormed and debated by agent panel #62 (feature roadmap — Tier 2)
• research: agent runtime architecture — from embedded component to browser-native runtime #72 — Agent runtime architecture research (Tidewave analysis, phased approach)