@martin0309205/click-annotate
v0.2.0
Published
Click any DOM element → annotate it → generate a rich, copy-pasteable prompt for code agents.
Maintainers
martin0309205Readme
@martin0309205/click-annotate
Click any DOM element → annotate it → generate a rich, copy-pasteable prompt for code agents (Claude, Cursor, GPT).
Zero per-component wraps. Wrap your app once, hit "Annotate", click anything, write a note. Hit Copy — the prompt lands in your clipboard with full context: selector, classes, ancestry, position, role, aria-label.
Install
npm install @martin0309205/click-annotatePeers: react, react-dom, framer-motion, @hugeicons/react, @hugeicons/core-free-icons.
Use
// app/layout.tsx
import { AnnotateProvider } from "@martin0309205/click-annotate";
export default function RootLayout({ children }) {
return (
<html>
<body>
<AnnotateProvider>{children}</AnnotateProvider>
</body>
</html>
);
}That's it. A floating "Annotate" button appears bottom-right. Click it, then click any element on your page.
Production safety: by default the provider is enabled only in development (process.env.NODE_ENV !== "production"). In a production build it short-circuits to a passthrough — no listeners, no UI, no localStorage writes. Override with the enabled prop:
<AnnotateProvider enabled={true}>{children}</AnnotateProvider> // force on (e.g. preview env)
<AnnotateProvider enabled={false}>{children}</AnnotateProvider> // force offWorkflow
- Toggle Annotate mode (bottom-right floating button).
- Hover over any DOM element — see a label with
tag.classes · "text content". - Click → popover opens with a textarea.
- Type your feedback, save (Cmd/Ctrl + Enter).
- Repeat across your pages — annotations persist via
localStorage. - Click View prompt → see all annotations + the generated prompt.
- Click Copy entire prompt — the prompt is in your clipboard, and the annotations auto-archive (so the next prompt starts fresh).
- Paste in your code agent.
What gets captured
For every clicked element:
- Tag (
<button>,<div>,<h2>) - Stable selector (
button.bg-brand.h-11.px-5) - All Tailwind / utility classes
- Truncated text content
- 4-deep parent chain (ancestry)
- On-screen rect (x, y, width, height)
- ARIA role + aria-label
- Page pathname
Generated prompt format
Fix the following items. Each item shows the clicked element with its full
context — selector, classes, ancestry, on-screen position, and the change
requested. Apply the fixes in order, then summarise what you fixed.
## /design-system/foundations
### 1. `<button>` — "Book the audit"
- **Selector**: `button.bg-brand.text-text-on-brand.h-11.px-5`
- **Classes**: `astry-button.inline-flex.items-center.justify-center...`
- **Ancestry**: `header.h-16 > div.flex > nav > button`
- **Rect**: x=1280, y=120, 156×44px
- **Note**: too big relative to the logo, should be size smAPI
import {
AnnotateProvider, // wrap your app
useAnnotate, // hook for advanced control
type Annotation, // captured annotation type
} from "@martin0309205/click-annotate";The provider auto-mounts the toolbar + overlay + drawer. To opt out, render null from a custom toolbar slot (advanced).
Persistence
Annotations live in localStorage under astry-ds-annotations-v2. They survive page navigation, refreshes, and tab close.
Archiving
When you copy a prompt, all active annotations are auto-archived. Archived items show in a separate fade-out section in the drawer with line-through styling. Re-archive anytime, delete forever, or clear all archived in one click.
Ignoring elements
Tag any DOM subtree with data-annotate-ignore and the system won't react to clicks or hover on it. Useful for dev overlays, third-party widgets, etc.
Keyboard
Escape→ close popover, then exit annotate modeCmd/Ctrl + Enter→ save annotation
Versions
- v0.1 — initial release. Auto-detect, archive workflow, rich prompt generation.
License
MIT