@trungtnm/agent-annotator 0.0.0-stage β 0.3.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 +21 -0
- package/README.md +215 -2
- package/dist/index.d.ts +232 -0
- package/dist/index.js +4054 -0
- package/dist/index.js.map +1 -0
- package/package.json +78 -4
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,216 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml)
|
|
12
|
+
[](https://www.npmjs.com/package/@trungtnm/agent-annotator)
|
|
13
|
+

|
|
14
|
+

|
|
15
|
+

|
|
16
|
+
|
|
17
|
+
<img src="docs/media/hero.gif" alt="Commenting on a dashboard, carrying on on a second page with personal data redacted, copying the prompt, and marking up a screenshot" width="860" />
|
|
18
|
+
|
|
19
|
+
<sub>βΆ <a href="docs/media/demo.mp4">Watch the 100-second walkthrough</a></sub>
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
|
|
23
|
+
## Why
|
|
24
|
+
|
|
25
|
+
You see the problem in the browser; your agent sees only the repository. Describing *where*
|
|
26
|
+
something is costs more words than describing *what* is wrong, and the agent still guesses
|
|
27
|
+
which of four `<Button>`s you meant.
|
|
28
|
+
|
|
29
|
+
agent-annotator closes that gap from where you already are, the running app:
|
|
30
|
+
|
|
31
|
+
| | |
|
|
32
|
+
|---|---|
|
|
33
|
+
| π― **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). |
|
|
34
|
+
| π§© **Context an agent can act on** | Component chain, role and accessible name, selector, styles, and a snapshot of the nearest components' props and state. |
|
|
35
|
+
| π **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. |
|
|
36
|
+
| πΌοΈ **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. |
|
|
37
|
+
| π **Stays on your machine** | Personal data is redacted, with country formats and your own patterns; the prompt and the image go to your clipboard or disk; nothing is sent anywhere. Not in your production bundle. |
|
|
38
|
+
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pnpm add -D @trungtnm/agent-annotator # or: npm i -D / yarn add -D / bun add -d
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
**Next.js (App Router)**: a client component in the root layout, loaded in development only:
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
// app/dev-annotator.tsx
|
|
49
|
+
'use client';
|
|
50
|
+
import dynamic from 'next/dynamic';
|
|
51
|
+
|
|
52
|
+
const DevAnnotator =
|
|
53
|
+
process.env.NODE_ENV === 'development'
|
|
54
|
+
? dynamic(() => import('@trungtnm/agent-annotator').then((m) => m.DevAnnotator), { ssr: false })
|
|
55
|
+
: null;
|
|
56
|
+
|
|
57
|
+
export function DevAnnotatorMount() {
|
|
58
|
+
return DevAnnotator && <DevAnnotator appName="web" />;
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Then render `<DevAnnotatorMount />` inside `<body>` in `app/layout.tsx`. [Full Next.js guide β](docs/guide-nextjs.md)
|
|
63
|
+
|
|
64
|
+
**Vite**:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
// main.tsx
|
|
68
|
+
const DevAnnotator = import.meta.env.DEV
|
|
69
|
+
? lazy(() => import('@trungtnm/agent-annotator').then((m) => ({ default: m.DevAnnotator })))
|
|
70
|
+
: null;
|
|
71
|
+
|
|
72
|
+
// β¦next to <App />:
|
|
73
|
+
{DevAnnotator && <Suspense fallback={null}><DevAnnotator appName="web" /></Suspense>}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
[Full Vite guide β](docs/guide-vite.md)
|
|
77
|
+
|
|
78
|
+
Start your dev server, press **Alt+Shift+C**, click something.
|
|
79
|
+
|
|
80
|
+
## A tour
|
|
81
|
+
|
|
82
|
+
Everything lives in one toolbar, bottom right, which folds into a single button when you need the
|
|
83
|
+
space:
|
|
84
|
+
|
|
85
|
+
<img src="docs/media/toolbar.png" alt="The toolbar: comment mode, pause, show comments, screenshot, redaction settings, list, copy prompt" width="430" />
|
|
86
|
+
|
|
87
|
+
### 1. Click anything and say what should change
|
|
88
|
+
|
|
89
|
+
<img src="docs/media/comment.png" alt="Comment editor open on the New order button" width="860" />
|
|
90
|
+
|
|
91
|
+
A click comments on an element. **Select text** to comment on a passage, **β/Ctrl+click** to put
|
|
92
|
+
several elements under one comment, **Shift+drag** to mark an area. **Alt+click** still uses the
|
|
93
|
+
page, so you can open the menu you want to comment on.
|
|
94
|
+
|
|
95
|
+
### 2. See every comment where it belongs
|
|
96
|
+
|
|
97
|
+
<img src="docs/media/comments.png" alt="Three comments drawn next to their elements" width="860" />
|
|
98
|
+
|
|
99
|
+
Comments stay on their elements as you scroll. Show them as numbered pins or in full.
|
|
100
|
+
|
|
101
|
+
### 3. Keep going across pages
|
|
102
|
+
|
|
103
|
+
<img src="docs/media/pages.png" alt="The comment list on the Customers page, with three comments marked other page" width="380" />
|
|
104
|
+
|
|
105
|
+
One request often spans several screens. Navigate as you normally would (**Alt**+click a link
|
|
106
|
+
while comment mode is on), and keep commenting. Comments survive client-side navigation and
|
|
107
|
+
full reloads. Each pin shows only on the page it was made on, and the list marks the rest
|
|
108
|
+
**other page**. The copied prompt covers every page and names each comment's path, so the
|
|
109
|
+
agent knows that comment 4 is about `/customers` and comment 1 about `/`.
|
|
110
|
+
|
|
111
|
+
### 4. Keep personal data out of the prompt
|
|
112
|
+
|
|
113
|
+
<img src="docs/media/redaction.png" alt="Redaction settings: an on/off switch, Vietnam, United States and Singapore number formats, and a box for your own patterns" width="380" />
|
|
114
|
+
|
|
115
|
+
Dev databases are often full of copied customer data, and the prompt goes to an AI service.
|
|
116
|
+
The props, state and page text in each comment are screened as it is made. Values under keys
|
|
117
|
+
like `phone`, `email`, `address` or `token` become `[redacted]`, and so do e-mail addresses
|
|
118
|
+
and phone and ID numbers inside any text. The **shield** button opens the settings. There
|
|
119
|
+
you choose which countries' formats to catch (**Vietnam**, the **United States**,
|
|
120
|
+
**Singapore**), add your own regular expressions, or switch redaction off. The `redaction`
|
|
121
|
+
prop sets the defaults for your team. [Redaction guide β](docs/redaction.md)
|
|
122
|
+
|
|
123
|
+
### 5. Copy one prompt and paste it into your agent
|
|
124
|
+
|
|
125
|
+
<img src="docs/media/prompt.png" alt="The copied prompt in a coding agent" width="860" />
|
|
126
|
+
|
|
127
|
+
Per comment, from every page: the page, the element and its text, its role, the section it sits in, a selector,
|
|
128
|
+
the **JSX file:line**, the component chain with where each one is rendered, its current styles,
|
|
129
|
+
and props/state with personal data replaced by `[redacted]` ([redaction settings](docs/redaction.md)).
|
|
130
|
+
[See a full prompt β](docs/prompt-format.md)
|
|
131
|
+
|
|
132
|
+
### 6. Capture and mark up
|
|
133
|
+
|
|
134
|
+
<img src="docs/media/editor.png" alt="Screenshot editor with a callout, an arrow, a ruler and pixelated emails" width="860" />
|
|
135
|
+
|
|
136
|
+
One click captures the tab with every comment shown. Then: **callouts** that point (drag from
|
|
137
|
+
the thing to where the text goes), arrows, boxes, highlights, pen, a **ruler** in CSS pixels,
|
|
138
|
+
**crop**, and **pixelate** for anything private. Marks can go past the edge and the picture
|
|
139
|
+
grows to fit. Copy or save the PNG. [Editor guide β](docs/screenshot-editor.md)
|
|
140
|
+
|
|
141
|
+
## Keyboard
|
|
142
|
+
|
|
143
|
+
| Overlay | |
|
|
144
|
+
|---|---|
|
|
145
|
+
| **Alt+Shift+C** | Comment mode on/off |
|
|
146
|
+
| Click Β· select text Β· **β/Ctrl**+click Β· **Shift**+drag | Comment on an element Β· a passage Β· several elements Β· an area |
|
|
147
|
+
| **Alt**+click | Use the page normally |
|
|
148
|
+
| **β/Ctrl+Enter** Β· Esc | Save the comment Β· close the editor, then leave comment mode |
|
|
149
|
+
|
|
150
|
+
The screenshot editor has its own shortcuts (V A T R H P M C B, βZ, βC, βSβ¦): every button's
|
|
151
|
+
tooltip shows them, and [the editor guide](docs/screenshot-editor.md) lists them all.
|
|
152
|
+
|
|
153
|
+
## Requirements
|
|
154
|
+
|
|
155
|
+
- **React 19** in development mode. Source locations come from React 19's `_debugStack`; a
|
|
156
|
+
production build has none, which is also why the overlay belongs in dev only.
|
|
157
|
+
- **Next.js 15** (webpack or Turbopack) or **Vite**, or any dev server that exposes source maps
|
|
158
|
+
beside its scripts or inline. Without one, the prompt still names the component chain and
|
|
159
|
+
gives the bundled line, flagged as approximate.
|
|
160
|
+
- Screenshots use the Screen Capture API: Chromium browsers on `localhost` or `https`. The browser
|
|
161
|
+
asks once per capture; choose **This tab**.
|
|
162
|
+
|
|
163
|
+
## Props
|
|
164
|
+
|
|
165
|
+
| Prop | | |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `appName` | required | Names the app in the prompt and the screenshot file, and keys the saved comments. |
|
|
168
|
+
| `appDir` | optional | The app's folder from the repo root (`apps/web`), so prompt paths open from the root in a monorepo. |
|
|
169
|
+
| `redaction` | optional | Default redaction settings: `{ enabled, countries, patterns }`. See [Redaction](docs/redaction.md). |
|
|
170
|
+
| `resolveFrames` | optional | Replace how stack frames are mapped to source; see `createNextResolver`. |
|
|
171
|
+
| `captureScreen` | optional | Replace how the tab is captured (tests, automation). |
|
|
172
|
+
|
|
173
|
+
## Privacy
|
|
174
|
+
|
|
175
|
+
- Values under keys that name personal data (phone, email, name, address, national ID, bank
|
|
176
|
+
account, password, token and similar) are replaced with `[redacted]` before they reach the
|
|
177
|
+
prompt, and so is any text that looks like an email address.
|
|
178
|
+
- Phone and ID formats are screened for the countries you pick: **Vietnam** (the default),
|
|
179
|
+
the **United States** and **Singapore**. You can also add your own regular expressions, or
|
|
180
|
+
switch redaction off. Use the shield button on the toolbar, or the `redaction` prop for
|
|
181
|
+
app-wide defaults. [Redaction guide β](docs/redaction.md)
|
|
182
|
+
- Settings apply to comments made from then on, and the prompt names any comment recorded
|
|
183
|
+
with redaction off.
|
|
184
|
+
- Untick **Include props/state** to leave data out entirely, and pixelate screenshots before sharing.
|
|
185
|
+
- Nothing is uploaded. Comments live in `sessionStorage`; preferences in `localStorage`.
|
|
186
|
+
|
|
187
|
+
## FAQ
|
|
188
|
+
|
|
189
|
+
**Does it ship to production?** Not if you mount it as shown: `process.env.NODE_ENV` /
|
|
190
|
+
`import.meta.env.DEV` is a constant in a production build, so the import is dropped.
|
|
191
|
+
|
|
192
|
+
**Which agent does the prompt target?** Any. It is plain Markdown that tells the agent what each
|
|
193
|
+
field means and how to work through the comments.
|
|
194
|
+
|
|
195
|
+
**Does it work with React 18?** No: React 18 has no `_debugStack`. React 19 only.
|
|
196
|
+
|
|
197
|
+
**Can I try it without installing?** Clone the repo and run the demo:
|
|
198
|
+
`pnpm install && pnpm --dir examples/demo install && pnpm --dir examples/demo dev`.
|
|
199
|
+
Its **Customers** page is full of made-up personal data for trying the redaction settings.
|
|
200
|
+
|
|
201
|
+
## Develop
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
pnpm install
|
|
205
|
+
pnpm check # lint, typecheck, test, build
|
|
206
|
+
pnpm --dir examples/demo dev # the demo app on http://localhost:5199, running src/ directly
|
|
207
|
+
pnpm media:shots # regenerate docs/media screenshots (demo must be running)
|
|
208
|
+
pnpm media:video # regenerate demo.mp4 and hero.gif (needs ffmpeg)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`dist/` is committed so the repository works as a git dependency; CI fails when it does not
|
|
212
|
+
match the source, so run `pnpm build` before committing.
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
[MIT](LICENSE)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { ReactNode } from 'react';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* What counts as personal data, and the switch that turns screening off. The prompt is
|
|
5
|
+
* pasted into an AI agent, so whatever gets through leaves the machine: a dev database can
|
|
6
|
+
* still hold a copy of real customer data.
|
|
7
|
+
*
|
|
8
|
+
* Two independent screens:
|
|
9
|
+
* - by KEY: a property whose name says it holds personal data or a secret is replaced
|
|
10
|
+
* whole, whatever its value;
|
|
11
|
+
* - by VALUE: inside every string, an e-mail address, the number formats of the selected
|
|
12
|
+
* countries and the user's own patterns are replaced where they stand, so text that
|
|
13
|
+
* merely mentions one (an element's label, a free-text note) is screened too.
|
|
14
|
+
*
|
|
15
|
+
* Amounts survive on purpose: they are what a UI bug is usually about. Every built-in
|
|
16
|
+
* number pattern needs a shape no money figure has (a leading 0 or country code, a
|
|
17
|
+
* separator, letters around the digits).
|
|
18
|
+
*/
|
|
19
|
+
declare const REDACTED = "[redacted]";
|
|
20
|
+
type RedactionCountry = 'vn' | 'us' | 'sg';
|
|
21
|
+
interface RedactionSettings {
|
|
22
|
+
/** Off: props, state and page text go into the prompt as they are. */
|
|
23
|
+
readonly enabled: boolean;
|
|
24
|
+
/** Whose phone and ID formats are screened by value; e-mail addresses always are. */
|
|
25
|
+
readonly countries: readonly RedactionCountry[];
|
|
26
|
+
/**
|
|
27
|
+
* Extra value patterns, as regular expression sources (`INV-\d{6}`) or literals with
|
|
28
|
+
* flags (`/acct[0-9]+/i`). Every match is replaced; blank and invalid lines are skipped.
|
|
29
|
+
*/
|
|
30
|
+
readonly patterns: readonly string[];
|
|
31
|
+
}
|
|
32
|
+
/** What `DevAnnotator`'s `redaction` prop takes: any field left out keeps its default. */
|
|
33
|
+
interface RedactionOptions {
|
|
34
|
+
readonly enabled?: boolean;
|
|
35
|
+
readonly countries?: readonly RedactionCountry[];
|
|
36
|
+
readonly patterns?: ReadonlyArray<string | RegExp>;
|
|
37
|
+
}
|
|
38
|
+
declare const COUNTRIES: RedactionCountry[];
|
|
39
|
+
declare const DEFAULT_REDACTION: RedactionSettings;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Taking the screenshot, and getting it out of the browser.
|
|
43
|
+
*
|
|
44
|
+
* The capture is the tab itself, through the Screen Capture API: the browser asks once
|
|
45
|
+
* ("share this tab?") and hands back real pixels β canvases, videos, cross-origin images
|
|
46
|
+
* and fonts exactly as rendered, which a DOM-to-image library can only approximate. Between
|
|
47
|
+
* the permission and the grab, `prepare` gets the page ready: the tool's own controls away,
|
|
48
|
+
* every comment shown in full.
|
|
49
|
+
*/
|
|
50
|
+
type ScreenCapture = (prepare: () => Promise<void>) => Promise<HTMLCanvasElement>;
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Where in the source an element's JSX is written.
|
|
54
|
+
*
|
|
55
|
+
* React 19 dropped `fiber._debugSource` (the file:line a Babel plugin used to stamp on
|
|
56
|
+
* every element). What it keeps, in development, is `fiber._debugStack`: an Error created
|
|
57
|
+
* when the element was created, so its stack names the render function β and the line β
|
|
58
|
+
* that wrote the JSX. Those frames point at bundled code (`webpack-internal:///β¦`), so
|
|
59
|
+
* they are sent to the dev server's own `/__nextjs_original-stack-frames`, the endpoint
|
|
60
|
+
* Next's error overlay uses to map frames back through the source maps. Under Turbopack
|
|
61
|
+
* that endpoint rejects browser chunk URLs, so those frames go through the chunk's own
|
|
62
|
+
* source map instead (`source-map.ts`).
|
|
63
|
+
*
|
|
64
|
+
* That endpoint is Next internals, not an API. Everything here degrades instead of
|
|
65
|
+
* failing: no answer means the frame's own file and bundled line, flagged as such.
|
|
66
|
+
*/
|
|
67
|
+
interface RawFrame {
|
|
68
|
+
readonly file: string;
|
|
69
|
+
readonly line1: number;
|
|
70
|
+
readonly column1: number;
|
|
71
|
+
readonly methodName: string;
|
|
72
|
+
}
|
|
73
|
+
interface SourceLocation {
|
|
74
|
+
/**
|
|
75
|
+
* Relative to the app's directory when Next mapped it (webpack), absolute when the chunk's
|
|
76
|
+
* source map did (Turbopack), else the bundled URL or path.
|
|
77
|
+
*/
|
|
78
|
+
readonly file: string;
|
|
79
|
+
readonly line: number;
|
|
80
|
+
readonly column: number | null;
|
|
81
|
+
/** True when the line is the ORIGINAL source line, false when it is the bundled one. */
|
|
82
|
+
readonly mapped: boolean;
|
|
83
|
+
/** Next flagged the frame as framework or library code: not where an edit belongs. */
|
|
84
|
+
readonly ignored?: boolean;
|
|
85
|
+
}
|
|
86
|
+
type FrameResolver = (frames: readonly RawFrame[]) => Promise<SourceLocation[]>;
|
|
87
|
+
/**
|
|
88
|
+
* Maps frames through Next's dev server in ONE request. Always resolves, one location per
|
|
89
|
+
* frame, in order: a frame Next could not map, or any failure of the request, falls back
|
|
90
|
+
* to the frame as bundled.
|
|
91
|
+
*/
|
|
92
|
+
declare function createNextResolver(fetchImpl?: typeof fetch): FrameResolver;
|
|
93
|
+
|
|
94
|
+
interface DevAnnotatorProps {
|
|
95
|
+
/** Names the app in the prompt and keys the saved comments (`web`, `admin`). */
|
|
96
|
+
readonly appName: string;
|
|
97
|
+
/** The app's directory from the repo root, so source paths in the prompt open as-is. */
|
|
98
|
+
readonly appDir?: string;
|
|
99
|
+
/**
|
|
100
|
+
* Personal-data redaction for this app: on or off, which countries' phone and ID
|
|
101
|
+
* formats to screen, and extra patterns. Each browser can change it from the toolbar's
|
|
102
|
+
* redaction settings; these are the defaults it starts from and resets to.
|
|
103
|
+
*/
|
|
104
|
+
readonly redaction?: RedactionOptions;
|
|
105
|
+
/** Overrides how stack frames are mapped to source; tests pass one, apps never do. */
|
|
106
|
+
readonly resolveFrames?: FrameResolver;
|
|
107
|
+
/** Overrides how the tab is captured; tests pass one, apps never do. */
|
|
108
|
+
readonly captureScreen?: ScreenCapture;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Development-only overlay: a floating button switches on "comment mode". In it, a click
|
|
112
|
+
* pins a comment to an element, a text selection to a passage, Cmd/Ctrl+click gathers
|
|
113
|
+
* several elements under one comment and Shift+drag marks an area β and the page sees
|
|
114
|
+
* none of it. "Copy prompt" puts every comment, with what the tool learned about its
|
|
115
|
+
* elements, on the clipboard as one Markdown prompt for a coding agent.
|
|
116
|
+
*
|
|
117
|
+
* Comments survive client-side navigation (this component lives in the root layout) and
|
|
118
|
+
* a full reload (sessionStorage), so one request can span several pages.
|
|
119
|
+
*/
|
|
120
|
+
declare function DevAnnotator(props: DevAnnotatorProps): ReactNode;
|
|
121
|
+
|
|
122
|
+
type Snapshot = null | boolean | number | string | readonly Snapshot[] | {
|
|
123
|
+
readonly [key: string]: Snapshot;
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Everything one comment records about its element, taken at the moment of the click.
|
|
128
|
+
* "The current value of the data" is the value the developer was LOOKING at when they
|
|
129
|
+
* noticed the problem, so it is captured then, not when the prompt is copied β by which
|
|
130
|
+
* time they may have navigated away and back.
|
|
131
|
+
*/
|
|
132
|
+
interface ElementCapture {
|
|
133
|
+
readonly page: {
|
|
134
|
+
readonly url: string;
|
|
135
|
+
readonly pathname: string;
|
|
136
|
+
readonly search: string;
|
|
137
|
+
readonly title: string;
|
|
138
|
+
};
|
|
139
|
+
readonly element: {
|
|
140
|
+
readonly tag: string;
|
|
141
|
+
readonly opening: string;
|
|
142
|
+
readonly selector: string;
|
|
143
|
+
readonly text: string;
|
|
144
|
+
readonly value: string | null;
|
|
145
|
+
readonly rect: {
|
|
146
|
+
readonly x: number;
|
|
147
|
+
readonly y: number;
|
|
148
|
+
readonly width: number;
|
|
149
|
+
readonly height: number;
|
|
150
|
+
};
|
|
151
|
+
readonly styles: Readonly<Record<string, string>>;
|
|
152
|
+
/** Role, accessible name and ARIA states: `button "Save" (disabled)`. */
|
|
153
|
+
readonly accessibility: string | null;
|
|
154
|
+
/** Page heading and enclosing section labels: `Debt batches βΊ New batch`. */
|
|
155
|
+
readonly section: string | null;
|
|
156
|
+
/** The text of the siblings either side, to tell identical elements apart. */
|
|
157
|
+
readonly nearby: string | null;
|
|
158
|
+
};
|
|
159
|
+
readonly viewport: {
|
|
160
|
+
readonly width: number;
|
|
161
|
+
readonly height: number;
|
|
162
|
+
readonly devicePixelRatio: number;
|
|
163
|
+
};
|
|
164
|
+
/** Where the element's own JSX is written: usually the line to edit. */
|
|
165
|
+
readonly jsx: SourceLocation | null;
|
|
166
|
+
/** Enclosing components, nearest first, each with where IT was rendered from. */
|
|
167
|
+
readonly components: ReadonlyArray<{
|
|
168
|
+
readonly name: string;
|
|
169
|
+
readonly renderedAt: SourceLocation | null;
|
|
170
|
+
}>;
|
|
171
|
+
/** Props and stateful hooks of the nearest components, personal data redacted unless redaction is off. */
|
|
172
|
+
readonly data: ReadonlyArray<{
|
|
173
|
+
readonly component: string;
|
|
174
|
+
readonly props: Snapshot;
|
|
175
|
+
readonly state: Snapshot;
|
|
176
|
+
}>;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
interface Rect {
|
|
180
|
+
readonly x: number;
|
|
181
|
+
readonly y: number;
|
|
182
|
+
readonly width: number;
|
|
183
|
+
readonly height: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* What one comment is about:
|
|
188
|
+
* - `element`: one clicked element;
|
|
189
|
+
* - `text`: a passage selected inside an element (the element is the target);
|
|
190
|
+
* - `group`: several elements picked with Cmd/Ctrl+click, one request for all of them;
|
|
191
|
+
* - `area`: a dragged region β the first target is the element holding the region, the
|
|
192
|
+
* rest are the elements wholly inside it (none, for a comment on empty space).
|
|
193
|
+
*/
|
|
194
|
+
type AnnotationKind = 'element' | 'text' | 'group' | 'area';
|
|
195
|
+
interface Annotation {
|
|
196
|
+
readonly id: string;
|
|
197
|
+
readonly kind: AnnotationKind;
|
|
198
|
+
readonly comment: string;
|
|
199
|
+
readonly createdAt: string;
|
|
200
|
+
readonly targets: readonly ElementCapture[];
|
|
201
|
+
/** `text` only: the selected passage, screened for personal data. */
|
|
202
|
+
readonly selectedText?: string;
|
|
203
|
+
/** `area` only: the dragged region in viewport pixels at the time of the comment. */
|
|
204
|
+
readonly area?: Rect;
|
|
205
|
+
/**
|
|
206
|
+
* `area` only: the same region relative to the container's top-left corner, so it can be
|
|
207
|
+
* drawn back over the page after scrolling or a reload. Not part of the prompt.
|
|
208
|
+
*/
|
|
209
|
+
readonly areaInContainer?: Rect;
|
|
210
|
+
/**
|
|
211
|
+
* `false` when the comment was made with redaction switched off, so its captures hold
|
|
212
|
+
* the page's data as it was. Comments saved before the setting existed were screened.
|
|
213
|
+
*/
|
|
214
|
+
readonly redacted?: boolean;
|
|
215
|
+
}
|
|
216
|
+
interface PromptOptions {
|
|
217
|
+
/** Shown in the heading: which app the comments are about. */
|
|
218
|
+
readonly appName: string;
|
|
219
|
+
/** The app's directory from the repo root (`apps/web`); prefixes every source path. */
|
|
220
|
+
readonly appDir?: string | undefined;
|
|
221
|
+
/** Include the props/state snapshots. */
|
|
222
|
+
readonly includeData: boolean;
|
|
223
|
+
readonly now: Date;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* The Markdown handed to the coding agent. It is written FOR the agent: what to do comes
|
|
227
|
+
* first, then one section per comment with the facts it needs to find the code without
|
|
228
|
+
* searching β the source line before the selector, the selector before the text.
|
|
229
|
+
*/
|
|
230
|
+
declare function buildPrompt(annotations: readonly Annotation[], options: PromptOptions): string;
|
|
231
|
+
|
|
232
|
+
export { type Annotation, COUNTRIES, DEFAULT_REDACTION, DevAnnotator, type DevAnnotatorProps, type ElementCapture, type FrameResolver, type PromptOptions, REDACTED, type RedactionCountry, type RedactionOptions, type RedactionSettings, type ScreenCapture, type SourceLocation, buildPrompt, createNextResolver };
|