@trungtnm/agent-annotator 0.0.0-stage β†’ 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 trungtnm
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,190 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # agent-annotator
4
+
5
+ **Point at your running UI. Say what should change. Your coding agent already knows where.**
6
+
7
+ A development-only overlay for React apps. Click any element, type what's wrong, and copy **one
8
+ prompt** that gives Claude Code, Codex or Cursor the exact **file and line** of the JSX, the
9
+ component chain and the live props: no more "the button, top right, the grey one".
10
+
11
+ [![CI](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml/badge.svg)](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml)
12
+ ![React 19](https://img.shields.io/badge/React-19-61dafb)
13
+ ![Next.js and Vite](https://img.shields.io/badge/works%20with-Next.js%20%C2%B7%20Vite-6d4aff)
14
+ ![License: MIT](https://img.shields.io/badge/license-MIT-green)
15
+
16
+ <img src="docs/media/hero.gif" alt="Commenting on a dashboard, copying the prompt, and marking up a screenshot" width="860" />
17
+
18
+ <sub>β–Ά <a href="docs/media/demo.mp4">Watch the 70-second walkthrough</a></sub>
19
+
20
+ </div>
21
+
22
+ ## Why
23
+
24
+ You see the problem in the browser; your agent sees only the repository. Describing *where*
25
+ something is costs more words than describing *what* is wrong, and the agent still guesses
26
+ which of four `<Button>`s you meant.
27
+
28
+ agent-annotator closes that gap from where you already are, the running app:
29
+
30
+ | | |
31
+ |---|---|
32
+ | 🎯 **Exact source, not a guess** | Each comment names the JSX file:line that rendered the element, mapped through your dev server's source maps (Next.js webpack and Turbopack, Vite). |
33
+ | 🧩 **Context an agent can act on** | Component chain, role and accessible name, selector, styles, and a snapshot of the nearest components' props and state. |
34
+ | πŸ“ **One prompt for many comments** | Comment on ten things across five pages, then paste once. The prompt tells the agent how to work through them. |
35
+ | πŸ–ΌοΈ **Screenshots that explain themselves** | Capture the tab with every comment drawn in, then add callouts, arrows, rulers, crop, and pixelate in a Shottr-style editor. |
36
+ | πŸ”’ **Stays on your machine** | Personal data is redacted; the prompt and the image go to your clipboard or disk; nothing is sent anywhere. Not in your production bundle. |
37
+
38
+ ## Quick start
39
+
40
+ ```bash
41
+ pnpm add -D @trungtnm/agent-annotator
42
+ # before the first npm release:
43
+ pnpm add -D github:trungtnm/agent-annotator#v0.2.0
44
+ ```
45
+
46
+ **Next.js (App Router)**: a client component in the root layout, loaded in development only:
47
+
48
+ ```tsx
49
+ // app/dev-annotator.tsx
50
+ 'use client';
51
+ import dynamic from 'next/dynamic';
52
+
53
+ const DevAnnotator =
54
+ process.env.NODE_ENV === 'development'
55
+ ? dynamic(() => import('@trungtnm/agent-annotator').then((m) => m.DevAnnotator), { ssr: false })
56
+ : null;
57
+
58
+ export function DevAnnotatorMount() {
59
+ return DevAnnotator && <DevAnnotator appName="web" />;
60
+ }
61
+ ```
62
+
63
+ Then render `<DevAnnotatorMount />` inside `<body>` in `app/layout.tsx`. [Full Next.js guide β†’](docs/guide-nextjs.md)
64
+
65
+ **Vite**:
66
+
67
+ ```tsx
68
+ // main.tsx
69
+ const DevAnnotator = import.meta.env.DEV
70
+ ? lazy(() => import('@trungtnm/agent-annotator').then((m) => ({ default: m.DevAnnotator })))
71
+ : null;
72
+
73
+ // …next to <App />:
74
+ {DevAnnotator && <Suspense fallback={null}><DevAnnotator appName="web" /></Suspense>}
75
+ ```
76
+
77
+ [Full Vite guide β†’](docs/guide-vite.md)
78
+
79
+ Start your dev server, press **Alt+Shift+C**, click something.
80
+
81
+ ## A tour
82
+
83
+ Everything lives in one toolbar, bottom right, which folds into a single button when you need the
84
+ space:
85
+
86
+ <img src="docs/media/toolbar.png" alt="The toolbar: comment mode, pause, show comments, screenshot, list, copy prompt" width="430" />
87
+
88
+ ### 1. Click anything and say what should change
89
+
90
+ <img src="docs/media/comment.png" alt="Comment editor open on the New order button" width="860" />
91
+
92
+ A click comments on an element. **Select text** to comment on a passage, **⌘/Ctrl+click** to put
93
+ several elements under one comment, **Shift+drag** to mark an area. **Alt+click** still uses the
94
+ page, so you can open the menu you want to comment on.
95
+
96
+ ### 2. See every comment where it belongs
97
+
98
+ <img src="docs/media/comments.png" alt="Three comments drawn next to their elements" width="860" />
99
+
100
+ Comments stay on their elements as you scroll and survive navigation and reloads. Show them as
101
+ numbered pins or in full; the list in the toolbar holds every comment, from this page and others.
102
+
103
+ ### 3. Copy one prompt and paste it into your agent
104
+
105
+ <img src="docs/media/prompt.png" alt="The copied prompt in a coding agent" width="860" />
106
+
107
+ Per comment: the page, the element and its text, its role, the section it sits in, a selector,
108
+ the **JSX file:line**, the component chain with where each one is rendered, its current styles,
109
+ and props/state with personal data replaced by `[redacted]`.
110
+ [See a full prompt β†’](docs/prompt-format.md)
111
+
112
+ ### 4. Capture and mark up
113
+
114
+ <img src="docs/media/editor.png" alt="Screenshot editor with a callout, an arrow, a ruler and pixelated emails" width="860" />
115
+
116
+ One click captures the tab with every comment shown. Then: **callouts** that point (drag from
117
+ the thing to where the text goes), arrows, boxes, highlights, pen, a **ruler** in CSS pixels,
118
+ **crop**, and **pixelate** for anything private. Marks can go past the edge and the picture
119
+ grows to fit. Copy or save the PNG. [Editor guide β†’](docs/screenshot-editor.md)
120
+
121
+ ## Keyboard
122
+
123
+ | Overlay | |
124
+ |---|---|
125
+ | **Alt+Shift+C** | Comment mode on/off |
126
+ | Click · select text · **⌘/Ctrl**+click · **Shift**+drag | Comment on an element · a passage · several elements · an area |
127
+ | **Alt**+click | Use the page normally |
128
+ | **⌘/Ctrl+Enter** · Esc | Save the comment · close the editor, then leave comment mode |
129
+
130
+ The screenshot editor has its own shortcuts (V A T R H P M C B, ⌘Z, ⌘C, ⌘S…): every button's
131
+ tooltip shows them, and [the editor guide](docs/screenshot-editor.md) lists them all.
132
+
133
+ ## Requirements
134
+
135
+ - **React 19** in development mode. Source locations come from React 19's `_debugStack`; a
136
+ production build has none, which is also why the overlay belongs in dev only.
137
+ - **Next.js 15** (webpack or Turbopack) or **Vite**, or any dev server that exposes source maps
138
+ beside its scripts or inline. Without one, the prompt still names the component chain and
139
+ gives the bundled line, flagged as approximate.
140
+ - Screenshots use the Screen Capture API: Chromium browsers on `localhost` or `https`. The browser
141
+ asks once per capture; choose **This tab**.
142
+
143
+ ## Props
144
+
145
+ | Prop | | |
146
+ |---|---|---|
147
+ | `appName` | required | Names the app in the prompt and the screenshot file, and keys the saved comments. |
148
+ | `appDir` | optional | The app's folder from the repo root (`apps/web`), so prompt paths open from the root in a monorepo. |
149
+ | `resolveFrames` | optional | Replace how stack frames are mapped to source; see `createNextResolver`. |
150
+ | `captureScreen` | optional | Replace how the tab is captured (tests, automation). |
151
+
152
+ ## Privacy
153
+
154
+ - Values under keys that name personal data (phone, email, name, address, national ID, bank
155
+ account, password, token and similar) are replaced with `[redacted]` before they reach the
156
+ prompt, and so is text that looks like an email address, a Vietnamese phone number or a
157
+ 12-digit Vietnamese citizen ID. Patterns for other countries are welcome.
158
+ - The element you click keeps its visible text: it is what you pointed at. Untick
159
+ **Include props/state** to leave data out entirely, and pixelate screenshots before sharing.
160
+ - Nothing is uploaded. Comments live in `sessionStorage`; preferences in `localStorage`.
161
+
162
+ ## FAQ
163
+
164
+ **Does it ship to production?** Not if you mount it as shown: `process.env.NODE_ENV` /
165
+ `import.meta.env.DEV` is a constant in a production build, so the import is dropped.
166
+
167
+ **Which agent does the prompt target?** Any. It is plain Markdown that tells the agent what each
168
+ field means and how to work through the comments.
169
+
170
+ **Does it work with React 18?** No: React 18 has no `_debugStack`. React 19 only.
171
+
172
+ **Can I try it without installing?** Clone the repo and run the demo:
173
+ `pnpm install && pnpm --dir examples/demo install && pnpm --dir examples/demo dev`.
174
+
175
+ ## Develop
176
+
177
+ ```bash
178
+ pnpm install
179
+ pnpm check # lint, typecheck, test, build
180
+ pnpm --dir examples/demo dev # the demo app on http://localhost:5199, running src/ directly
181
+ pnpm media:shots # regenerate docs/media screenshots (demo must be running)
182
+ pnpm media:video # regenerate demo.mp4 and hero.gif (needs ffmpeg)
183
+ ```
184
+
185
+ `dist/` is committed so the repository works as a git dependency; CI fails when it does not
186
+ match the source, so run `pnpm build` before committing.
187
+
188
+ ## License
189
+
190
+ [MIT](LICENSE)
@@ -0,0 +1,183 @@
1
+ import { ReactNode } from 'react';
2
+
3
+ /**
4
+ * Taking the screenshot, and getting it out of the browser.
5
+ *
6
+ * The capture is the tab itself, through the Screen Capture API: the browser asks once
7
+ * ("share this tab?") and hands back real pixels β€” canvases, videos, cross-origin images
8
+ * and fonts exactly as rendered, which a DOM-to-image library can only approximate. Between
9
+ * the permission and the grab, `prepare` gets the page ready: the tool's own controls away,
10
+ * every comment shown in full.
11
+ */
12
+ type ScreenCapture = (prepare: () => Promise<void>) => Promise<HTMLCanvasElement>;
13
+
14
+ /**
15
+ * Where in the source an element's JSX is written.
16
+ *
17
+ * React 19 dropped `fiber._debugSource` (the file:line a Babel plugin used to stamp on
18
+ * every element). What it keeps, in development, is `fiber._debugStack`: an Error created
19
+ * when the element was created, so its stack names the render function β€” and the line β€”
20
+ * that wrote the JSX. Those frames point at bundled code (`webpack-internal:///…`), so
21
+ * they are sent to the dev server's own `/__nextjs_original-stack-frames`, the endpoint
22
+ * Next's error overlay uses to map frames back through the source maps. Under Turbopack
23
+ * that endpoint rejects browser chunk URLs, so those frames go through the chunk's own
24
+ * source map instead (`source-map.ts`).
25
+ *
26
+ * That endpoint is Next internals, not an API. Everything here degrades instead of
27
+ * failing: no answer means the frame's own file and bundled line, flagged as such.
28
+ */
29
+ interface RawFrame {
30
+ readonly file: string;
31
+ readonly line1: number;
32
+ readonly column1: number;
33
+ readonly methodName: string;
34
+ }
35
+ interface SourceLocation {
36
+ /**
37
+ * Relative to the app's directory when Next mapped it (webpack), absolute when the chunk's
38
+ * source map did (Turbopack), else the bundled URL or path.
39
+ */
40
+ readonly file: string;
41
+ readonly line: number;
42
+ readonly column: number | null;
43
+ /** True when the line is the ORIGINAL source line, false when it is the bundled one. */
44
+ readonly mapped: boolean;
45
+ /** Next flagged the frame as framework or library code: not where an edit belongs. */
46
+ readonly ignored?: boolean;
47
+ }
48
+ type FrameResolver = (frames: readonly RawFrame[]) => Promise<SourceLocation[]>;
49
+ /**
50
+ * Maps frames through Next's dev server in ONE request. Always resolves, one location per
51
+ * frame, in order: a frame Next could not map, or any failure of the request, falls back
52
+ * to the frame as bundled.
53
+ */
54
+ declare function createNextResolver(fetchImpl?: typeof fetch): FrameResolver;
55
+
56
+ interface DevAnnotatorProps {
57
+ /** Names the app in the prompt and keys the saved comments (`web`, `admin`). */
58
+ readonly appName: string;
59
+ /** The app's directory from the repo root, so source paths in the prompt open as-is. */
60
+ readonly appDir?: string;
61
+ /** Overrides how stack frames are mapped to source; tests pass one, apps never do. */
62
+ readonly resolveFrames?: FrameResolver;
63
+ /** Overrides how the tab is captured; tests pass one, apps never do. */
64
+ readonly captureScreen?: ScreenCapture;
65
+ }
66
+ /**
67
+ * Development-only overlay: a floating button switches on "comment mode". In it, a click
68
+ * pins a comment to an element, a text selection to a passage, Cmd/Ctrl+click gathers
69
+ * several elements under one comment and Shift+drag marks an area β€” and the page sees
70
+ * none of it. "Copy prompt" puts every comment, with what the tool learned about its
71
+ * elements, on the clipboard as one Markdown prompt for a coding agent.
72
+ *
73
+ * Comments survive client-side navigation (this component lives in the root layout) and
74
+ * a full reload (sessionStorage), so one request can span several pages.
75
+ */
76
+ declare function DevAnnotator(props: DevAnnotatorProps): ReactNode;
77
+
78
+ type Snapshot = null | boolean | number | string | readonly Snapshot[] | {
79
+ readonly [key: string]: Snapshot;
80
+ };
81
+
82
+ /**
83
+ * Everything one comment records about its element, taken at the moment of the click.
84
+ * "The current value of the data" is the value the developer was LOOKING at when they
85
+ * noticed the problem, so it is captured then, not when the prompt is copied β€” by which
86
+ * time they may have navigated away and back.
87
+ */
88
+ interface ElementCapture {
89
+ readonly page: {
90
+ readonly url: string;
91
+ readonly pathname: string;
92
+ readonly search: string;
93
+ readonly title: string;
94
+ };
95
+ readonly element: {
96
+ readonly tag: string;
97
+ readonly opening: string;
98
+ readonly selector: string;
99
+ readonly text: string;
100
+ readonly value: string | null;
101
+ readonly rect: {
102
+ readonly x: number;
103
+ readonly y: number;
104
+ readonly width: number;
105
+ readonly height: number;
106
+ };
107
+ readonly styles: Readonly<Record<string, string>>;
108
+ /** Role, accessible name and ARIA states: `button "Save" (disabled)`. */
109
+ readonly accessibility: string | null;
110
+ /** Page heading and enclosing section labels: `Debt batches β€Ί New batch`. */
111
+ readonly section: string | null;
112
+ /** The text of the siblings either side, to tell identical elements apart. */
113
+ readonly nearby: string | null;
114
+ };
115
+ readonly viewport: {
116
+ readonly width: number;
117
+ readonly height: number;
118
+ readonly devicePixelRatio: number;
119
+ };
120
+ /** Where the element's own JSX is written: usually the line to edit. */
121
+ readonly jsx: SourceLocation | null;
122
+ /** Enclosing components, nearest first, each with where IT was rendered from. */
123
+ readonly components: ReadonlyArray<{
124
+ readonly name: string;
125
+ readonly renderedAt: SourceLocation | null;
126
+ }>;
127
+ /** Props and stateful hooks of the nearest components, PII redacted. */
128
+ readonly data: ReadonlyArray<{
129
+ readonly component: string;
130
+ readonly props: Snapshot;
131
+ readonly state: Snapshot;
132
+ }>;
133
+ }
134
+
135
+ interface Rect {
136
+ readonly x: number;
137
+ readonly y: number;
138
+ readonly width: number;
139
+ readonly height: number;
140
+ }
141
+
142
+ /**
143
+ * What one comment is about:
144
+ * - `element`: one clicked element;
145
+ * - `text`: a passage selected inside an element (the element is the target);
146
+ * - `group`: several elements picked with Cmd/Ctrl+click, one request for all of them;
147
+ * - `area`: a dragged region β€” the first target is the element holding the region, the
148
+ * rest are the elements wholly inside it (none, for a comment on empty space).
149
+ */
150
+ type AnnotationKind = 'element' | 'text' | 'group' | 'area';
151
+ interface Annotation {
152
+ readonly id: string;
153
+ readonly kind: AnnotationKind;
154
+ readonly comment: string;
155
+ readonly createdAt: string;
156
+ readonly targets: readonly ElementCapture[];
157
+ /** `text` only: the selected passage, screened for personal data. */
158
+ readonly selectedText?: string;
159
+ /** `area` only: the dragged region in viewport pixels at the time of the comment. */
160
+ readonly area?: Rect;
161
+ /**
162
+ * `area` only: the same region relative to the container's top-left corner, so it can be
163
+ * drawn back over the page after scrolling or a reload. Not part of the prompt.
164
+ */
165
+ readonly areaInContainer?: Rect;
166
+ }
167
+ interface PromptOptions {
168
+ /** Shown in the heading: which app the comments are about. */
169
+ readonly appName: string;
170
+ /** The app's directory from the repo root (`apps/web`); prefixes every source path. */
171
+ readonly appDir?: string | undefined;
172
+ /** Include the props/state snapshots. */
173
+ readonly includeData: boolean;
174
+ readonly now: Date;
175
+ }
176
+ /**
177
+ * The Markdown handed to the coding agent. It is written FOR the agent: what to do comes
178
+ * first, then one section per comment with the facts it needs to find the code without
179
+ * searching β€” the source line before the selector, the selector before the text.
180
+ */
181
+ declare function buildPrompt(annotations: readonly Annotation[], options: PromptOptions): string;
182
+
183
+ export { type Annotation, DevAnnotator, type DevAnnotatorProps, type ElementCapture, type FrameResolver, type PromptOptions, type ScreenCapture, type SourceLocation, buildPrompt, createNextResolver };