agentation 1.3.2 → 2.1.0

package/README.md

@@ -1,6 +1,9 @@
-# agentation
+<img src="https://raw.githubusercontent.com/benjitaylor/agentation/main/package/logo.svg" alt="Agentation" width="50" />
 
-Agentation is an agent-agnostic visual feedback tool. Click elements on your page, add notes, and copy structured output that helps AI coding agents find the exact code you're referring to.
+[![npm version](https://img.shields.io/npm/v/agentation)](https://www.npmjs.com/package/agentation)
+[![downloads](https://img.shields.io/npm/dm/agentation)](https://www.npmjs.com/package/agentation)
+
+**[Agentation](https://agentation.dev)** is an agent-agnostic visual feedback tool. 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
 
@@ -34,7 +37,7 @@ The toolbar appears in the bottom-right corner. Click to activate, then click an
 - **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
+- **Dark/light mode** – Toggle in settings, persists to localStorage
 - **Zero dependencies** – Pure CSS animations, no runtime libraries
 
 ## Props
@@ -46,7 +49,12 @@ The toolbar appears in the bottom-right corner. Click to activate, then click an
 | `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 |
+| `onSubmit` | `(output: string, annotations: Annotation[]) => void` | - | Called when "Send Annotations" is clicked |
 | `copyToClipboard` | `boolean` | `true` | Set to false to prevent writing to clipboard |
+| `endpoint` | `string` | - | Server URL for Agent Sync (e.g., `"http://localhost:4747"`) |
+| `sessionId` | `string` | - | Pre-existing session ID to join |
+| `onSessionCreated` | `(sessionId: string) => void` | - | Called when a new session is created |
+| `webhookUrl` | `string` | - | Webhook URL to receive annotation events |
 
 ### Programmatic Integration
 
@@ -85,7 +93,7 @@ function App() {
 type Annotation = {
   id: string;
   x: number;                    // % of viewport width
-  y: number;                    // px from top (viewport if fixed)
+  y: number;                    // px from top of document (absolute) OR viewport (if isFixed)
   comment: string;              // User's note
   element: string;              // e.g., "Button"
   elementPath: string;          // e.g., "body > div > button"
@@ -105,6 +113,8 @@ type Annotation = {
 };
 ```
 
+> **Note:** This is a simplified type. The full type includes additional fields for Agent Sync (`url`, `status`, `thread`, `reactComponents`, etc.). See [agentation.dev/schema](https://agentation.dev/schema) for the complete schema.
+
 ## 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.
@@ -121,4 +131,5 @@ Full documentation at [agentation.dev](https://agentation.dev)
 ## License
 
 © 2026 Benji Taylor
+
 Licensed under PolyForm Shield 1.0.0

package/dist/index.d.mts

@@ -24,6 +24,34 @@ type Annotation = {
     accessibility?: string;
     isMultiSelect?: boolean;
     isFixed?: boolean;
+    reactComponents?: string;
+    elementBoundingBoxes?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    sessionId?: string;
+    url?: string;
+    intent?: AnnotationIntent;
+    severity?: AnnotationSeverity;
+    status?: AnnotationStatus;
+    thread?: ThreadMessage[];
+    createdAt?: string;
+    updatedAt?: string;
+    resolvedAt?: string;
+    resolvedBy?: "human" | "agent";
+    authorId?: string;
+    _syncedTo?: string;
+};
+type AnnotationIntent = "fix" | "change" | "question" | "approve";
+type AnnotationSeverity = "blocking" | "important" | "suggestion";
+type AnnotationStatus = "pending" | "acknowledged" | "resolved" | "dismissed";
+type ThreadMessage = {
+    id: string;
+    role: "human" | "agent";
+    content: string;
+    timestamp: number;
 };
 
 type DemoAnnotation = {
@@ -45,12 +73,22 @@ type PageFeedbackToolbarCSSProps = {
     onAnnotationsClear?: (annotations: Annotation[]) => void;
     /** Callback fired when the copy button is clicked. Receives the markdown output. */
     onCopy?: (markdown: string) => void;
+    /** Callback fired when "Send to Agent" is clicked. Receives the markdown output and annotations. */
+    onSubmit?: (output: string, annotations: Annotation[]) => void;
     /** Whether to copy to clipboard when the copy button is clicked. Defaults to true. */
     copyToClipboard?: boolean;
+    /** Server URL for sync (e.g., "http://localhost:4747"). If not provided, uses localStorage only. */
+    endpoint?: string;
+    /** Pre-existing session ID to join. If not provided with endpoint, creates a new session. */
+    sessionId?: string;
+    /** Called when a new session is created (only when endpoint is provided without sessionId). */
+    onSessionCreated?: (sessionId: string) => void;
+    /** Webhook URL to receive annotation events. */
+    webhookUrl?: string;
 };
 /** Alias for PageFeedbackToolbarCSSProps */
 type AgentationProps = PageFeedbackToolbarCSSProps;
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, copyToClipboard, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -69,6 +107,8 @@ interface AnnotationPopupCSSProps {
     onSubmit: (text: string) => void;
     /** Called when popup is cancelled/dismissed */
     onCancel: () => void;
+    /** Called when delete button is clicked (only shown if provided) */
+    onDelete?: () => void;
     /** Position styles (left, top) */
     style?: React.CSSProperties;
     /** Custom color for submit button and textarea focus (hex) */
@@ -115,6 +155,14 @@ declare const IconCopyAnimated: ({ size, copied }: {
     size?: number;
     copied?: boolean;
 }) => react_jsx_runtime.JSX.Element;
+declare const IconSendArrow: ({ size, state }: {
+    size?: number;
+    state?: "idle" | "sending" | "sent" | "failed";
+}) => react_jsx_runtime.JSX.Element;
+declare const IconSendAnimated: ({ size, sent }: {
+    size?: number;
+    sent?: boolean;
+}) => react_jsx_runtime.JSX.Element;
 declare const IconEye: ({ size }: {
     size?: number;
 }) => react_jsx_runtime.JSX.Element;
@@ -175,13 +223,38 @@ declare const IconSun: ({ size }: {
 declare const IconMoon: ({ size }: {
     size?: number;
 }) => react_jsx_runtime.JSX.Element;
+declare const IconEdit: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconTrash: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChevronLeft: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChevronRight: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
 declare const AnimatedBunny: ({ size, color, }: {
     size?: number;
     color?: string;
 }) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Finds the closest ancestor matching a selector, crossing shadow DOM boundaries.
+ */
+declare function closestCrossingShadow(element: Element, selector: string): Element | null;
+/**
+ * Checks if an element is inside a shadow DOM
+ */
+declare function isInShadowDOM(element: Element): boolean;
+/**
+ * Gets the shadow host for an element, or null if not in shadow DOM
+ */
+declare function getShadowHost(element: Element): Element | null;
 /**
  * Gets a readable path for an element (e.g., "article > section > p")
+ * Supports elements inside shadow DOM by crossing shadow boundaries.
  */
 declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
 /**
@@ -208,4 +281,4 @@ 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, 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 };
+export { PageFeedbackToolbarCSS as Agentation, type AgentationProps, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations };

package/dist/index.d.ts

@@ -24,6 +24,34 @@ type Annotation = {
     accessibility?: string;
     isMultiSelect?: boolean;
     isFixed?: boolean;
+    reactComponents?: string;
+    elementBoundingBoxes?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    sessionId?: string;
+    url?: string;
+    intent?: AnnotationIntent;
+    severity?: AnnotationSeverity;
+    status?: AnnotationStatus;
+    thread?: ThreadMessage[];
+    createdAt?: string;
+    updatedAt?: string;
+    resolvedAt?: string;
+    resolvedBy?: "human" | "agent";
+    authorId?: string;
+    _syncedTo?: string;
+};
+type AnnotationIntent = "fix" | "change" | "question" | "approve";
+type AnnotationSeverity = "blocking" | "important" | "suggestion";
+type AnnotationStatus = "pending" | "acknowledged" | "resolved" | "dismissed";
+type ThreadMessage = {
+    id: string;
+    role: "human" | "agent";
+    content: string;
+    timestamp: number;
 };
 
 type DemoAnnotation = {
@@ -45,12 +73,22 @@ type PageFeedbackToolbarCSSProps = {
     onAnnotationsClear?: (annotations: Annotation[]) => void;
     /** Callback fired when the copy button is clicked. Receives the markdown output. */
     onCopy?: (markdown: string) => void;
+    /** Callback fired when "Send to Agent" is clicked. Receives the markdown output and annotations. */
+    onSubmit?: (output: string, annotations: Annotation[]) => void;
     /** Whether to copy to clipboard when the copy button is clicked. Defaults to true. */
     copyToClipboard?: boolean;
+    /** Server URL for sync (e.g., "http://localhost:4747"). If not provided, uses localStorage only. */
+    endpoint?: string;
+    /** Pre-existing session ID to join. If not provided with endpoint, creates a new session. */
+    sessionId?: string;
+    /** Called when a new session is created (only when endpoint is provided without sessionId). */
+    onSessionCreated?: (sessionId: string) => void;
+    /** Webhook URL to receive annotation events. */
+    webhookUrl?: string;
 };
 /** Alias for PageFeedbackToolbarCSSProps */
 type AgentationProps = PageFeedbackToolbarCSSProps;
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, copyToClipboard, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -69,6 +107,8 @@ interface AnnotationPopupCSSProps {
     onSubmit: (text: string) => void;
     /** Called when popup is cancelled/dismissed */
     onCancel: () => void;
+    /** Called when delete button is clicked (only shown if provided) */
+    onDelete?: () => void;
     /** Position styles (left, top) */
     style?: React.CSSProperties;
     /** Custom color for submit button and textarea focus (hex) */
@@ -115,6 +155,14 @@ declare const IconCopyAnimated: ({ size, copied }: {
     size?: number;
     copied?: boolean;
 }) => react_jsx_runtime.JSX.Element;
+declare const IconSendArrow: ({ size, state }: {
+    size?: number;
+    state?: "idle" | "sending" | "sent" | "failed";
+}) => react_jsx_runtime.JSX.Element;
+declare const IconSendAnimated: ({ size, sent }: {
+    size?: number;
+    sent?: boolean;
+}) => react_jsx_runtime.JSX.Element;
 declare const IconEye: ({ size }: {
     size?: number;
 }) => react_jsx_runtime.JSX.Element;
@@ -175,13 +223,38 @@ declare const IconSun: ({ size }: {
 declare const IconMoon: ({ size }: {
     size?: number;
 }) => react_jsx_runtime.JSX.Element;
+declare const IconEdit: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconTrash: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChevronLeft: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChevronRight: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
 declare const AnimatedBunny: ({ size, color, }: {
     size?: number;
     color?: string;
 }) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Finds the closest ancestor matching a selector, crossing shadow DOM boundaries.
+ */
+declare function closestCrossingShadow(element: Element, selector: string): Element | null;
+/**
+ * Checks if an element is inside a shadow DOM
+ */
+declare function isInShadowDOM(element: Element): boolean;
+/**
+ * Gets the shadow host for an element, or null if not in shadow DOM
+ */
+declare function getShadowHost(element: Element): Element | null;
 /**
  * Gets a readable path for an element (e.g., "article > section > p")
+ * Supports elements inside shadow DOM by crossing shadow boundaries.
  */
 declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
 /**
@@ -208,4 +281,4 @@ 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, 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 };
+export { PageFeedbackToolbarCSS as Agentation, type AgentationProps, AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations };