HoverSource

Translate What You See To What Your Agent Needs.

You are a VibeCoder? Ever tried to describe a UI element with human language then see your agent burn your quota just to figure out what on Earth you are talking about, then fix the wrong thing?

You are a Senior who knows what Ctrl + Shift + I is to copy the right thing and give it to your Agent, but you feel pathetic spending your life doing that?

I cured the curse. Hover on what you want the AI to change, press Alt + C, then Ctrl + V.

Features

• Dual Interaction Modes:
  • Inspector Mode: Hover over components to view layout boundaries, selector paths, and file deep-links. Copies HoverSource Component Metadata with Alt + C.
  • Design Mode (Alt + X to toggle): Drag a targeting crosshair to snap against horizontal/vertical edges and measure pixel-perfect offsets. Copies HoverSource Design Placement Metadata with Alt + C.
• Copy AI-Ready Metadata (Alt + C / Alt + Shift + C): Copies a structured Markdown block to your clipboard — component name, exact file path with line/column, computed styles, parent visual effects with CSS source locations, layout constraints, JSDoc comments, and raw JSX attributes (or snapping offsets and absolute CSS anchors in Design Mode). Pressing Alt + Shift + C copies the metadata of all ancestor layers under the cursor plus a minified structural HTML skeleton of the target element, providing the AI with layout and nesting context.
• Freeze State (Alt + P): Locks dynamic elements (like tooltips, popovers, or dropdowns) in place so you can hover and capture them without them disappearing.
• Toggle Overlay (Alt + H): Show or hide the developer overlay bounding box and floating spec card.
• Deep-linking (Click filename): Instantly opens the file in your preferred editor (VS Code or Cursor) at the exact line number.
• Source Line Correction: Silently checks and corrects compiler-shifted line numbers in the background.
• Layered Element Navigation (Alt + Shift + Scroll): Cycle through overlapping DOM elements under the cursor using a scroll combination, showing a clean 2D overlapping layer stack in the tooltip to easily target parent/child elements. Customize shortcuts in the dashboard.
• Element Selector & CSS Source Location: Captures the exact HTML tag and classes of the hovered element, along with the specific line and file of their CSS definition. This includes support for CSS Preprocessors (Sass, SCSS, Less) with nested selectors, and CSS Modules (auto-resolving hashed class names back to their source definitions).

Benchmark: Human Language vs. HoverSource Metadata

To measure the efficiency gains, we ran comprehensive benchmarks with an AI coding agent (Gemini 3.5 Flash) performing style modification tasks in a dry-run environment (logged using chronicle-mcp). We compared three prompt variations:

1. Prompt A: Pure Natural Language (simulating a user who does not know the codebase).
2. Prompt B: Senior Developer Context (manual file path and component naming).
3. Prompt C: HoverSource Metadata (automatic clipboard metadata block).

The benchmarks were performed on two public open-source projects of different scales:

1. Cal.com (cal.diy): Giant enterprise-level monorepo (~7,700 source files, multiple apps/packages).
2. YumeShelf: Medium-sized desktop Electron application (~200 source files).

Benchmark 1: Cal.com Monorepo (Giant Enterprise Codebase - 10 Tasks)

• Detailed Report & Logs: Cal.com Benchmark Report

Metric	Pure Natural Language (A)	Senior Developer (B)	HoverSource Metadata (C)	Delta (C vs A)
Task Achievement	60.0% (6/10)	100.0% (10/10)	100.0% (10/10)	+66.7%
Avg Agent Steps	65.6	18.0	17.1	-73.9%
Avg Tool Calls	30.5	6.5	5.9	-80.7%
Avg Execution Time	142.0s	44.2s	16.4s	-88.5% (8.7x faster)
Avg Cumulative Input Tokens	651,681	37,858	35,733	-94.5% (18.2x fewer tokens)
Avg Peak Context Window	28,257	7,372	6,486	-77.0%

Benchmark 2: YumeShelf (Medium Codebase - 5 Tasks)

• Detailed Report & Logs: YumeShelf Benchmark Report

Metric	Pure Natural Language (A)	Senior Developer (B)	HoverSource Metadata (C)	Delta (C vs A)
Task Achievement	100.0% (5/5)	100.0% (5/5)	100.0% (5/5)	-
Avg Agent Steps	34.4	22.0	26.0	-24.4%
Avg Tool Calls	15.2	8.8	11.0	-27.6%
Avg Execution Time	34.4s	38.8s	24.8s	-27.9% (1.4x faster)
Avg Cumulative Input Tokens	118,354	44,382	61,255	-48.2% (1.9x fewer tokens)
Avg Peak Context Window	14,140	8,589	9,984	-29.4%

Why HoverSource scales with codebase complexity

• Zero Search & Exploration Overhead: In YumeShelf, the natural language agent had to scan directories and run global searches (grep) to locate the card and CSS files. In Cal.com's monorepo, this overhead exploded. The agent had to list multiple directories, inspect packages, and evaluate ambiguous components across different packages (such as packages/ui vs packages/coss-ui) just to find the active Button code. Guided by HoverSource, the agent went straight to the exact target line in a single turn.
• Context Preservation: By bypassing global searches and file listings, HoverSource keeps the agent's context window extremely clean, leading to a 98.6% reduction in token consumption on Cal.com (from half a million tokens to just under 7k). This directly translates to lower API costs and faster responses.

Modes of Operation

HoverSource runs in two distinct interaction modes depending on your task. You can toggle between them at any time by pressing Alt + X.

1. Inspector Mode (Default)

Ideal for debugging, modifying, or refactoring existing elements.

• Hovering elements highlights their layout bounding box and opens a floating card containing file paths, component names, CSS locations, and layout context.
• Pressing Alt + C copies Component Metadata (see Clipboard Output).

2. Design Mode

Ideal for positioning new UI elements (cards, badges, modals, tooltips) relative to existing elements.

• Activates a drag-and-drop targeting crosshair.
• Snaps the crosshair horizontally or vertically against nearby element boundaries (edges or center axes) to measure precise offsets (dX, dY).
• Pressing Alt + C copies Design Placement Metadata containing:
  • Exact target and snap anchor selectors.
  • Pixel-perfect offsets and boundaries.
  • Pre-computed absolute position CSS block (top, left, white-space).
  • Structural guidance for AI agents to decide on DOM insertion and flex/grid adjustments.

Framework Support Matrix

HoverSource supports resolving metadata for multiple frontend frameworks at different levels of depth depending on what information is exposed by the framework's development mode:

Metadata Field	React (Non-Invasive / Invasive)	Vue (Non-Invasive / Invasive)	Svelte (Non-Invasive)	Angular (Non-Invasive / Invasive)	SolidJS (Non-Invasive)	Preact (Non-Invasive)	Astro (Non-Invasive)	Vanilla / Fallback
Component Name	Resolved	Resolved	Resolved	Resolved	Resolved	Resolved	Resolved	Fallback (DOM tag)
File Path	Resolved	Resolved	Resolved	Unresolved / Resolved*	Resolved	Resolved	Resolved	Partially Resolved**
Line Number	Resolved	None / Resolved*	Resolved	None / Resolved*	Resolved	Resolved	Resolved	Resolved**
Column Number	Resolved	None / Resolved*	Resolved	None / Resolved*	Resolved	Resolved	Resolved	Resolved**
Tag Name & Classes	Resolved	Resolved	Resolved	Resolved	Resolved	Resolved	Resolved	Resolved

* Note: Vue and Angular require compile-time template tagging (Invasive mode via hs install --vue or hs install --angular) to expose line/column locations (and file path for Angular). Other frameworks resolve them out-of-the-box in development mode (Non-Invasive). For server-side environments (React Server Components / SSR in Next.js), React utilizes automatic, zero-config on-disk runtime patching during dev server execution.

** Note: Vanilla JS/TS resolves source locations dynamically via runtime monkey patching of DOM creation APIs (document.createElement and Element.prototype.innerHTML setter). Static elements in index.html or elements created before the overlay is injected will remain unresolved (Unknown).

Next.js & React Server Components (RSC) Support

For Next.js 14+ projects, HoverSource automatically resolves source code locations (file path, line, and column) for both server-rendered components (SSR) and React Server Components (RSC) when launched using hs dev or hs start.

• Mechanism: HoverSource temporarily patches the standard React CJS development runtimes and Next.js's vendored app-page router runtimes on disk during development server execution. All patched files are restored to their original state upon process exit or CLI shutdown.
• Optimized SWC Integration: For elements compiled with dev-mode source tracking (__source), HoverSource reads the source locations directly without performance overhead. For RSC elements where compiler-level source attributes are stripped, HoverSource resolves locations dynamically on the server.

Vanilla JS/TS Source Resolution

For projects not using a component framework, HoverSource resolves source locations dynamically using a runtime monkey-patching approach:

• Overrides document.createElement to capture the stack trace when an element is instantiated.
• Overrides the Element.prototype.innerHTML setter to capture the stack trace and tag the element and its direct children.
• Parses the V8 stack trace to extract the file path, line, and column, and stores them in the data-hs-source attribute.

Limitations of Vanilla Resolution

• Timing & CDP Injection Delay: Only elements created or modified after the HoverSource overlay is loaded and the monkey patches are applied will have source metadata. In Electron or SPA applications, elements in the initial HTML payload or rendered immediately during application boot time will be painted before the CDP injector connects. These elements will initially show Unknown.
  • Workaround A (Interactive): Simply perform any UI action that triggers a re-render or re-creates the DOM elements (e.g., toggling a favorite state, applying a search query, switching tabs, or clicking a refresh list button) once the HoverSource overlay is loaded.
  • Workaround B (Pre-Injection): For 100% accurate startup resolution without manual interaction, manually add the HoverSource overlay script tag at the very top of your project's main HTML file's <head> during active development:

    <script src="http://127.0.0.1:7300/hoversource-overlay.js"></script>

• Bundling/Transpilation: If the code is bundled or transpiled without source maps, the captured stack trace will point to the bundled output rather than the original source files.

Proxy & Security Transport Matrix

When utilizing HoverSource in Web Application Proxy Mode (hs --target=<url>), the reverse proxy employs dedicated routing and headers interception layers to handle modern browser restrictions: