agentation-vue3 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# agentation-vue3
+
+[中文](#中文) | [English](#english)
+
+---
+
+## 中文
+
+> **作者 [binyy](https://github.com/408460486)**，基于 [Benji Taylor](https://x.com/benjitaylor)、[Dennis Jin](https://x.com/seldom) 和 [Alex Vanderzon](https://x.com/alexvanderzon) 的 React 版本
+>
+> 原始 React 版本：[GitHub](https://github.com/benjitaylor/agentation) · [NPM](https://www.npmjs.com/package/agentation)
+
+Agentation 是一个与 AI 工具无关的 Vue 3 可视化反馈工具。点击页面上的元素，添加注释，然后复制结构化输出，帮助 AI 编程助手找到您所指的确切代码。
+
+### 安装
+
+```bash
+npm install agentation-vue3 -D
+```
+
+### 使用方法
+
+```vue
+<script setup>
+import { Agentation } from 'agentation-vue3'
+import 'agentation-vue3/dist/style.css'
+</script>
+
+<template>
+  <YourApp />
+  <Agentation />
+</template>
+```
+
+工具栏出现在右下角。点击激活，然后点击任意元素进行标注。
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `accentColor` | `string` | `'#3c82f7'` | 自定义强调色（十六进制） |
+| `copyToClipboard` | `boolean` | `true` | 点击复制按钮时是否复制到剪贴板 |
+| `lightMode` | `boolean` | `false` | 浅色模式样式 |
+| `zIndex` | `number` | `2147483647` | 工具栏的 z-index |
+
+### 功能特性
+
+- **点击标注** – 点击任意元素，自动识别选择器
+- **文本选择** – 选择文本以标注特定内容
+- **动画暂停** – 冻结 CSS 动画以捕获特定状态
+- **结构化输出** – 复制包含选择器、位置和上下文的 markdown
+- **深色/浅色模式** – 匹配您的偏好或手动设置
+- **可拖拽工具栏** – 将工具栏重新定位到屏幕任意位置
+- **键盘快捷键** – 按 ESC 关闭工具栏
+- **零依赖** – 纯 CSS 动画，无运行时库
+
+### 工作原理
+
+Agentation 捕获类名、选择器和元素位置，以便 AI 助手可以 `grep` 搜索您所指的确切代码。您不再需要描述"侧边栏中的蓝色按钮"，而是直接给 AI 助手提供 `.sidebar > button.primary` 和您的反馈。
+
+### 系统要求
+
+- Vue 3.3+
+- 桌面浏览器（不支持移动端）
+
+### 文档
+
+完整文档请访问 [agentation.dev](https://agentation.dev)
+
+---
+
+## English
+
+> **Made by [binyy](https://github.com/408460486)**, forked from [Benji Taylor](https://x.com/benjitaylor), [Dennis Jin](https://x.com/seldom), and [Alex Vanderzon](https://x.com/alexvanderzon)'s React version
+>
+> Original React Version: [GitHub](https://github.com/benjitaylor/agentation) · [NPM](https://www.npmjs.com/package/agentation)
+
+Agentation is an agent-agnostic visual feedback tool for Vue 3. Click elements on your page, add notes, and copy structured output that helps AI coding agents find the exact code you're referring to.
+
+### Install
+
+```bash
+npm install agentation-vue3 -D
+```
+
+### Usage
+
+```vue
+<script setup>
+import { Agentation } from 'agentation-vue3'
+import 'agentation-vue3/dist/style.css'
+</script>
+
+<template>
+  <YourApp />
+  <Agentation />
+</template>
+```
+
+The toolbar appears in the bottom-right corner. Click to activate, then click any element to annotate it.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `accentColor` | `string` | `'#3c82f7'` | Custom accent color (hex) |
+| `copyToClipboard` | `boolean` | `true` | Whether to copy to clipboard when the copy button is clicked |
+| `lightMode` | `boolean` | `false` | Light mode styling |
+| `zIndex` | `number` | `2147483647` | z-index for the toolbar |
+
+### Features
+
+- **Click to annotate** – Click any element with automatic selector identification
+- **Text selection** – Select text to annotate specific content
+- **Animation pause** – Freeze CSS animations to capture specific states
+- **Structured output** – Copy markdown with selectors, positions, and context
+- **Dark/light mode** – Matches your preference or set manually
+- **Draggable toolbar** – Reposition the toolbar anywhere on screen
+- **Keyboard shortcuts** – Press ESC to close the toolbar
+- **Zero dependencies** – Pure CSS animations, no runtime libraries
+
+### How it works
+
+Agentation captures class names, selectors, and element positions so AI agents can `grep` for the exact code you're referring to. Instead of describing "the blue button in the sidebar," you give the agent `.sidebar > button.primary` and your feedback.
+
+### Requirements
+
+- Vue 3.3+
+- Desktop browser (mobile not supported)
+
+### Docs
+
+Full documentation at [agentation.dev](https://agentation.dev)
+
+---
+
+## License
+
+© 2026 Binyy
+Licensed under PolyForm Shield 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { CSSProperties } from 'vue';
+import { DefineComponent } from 'vue';
+import { ExtractPropTypes } from 'vue';
+import { FunctionalComponent } from 'vue';
+import { PropType } from 'vue';
+import { PublicProps } from 'vue';
+
+declare type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+
+declare type __VLS_NonUndefinedable_2<T> = T extends undefined ? never : T;
+
+declare type __VLS_Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_Prettify_2<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+declare type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
+declare type __VLS_TypePropsToRuntimeProps_2<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable_2<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
+declare type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+
+declare type __VLS_WithDefaults_2<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_Prettify_2<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+
+export declare interface AgentationProps {
+    /** Custom accent color (hex) */
+    accentColor?: string;
+    /** Whether to copy to clipboard when the copy button is clicked */
+    copyToClipboard?: boolean;
+    /** Light mode styling */
+    lightMode?: boolean;
+    /** z-index for the toolbar */
+    zIndex?: number;
+    /** Demo annotations to show on page load */
+    demoAnnotations?: Array<{
+        selector: string;
+        comment: string;
+    }>;
+    /** Delay before showing demo annotations (ms) */
+    demoDelay?: number;
+    /** Enable demo mode */
+    enableDemoMode?: boolean;
+}
+
+export declare const AnimatedBunny: FunctionalComponent<IconPropsWithColor>;
+
+/**
+ * Annotation Type | 标注类型
+ *
+ * Represents a single annotation created by the user on a web page element.
+ * Contains all metadata needed to identify, locate, and describe the annotated element.
+ *
+ * 表示用户在网页元素上创建的单个标注。
+ * 包含识别、定位和描述被标注元素所需的所有元数据。
+ */
+export declare type Annotation = {
+    /** Unique identifier for the annotation | 标注的唯一标识符 */
+    id: string;
+    /** X position as percentage of viewport width | X 位置（视口宽度的百分比） */
+    x: number;
+    /**
+     * Y position in pixels from top of document (absolute positioning)
+     * OR from viewport top (if isFixed is true)
+     * Y 位置（从文档顶部的像素值，或如果 isFixed 为 true 则从视口顶部）
+     */
+    y: number;
+    /** User's comment/feedback text | 用户的评论/反馈文本 */
+    comment: string;
+    /** Human-readable element name (e.g., "button 'Submit'") | 人类可读的元素名称 */
+    element: string;
+    /** CSS selector path to the element (e.g., ".form > button.primary") | 元素的 CSS 选择器路径 */
+    elementPath: string;
+    /** Unix timestamp when annotation was created | 创建标注时的 Unix 时间戳 */
+    timestamp: number;
+    /** Selected text content if user selected text | 用户选中的文本内容（如果有） */
+    selectedText?: string;
+    /**
+     * Element's bounding box coordinates and dimensions
+     * 元素的边界框坐标和尺寸
+     */
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Text content from element and nearby siblings | 元素及其相邻兄弟元素的文本内容 */
+    nearbyText?: string;
+    /** CSS class names (cleaned of module hashes) | CSS 类名（已清理模块哈希） */
+    cssClasses?: string;
+    /** Identifiers of nearby sibling elements | 相邻兄弟元素的标识符 */
+    nearbyElements?: string;
+    /** Computed CSS styles snapshot | 计算后的 CSS 样式快照 */
+    computedStyles?: string;
+    /** Full DOM ancestry path (for forensic mode) | 完整的 DOM 祖先路径（用于取证模式） */
+    fullPath?: string;
+    /** Accessibility attributes (role, aria-label, etc.) | 无障碍属性 */
+    accessibility?: string;
+    /** True if created via drag selection (multi-select mode) | 是否通过拖拽选择创建 */
+    isMultiSelect?: boolean;
+    /** True if element has fixed/sticky positioning | 元素是否具有固定/粘性定位 */
+    isFixed?: boolean;
+};
+
+export declare const AnnotationPopup: DefineComponent<ExtractPropTypes<__VLS_WithDefaults_2<__VLS_TypePropsToRuntimeProps_2<AnnotationPopupProps>, {
+placeholder: string;
+initialValue: string;
+submitLabel: string;
+accentColor: string;
+isExiting: boolean;
+lightMode: boolean;
+}>>, {
+/** Shake the popup (e.g., when user clicks outside) */
+shake: () => void;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+submit: (text: string) => void;
+cancel: () => void;
+}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_WithDefaults_2<__VLS_TypePropsToRuntimeProps_2<AnnotationPopupProps>, {
+placeholder: string;
+initialValue: string;
+submitLabel: string;
+accentColor: string;
+isExiting: boolean;
+lightMode: boolean;
+}>>> & Readonly<{
+onSubmit?: ((text: string) => any) | undefined;
+onCancel?: (() => any) | undefined;
+}>, {
+placeholder: string;
+initialValue: string;
+submitLabel: string;
+accentColor: string;
+isExiting: boolean;
+lightMode: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
+export declare interface AnnotationPopupExpose {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+
+export declare interface AnnotationPopupProps {
+    /** Element name to display in header */
+    element: string;
+    /** Optional timestamp display (e.g., "@ 1.23s" for animation feedback) */
+    timestamp?: string;
+    /** Optional selected/highlighted text */
+    selectedText?: string;
+    /** Placeholder text for the textarea */
+    placeholder?: string;
+    /** Initial value for textarea (for edit mode) */
+    initialValue?: string;
+    /** Label for submit button (default: "Add") */
+    submitLabel?: string;
+    /** Position styles (left, top) */
+    popupStyle?: Record<string, string | number>;
+    /** Custom color for submit button and textarea focus (hex) */
+    accentColor?: string;
+    /** External exit state (parent controls exit animation) */
+    isExiting?: boolean;
+    /** Light mode styling */
+    lightMode?: boolean;
+    /** Computed styles for the selected element */
+    computedStyles?: Record<string, string>;
+}
+
+/**
+ * Clears all annotations for a given page from localStorage.
+ * 从 localStorage 清除指定页面的所有标注。
+ *
+ * @param pathname - The page pathname | 页面路径名
+ */
+export declare function clearAnnotations(pathname: string): void;
+
+declare const _default: DefineComponent<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<AgentationProps>, {
+accentColor: string;
+copyToClipboard: boolean;
+lightMode: boolean;
+zIndex: number;
+demoAnnotations: () => never[];
+demoDelay: number;
+enableDemoMode: boolean;
+}>>, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
+copy: (markdown: string) => void;
+annotationAdd: (annotation: Annotation) => void;
+annotationDelete: (annotation: Annotation) => void;
+annotationUpdate: (annotation: Annotation) => void;
+annotationsClear: (annotations: Annotation[]) => void;
+}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToRuntimeProps<AgentationProps>, {
+accentColor: string;
+copyToClipboard: boolean;
+lightMode: boolean;
+zIndex: number;
+demoAnnotations: () => never[];
+demoDelay: number;
+enableDemoMode: boolean;
+}>>> & Readonly<{
+onCopy?: ((markdown: string) => any) | undefined;
+onAnnotationAdd?: ((annotation: Annotation) => any) | undefined;
+onAnnotationDelete?: ((annotation: Annotation) => any) | undefined;
+onAnnotationUpdate?: ((annotation: Annotation) => any) | undefined;
+onAnnotationsClear?: ((annotations: Annotation[]) => any) | undefined;
+}>, {
+accentColor: string;
+lightMode: boolean;
+zIndex: number;
+copyToClipboard: boolean;
+demoAnnotations: Array<{
+selector: string;
+comment: string;
+}>;
+demoDelay: number;
+enableDemoMode: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export { _default as Agentation }
+export { _default as AgentationVue }
+
+/**
+ * Gets accessibility information for an element
+ */
+export declare function getAccessibilityInfo(target: HTMLElement): string;
+
+/**
+ * Gets key computed styles for an element (useful for styling issues)
+ */
+export declare function getComputedStylesSnapshot(target: HTMLElement): string;
+
+/**
+ * Gets key computed styles for the annotation popup display.
+ * Returns different properties based on element type to show the most relevant
+ * CSS properties for debugging (e.g., typography for text, layout for containers).
+ */
+export declare function getDetailedComputedStyles(target: HTMLElement): Record<string, string>;
+
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+export declare function getElementClasses(target: HTMLElement): string;
+
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+export declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+
+/**
+ * Gets full computed styles for forensic output.
+ * Returns a comprehensive semicolon-separated string of all relevant CSS properties
+ * for maximum debugging detail in the forensic output format.
+ */
+export declare function getForensicComputedStyles(target: HTMLElement): string;
+
+/**
+ * Gets full DOM ancestry path (for forensic mode)
+ */
+export declare function getFullElementPath(target: HTMLElement): string;
+
+/**
+ * Gets nearby sibling elements for structural context
+ */
+export declare function getNearbyElements(element: HTMLElement): string;
+
+/**
+ * Gets text content from element and siblings for context
+ */
+export declare function getNearbyText(element: HTMLElement): string;
+
+/**
+ * Generates a storage key for a given pathname.
+ * 根据给定路径名生成存储键。
+ *
+ * @param pathname - The page pathname (e.g., "/dashboard") | 页面路径名
+ * @returns The full storage key | 完整的存储键
+ */
+export declare function getStorageKey(pathname: string): string;
+
+export declare const IconChatEllipsis: FunctionalComponent<IconPropsWithStyle>;
+
+export declare const IconCheck: FunctionalComponent<IconProps>;
+
+export declare const IconCheckmark: FunctionalComponent<IconProps>;
+
+export declare const IconCheckmarkCircle: FunctionalComponent<IconProps>;
+
+export declare const IconCheckmarkLarge: FunctionalComponent<IconProps>;
+
+export declare const IconCheckSmall: FunctionalComponent<IconProps>;
+
+export declare const IconCheckSmallAnimated: FunctionalComponent<IconProps>;
+
+export declare const IconClose: FunctionalComponent<IconProps>;
+
+export declare const IconCopyAlt: FunctionalComponent<IconProps>;
+
+export declare const IconCopyAnimated: FunctionalComponent<IconCopyAnimatedProps>;
+
+declare interface IconCopyAnimatedProps extends IconProps {
+    copied?: boolean;
+}
+
+export declare const IconEye: FunctionalComponent<IconProps>;
+
+export declare const IconEyeAlt: FunctionalComponent<IconProps>;
+
+export declare const IconEyeAnimated: FunctionalComponent<IconEyeAnimatedProps>;
+
+declare interface IconEyeAnimatedProps extends IconProps {
+    isOpen?: boolean;
+}
+
+export declare const IconEyeClosed: FunctionalComponent<IconProps>;
+
+export declare const IconEyeMinus: FunctionalComponent<IconProps>;
+
+export declare const IconGear: FunctionalComponent<IconProps>;
+
+export declare const IconHelp: FunctionalComponent<IconProps>;
+
+export declare const IconListSparkle: FunctionalComponent<IconPropsWithStyle>;
+
+export declare const IconMoon: FunctionalComponent<IconProps>;
+
+export declare const IconPause: FunctionalComponent<IconProps>;
+
+export declare const IconPauseAlt: FunctionalComponent<IconProps>;
+
+export declare const IconPausePlayAnimated: FunctionalComponent<IconPausePlayAnimatedProps>;
+
+declare interface IconPausePlayAnimatedProps extends IconProps {
+    isPaused?: boolean;
+}
+
+export declare const IconPlayAlt: FunctionalComponent<IconProps>;
+
+export declare const IconPlus: FunctionalComponent<IconProps>;
+
+declare interface IconProps {
+    size?: number;
+}
+
+declare interface IconPropsWithColor extends IconProps {
+    color?: string;
+}
+
+declare interface IconPropsWithStyle extends IconProps {
+    style?: CSSProperties;
+}
+
+export declare const IconSun: FunctionalComponent<IconProps>;
+
+export declare const IconTrashAlt: FunctionalComponent<IconProps>;
+
+export declare const IconXmark: FunctionalComponent<IconProps>;
+
+export declare const IconXmarkLarge: FunctionalComponent<IconProps>;
+
+/**
+ * Simplified element identifier for animation feedback (less verbose)
+ */
+export declare function identifyAnimationElement(target: HTMLElement): string;
+
+/**
+ * Identifies an element and returns a human-readable name + path
+ */
+export declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+
+/**
+ * Loads annotations from localStorage for a given page.
+ * Automatically filters out annotations older than the retention period.
+ *
+ * 从 localStorage 加载指定页面的标注。
+ * 自动过滤掉超过保留期的旧标注。
+ *
+ * @param pathname - The page pathname | 页面路径名
+ * @returns Array of annotations (empty if none found or on error) | 标注数组
+ */
+export declare function loadAnnotations<T = Annotation>(pathname: string): T[];
+
+/**
+ * Parses a forensic computed styles string back into a Record.
+ * Inverse of getForensicComputedStyles - used when editing annotations.
+ */
+export declare function parseComputedStylesString(stylesStr: string | undefined): Record<string, string> | undefined;
+
+/**
+ * Saves annotations to localStorage for a given page.
+ * Silently fails if localStorage is full or disabled.
+ *
+ * 将标注保存到 localStorage。
+ * 如果 localStorage 已满或被禁用，则静默失败。
+ *
+ * @param pathname - The page pathname | 页面路径名
+ * @param annotations - Array of annotations to save | 要保存的标注数组
+ */
+export declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
+
+export { }