vite-plugin-ai-annotator 1.14.8 → 1.14.10

package/README.md

@@ -144,9 +144,10 @@ Example prompt: *"Make the selected button larger and change its color to blue"*
 
 ```typescript
 annotator({
-  port: 7318,           // Server port (default: 7318)
-  autoSetupMcp: true,   // Auto-configure MCP files (default: false)
-  verbose: false,       // Enable detailed logging (default: false)
+  port: 7318,              // Server port (default: 7318)
+  autoSetupMcp: true,      // Auto-configure MCP files (default: false)
+  autoSetupSkills: true,   // Auto-write AI tool skill files (default: true)
+  verbose: false,          // Enable detailed logging (default: false)
 })
 ```
 
@@ -166,4 +167,48 @@ When `autoSetupMcp: true`, the plugin automatically:
 
 3. **Preserves existing config** - merges with other MCP servers, doesn't overwrite
 
+### Auto AI Skills Setup
+
+When `autoSetupSkills: true` (default), the plugin writes skill/instruction files on every dev server start with the correct server address baked in. This means AI tools automatically know how to call the REST API:
+
+| AI Tool | File | Format |
+|---------|------|--------|
+| Claude Code | `.claude/skills/ai-annotator/SKILL.md` | YAML frontmatter (`name`, `description`) |
+| Cursor | `.cursor/rules/ai-annotator.mdc` | `alwaysApply: true` |
+| Windsurf | `.windsurf/rules/ai-annotator.md` | `trigger: always_on` |
+| Codex | `AGENTS.md` | Marker-delimited section |
+| Copilot | `.github/instructions/ai-annotator.instructions.md` | `applyTo: "**"` |
+| Cline | `.clinerules/ai-annotator.md` | Plain markdown |
+
+Files are updated on every server restart, so the address is always correct.
+
+## REST API
+
+The server exposes a plain HTTP REST API at `/api/*`, usable by any HTTP client — no MCP required.
+
+```bash
+# List sessions
+curl http://localhost:7318/api/sessions
+
+# Get feedback
+curl http://localhost:7318/api/sessions/<id>/feedback
+
+# Inject JS
+curl -X POST http://localhost:7318/api/sessions/<id>/inject-js \
+  -H 'Content-Type: application/json' \
+  -d '{"code": "document.title"}'
+```
+
+| Method | Endpoint | Body/Query | Description |
+|--------|----------|------------|-------------|
+| `GET` | `/api/sessions` | — | List connected browser sessions |
+| `GET` | `/api/sessions/:id/page-context` | — | Page URL, title, selection count |
+| `POST` | `/api/sessions/:id/select` | `{mode?, selector?, selectorType?}` | Trigger feedback selection |
+| `GET` | `/api/sessions/:id/feedback` | `?fields=xpath,attributes,styles,children` | Get selected feedback items |
+| `DELETE` | `/api/sessions/:id/feedback` | — | Clear all selections |
+| `POST` | `/api/sessions/:id/screenshot` | `{type?, selector?, quality?}` | Capture screenshot |
+| `POST` | `/api/sessions/:id/inject-css` | `{css}` | Inject CSS into page |
+| `POST` | `/api/sessions/:id/inject-js` | `{code}` | Execute JS in page context |
+| `GET` | `/api/sessions/:id/console` | `?clear=true` | Get captured console logs |
+
 **Happy coding! 🚀**

package/dist/annotator-toolbar.d.ts

@@ -11,6 +11,7 @@ import { LitElement } from 'lit';
 export declare class AnnotatorToolbar extends LitElement {
     wsEndpoint: string;
     verbose: boolean;
+    demo: boolean;
     private connected;
     private sessionId;
     private selectionCount;
@@ -37,6 +38,7 @@ export declare class AnnotatorToolbar extends LitElement {
     private initializeConsoleCapture;
     private restoreConsoleMethods;
     private connectToServer;
+    private wrapRpcHandler;
     private registerRpcHandlers;
     private reportPageContext;
     private getPageContext;

package/dist/annotator-toolbar.js

@@ -6236,12 +6236,6 @@
     static isValidId(id) {
       return Boolean(id) && /^\S.*$/.test(id) && !/[[\](){}<>]/.test(id);
     }
-    /**
-     * Generate optimized CSS selector using optimal-select library
-     */
-    static generateOptimalSelector(element) {
-      return this.generateEnhancedCSSSelector(element);
-    }
     /**
      * Generate enhanced CSS selector optimized for browser environment
      */
@@ -6324,7 +6318,7 @@
      */
     static generateElementSelector(element) {
       const xpath = this.generateXPath(element);
-      const cssSelector = this.generateOptimalSelector(element);
+      const cssSelector = this.generateEnhancedCSSSelector(element);
       const siblings = Array.from(element.parentElement?.children || []).filter((sibling) => sibling.tagName === element.tagName);
       const position = siblings.length > 1 ? {
         index: siblings.indexOf(element) + 1,
@@ -6365,13 +6359,6 @@
       if (element.getAttribute("aria-label")) {
         fallbacks.push(`[aria-label="${element.getAttribute("aria-label")}"]`);
       }
-      const textContent = element.textContent?.trim();
-      if (textContent && textContent.length > 0 && textContent.length < 50) {
-        const elementsWithSameText = Array.from(document.querySelectorAll("*")).filter((el) => el.textContent?.trim() === textContent);
-        if (elementsWithSameText.length === 1) {
-          fallbacks.push(`${element.tagName.toLowerCase()}:contains("${textContent}")`);
-        }
-      }
       let confidence = "low";
       if (this.validateXPath(primary.xpath, element) && this.validateCSSSelector(primary.cssSelector, element)) {
         confidence = "high";
@@ -6563,6 +6550,8 @@
           cleanup?.();
           badge.remove();
           overlay.remove();
+          selectedElements.delete(element);
+          selectionGroups.delete(element);
           return;
         }
         const rect = element.getBoundingClientRect();
@@ -7054,6 +7043,7 @@
         }
         return componentInfo;
       }
+      if (!element.parentElement) return null;
       return findNearestComponent(element.parentElement, verbose);
     } catch (e5) {
       logger.error("Error finding nearest component:", e5);
@@ -7293,7 +7283,7 @@
       const locationInfo = {};
       if (vnode?.loc) {
         locationInfo.elementLocation = {
-          file: vnode.loc.source || "",
+          file: "",
           line: vnode.loc.start?.line || 0,
           column: vnode.loc.start?.column || 0,
           endLine: vnode.loc.end?.line,
@@ -7537,6 +7527,7 @@
       super(...arguments);
       this.wsEndpoint = "http://localhost:7318";
       this.verbose = false;
+      this.demo = false;
       this.connected = false;
       this.sessionId = "";
       this.selectionCount = 0;
@@ -7580,8 +7571,12 @@
     connectedCallback() {
       super.connectedCallback();
       this.initializeManagers();
-      this.initializeConsoleCapture();
-      this.connectToServer();
+      if (this.demo) {
+        this.connected = true;
+      } else {
+        this.initializeConsoleCapture();
+        this.connectToServer();
+      }
     }
     disconnectedCallback() {
       super.disconnectedCallback();
@@ -7672,73 +7667,27 @@
         this.log("Connection error:", error.message);
       });
     }
-    registerRpcHandlers() {
-      if (!this.rpc) return;
-      this.rpc.handle.getPageContext(async () => {
+    wrapRpcHandler(name, handler) {
+      return (async (...args) => {
         try {
-          return await this.getPageContext();
+          return await handler(...args);
         } catch (error) {
-          this.log("[getPageContext] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.getSelectedElements(async () => {
-        try {
-          return await this.getSelectedElements();
-        } catch (error) {
-          this.log("[getSelectedElements] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.triggerSelection(async (mode, selector, selectorType) => {
-        try {
-          return await this.triggerSelection(mode, selector, selectorType);
-        } catch (error) {
-          this.log("[triggerSelection] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.captureScreenshot(async (type, selector, quality) => {
-        try {
-          return await this.captureScreenshot(type, selector, quality);
-        } catch (error) {
-          this.log("[captureScreenshot] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.clearSelection(async () => {
-        try {
-          return await this.clearSelection();
-        } catch (error) {
-          this.log("[clearSelection] Handler error:", error);
+          this.log(`[${name}] Handler error:`, error);
           throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
         }
       });
+    }
+    registerRpcHandlers() {
+      if (!this.rpc) return;
+      this.rpc.handle.getPageContext(this.wrapRpcHandler("getPageContext", async () => this.getPageContext()));
+      this.rpc.handle.getSelectedElements(this.wrapRpcHandler("getSelectedElements", async () => this.getSelectedElements()));
+      this.rpc.handle.triggerSelection(this.wrapRpcHandler("triggerSelection", async (mode, selector, selectorType) => this.triggerSelection(mode, selector, selectorType)));
+      this.rpc.handle.captureScreenshot(this.wrapRpcHandler("captureScreenshot", async (type, selector, quality) => this.captureScreenshot(type, selector, quality)));
+      this.rpc.handle.clearSelection(this.wrapRpcHandler("clearSelection", async () => this.clearSelection()));
       this.rpc.handle.ping(async () => "pong");
-      this.rpc.handle.injectCSS(async (css) => {
-        try {
-          return await this.injectCSS(css);
-        } catch (error) {
-          this.log("[injectCSS] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.injectJS(async (code) => {
-        try {
-          return await this.injectJS(code);
-        } catch (error) {
-          this.log("[injectJS] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
-      this.rpc.handle.getConsole(async (clear) => {
-        try {
-          return await this.getConsoleLogs(clear);
-        } catch (error) {
-          this.log("[getConsole] Handler error:", error);
-          throw { message: error instanceof Error ? error.message : String(error), code: "INTERNAL_ERROR", data: void 0 };
-        }
-      });
+      this.rpc.handle.injectCSS(this.wrapRpcHandler("injectCSS", async (css) => this.injectCSS(css)));
+      this.rpc.handle.injectJS(this.wrapRpcHandler("injectJS", async (code) => this.injectJS(code)));
+      this.rpc.handle.getConsole(this.wrapRpcHandler("getConsole", async (clear) => this.getConsoleLogs(clear)));
     }
     reportPageContext() {
       if (!this.socket?.connected) return;
@@ -8030,9 +7979,6 @@
         this.popoverCleanup();
         this.popoverCleanup = null;
       }
-      const popoverEl = this.shadowRoot?.querySelector(".popover");
-      if (popoverEl) {
-      }
       this.commentPopover = { visible: false, element: null, comment: "" };
     }
     handlePopoverInput(e5) {
@@ -8212,6 +8158,10 @@
     }
     async copySessionId() {
       this.exitInspectingMode();
+      if (this.demo) {
+        this.showToast("Demo mode \u2014 no server");
+        return;
+      }
       if (!this.sessionId) {
         this.showToast("No session ID");
         return;
@@ -8600,6 +8550,9 @@
   __decorateClass([
     n4({ attribute: "verbose", type: Boolean })
   ], AnnotatorToolbar.prototype, "verbose", 2);
+  __decorateClass([
+    n4({ attribute: "demo", type: Boolean })
+  ], AnnotatorToolbar.prototype, "demo", 2);
   __decorateClass([
     r5()
   ], AnnotatorToolbar.prototype, "connected", 2);

package/dist/auto-setup-skills.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Auto-setup AI tool skill/instruction files with the running server address.
+ *
+ * Writes proper skill/rule files for each AI tool:
+ * - Claude Code: .claude/skills/ai-annotator/SKILL.md
+ * - Cursor: .cursor/rules/ai-annotator.mdc (alwaysApply)
+ * - Windsurf: .windsurf/rules/ai-annotator.md (trigger: always_on)
+ * - Codex: AGENTS.md (marker-delimited section)
+ * - Copilot: .github/instructions/ai-annotator.instructions.md (applyTo: **)
+ * - Cline: .clinerules/ai-annotator.md
+ *
+ * Each file contains REST API docs with the actual server URL baked in.
+ * Updated on every server start so the address is always correct.
+ */
+export interface AutoSetupSkillsOptions {
+    projectRoot: string;
+    serverUrl: string;
+    verbose?: boolean;
+}
+export interface AutoSetupSkillsResult {
+    updated: string[];
+    alreadyConfigured: string[];
+}
+export declare function autoSetupSkills(options: AutoSetupSkillsOptions): AutoSetupSkillsResult;