@useclickly/react 0.2.0 → 1.0.1

package/README.md

@@ -1,15 +1,19 @@
 # @useclickly/react
 
+[![npm version](https://img.shields.io/npm/v/@useclickly/react.svg?color=0ea5e9)](https://www.npmjs.com/package/@useclickly/react)
+[![license](https://img.shields.io/npm/l/@useclickly/react.svg?color=10b981)](../../LICENSE)
+
 > Click-to-annotate dev toolbar for React. Generates prompts your AI coding agent can actually act on.
 
-Drop `<Clickly />` into your React app (dev only). A small floating action button appears in the bottom-right. Open it, click any element, write a comment — copy a perfectly-formatted markdown prompt into Claude Code / Cursor / Codex.
+Drop `<Clickly />` into your React app (dev only). A small floating action button appears in the bottom-right corner. Open it, click any element, write a comment — copy a perfectly-formatted markdown prompt into **Claude Code**, **Cursor**, **Codex**, or any MCP-aware tool.
 
 ## Install
 
 ```bash
 npm install -D @useclickly/react
-# or: pnpm add -D @useclickly/react
-# or: yarn add -D @useclickly/react
+# or:
+pnpm add -D @useclickly/react
+yarn add -D @useclickly/react
 ```
 
 ## Use
@@ -27,20 +31,30 @@ export default function App() {
 }
 ```
 
-That's it.
+That's it. The component returns `null` on the server (safe under SSR / Next App Router) and ships with `"use client"` already baked into the bundle.
+
+## What it does
+
+| Mode | How |
+|---|---|
+| **Single** | Click any element → popup with comment box |
+| **Multi-select** | Press `2` or shift-click to pin elements, hit **Annotate (N)** when done |
+| **Area drag** | Press `3`, drag a rectangle, every intersecting element gets pinned |
+| **Persistent pins** | Annotated elements stay numbered on the page across page interactions |
+| **Auto-copy** | Submitting an annotation copies markdown to clipboard (toggleable) |
+| **Settings** | Output detail tier, React component info, marker colour — all in the gear menu |
+
+## What gets captured
 
-## Features
+For every selected element, Clickly automatically collects:
 
-- **Click any element** → annotation popup with comment box
-- **Multi-select** — shift-click to pin elements, hit `Annotate (N)` when done
-- **Area drag** — press `3`, drag a rectangle, every intersecting element gets pinned
-- **Persistent numbered pins** on every annotated element
-- **CSS selectors + DOM paths + computed styles** captured automatically
-- **Auto-copy markdown** to clipboard on every Add
-- **AFS 1.1 schema** — wire-compatible with Agentation, parseable by any MCP-aware agent
-- **Crosshair cursor + text-select disabled** while inspecting
-- **Shadow DOM** for zero CSS leakage in either direction
-- **`"use client"` baked in** — Next.js App Router just works
+- Short + full CSS selector (`section.hero > button.cta`)
+- Computed styles (curated by detail tier)
+- Bounding box + position (handles `fixed` / `sticky`)
+- ARIA / `role` / `tabindex` / `title`
+- Visible nearby text (truncated)
+- **React component tree** (`App > Dashboard > Button`) via Fiber walk
+- **Source file + line** (`src/Button.tsx:42`) on Vite/Next — instant grep target
 
 ## Keyboard shortcuts
 
@@ -53,17 +67,51 @@ That's it.
 | `C` | Copy all annotations as markdown |
 | `X` | Clear all annotations |
 
+## Props
+
+All optional; `<Clickly />` works with zero config.
+
+```ts
+interface ClicklyProps {
+  className?: string;
+  endpoint?: string;          // MCP server URL — see @useclickly/mcp-server
+  sessionId?: string;
+  onAnnotationAdd?: (id: string) => void;
+  onAnnotationDelete?: (id: string) => void;
+  onAnnotationsClear?: () => void;
+  onCopy?: (markdown: string) => void;
+  onSessionCreated?: (sessionId: string) => void;
+}
+```
+
+## Output
+
+```md
+## Annotation #1
+**Element:** `button.cta.primary`
+**Path:** `body > main > section.hero > button.cta.primary`
+**Position:** 120px, 480px (200×48px)
+**Source:** `src/components/Hero.tsx:42`
+**React:** App > LandingPage > HeroSection > CTAButton
+**Feedback:** Button is cut off on mobile viewport
+```
+
+Configurable via the settings popover: `compact` (one-liner) → `standard` → `detailed` → `forensic` (full computed styles).
+
+The shape is **[AFS 1.1](https://agentation.dev/schema/annotation.v1.1.json)**-compatible — every MCP-aware agent can parse it.
+
 ## Requirements
 
 - React 18+ or 19+
 - Browser environment (no SSR; component returns `null` server-side)
 - Desktop only — touch / mobile is not optimised
+- **Not for React Native** — see the main [README](https://github.com/useclickly/clickly#react-native)
+
+## Advanced
 
-## Links
+For framework-agnostic engine access — building your own UI on top of Clickly's selection + metadata — see [`@useclickly/core`](https://www.npmjs.com/package/@useclickly/core).
 
-- Main repo and docs: [github.com/clickly/clickly](https://github.com/clickly/clickly)
-- AFS 1.1 schema: see `@useclickly/core`
-- MCP server (for agent integration): see `@useclickly/mcp-server`
+For agent integration over MCP — your agent reading/responding to annotations directly — see [`@useclickly/mcp-server`](https://www.npmjs.com/package/@useclickly/mcp-server).
 
 ## License
 

package/dist/Clickly.d.ts

@@ -0,0 +1,25 @@
+export interface ClicklyProps {
+    /** Custom class on the host element (for z-index / positioning overrides). */
+    className?: string;
+    /** Optional MCP server endpoint, e.g. "http://localhost:4747". */
+    endpoint?: string;
+    /** Join an existing MCP session by ID. */
+    sessionId?: string;
+    onAnnotationAdd?: (id: string) => void;
+    onAnnotationDelete?: (id: string) => void;
+    onAnnotationsClear?: () => void;
+    onCopy?: (markdown: string) => void;
+    onSessionCreated?: (sessionId: string) => void;
+}
+/**
+ * Mount once near the root of your React app. Dev-only by convention:
+ *
+ * ```tsx
+ * {process.env.NODE_ENV === "development" && <Clickly />}
+ * ```
+ *
+ * Renders a small floating button (FAB) in the bottom-right corner.
+ * Click it (or press `⌘/Ctrl+Shift+F`) to open the full toolbar.
+ */
+export declare function Clickly({ className }?: ClicklyProps): import("react").ReactPortal | null;
+//# sourceMappingURL=Clickly.d.ts.map

package/dist/Clickly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Clickly.d.ts","sourceRoot":"","sources":["../src/Clickly.tsx"],"names":[],"mappings":"AAYA,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,gBAAgB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AASD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,EAAE,SAAS,EAAE,GAAE,YAAiB,sCA6EvD"}

package/dist/hooks/useDraggable.d.ts

@@ -0,0 +1,28 @@
+export interface Position {
+    x: number;
+    y: number;
+}
+interface DraggableApi {
+    position: Position;
+    setPosition: (p: Position) => void;
+    /** Spread onto the drag handle. */
+    handleProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        style: React.CSSProperties;
+    };
+    isDragging: boolean;
+}
+/**
+ * In-session drag positioning. Position resets to `defaultPos` whenever
+ * the consumer remounts (e.g. toolbar collapse → expand cycle).
+ *
+ * We deliberately do NOT persist across reloads — users expect the
+ * toolbar to come back at its default anchor, not where they last left
+ * it three sessions ago. Drag is for "get out of my way right now".
+ */
+export declare function useDraggable(defaultPos: Position, size: {
+    width: number;
+    height: number;
+}): DraggableApi;
+export {};
+//# sourceMappingURL=useDraggable.d.ts.map

package/dist/hooks/useDraggable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDraggable.d.ts","sourceRoot":"","sources":["../../src/hooks/useDraggable.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;IACnC,mCAAmC;IACnC,WAAW,EAAE;QACX,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QAC/C,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;KAC5B,CAAC;IACF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,QAAQ,EACpB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC,YAAY,CAqDd"}

package/dist/hooks/usePersistedState.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `useState` + localStorage. Plain JSON-serializable values only.
+ * Safe under SSR (returns `initial` on first render).
+ */
+export declare function usePersistedState<T>(key: string, initial: T): [T, (next: T | ((prev: T) => T)) => void];
+//# sourceMappingURL=usePersistedState.d.ts.map

package/dist/hooks/usePersistedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePersistedState.d.ts","sourceRoot":"","sources":["../../src/hooks/usePersistedState.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,GACT,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAqB3C"}