ui-sniper 3.0.2

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,140 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/benjitaylor/ui-sniper/main/package/logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/benjitaylor/ui-sniper/main/package/logo.svg" alt="UI Sniper" width="200">
+</picture>
+
+<br>
+
+[![npm version](https://img.shields.io/npm/v/ui-sniper)](https://www.npmjs.com/package/ui-sniper)
+[![downloads](https://img.shields.io/npm/dm/ui-sniper)](https://www.npmjs.com/package/ui-sniper)
+
+**[UI Sniper](https://hara-xy.com)** 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 ui-sniper -D
+```
+
+## Usage
+
+```tsx
+import { UI Sniper } from 'ui-sniper';
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <UI Sniper />
+    </>
+  );
+}
+```
+
+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 all animations (CSS, JS, videos) 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** – Toggle in settings, persists to localStorage
+- **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 |
+| `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
+
+Use callbacks to receive annotation data directly:
+
+```tsx
+import { UI Sniper, type Annotation } from 'ui-sniper';
+
+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 />
+      <UI Sniper
+        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 of document (absolute) OR viewport (if isFixed)
+  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;
+};
+```
+
+> **Note:** This is a simplified type. The full type includes additional fields for Agent Sync (`url`, `status`, `thread`, `reactComponents`, etc.). See [hara-xy.com/schema](https://hara-xy.com/schema) for the complete schema.
+
+## How it works
+
+UI Sniper 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 [hara-xy.com](https://hara-xy.com)
+
+## License
+
+© 2026 Benji Taylor
+
+Licensed under PolyForm Shield 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,317 @@
+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;
+    reactComponents?: string;
+    sourceFile?: string;
+    drawingIndex?: number;
+    elementBoundingBoxes?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    kind?: "feedback" | "placement" | "rearrange";
+    placement?: {
+        componentType: string;
+        width: number;
+        height: number;
+        scrollY: number;
+        text?: string;
+    };
+    rearrange?: {
+        selector: string;
+        label: string;
+        tagName: string;
+        originalRect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        currentRect: {
+            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 = {
+    selector: string;
+    comment: string;
+    selectedText?: string;
+};
+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;
+    /** 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;
+    /** Custom class name applied to the toolbar container. Use to adjust positioning or z-index. */
+    className?: string;
+};
+/** Alias for PageFeedbackToolbarCSSProps */
+type UISniperProps = PageFeedbackToolbarCSSProps;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, className: userClassName, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+
+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;
+    /** 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) */
+    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>;
+}
+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, ...props }: {
+    size?: number;
+} & React.SVGProps<SVGSVGElement>) => 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, tint, }: {
+    size?: number;
+    copied?: boolean;
+    tint?: string;
+}) => 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;
+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 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;
+declare const IconLayout: ({ size }: {
+    size?: number;
+}) => 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;
+/**
+ * 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;
+
+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 { 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, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, PageFeedbackToolbarCSS as UISniper, type UISniperProps, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations };