agentation 0.0.2 → 1.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+PolyForm Shield License 1.0.0
+
+Copyright (c) 2026 Benji Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software, subject to the following conditions:
+
+1. You may not use the Software to provide a product or service that competes
+   with the Software or any product or service offered by the Licensor that
+   includes the Software.
+
+2. You may not remove or obscure any licensing, copyright, or other notices
+   included in the Software.
+
+3. If you distribute the Software or any derivative works, you must include a
+   copy of this license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For more information, see https://polyformproject.org/licenses/shield/1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# agentation
+
+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.
+
+## Install
+
+```bash
+npm install agentation -D
+```
+
+## Usage
+
+```tsx
+import { Agentation } from 'agentation';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <Agentation />
+    </>
+  );
+}
+```
+
+The toolbar appears in the bottom-right corner. Click to activate, then click any element to annotate it.
+
+## Features
+
+- **Click to annotate** – Click any element with automatic selector identification
+- **Text selection** – Select text to annotate specific content
+- **Multi-select** – Drag to select multiple elements at once
+- **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
+- **Dark/light mode** – Matches your preference or set manually
+- **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
+
+- React 18+
+- Desktop browser (mobile not supported)
+
+## Docs
+
+Full documentation at [agentation.dev](https://agentation.dev)
+
+## License
+
+© 2026 Benji Taylor
+Licensed under PolyForm Shield 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,222 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type DemoAnnotation = {
+    selector: string;
+    comment: string;
+    selectedText?: string;
+};
+type PageFeedbackToolbarCSSProps = {
+    demoAnnotations?: DemoAnnotation[];
+    demoDelay?: number;
+    enableDemoMode?: boolean;
+};
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+
+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;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** Color variant for submit button */
+    variant?: "blue" | "green";
+}
+interface AnnotationPopupHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopup: react.ForwardRefExoticComponent<AnnotationPopupProps & react.RefAttributes<AnnotationPopupHandle>>;
+declare function AnnotationPopupPresence({ isOpen, ...props }: AnnotationPopupProps & {
+    isOpen: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+interface AnnotationPopupCSSProps {
+    /** 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;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** 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;
+}
+interface AnnotationPopupCSSHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopupCSS: react.ForwardRefExoticComponent<AnnotationPopupCSSProps & react.RefAttributes<AnnotationPopupCSSHandle>>;
+
+declare const IconClose: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPlus: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheck: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckSmall: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconListSparkle: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconHelp: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckSmallAnimated: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCopyAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCopyAnimated: ({ size, copied }: {
+    size?: number;
+    copied?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEye: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeClosed: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeAnimated: ({ size, isOpen }: {
+    size?: number;
+    isOpen?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPausePlayAnimated: ({ size, isPaused }: {
+    size?: number;
+    isPaused?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeMinus: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconGear: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPauseAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPause: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPlayAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconTrashAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChatEllipsis: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmark: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmarkLarge: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmarkCircle: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconXmark: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconXmarkLarge: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconSun: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconMoon: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const AnimatedBunny: ({ size, color, }: {
+    size?: number;
+    color?: string;
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name + path
+ */
+declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+/**
+ * Gets text content from element and siblings for context
+ */
+declare function getNearbyText(element: HTMLElement): string;
+/**
+ * Simplified element identifier for animation feedback (less verbose)
+ */
+declare function identifyAnimationElement(target: HTMLElement): string;
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+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, PageFeedbackToolbarCSS as AgentationCSS, AnimatedBunny, type Annotation, AnnotationPopup, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type AnnotationPopupHandle, AnnotationPopupPresence, type AnnotationPopupProps, 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

@@ -0,0 +1,222 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type DemoAnnotation = {
+    selector: string;
+    comment: string;
+    selectedText?: string;
+};
+type PageFeedbackToolbarCSSProps = {
+    demoAnnotations?: DemoAnnotation[];
+    demoDelay?: number;
+    enableDemoMode?: boolean;
+};
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+
+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;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** Color variant for submit button */
+    variant?: "blue" | "green";
+}
+interface AnnotationPopupHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopup: react.ForwardRefExoticComponent<AnnotationPopupProps & react.RefAttributes<AnnotationPopupHandle>>;
+declare function AnnotationPopupPresence({ isOpen, ...props }: AnnotationPopupProps & {
+    isOpen: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+interface AnnotationPopupCSSProps {
+    /** 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;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** 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;
+}
+interface AnnotationPopupCSSHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopupCSS: react.ForwardRefExoticComponent<AnnotationPopupCSSProps & react.RefAttributes<AnnotationPopupCSSHandle>>;
+
+declare const IconClose: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPlus: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheck: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckSmall: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconListSparkle: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconHelp: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckSmallAnimated: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCopyAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCopyAnimated: ({ size, copied }: {
+    size?: number;
+    copied?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEye: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeClosed: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeAnimated: ({ size, isOpen }: {
+    size?: number;
+    isOpen?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPausePlayAnimated: ({ size, isPaused }: {
+    size?: number;
+    isPaused?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconEyeMinus: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconGear: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPauseAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPause: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconPlayAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconTrashAlt: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconChatEllipsis: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmark: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmarkLarge: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconCheckmarkCircle: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconXmark: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconXmarkLarge: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconSun: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const IconMoon: ({ size }: {
+    size?: number;
+}) => react_jsx_runtime.JSX.Element;
+declare const AnimatedBunny: ({ size, color, }: {
+    size?: number;
+    color?: string;
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name + path
+ */
+declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+/**
+ * Gets text content from element and siblings for context
+ */
+declare function getNearbyText(element: HTMLElement): string;
+/**
+ * Simplified element identifier for animation feedback (less verbose)
+ */
+declare function identifyAnimationElement(target: HTMLElement): string;
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+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, PageFeedbackToolbarCSS as AgentationCSS, AnimatedBunny, type Annotation, AnnotationPopup, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type AnnotationPopupHandle, AnnotationPopupPresence, type AnnotationPopupProps, 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 };