@blqke/vgentation 0.1.0

package/dist/nuxt/module.d.ts

@@ -0,0 +1,9 @@
+export interface ModuleOptions {
+    /**
+     * Auto-import CSS styles.
+     * @default true
+     */
+    css?: boolean;
+}
+declare const _default: NuxtModule<TOptions, TOptions, false>;
+export default _default;

package/dist/nuxt.cjs

@@ -0,0 +1,47 @@
+"use strict";
+const kit = require("@nuxt/kit");
+const module$1 = kit.defineNuxtModule({
+  meta: {
+    name: "vgentation",
+    configKey: "vgentation",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    css: true
+  },
+  setup(options, nuxt) {
+    if (options.css) {
+      nuxt.options.css.push("vgentation/style.css");
+    }
+    kit.addImports({
+      name: "useVgentation",
+      from: "vgentation"
+    });
+    kit.addComponent({
+      name: "Vgentation",
+      filePath: "vgentation",
+      export: "Vgentation",
+      mode: "client"
+    });
+    kit.addTemplate({
+      filename: "vgentation-plugin.client.ts",
+      write: true,
+      getContents: () => `
+import { defineNuxtPlugin } from '#app'
+import { VgentationKey, createVgentationContext } from 'vgentation'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const context = createVgentationContext()
+  nuxtApp.vueApp.provide(VgentationKey, context)
+})
+`
+    });
+    kit.addPlugin({
+      src: "#build/vgentation-plugin.client",
+      mode: "client"
+    });
+  }
+});
+module.exports = module$1;

package/dist/nuxt.d.ts

@@ -0,0 +1,4 @@
+export {}
+import Vgentation from './nuxt/module'
+export default Vgentation
+export {}

package/dist/nuxt.mjs

@@ -0,0 +1,48 @@
+import { defineNuxtModule, addImports, addComponent, addTemplate, addPlugin } from "@nuxt/kit";
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "vgentation",
+    configKey: "vgentation",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    css: true
+  },
+  setup(options, nuxt) {
+    if (options.css) {
+      nuxt.options.css.push("vgentation/style.css");
+    }
+    addImports({
+      name: "useVgentation",
+      from: "vgentation"
+    });
+    addComponent({
+      name: "Vgentation",
+      filePath: "vgentation",
+      export: "Vgentation",
+      mode: "client"
+    });
+    addTemplate({
+      filename: "vgentation-plugin.client.ts",
+      write: true,
+      getContents: () => `
+import { defineNuxtPlugin } from '#app'
+import { VgentationKey, createVgentationContext } from 'vgentation'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const context = createVgentationContext()
+  nuxtApp.vueApp.provide(VgentationKey, context)
+})
+`
+    });
+    addPlugin({
+      src: "#build/vgentation-plugin.client",
+      mode: "client"
+    });
+  }
+});
+export {
+  module$1 as default
+};

package/dist/playground/App.vue.d.ts

@@ -0,0 +1,3 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+declare const _default: DefineComponent<{}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, HTMLDivElement>;
+export default _default;

package/dist/playground/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin.d.ts

@@ -0,0 +1,37 @@
+import { Plugin } from 'vue';
+export interface VgentationPluginOptions {
+    /**
+     * Register the Vgentation component globally.
+     * @default true
+     */
+    registerComponent?: boolean;
+}
+/**
+ * Vue plugin for Vgentation.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { VgentationPlugin } from 'vgentation'
+ * import 'vgentation/style.css'
+ *
+ * const app = createApp(App)
+ * app.use(VgentationPlugin)
+ * app.mount('#app')
+ * ```
+ *
+ * Then use anywhere:
+ * ```vue
+ * <template>
+ *   <Vgentation />
+ *   <button @click="toggle">Toggle</button>
+ * </template>
+ *
+ * <script setup>
+ * import { useVgentation } from 'vgentation'
+ * const { toggle } = useVgentation()
+ * </script>
+ * ```
+ */
+export declare const VgentationPlugin: Plugin<VgentationPluginOptions>;
+export default VgentationPlugin;

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Source location for "Open in Editor" feature
+ */
+export interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Component tree node with optional file path and type indicators
+ */
+export interface ComponentTreeNode {
+    name: string;
+    filePath?: string;
+    isPage?: boolean;
+    isLayout?: boolean;
+}
+export type Annotation = {
+    id: string;
+    x: number;
+    y: number;
+    comment: string;
+    element: string;
+    elementPath: string;
+    timestamp: number;
+    selectedText?: string;
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    nearbyText?: string;
+    cssClasses?: string;
+    nearbyElements?: string;
+    computedStyles?: string;
+    fullPath?: string;
+    accessibility?: string;
+    isMultiSelect?: boolean;
+    isFixed?: boolean;
+    vueComponent?: string;
+    vueComponentPath?: string;
+    vueProps?: Record<string, unknown>;
+    vueComponentTree?: ComponentTreeNode[];
+    vueSourceLocation?: SourceLocation;
+    vueComponentFile?: string;
+    nuxtRoute?: string;
+    nuxtRouteName?: string;
+    nuxtPage?: string;
+    nuxtLayout?: string;
+    nuxtPageFile?: string;
+    nuxtLayoutFile?: string;
+    devToolsEnhanced?: boolean;
+};

package/dist/utils/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Configuration Module for Annotation Picker
+ *
+ * Manages user preferences for:
+ * - Editor integration (VS Code, WebStorm, etc.)
+ * - Component tree display limits
+ * - Hover tooltip display modes
+ * - Output field toggles
+ */
+export type HoverDisplayMode = 'path' | 'file' | 'both';
+/**
+ * Output field toggles - controls which fields are included in copied output
+ */
+export interface OutputFieldsConfig {
+    location: boolean;
+    selectedText: boolean;
+    componentName: boolean;
+    componentFile: boolean;
+    componentTree: boolean;
+    props: boolean;
+    routePath: boolean;
+    routeName: boolean;
+    pageName: boolean;
+    layoutName: boolean;
+    cssClasses: boolean;
+    position: boolean;
+    context: boolean;
+    fullDomPath: boolean;
+    computedStyles: boolean;
+    accessibility: boolean;
+    nearbyElements: boolean;
+}
+export type OutputPreset = 'minimal' | 'standard' | 'full' | 'custom';
+export interface PickerConfig {
+    /**
+     * Editor protocol for "Open in Editor" feature
+     * @default 'vscode'
+     */
+    editorProtocol: string;
+    /**
+     * Maximum number of components to show in tree before "show more"
+     * @default 5
+     */
+    componentTreeLimit: number;
+    /**
+     * How to display component info in hover tooltip
+     * - 'path': Show component ancestry (App > Layout > Component)
+     * - 'file': Show component name + file (Component.vue:42)
+     * - 'both': Show both path and file info
+     * @default 'both'
+     */
+    hoverDisplayMode: HoverDisplayMode;
+    /**
+     * Output field toggles - controls which fields appear in copied output
+     */
+    outputFields: OutputFieldsConfig;
+}
+export declare const OUTPUT_PRESETS: Record<Exclude<OutputPreset, 'custom'>, OutputFieldsConfig>;
+export declare const DEFAULT_OUTPUT_FIELDS: OutputFieldsConfig;
+export declare const DEFAULT_CONFIG: PickerConfig;
+/**
+ * Load configuration from localStorage, merging with defaults
+ */
+export declare function loadConfig(): PickerConfig;
+/**
+ * Save configuration to localStorage
+ */
+export declare function saveConfig(config: Partial<PickerConfig>): void;
+/**
+ * Reset configuration to defaults
+ */
+export declare function resetConfig(): void;
+/**
+ * Get available editor options for UI dropdown
+ */
+export declare function getEditorOptions(): Array<{
+    value: string;
+    label: string;
+}>;
+export declare const HOVER_DISPLAY_OPTIONS: Array<{
+    value: HoverDisplayMode;
+    label: string;
+}>;
+/**
+ * Get available hover display mode options for UI dropdown
+ */
+export declare function getHoverDisplayOptions(): Array<{
+    value: HoverDisplayMode;
+    label: string;
+}>;
+/**
+ * Detect which preset matches the current config (or 'custom' if none match)
+ */
+export declare function detectPreset(config: OutputFieldsConfig): OutputPreset;
+/**
+ * Get the output fields config for a preset
+ */
+export declare function getPresetConfig(preset: Exclude<OutputPreset, 'custom'>): OutputFieldsConfig;

package/dist/utils/devtools-integration.d.ts

@@ -0,0 +1,190 @@
+/**
+ * DevTools Integration Module
+ *
+ * Provides integration with Vue DevTools and Nuxt DevTools global hooks
+ * for enhanced component detection and "Open in Editor" functionality.
+ *
+ * All features are optional - gracefully falls back when DevTools not available.
+ */
+declare global {
+    interface Window {
+        /**
+         * Vue DevTools Global Hook
+         * Available when Vue DevTools browser extension is installed
+         */
+        __VUE_DEVTOOLS_GLOBAL_HOOK__?: {
+            apps: Map<number, {
+                app: VueAppRecord;
+                version: string;
+            }>;
+            on(event: string, fn: (...args: unknown[]) => void): void;
+            off(event: string, fn: (...args: unknown[]) => void): void;
+            emit(event: string, ...args: unknown[]): void;
+        };
+        /**
+         * Vue Inspector
+         * Available when vite-plugin-vue-inspector or similar is installed
+         */
+        __VUE_INSPECTOR__?: {
+            enabled: boolean;
+            linkParams: {
+                file: string;
+                line: number;
+                column: number;
+            };
+            openInEditor(baseUrl: string, file: string, line: number, column: number): void;
+            enable(): void;
+            disable(): void;
+        };
+        /**
+         * Nuxt DevTools Host Client
+         * Available when @nuxt/devtools is installed and running
+         */
+        __NUXT_DEVTOOLS_HOST__?: {
+            nuxt: NuxtAppInstance;
+            devtools: {
+                open(): void;
+                close(): void;
+                toggle(): void;
+                navigate(path: string): void;
+            };
+            app: {
+                reload(): void;
+                navigate(path: string, hard?: boolean): void;
+            };
+        };
+    }
+}
+interface VueAppRecord {
+    _component?: {
+        name?: string;
+    };
+    _instance?: VueComponentInstanceInternal;
+}
+interface VueComponentInstanceInternal {
+    type?: {
+        name?: string;
+        displayName?: string;
+        __name?: string;
+        __file?: string;
+        __hmrId?: string;
+        _componentTag?: string;
+        __VUE_DEVTOOLS_COMPONENT_GUSSED_NAME__?: string;
+        components?: Record<string, unknown>;
+    };
+    parent?: VueComponentInstanceInternal;
+    appContext?: {
+        components?: Record<string, unknown>;
+        app?: {
+            __VUE_DEVTOOLS_NEXT_APP_RECORD_ID__?: number;
+        };
+    };
+    root?: VueComponentInstanceInternal;
+    uid?: number;
+}
+interface NuxtAppInstance {
+    $route?: {
+        path: string;
+        name?: string;
+        fullPath: string;
+        meta?: Record<string, unknown>;
+        matched?: Array<{
+            path: string;
+            name?: string;
+            components?: Record<string, {
+                __file?: string;
+            }>;
+        }>;
+        params?: Record<string, string>;
+        query?: Record<string, string>;
+    };
+    $router?: {
+        currentRoute: {
+            value: NuxtAppInstance['$route'];
+        };
+    };
+    _route?: NuxtAppInstance['$route'];
+}
+export interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface DevToolsStatus {
+    vueDevTools: boolean;
+    vueInspector: boolean;
+    nuxtDevTools: boolean;
+}
+export declare const EDITOR_PROTOCOLS: Record<string, string>;
+export declare const EDITOR_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/**
+ * Check if Vue DevTools global hook is available
+ */
+export declare function isVueDevToolsAvailable(): boolean;
+/**
+ * Check if Vue Inspector (vite-plugin-vue-inspector) is available
+ */
+export declare function isVueInspectorAvailable(): boolean;
+/**
+ * Check if Nuxt DevTools host client is available
+ */
+export declare function isNuxtDevToolsAvailable(): boolean;
+/**
+ * Get combined DevTools availability status
+ */
+export declare function getDevToolsStatus(): DevToolsStatus;
+/**
+ * Get component name using DevTools-style resolution with multiple fallbacks.
+ * This mirrors the logic used by Vue DevTools for consistent naming.
+ *
+ * Resolution order:
+ * 1. displayName
+ * 2. name
+ * 3. __name (SFC compiler)
+ * 4. __VUE_DEVTOOLS_COMPONENT_GUSSED_NAME__ (cached guess)
+ * 5. _componentTag
+ * 6. Filename from __file
+ * 7. Parent component lookup
+ * 8. 'Anonymous'
+ */
+export declare function getInstanceNameEnhanced(instance: unknown): string;
+/**
+ * Extract source location from a Vue component instance
+ */
+export declare function getSourceLocationFromInstance(instance: unknown): SourceLocation | null;
+/**
+ * Get current source location from Vue Inspector if available and enabled
+ */
+export declare function getInspectorSourceLocation(): SourceLocation | null;
+/**
+ * Build editor URL from protocol pattern and source location
+ */
+export declare function buildEditorUrl(protocol: string, loc: SourceLocation): string;
+/**
+ * Open a file in the configured editor
+ */
+export declare function openInEditor(loc: SourceLocation, protocol?: string): void;
+/**
+ * Get Nuxt app instance from DevTools host client
+ */
+export declare function getNuxtAppFromDevTools(): NuxtAppInstance | null;
+/**
+ * Get current route from Nuxt DevTools
+ */
+export declare function getRouteFromNuxtDevTools(): NuxtAppInstance['$route'] | null;
+/**
+ * Get page file path from matched route
+ */
+export declare function getPageFileFromRoute(): string | null;
+/**
+ * Format a file path for display (show filename only)
+ */
+export declare function formatFilePath(fullPath: string): string;
+/**
+ * Format a file path showing last N segments
+ */
+export declare function formatFilePathWithContext(fullPath: string, segments?: number): string;
+export {};

package/dist/utils/element-identification.d.ts

@@ -0,0 +1,72 @@
+import { VueDetectionResult } from './vue-detection';
+import { NuxtDetectionResult } from './nuxt-detection';
+import { SourceLocation, ComponentTreeNode } from '../types';
+export interface FrameworkContext {
+    vue?: VueDetectionResult;
+    nuxt?: NuxtDetectionResult;
+}
+/**
+ * Detect Vue and Nuxt context for an element
+ */
+export declare function detectFrameworkContext(element: HTMLElement): FrameworkContext;
+/**
+ * Get annotation-ready framework context (flattened strings + enhanced data)
+ */
+export declare function getFrameworkAnnotationData(element: HTMLElement): {
+    vueComponent?: string;
+    vueComponentPath?: string;
+    vueProps?: Record<string, unknown>;
+    nuxtRoute?: string;
+    nuxtPage?: string;
+    nuxtLayout?: string;
+    vueComponentTree?: ComponentTreeNode[];
+    vueSourceLocation?: SourceLocation;
+    vueComponentFile?: string;
+    nuxtRouteName?: string;
+    nuxtPageFile?: string;
+    nuxtLayoutFile?: string;
+    devToolsEnhanced?: boolean;
+};
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+export declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name + path
+ */
+export declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+/**
+ * Gets text content from element and siblings for context
+ */
+export declare function getNearbyText(element: HTMLElement): string;
+/**
+ * Simplified element identifier for animation feedback (less verbose)
+ */
+export declare function identifyAnimationElement(target: HTMLElement): string;
+/**
+ * Gets nearby sibling elements for structural context
+ */
+export declare function getNearbyElements(element: HTMLElement): string;
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+export declare function getElementClasses(target: HTMLElement): string;
+/**
+ * Gets key computed styles for an element (useful for styling issues)
+ */
+export declare function getComputedStylesSnapshot(target: HTMLElement): string;
+/**
+ * Gets detailed computed styles for forensic-level debugging
+ */
+export declare function getDetailedComputedStyles(target: HTMLElement): Record<string, string>;
+/**
+ * Gets accessibility information for an element
+ */
+export declare function getAccessibilityInfo(target: HTMLElement): string;
+/**
+ * Gets full DOM ancestry path (for forensic mode)
+ */
+export declare function getFullElementPath(target: HTMLElement): string;

package/dist/utils/nuxt-detection.d.ts

@@ -0,0 +1,90 @@
+import { VueComponentInfo } from './vue-detection';
+/**
+ * Nuxt app instance interface (partial)
+ */
+interface NuxtApp {
+    vueApp?: {
+        _context?: {
+            components?: Record<string, unknown>;
+        };
+    };
+    $router?: {
+        currentRoute?: {
+            value?: RouteInfo;
+        };
+    };
+    _route?: RouteInfo;
+}
+interface RouteInfo {
+    path?: string;
+    name?: string | symbol;
+    fullPath?: string;
+    params?: Record<string, string | string[]>;
+    query?: Record<string, string | string[] | undefined>;
+    meta?: Record<string, unknown>;
+    matched?: Array<{
+        name?: string | symbol;
+        path?: string;
+        components?: Record<string, unknown>;
+    }>;
+}
+export interface NuxtRouteInfo {
+    path: string;
+    name?: string;
+    fullPath?: string;
+    params?: Record<string, string | string[]>;
+}
+export interface NuxtPageInfo {
+    name: string;
+    filePath?: string;
+}
+export interface NuxtDetectionResult {
+    isNuxt: boolean;
+    route?: NuxtRouteInfo;
+    page?: NuxtPageInfo;
+    layout?: string;
+    layoutFile?: string;
+    pageFile?: string;
+    devToolsEnhanced?: boolean;
+}
+/**
+ * Get the Nuxt app instance
+ */
+export declare function getNuxtApp(): NuxtApp | null;
+/**
+ * Check if we're in a Nuxt application
+ */
+export declare function isNuxtApp(): boolean;
+/**
+ * Get current route information
+ */
+export declare function getCurrentRoute(): NuxtRouteInfo | null;
+/**
+ * Get current page component info
+ */
+export declare function getCurrentPage(): NuxtPageInfo | null;
+/**
+ * Get current layout name
+ */
+export declare function getCurrentLayout(): string | null;
+/**
+ * Detect if a component is a Nuxt-specific component
+ */
+export declare function isNuxtComponent(componentName: string): boolean;
+/**
+ * Detect if a component is a layout component
+ */
+export declare function isLayoutComponent(component: VueComponentInfo): boolean;
+/**
+ * Detect if a component is a page component
+ */
+export declare function isPageComponent(component: VueComponentInfo): boolean;
+/**
+ * Main detection function - gets Nuxt context for an element
+ */
+export declare function detectNuxtContext(element: HTMLElement): NuxtDetectionResult;
+/**
+ * Format route for display
+ */
+export declare function formatRoute(route: NuxtRouteInfo): string;
+export {};

package/dist/utils/storage.d.ts

@@ -0,0 +1,5 @@
+import { Annotation } from '../types';
+export declare function getStorageKey(pathname: string): string;
+export declare function loadAnnotations<T = Annotation>(pathname: string): T[];
+export declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
+export declare function clearAnnotations(pathname: string): void;