vite-plugin-source-locator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Benshimol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# vite-plugin-source-locator
+
+Dev-only tool for jumping from UI elements in the browser to source files in your IDE. Works as a drop-in Vite plugin for React apps.
+
+## Project Structure
+
+```
+├── src/
+│   ├── vite/      # Vite plugin, Babel plugin, editor integration
+│   ├── client/    # Browser overlay (pick mode, tooltip, highlight)
+│   └── shared/    # Types, constants, theme utilities
+├── tests/         # Mirrors src/ layout
+├── dist/          # Build output (published to npm)
+└── .github/       # CI workflows
+```
+
+## Install
+
+```bash
+npm install -D vite-plugin-source-locator
+```
+
+You also need `@vitejs/plugin-react` (or another setup that runs the Babel plugin in dev).
+
+## Usage
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { sourceLocator } from 'vite-plugin-source-locator/vite'
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    react(command === 'serve' ? sourceLocator.babel() : undefined),
+    sourceLocator(),
+  ],
+}))
+```
+
+No `main.tsx` wiring required. The plugin auto-injects the client overlay in dev.
+
+## Pick Mode
+
+1. Click the badge (bottom-right): **Source Locator (cursor) — click to pick**
+2. Hover elements — blue highlight + file paths in tooltip
+3. Click to open source — cycles **TSX → CSS → TSX** when both exist
+4. **Esc** — cancel pick mode
+5. **Shift+L** — cycle IDE: cursor → vscode → webstorm
+
+## Exports
+
+| Subpath | Purpose |
+|---------|---------|
+| `vite-plugin-source-locator/vite` | Vite plugin + `sourceLocator.babel()` |
+| `vite-plugin-source-locator/client` | Manual `initSourceLocator()` if auto-inject disabled |
+| `vite-plugin-source-locator/shared` | Types, constants, parse/format utilities |
+
+## Options
+
+```typescript
+sourceLocator({
+  enabled: true,
+  endpoint: '/__open-in-editor',
+  attribute: 'data-source',
+  ides: ['cursor', 'vscode', 'webstorm'],
+  theme: 'light',
+})
+```
+
+### Theme
+
+Control overlay colors (badge, tooltip, highlight). Presets or custom colors:
+
+| Preset | Look |
+|--------|------|
+| `'default'` | Dark slate + cyan accent |
+| `'light'` | White background + blue accent |
+| `'dark'` | Black background + white/gray text |
+| `'blue'` | Navy background + light blue accent |
+
+```typescript
+// preset
+sourceLocator({ theme: 'light' })
+
+// custom (merged over default)
+import { initSourceLocator } from 'vite-plugin-source-locator/client'
+
+initSourceLocator({
+  endpoint: '/__open-in-editor',
+  attribute: 'data-source',
+  ides: ['cursor', 'vscode', 'webstorm'],
+  theme: {
+    background: '#ffffff',
+    text: '#000000',
+    accent: '#2563eb',
+  },
+})
+```
+
+| Token | Used for |
+|-------|----------|
+| `background` | Badge & tooltip background |
+| `text` | Tooltip text |
+| `accent` | Borders, highlight, badge label |
+
+## CSS Detection
+
+When an element has styles from a project `.css` file (e.g. `index.css` custom classes like `.glass`), the tooltip shows:
+
+```
+components/DashboardStats.tsx
+CSS: index.css
+Click → TSX | next: CSS
+```
+
+Click cycles between opening the TSX and CSS file.
+
+**Limitation:** Tailwind utility classes (`bg-slate-950`, etc.) are injected as inline `<style>` tags with no `.css` href — no CSS file is shown for those. CSS detection works for external `.css` stylesheets only. CSS opens at line 1 in v1.
+
+## MFE Safety
+
+- **Idempotent** — `window.__sourceLocator` guard: multiple bundles loading the locator mount only one overlay
+- **Shadow DOM** — overlay styles isolated from host/MFE CSS
+- **Virtual module** — client injected via `virtual:source-locator-client`, works from any consuming app
+
+## Manual Init
+
+```typescript
+import { initSourceLocator } from 'vite-plugin-source-locator/client'
+
+initSourceLocator({
+  endpoint: '/__open-in-editor',
+  attribute: 'data-source',
+  ides: ['cursor', 'vscode', 'webstorm'],
+  theme: 'blue',
+})
+```
+
+## Adding a New IDE
+
+1. Extend `LocatorIde` and `IDE_ORDER` in `src/shared/index.ts`
+2. Add entry to `EDITORS` in `src/vite/editors.ts`
+
+## Limitations
+
+- macOS only for IDE opening
+- Dev only — no production impact
+- JSX/TSX only for `data-source` injection
+- CSS line 1 only (no source-map line mapping yet)
+
+## License
+
+MIT

package/dist/client/controller.d.ts

@@ -0,0 +1,8 @@
+import type { LocatorIde, LocatorThemeInput } from '../shared/index.js';
+export type ClientConfig = {
+    endpoint: string;
+    attribute: string;
+    ides: LocatorIde[];
+    theme?: LocatorThemeInput;
+};
+export declare function startPickController(root: ShadowRoot, host: Element, config: ClientConfig): () => void;

package/dist/client/controller.js

@@ -0,0 +1,101 @@
+import { nextClickTarget, parseSourceLocation, resolveTheme } from '../shared/index.js';
+import { findCssSource } from './css-source.js';
+import { createLocatorOverlayUi } from './overlay.js';
+import { cycleStoredIde, getStoredIde } from './preference.js';
+function getSourceEl(target, attribute, host) {
+    if (!target || host.contains(target) || target === host)
+        return null;
+    const el = target.closest(`[${attribute}]`);
+    return el instanceof HTMLElement ? el : null;
+}
+async function openSourceInEditor(source, config) {
+    const loc = parseSourceLocation(source);
+    const params = new URLSearchParams({
+        file: loc.file,
+        line: loc.line,
+        col: loc.col,
+        ide: getStoredIde(),
+    });
+    await fetch(`${config.endpoint}?${params.toString()}`);
+}
+function readElementSources(el, attribute) {
+    const tsx = el.getAttribute(attribute) ?? undefined;
+    const css = findCssSource(el);
+    return { tsx, css, clickTarget: 'tsx' };
+}
+function resolveOpenSource(sources) {
+    if (sources.clickTarget === 'css')
+        return sources.css;
+    return sources.tsx;
+}
+export function startPickController(root, host, config) {
+    let pickMode = false;
+    let sources = { tsx: undefined, css: undefined, clickTarget: 'tsx' };
+    const ui = createLocatorOverlayUi(root, () => setPickMode(!pickMode), resolveTheme(config.theme));
+    function setPickMode(active) {
+        pickMode = active;
+        ui.setPickActive(active);
+        if (!active)
+            sources = { tsx: undefined, css: undefined, clickTarget: 'tsx' };
+    }
+    const updateHover = (target, x, y) => {
+        const el = getSourceEl(target, config.attribute, host);
+        if (!el) {
+            ui.removeTooltip();
+            return;
+        }
+        if (el !== ui.getActiveEl()) {
+            sources = readElementSources(el, config.attribute);
+        }
+        ui.showSourceTooltip(el, sources.tsx, sources.css, sources.clickTarget, x, y);
+    };
+    const onMouseMove = (e) => {
+        if (!pickMode) {
+            ui.removeTooltip();
+            return;
+        }
+        updateHover(e.target, e.clientX, e.clientY);
+    };
+    const onKeyDown = (e) => {
+        if (e.key === 'Escape' && pickMode) {
+            setPickMode(false);
+            return;
+        }
+        if (!e.shiftKey || e.key !== 'L')
+            return;
+        const next = cycleStoredIde(config.ides);
+        if (!pickMode)
+            ui.refreshBadgeLabel();
+        ui.flashMessage(`IDE: ${next}`);
+    };
+    const onClick = async (e) => {
+        if (!pickMode || host.contains(e.target))
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        const el = getSourceEl(e.target, config.attribute, host);
+        if (!el) {
+            ui.flashMessage('No source for this element');
+            return;
+        }
+        if (el !== ui.getActiveEl())
+            sources = readElementSources(el, config.attribute);
+        const openSource = resolveOpenSource(sources);
+        if (!openSource) {
+            ui.flashMessage('No source for this element');
+            return;
+        }
+        await openSourceInEditor(openSource, config);
+        sources.clickTarget = nextClickTarget(sources.clickTarget, !!sources.css);
+        ui.showSourceTooltip(el, sources.tsx, sources.css, sources.clickTarget, e.clientX, e.clientY);
+    };
+    document.addEventListener('keydown', onKeyDown);
+    document.addEventListener('mousemove', onMouseMove);
+    document.addEventListener('click', onClick, true);
+    ui.mountBadge();
+    return () => {
+        document.removeEventListener('keydown', onKeyDown);
+        document.removeEventListener('mousemove', onMouseMove);
+        document.removeEventListener('click', onClick, true);
+    };
+}

package/dist/client/css-source.d.ts

@@ -0,0 +1 @@
+export declare function findCssSource(element: Element): string | undefined;

package/dist/client/css-source.js

@@ -0,0 +1,57 @@
+import { formatSourceLocation } from '../shared/index.js';
+function scoreSelector(selector, element) {
+    let score = selector.length;
+    if (selector.includes('#'))
+        score += 100;
+    if (selector.includes('.'))
+        score += 50;
+    if (element instanceof HTMLElement) {
+        element.classList.forEach((cls) => {
+            if (selector.includes(`.${cls}`))
+                score += 200;
+        });
+    }
+    return score;
+}
+function isProjectStylesheet(href) {
+    return href.includes('.css') && (href.includes('localhost') || href.includes('/src/'));
+}
+function hrefToFile(href) {
+    const url = new URL(href, window.location.origin);
+    return decodeURIComponent(url.pathname);
+}
+export function findCssSource(element) {
+    let bestScore = -1;
+    let bestFile;
+    Array.from(document.styleSheets).forEach((sheet) => {
+        const href = sheet.href ?? '';
+        if (!href || !isProjectStylesheet(href))
+            return;
+        let rules;
+        try {
+            rules = sheet.cssRules;
+        }
+        catch {
+            return;
+        }
+        Array.from(rules).forEach((rule) => {
+            if (!(rule instanceof CSSStyleRule))
+                return;
+            try {
+                if (!element.matches(rule.selectorText))
+                    return;
+            }
+            catch {
+                return;
+            }
+            const score = scoreSelector(rule.selectorText, element);
+            if (score <= bestScore)
+                return;
+            bestScore = score;
+            bestFile = hrefToFile(href);
+        });
+    });
+    if (!bestFile)
+        return undefined;
+    return formatSourceLocation({ file: bestFile, line: '1', col: '1' });
+}

package/dist/client/index.d.ts

@@ -0,0 +1,10 @@
+import type { ClientConfig } from './controller.js';
+declare global {
+    interface Window {
+        __sourceLocator?: {
+            dispose: () => void;
+        };
+        __SOURCE_LOCATOR_CONFIG__?: ClientConfig;
+    }
+}
+export declare function initSourceLocator(config: ClientConfig): void;

package/dist/client/index.js

@@ -0,0 +1,21 @@
+import { startPickController } from './controller.js';
+const HOST_ID = 'source-locator-host';
+export function initSourceLocator(config) {
+    if (window.__sourceLocator || document.getElementById(HOST_ID))
+        return;
+    const host = document.createElement('div');
+    host.id = HOST_ID;
+    const root = host.attachShadow({ mode: 'open' });
+    document.body.appendChild(host);
+    const disposeController = startPickController(root, host, config);
+    window.__sourceLocator = {
+        dispose: () => {
+            disposeController();
+            host.remove();
+            delete window.__sourceLocator;
+        },
+    };
+}
+const injected = window.__SOURCE_LOCATOR_CONFIG__;
+if (injected)
+    initSourceLocator(injected);

package/dist/client/overlay.d.ts

@@ -0,0 +1,11 @@
+import type { ClickTarget, LocatorTheme } from '../shared/index.js';
+export declare function createLocatorOverlayUi(root: ShadowRoot, onTogglePick: () => void, theme: LocatorTheme): {
+    mountBadge: () => void;
+    setPickActive: (active: boolean) => void;
+    refreshBadgeLabel: () => void;
+    showSourceTooltip: (el: Element, tsxSource: string | undefined, cssSource: string | undefined, clickTarget: ClickTarget, x: number, y: number) => void;
+    flashMessage: (text: string) => void;
+    removeTooltip: () => void;
+    getActiveEl: () => Element | null;
+};
+export type LocatorOverlayUi = ReturnType<typeof createLocatorOverlayUi>;

package/dist/client/overlay.js

@@ -0,0 +1,166 @@
+import { parseSourceLocation } from '../shared/index.js';
+import { badgeLabel } from './preference.js';
+const UI_IDS = {
+    badge: 'source-locator-badge',
+    tooltip: 'source-locator-tooltip',
+    highlight: 'source-locator-highlight',
+};
+const LAYOUT = {
+    badge: {
+        position: 'fixed',
+        bottom: '12px',
+        right: '12px',
+        padding: '8px 12px',
+        borderRadius: '999px',
+        fontSize: '11px',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+        zIndex: '99999',
+        cursor: 'pointer',
+        boxShadow: '0 4px 16px rgba(0, 0, 0, 0.35)',
+    },
+    tooltip: {
+        position: 'fixed',
+        padding: '8px 12px',
+        borderRadius: '8px',
+        fontSize: '12px',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+        zIndex: '99999',
+        pointerEvents: 'none',
+        boxShadow: '0 8px 24px rgba(0, 0, 0, 0.45)',
+        maxWidth: '420px',
+        whiteSpace: 'pre',
+        lineHeight: '1.5',
+    },
+    highlight: {
+        position: 'fixed',
+        borderWidth: '2px',
+        borderStyle: 'solid',
+        borderRadius: '4px',
+        pointerEvents: 'none',
+        zIndex: '99998',
+    },
+};
+function formatSourceLabel(source, prefix) {
+    const { file, line } = parseSourceLocation(source);
+    const name = file.split('/').pop() ?? file;
+    const label = line !== '1' ? `${name}:${line}` : name;
+    if (prefix)
+        return `${prefix}: ${label}`;
+    return label;
+}
+function buildTooltipText(tsxSource, cssSource, clickTarget) {
+    const lines = [];
+    if (tsxSource)
+        lines.push(formatSourceLabel(tsxSource, 'TSX'));
+    if (cssSource)
+        lines.push(formatSourceLabel(cssSource, 'CSS'));
+    if (!cssSource) {
+        lines.push('Click → open TSX');
+        return lines.join('\n');
+    }
+    if (clickTarget === 'tsx') {
+        lines.push('Click → open TSX');
+        lines.push('Click again → open CSS');
+        return lines.join('\n');
+    }
+    lines.push('Click → open CSS');
+    lines.push('Click again → open TSX');
+    return lines.join('\n');
+}
+export function createLocatorOverlayUi(root, onTogglePick, theme) {
+    let activeEl = null;
+    let flashTimeout = null;
+    let badgeEl = null;
+    const removeHighlight = () => root.getElementById(UI_IDS.highlight)?.remove();
+    const removeTooltip = () => {
+        root.getElementById(UI_IDS.tooltip)?.remove();
+        activeEl = null;
+        removeHighlight();
+    };
+    const showHighlight = (el) => {
+        removeHighlight();
+        const rect = el.getBoundingClientRect();
+        const highlight = document.createElement('div');
+        highlight.id = UI_IDS.highlight;
+        Object.assign(highlight.style, LAYOUT.highlight, {
+            top: `${rect.top - 2}px`,
+            left: `${rect.left - 2}px`,
+            width: `${rect.width + 4}px`,
+            height: `${rect.height + 4}px`,
+            borderColor: theme.highlightBorder,
+            background: theme.highlightBackground,
+            boxShadow: `0 0 0 1px ${theme.highlightShadow}`,
+        });
+        root.appendChild(highlight);
+    };
+    const showTooltip = (text, el, x, y) => {
+        removeTooltip();
+        const tooltip = document.createElement('div');
+        tooltip.id = UI_IDS.tooltip;
+        tooltip.textContent = text;
+        Object.assign(tooltip.style, LAYOUT.tooltip, {
+            top: `${y + 16}px`,
+            left: `${x + 16}px`,
+            background: theme.tooltipBackground,
+            color: theme.tooltipText,
+            border: `1px solid ${theme.tooltipBorder}`,
+        });
+        root.appendChild(tooltip);
+        activeEl = el;
+        if (el)
+            showHighlight(el);
+    };
+    const showSourceTooltip = (el, tsxSource, cssSource, clickTarget, x, y) => {
+        showTooltip(buildTooltipText(tsxSource, cssSource, clickTarget), el, x, y);
+    };
+    const flashMessage = (text) => {
+        if (flashTimeout)
+            clearTimeout(flashTimeout);
+        showTooltip(text, null, window.innerWidth / 2 - 80, window.innerHeight - 80);
+        flashTimeout = setTimeout(removeTooltip, 1500);
+    };
+    const applyBadgeColors = (active) => {
+        if (!badgeEl)
+            return;
+        badgeEl.style.background = active ? theme.badgeActiveBackground : theme.badgeBackground;
+        badgeEl.style.color = active ? theme.badgeActiveText : theme.badgeText;
+    };
+    const setPickActive = (active) => {
+        document.body.style.cursor = active ? 'crosshair' : '';
+        if (!badgeEl)
+            return;
+        badgeEl.textContent = badgeLabel(active);
+        applyBadgeColors(active);
+        if (!active)
+            removeTooltip();
+    };
+    const refreshBadgeLabel = () => {
+        if (badgeEl)
+            badgeEl.textContent = badgeLabel(false);
+    };
+    const mountBadge = () => {
+        badgeEl = document.createElement('button');
+        badgeEl.id = UI_IDS.badge;
+        badgeEl.type = 'button';
+        badgeEl.textContent = badgeLabel(false);
+        Object.assign(badgeEl.style, LAYOUT.badge, {
+            background: theme.badgeBackground,
+            color: theme.badgeText,
+            border: `1px solid ${theme.badgeBorder}`,
+        });
+        badgeEl.addEventListener('click', (event) => {
+            event.stopPropagation();
+            onTogglePick();
+        });
+        root.appendChild(badgeEl);
+    };
+    return {
+        mountBadge,
+        setPickActive,
+        refreshBadgeLabel,
+        showSourceTooltip,
+        flashMessage,
+        removeTooltip,
+        getActiveEl: () => activeEl,
+    };
+}

package/dist/client/preference.d.ts

@@ -0,0 +1,5 @@
+import type { LocatorIde } from '../shared/index.js';
+export declare function getStoredIde(): LocatorIde;
+export declare function setStoredIde(ide: LocatorIde): void;
+export declare function cycleStoredIde(order: LocatorIde[]): LocatorIde;
+export declare function badgeLabel(picking: boolean): string;

package/dist/client/preference.js

@@ -0,0 +1,19 @@
+import { DEFAULT_IDE, STORAGE_KEY, isLocatorIde, nextIde } from '../shared/index.js';
+export function getStoredIde() {
+    const stored = localStorage.getItem(STORAGE_KEY) ?? DEFAULT_IDE;
+    return isLocatorIde(stored) ? stored : DEFAULT_IDE;
+}
+export function setStoredIde(ide) {
+    localStorage.setItem(STORAGE_KEY, ide);
+}
+export function cycleStoredIde(order) {
+    const next = nextIde(getStoredIde(), order);
+    setStoredIde(next);
+    return next;
+}
+export function badgeLabel(picking) {
+    const ide = getStoredIde();
+    if (picking)
+        return `Pick element (${ide}) — Esc to cancel`;
+    return `Source Locator (${ide}) — click to pick`;
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,19 @@
+export type { LocatorTheme, LocatorThemeInput, LocatorThemeOverride, LocatorThemePreset, } from './theme.js';
+export { resolveTheme } from './theme.js';
+export type LocatorIde = 'cursor' | 'vscode' | 'webstorm';
+export type SourceLocation = {
+    file: string;
+    line: string;
+    col: string;
+};
+export type ClickTarget = 'tsx' | 'css';
+export declare const SOURCE_ATTR = "data-source";
+export declare const OPEN_ENDPOINT = "/__open-in-editor";
+export declare const STORAGE_KEY = "locator-ide";
+export declare const DEFAULT_IDE: LocatorIde;
+export declare const IDE_ORDER: LocatorIde[];
+export declare function isLocatorIde(value: string): value is LocatorIde;
+export declare function nextIde(current: LocatorIde, order?: LocatorIde[]): LocatorIde;
+export declare function parseSourceLocation(raw: string): SourceLocation;
+export declare function formatSourceLocation(loc: SourceLocation): string;
+export declare function nextClickTarget(current: ClickTarget, hasCss: boolean): ClickTarget;

package/dist/shared/index.js

@@ -0,0 +1,29 @@
+export { resolveTheme } from './theme.js';
+export const SOURCE_ATTR = 'data-source';
+export const OPEN_ENDPOINT = '/__open-in-editor';
+export const STORAGE_KEY = 'locator-ide';
+export const DEFAULT_IDE = 'cursor';
+export const IDE_ORDER = ['cursor', 'vscode', 'webstorm'];
+export function isLocatorIde(value) {
+    return IDE_ORDER.includes(value);
+}
+export function nextIde(current, order = IDE_ORDER) {
+    const index = order.indexOf(current);
+    const nextIndex = (index + 1) % order.length;
+    return order[nextIndex] ?? DEFAULT_IDE;
+}
+export function parseSourceLocation(raw) {
+    const parts = raw.split(':');
+    const col = parts.pop();
+    const line = parts.pop();
+    const file = parts.join(':');
+    return { file, line, col };
+}
+export function formatSourceLocation(loc) {
+    return `${loc.file}:${loc.line}:${loc.col}`;
+}
+export function nextClickTarget(current, hasCss) {
+    if (!hasCss)
+        return 'tsx';
+    return current === 'tsx' ? 'css' : 'tsx';
+}

package/dist/shared/theme.d.ts

@@ -0,0 +1,21 @@
+export type LocatorThemePreset = 'default' | 'light' | 'dark' | 'blue';
+export type LocatorThemeOverride = {
+    background?: string;
+    text?: string;
+    accent?: string;
+};
+export type LocatorThemeInput = LocatorThemePreset | LocatorThemeOverride;
+export type LocatorTheme = {
+    badgeBackground: string;
+    badgeText: string;
+    badgeActiveBackground: string;
+    badgeActiveText: string;
+    badgeBorder: string;
+    tooltipBackground: string;
+    tooltipText: string;
+    tooltipBorder: string;
+    highlightBorder: string;
+    highlightBackground: string;
+    highlightShadow: string;
+};
+export declare function resolveTheme(input?: LocatorThemeInput): LocatorTheme;

package/dist/shared/theme.js

@@ -0,0 +1,42 @@
+const PRESET_COLORS = {
+    default: { background: '#0f172a', text: '#f8fafc', accent: '#38bdf8' },
+    light: { background: '#ffffff', text: '#0f172a', accent: '#2563eb' },
+    dark: { background: '#000000', text: '#ffffff', accent: '#a3a3a3' },
+    blue: { background: '#1e3a8a', text: '#eff6ff', accent: '#60a5fa' },
+};
+function withAlpha(hex, alpha) {
+    if (!hex.startsWith('#') || hex.length !== 7)
+        return hex;
+    const channel = Math.round(alpha * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `${hex}${channel}`;
+}
+function buildTheme(colors) {
+    const { background, text, accent } = colors;
+    return {
+        badgeBackground: background,
+        badgeText: accent,
+        badgeActiveBackground: accent,
+        badgeActiveText: background,
+        badgeBorder: accent,
+        tooltipBackground: background,
+        tooltipText: text,
+        tooltipBorder: accent,
+        highlightBorder: accent,
+        highlightBackground: withAlpha(accent, 0.12),
+        highlightShadow: withAlpha(background, 0.8),
+    };
+}
+function isThemePreset(value) {
+    return typeof value === 'string';
+}
+export function resolveTheme(input) {
+    if (!input)
+        return buildTheme(PRESET_COLORS.default);
+    if (isThemePreset(input)) {
+        const preset = PRESET_COLORS[input] ?? PRESET_COLORS.default;
+        return buildTheme(preset);
+    }
+    return buildTheme({ ...PRESET_COLORS.default, ...input });
+}

package/dist/vite/babel-plugin.d.ts

@@ -0,0 +1,18 @@
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+type BabelOptions = {
+    attribute: string;
+};
+export declare function babelPluginAddSourceAttr(_: unknown, opts: BabelOptions): {
+    name: string;
+    visitor: {
+        JSXOpeningElement(path: NodePath<t.JSXOpeningElement>, state: {
+            file: {
+                opts: {
+                    filename?: string;
+                };
+            };
+        }): void;
+    };
+};
+export {};

package/dist/vite/babel-plugin.js

@@ -0,0 +1,25 @@
+import * as t from '@babel/types';
+function hasSourceAttr(attributes, attribute) {
+    return attributes.some((attr) => t.isJSXAttribute(attr) && attr.name.name === attribute);
+}
+function createSourceAttr(attribute, value) {
+    return t.jsxAttribute(t.jsxIdentifier(attribute), t.stringLiteral(value));
+}
+export function babelPluginAddSourceAttr(_, opts) {
+    const attribute = opts.attribute;
+    return {
+        name: 'add-source-attr',
+        visitor: {
+            JSXOpeningElement(path, state) {
+                const loc = path.node.loc;
+                const filename = state.file.opts.filename;
+                if (!loc || !filename)
+                    return;
+                if (hasSourceAttr(path.node.attributes, attribute))
+                    return;
+                const value = `${filename}:${loc.start.line}:${loc.start.column + 1}`;
+                path.node.attributes.push(createSourceAttr(attribute, value));
+            },
+        },
+    };
+}

package/dist/vite/editors.d.ts

@@ -0,0 +1,2 @@
+import type { SourceLocation } from '../shared/index.js';
+export declare function openInEditor(loc: SourceLocation, ideParam: string): void;

package/dist/vite/editors.js

@@ -0,0 +1,64 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { DEFAULT_IDE, isLocatorIde } from '../shared/index.js';
+function createVscodeForkEditor(id, cliCandidates) {
+    return {
+        id,
+        cliCandidates,
+        openWithCli(cli, loc) {
+            execFileSync(cli, ['-r', '-g', `${loc.file}:${loc.line}:${loc.col}`], { stdio: 'ignore' });
+        },
+        openWithUrl(loc) {
+            execFileSync('open', [`${id}://file/${loc.file}:${loc.line}:${loc.col}`], { stdio: 'ignore' });
+        },
+    };
+}
+const EDITORS = [
+    createVscodeForkEditor('cursor', [
+        '/Applications/Cursor.app/Contents/Resources/app/bin/cursor',
+        'cursor',
+    ]),
+    createVscodeForkEditor('vscode', [
+        '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+        'code',
+    ]),
+    {
+        id: 'webstorm',
+        cliCandidates: ['/Applications/WebStorm.app/Contents/MacOS/webstorm', 'webstorm'],
+        openWithCli(cli, loc) {
+            execFileSync(cli, ['--line', loc.line, loc.file], { stdio: 'ignore' });
+        },
+        openWithUrl(loc) {
+            const uri = `webstorm://open?file=${encodeURIComponent(loc.file)}&line=${loc.line}`;
+            execFileSync('open', [uri], { stdio: 'ignore' });
+        },
+    },
+];
+function canRun(command) {
+    try {
+        execFileSync('which', [command], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveCli(candidates) {
+    const appPath = candidates.find((path) => path.includes('/') && existsSync(path));
+    if (appPath)
+        return appPath;
+    return candidates.filter((path) => !path.includes('/')).find((path) => canRun(path)) ?? null;
+}
+function findEditor(ide) {
+    return EDITORS.find((entry) => entry.id === ide) ?? EDITORS[0];
+}
+export function openInEditor(loc, ideParam) {
+    const ide = isLocatorIde(ideParam) ? ideParam : DEFAULT_IDE;
+    const editor = findEditor(ide);
+    const cli = resolveCli(editor.cliCandidates);
+    if (cli) {
+        editor.openWithCli(cli, loc);
+        return;
+    }
+    editor.openWithUrl(loc);
+}

package/dist/vite/index.d.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from 'vite';
+import type { LocatorIde, LocatorThemeInput } from '../shared/index.js';
+import { babelPluginAddSourceAttr } from './babel-plugin.js';
+export type SourceLocatorOptions = {
+    enabled?: boolean;
+    endpoint?: string;
+    attribute?: string;
+    ides?: LocatorIde[];
+    theme?: LocatorThemeInput;
+};
+declare function sourceLocator(options?: SourceLocatorOptions): Plugin;
+declare namespace sourceLocator {
+    var babel: (options?: SourceLocatorOptions) => {
+        babel: {
+            plugins: (typeof babelPluginAddSourceAttr | {
+                attribute: string;
+            })[][];
+        };
+    };
+}
+export { sourceLocator };

package/dist/vite/index.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_IDE, IDE_ORDER, OPEN_ENDPOINT, SOURCE_ATTR } from '../shared/index.js';
+import { babelPluginAddSourceAttr } from './babel-plugin.js';
+import { openInEditor } from './editors.js';
+const VIRTUAL_CLIENT_ID = 'virtual:source-locator-client';
+const RESOLVED_VIRTUAL_CLIENT_ID = '\0virtual:source-locator-client';
+const CLIENT_ENTRY = fileURLToPath(new URL('../client/index.js', import.meta.url));
+function resolveOptions(options = {}) {
+    return {
+        enabled: options.enabled ?? true,
+        endpoint: options.endpoint ?? OPEN_ENDPOINT,
+        attribute: options.attribute ?? SOURCE_ATTR,
+        ides: options.ides ?? IDE_ORDER,
+        theme: options.theme,
+    };
+}
+function readQuery(url) {
+    const parsed = new URL(url, 'http://localhost');
+    return {
+        file: parsed.searchParams.get('file'),
+        line: parsed.searchParams.get('line') ?? '1',
+        col: parsed.searchParams.get('col') ?? '1',
+        ide: parsed.searchParams.get('ide') ?? DEFAULT_IDE,
+    };
+}
+function resolveFilePath(file, root) {
+    if (file.startsWith('/src/'))
+        return resolve(root, file.slice(1));
+    if (isAbsolute(file))
+        return file;
+    return resolve(root, file);
+}
+function sourceLocator(options = {}) {
+    const config = resolveOptions(options);
+    const clientConfig = {
+        endpoint: config.endpoint,
+        attribute: config.attribute,
+        ides: config.ides,
+        theme: config.theme,
+    };
+    return {
+        name: 'source-locator',
+        apply: 'serve',
+        resolveId(id) {
+            if (id === VIRTUAL_CLIENT_ID)
+                return RESOLVED_VIRTUAL_CLIENT_ID;
+            return undefined;
+        },
+        load(id) {
+            if (id !== RESOLVED_VIRTUAL_CLIENT_ID)
+                return undefined;
+            return `import ${JSON.stringify(CLIENT_ENTRY)}`;
+        },
+        configureServer(server) {
+            server.middlewares.use(config.endpoint, (req, res) => {
+                const { file, line, col, ide } = readQuery(req.url ?? '');
+                if (!file) {
+                    res.writeHead(400);
+                    res.end('missing file');
+                    return;
+                }
+                try {
+                    const resolvedFile = resolveFilePath(file, server.config.root);
+                    if (!existsSync(resolvedFile)) {
+                        res.writeHead(404);
+                        res.end('file not found');
+                        return;
+                    }
+                    openInEditor({ file: resolvedFile, line, col }, ide);
+                    res.writeHead(200, { 'Content-Type': 'text/plain' });
+                    res.end('ok');
+                }
+                catch {
+                    res.writeHead(500);
+                    res.end('failed to open editor');
+                }
+            });
+        },
+        transformIndexHtml() {
+            if (!config.enabled)
+                return;
+            return {
+                html: '',
+                tags: [
+                    {
+                        tag: 'script',
+                        children: `window.__SOURCE_LOCATOR_CONFIG__=${JSON.stringify(clientConfig)}`,
+                        injectTo: 'head',
+                    },
+                    {
+                        tag: 'script',
+                        attrs: { type: 'module', src: `/@id/${VIRTUAL_CLIENT_ID}` },
+                        injectTo: 'body',
+                    },
+                ],
+            };
+        },
+    };
+}
+sourceLocator.babel = (options = {}) => {
+    const attribute = options.attribute ?? SOURCE_ATTR;
+    return { babel: { plugins: [[babelPluginAddSourceAttr, { attribute }]] } };
+};
+export { sourceLocator };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "vite-plugin-source-locator",
+  "version": "1.0.0",
+  "description": "Dev-only Vite plugin: click UI elements to jump to source in your IDE",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "default": "./dist/shared/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0"
+  },
+  "dependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/traverse": "^7.29.7",
+    "@babel/types": "^7.29.7"
+  },
+  "devDependencies": {
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__traverse": "^7.20.7",
+    "@types/node": "^20.12.12",
+    "happy-dom": "^15.11.7",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11",
+    "vitest": "^2.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amir1824/UI-Locator.git"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "source-locator",
+    "devtools",
+    "cursor",
+    "vscode"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}