agentation 1.1.0 → 1.2.0

package/README.md

@@ -33,9 +33,78 @@ The toolbar appears in the bottom-right corner. Click to activate, then click an
 - **Area selection** – Drag to annotate any region, even empty space
 - **Animation pause** – Freeze CSS animations to capture specific states
 - **Structured output** – Copy markdown with selectors, positions, and context
+- **Programmatic access** – Callback prop for direct integration with tools
 - **Dark/light mode** – Matches your preference or set manually
 - **Zero dependencies** – Pure CSS animations, no runtime libraries
 
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onAnnotationAdd` | `(annotation: Annotation) => void` | - | Called when an annotation is created |
+| `onAnnotationDelete` | `(annotation: Annotation) => void` | - | Called when an annotation is deleted |
+| `onAnnotationUpdate` | `(annotation: Annotation) => void` | - | Called when an annotation is edited |
+| `onAnnotationsClear` | `(annotations: Annotation[]) => void` | - | Called when all annotations are cleared |
+| `onCopy` | `(markdown: string) => void` | - | Callback with markdown output when copy is clicked |
+| `copyToClipboard` | `boolean` | `true` | Set to false to prevent writing to clipboard |
+
+### Programmatic Integration
+
+Use callbacks to receive annotation data directly:
+
+```tsx
+import { Agentation, type Annotation } from 'agentation';
+
+function App() {
+  const handleAnnotation = (annotation: Annotation) => {
+    // Structured data - no parsing needed
+    console.log(annotation.element);      // "Button"
+    console.log(annotation.elementPath);  // "body > div > button"
+    console.log(annotation.boundingBox);  // { x, y, width, height }
+    console.log(annotation.cssClasses);   // "btn btn-primary"
+
+    // Send to your agent, API, etc.
+    sendToAgent(annotation);
+  };
+
+  return (
+    <>
+      <YourApp />
+      <Agentation
+        onAnnotationAdd={handleAnnotation}
+        copyToClipboard={false}  // Don't write to clipboard
+      />
+    </>
+  );
+}
+```
+
+### Annotation Type
+
+```typescript
+type Annotation = {
+  id: string;
+  x: number;                    // % of viewport width
+  y: number;                    // px from top (viewport if fixed)
+  comment: string;              // User's note
+  element: string;              // e.g., "Button"
+  elementPath: string;          // e.g., "body > div > button"
+  timestamp: number;
+
+  // Optional metadata (when available)
+  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;
+};
+```
+
 ## 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.

package/dist/index.d.mts

@@ -1,6 +1,31 @@
 import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+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;
+};
+
 type DemoAnnotation = {
     selector: string;
     comment: string;
@@ -10,8 +35,22 @@ type PageFeedbackToolbarCSSProps = {
     demoAnnotations?: DemoAnnotation[];
     demoDelay?: number;
     enableDemoMode?: boolean;
+    /** Callback fired when an annotation is added. */
+    onAnnotationAdd?: (annotation: Annotation) => void;
+    /** Callback fired when an annotation is deleted. */
+    onAnnotationDelete?: (annotation: Annotation) => void;
+    /** Callback fired when an annotation comment is edited. */
+    onAnnotationUpdate?: (annotation: Annotation) => void;
+    /** Callback fired when all annotations are cleared. Receives the annotations that were cleared. */
+    onAnnotationsClear?: (annotations: Annotation[]) => void;
+    /** Callback fired when the copy button is clicked. Receives the markdown output. */
+    onCopy?: (markdown: string) => void;
+    /** Whether to copy to clipboard when the copy button is clicked. Defaults to true. */
+    copyToClipboard?: boolean;
 };
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+/** Alias for PageFeedbackToolbarCSSProps */
+type AgentationProps = PageFeedbackToolbarCSSProps;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, copyToClipboard, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -163,33 +202,8 @@ declare function identifyAnimationElement(target: HTMLElement): string;
  */
 declare function getElementClasses(target: HTMLElement): string;
 
-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;
-};
-
 declare function getStorageKey(pathname: string): string;
 declare function loadAnnotations<T = Annotation>(pathname: string): T[];
 declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
 
-export { PageFeedbackToolbarCSS as Agentation, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconClose, IconCopyAlt, IconCopyAnimated, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSun, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, getElementClasses, getElementPath, getNearbyText, getStorageKey, identifyAnimationElement, identifyElement, loadAnnotations, saveAnnotations };
+export { PageFeedbackToolbarCSS as Agentation, type AgentationProps, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconClose, IconCopyAlt, IconCopyAnimated, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSun, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, getElementClasses, getElementPath, getNearbyText, getStorageKey, identifyAnimationElement, identifyElement, loadAnnotations, saveAnnotations };

package/dist/index.d.ts

@@ -1,6 +1,31 @@
 import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+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;
+};
+
 type DemoAnnotation = {
     selector: string;
     comment: string;
@@ -10,8 +35,22 @@ type PageFeedbackToolbarCSSProps = {
     demoAnnotations?: DemoAnnotation[];
     demoDelay?: number;
     enableDemoMode?: boolean;
+    /** Callback fired when an annotation is added. */
+    onAnnotationAdd?: (annotation: Annotation) => void;
+    /** Callback fired when an annotation is deleted. */
+    onAnnotationDelete?: (annotation: Annotation) => void;
+    /** Callback fired when an annotation comment is edited. */
+    onAnnotationUpdate?: (annotation: Annotation) => void;
+    /** Callback fired when all annotations are cleared. Receives the annotations that were cleared. */
+    onAnnotationsClear?: (annotations: Annotation[]) => void;
+    /** Callback fired when the copy button is clicked. Receives the markdown output. */
+    onCopy?: (markdown: string) => void;
+    /** Whether to copy to clipboard when the copy button is clicked. Defaults to true. */
+    copyToClipboard?: boolean;
 };
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+/** Alias for PageFeedbackToolbarCSSProps */
+type AgentationProps = PageFeedbackToolbarCSSProps;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, copyToClipboard, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -163,33 +202,8 @@ declare function identifyAnimationElement(target: HTMLElement): string;
  */
 declare function getElementClasses(target: HTMLElement): string;
 
-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;
-};
-
 declare function getStorageKey(pathname: string): string;
 declare function loadAnnotations<T = Annotation>(pathname: string): T[];
 declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
 
-export { PageFeedbackToolbarCSS as Agentation, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconClose, IconCopyAlt, IconCopyAnimated, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSun, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, getElementClasses, getElementPath, getNearbyText, getStorageKey, identifyAnimationElement, identifyElement, loadAnnotations, saveAnnotations };
+export { PageFeedbackToolbarCSS as Agentation, type AgentationProps, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconClose, IconCopyAlt, IconCopyAnimated, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSun, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, getElementClasses, getElementPath, getNearbyText, getStorageKey, identifyAnimationElement, identifyElement, loadAnnotations, saveAnnotations };

package/dist/index.js

@@ -1540,7 +1540,13 @@ function generateOutput(annotations, pathname, detailLevel = "standard") {
 function PageFeedbackToolbarCSS({
   demoAnnotations,
   demoDelay = 1e3,
-  enableDemoMode = false
+  enableDemoMode = false,
+  onAnnotationAdd,
+  onAnnotationDelete,
+  onAnnotationUpdate,
+  onAnnotationsClear,
+  onCopy,
+  copyToClipboard = true
 } = {}) {
   const [isActive, setIsActive] = (0, import_react2.useState)(false);
   const [annotations, setAnnotations] = (0, import_react2.useState)([]);
@@ -2262,6 +2268,7 @@ function PageFeedbackToolbarCSS({
       setTimeout(() => {
         setAnimatedMarkers((prev) => new Set(prev).add(newAnnotation.id));
       }, 250);
+      onAnnotationAdd?.(newAnnotation);
       setPendingExiting(true);
       setTimeout(() => {
         setPendingAnnotation(null);
@@ -2269,7 +2276,7 @@ function PageFeedbackToolbarCSS({
       }, 150);
       window.getSelection()?.removeAllRanges();
     },
-    [pendingAnnotation]
+    [pendingAnnotation, onAnnotationAdd]
   );
   const cancelAnnotation = (0, import_react2.useCallback)(() => {
     setPendingExiting(true);
@@ -2281,8 +2288,12 @@ function PageFeedbackToolbarCSS({
   const deleteAnnotation = (0, import_react2.useCallback)(
     (id) => {
       const deletedIndex = annotations.findIndex((a) => a.id === id);
+      const deletedAnnotation = annotations[deletedIndex];
       setDeletingMarkerId(id);
       setExitingMarkers((prev) => new Set(prev).add(id));
+      if (deletedAnnotation) {
+        onAnnotationDelete?.(deletedAnnotation);
+      }
       setTimeout(() => {
         setAnnotations((prev) => prev.filter((a) => a.id !== id));
         setExitingMarkers((prev) => {
@@ -2297,7 +2308,7 @@ function PageFeedbackToolbarCSS({
         }
       }, 150);
     },
-    [annotations]
+    [annotations, onAnnotationDelete]
   );
   const startEditAnnotation = (0, import_react2.useCallback)((annotation) => {
     setEditingAnnotation(annotation);
@@ -2306,18 +2317,20 @@ function PageFeedbackToolbarCSS({
   const updateAnnotation = (0, import_react2.useCallback)(
     (newComment) => {
       if (!editingAnnotation) return;
+      const updatedAnnotation = { ...editingAnnotation, comment: newComment };
       setAnnotations(
         (prev) => prev.map(
-          (a) => a.id === editingAnnotation.id ? { ...a, comment: newComment } : a
+          (a) => a.id === editingAnnotation.id ? updatedAnnotation : a
         )
       );
+      onAnnotationUpdate?.(updatedAnnotation);
       setEditExiting(true);
       setTimeout(() => {
         setEditingAnnotation(null);
         setEditExiting(false);
       }, 150);
     },
-    [editingAnnotation]
+    [editingAnnotation, onAnnotationUpdate]
   );
   const cancelEditAnnotation = (0, import_react2.useCallback)(() => {
     setEditExiting(true);
@@ -2329,6 +2342,7 @@ function PageFeedbackToolbarCSS({
   const clearAll = (0, import_react2.useCallback)(() => {
     const count = annotations.length;
     if (count === 0) return;
+    onAnnotationsClear?.(annotations);
     setIsClearing(true);
     setCleared(true);
     const totalAnimationTime = count * 30 + 200;
@@ -2339,11 +2353,17 @@ function PageFeedbackToolbarCSS({
       setIsClearing(false);
     }, totalAnimationTime);
     setTimeout(() => setCleared(false), 1500);
-  }, [pathname, annotations.length]);
+  }, [pathname, annotations, onAnnotationsClear]);
   const copyOutput = (0, import_react2.useCallback)(async () => {
     const output = generateOutput(annotations, pathname, settings.outputDetail);
     if (!output) return;
-    await navigator.clipboard.writeText(output);
+    if (copyToClipboard) {
+      try {
+        await navigator.clipboard.writeText(output);
+      } catch {
+      }
+    }
+    onCopy?.(output);
     setCopied(true);
     setTimeout(() => setCopied(false), 2e3);
     if (settings.autoClearAfterCopy) {
@@ -2354,7 +2374,9 @@ function PageFeedbackToolbarCSS({
     pathname,
     settings.outputDetail,
     settings.autoClearAfterCopy,
-    clearAll
+    clearAll,
+    copyToClipboard,
+    onCopy
   ]);
   (0, import_react2.useEffect)(() => {
     if (!dragStartPos) return;
@@ -2674,7 +2696,7 @@ function PageFeedbackToolbarCSS({
                         ] }),
                         /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: styles_module_default2.settingsVersion, children: [
                           "v",
-                          "1.1.0"
+                          "1.2.0"
                         ] }),
                         /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
                           "button",
@@ -2765,10 +2787,10 @@ function PageFeedbackToolbarCSS({
                                 className: `${styles_module_default2.colorOption} ${settings.annotationColor === color.value ? styles_module_default2.selected : ""}`,
                                 style: { backgroundColor: color.value },
                                 title: color.label
-                              },
-                              color.value
+                              }
                             )
-                          }
+                          },
+                          color.value
                         )) })
                       ] }),
                       /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: styles_module_default2.settingsSection, children: [