@trungtnm/agent-annotator 0.2.0 → 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/README.md +43 -17
- package/dist/index.d.ts +51 -2
- package/dist/index.js +416 -138
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,13 +9,14 @@ prompt** that gives Claude Code, Codex or Cursor the exact **file and line** of
|
|
|
9
9
|
component chain and the live props: no more "the button, top right, the grey one".
|
|
10
10
|
|
|
11
11
|
[](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml)
|
|
12
|
+
[](https://www.npmjs.com/package/@trungtnm/agent-annotator)
|
|
12
13
|

|
|
13
14
|

|
|
14
15
|

|
|
15
16
|
|
|
16
|
-
<img src="docs/media/hero.gif" alt="Commenting on a dashboard, copying the prompt, and marking up a screenshot" width="860" />
|
|
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" />
|
|
17
18
|
|
|
18
|
-
<sub>▶ <a href="docs/media/demo.mp4">Watch the
|
|
19
|
+
<sub>▶ <a href="docs/media/demo.mp4">Watch the 100-second walkthrough</a></sub>
|
|
19
20
|
|
|
20
21
|
</div>
|
|
21
22
|
|
|
@@ -33,14 +34,12 @@ agent-annotator closes that gap from where you already are, the running app:
|
|
|
33
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. |
|
|
34
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. |
|
|
35
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. |
|
|
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
|
+
| 🔒 **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. |
|
|
37
38
|
|
|
38
39
|
## Quick start
|
|
39
40
|
|
|
40
41
|
```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
|
|
42
|
+
pnpm add -D @trungtnm/agent-annotator # or: npm i -D / yarn add -D / bun add -d
|
|
44
43
|
```
|
|
45
44
|
|
|
46
45
|
**Next.js (App Router)**: a client component in the root layout, loaded in development only:
|
|
@@ -83,7 +82,7 @@ Start your dev server, press **Alt+Shift+C**, click something.
|
|
|
83
82
|
Everything lives in one toolbar, bottom right, which folds into a single button when you need the
|
|
84
83
|
space:
|
|
85
84
|
|
|
86
|
-
<img src="docs/media/toolbar.png" alt="The toolbar: comment mode, pause, show comments, screenshot, list, copy prompt" width="430" />
|
|
85
|
+
<img src="docs/media/toolbar.png" alt="The toolbar: comment mode, pause, show comments, screenshot, redaction settings, list, copy prompt" width="430" />
|
|
87
86
|
|
|
88
87
|
### 1. Click anything and say what should change
|
|
89
88
|
|
|
@@ -97,19 +96,40 @@ page, so you can open the menu you want to comment on.
|
|
|
97
96
|
|
|
98
97
|
<img src="docs/media/comments.png" alt="Three comments drawn next to their elements" width="860" />
|
|
99
98
|
|
|
100
|
-
Comments stay on their elements as you scroll
|
|
101
|
-
numbered pins or in full; the list in the toolbar holds every comment, from this page and others.
|
|
99
|
+
Comments stay on their elements as you scroll. Show them as numbered pins or in full.
|
|
102
100
|
|
|
103
|
-
### 3.
|
|
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
|
|
104
124
|
|
|
105
125
|
<img src="docs/media/prompt.png" alt="The copied prompt in a coding agent" width="860" />
|
|
106
126
|
|
|
107
|
-
Per comment: the page, the element and its text, its role, the section it sits in, a selector,
|
|
127
|
+
Per comment, from every page: the page, the element and its text, its role, the section it sits in, a selector,
|
|
108
128
|
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]
|
|
129
|
+
and props/state with personal data replaced by `[redacted]` ([redaction settings](docs/redaction.md)).
|
|
110
130
|
[See a full prompt →](docs/prompt-format.md)
|
|
111
131
|
|
|
112
|
-
###
|
|
132
|
+
### 6. Capture and mark up
|
|
113
133
|
|
|
114
134
|
<img src="docs/media/editor.png" alt="Screenshot editor with a callout, an arrow, a ruler and pixelated emails" width="860" />
|
|
115
135
|
|
|
@@ -146,6 +166,7 @@ tooltip shows them, and [the editor guide](docs/screenshot-editor.md) lists them
|
|
|
146
166
|
|---|---|---|
|
|
147
167
|
| `appName` | required | Names the app in the prompt and the screenshot file, and keys the saved comments. |
|
|
148
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). |
|
|
149
170
|
| `resolveFrames` | optional | Replace how stack frames are mapped to source; see `createNextResolver`. |
|
|
150
171
|
| `captureScreen` | optional | Replace how the tab is captured (tests, automation). |
|
|
151
172
|
|
|
@@ -153,10 +174,14 @@ tooltip shows them, and [the editor guide](docs/screenshot-editor.md) lists them
|
|
|
153
174
|
|
|
154
175
|
- Values under keys that name personal data (phone, email, name, address, national ID, bank
|
|
155
176
|
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
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
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.
|
|
160
185
|
- Nothing is uploaded. Comments live in `sessionStorage`; preferences in `localStorage`.
|
|
161
186
|
|
|
162
187
|
## FAQ
|
|
@@ -171,6 +196,7 @@ field means and how to work through the comments.
|
|
|
171
196
|
|
|
172
197
|
**Can I try it without installing?** Clone the repo and run the demo:
|
|
173
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.
|
|
174
200
|
|
|
175
201
|
## Develop
|
|
176
202
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,43 @@
|
|
|
1
1
|
import { ReactNode } from 'react';
|
|
2
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
|
+
|
|
3
41
|
/**
|
|
4
42
|
* Taking the screenshot, and getting it out of the browser.
|
|
5
43
|
*
|
|
@@ -58,6 +96,12 @@ interface DevAnnotatorProps {
|
|
|
58
96
|
readonly appName: string;
|
|
59
97
|
/** The app's directory from the repo root, so source paths in the prompt open as-is. */
|
|
60
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;
|
|
61
105
|
/** Overrides how stack frames are mapped to source; tests pass one, apps never do. */
|
|
62
106
|
readonly resolveFrames?: FrameResolver;
|
|
63
107
|
/** Overrides how the tab is captured; tests pass one, apps never do. */
|
|
@@ -124,7 +168,7 @@ interface ElementCapture {
|
|
|
124
168
|
readonly name: string;
|
|
125
169
|
readonly renderedAt: SourceLocation | null;
|
|
126
170
|
}>;
|
|
127
|
-
/** Props and stateful hooks of the nearest components,
|
|
171
|
+
/** Props and stateful hooks of the nearest components, personal data redacted unless redaction is off. */
|
|
128
172
|
readonly data: ReadonlyArray<{
|
|
129
173
|
readonly component: string;
|
|
130
174
|
readonly props: Snapshot;
|
|
@@ -163,6 +207,11 @@ interface Annotation {
|
|
|
163
207
|
* drawn back over the page after scrolling or a reload. Not part of the prompt.
|
|
164
208
|
*/
|
|
165
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;
|
|
166
215
|
}
|
|
167
216
|
interface PromptOptions {
|
|
168
217
|
/** Shown in the heading: which app the comments are about. */
|
|
@@ -180,4 +229,4 @@ interface PromptOptions {
|
|
|
180
229
|
*/
|
|
181
230
|
declare function buildPrompt(annotations: readonly Annotation[], options: PromptOptions): string;
|
|
182
231
|
|
|
183
|
-
export { type Annotation, DevAnnotator, type DevAnnotatorProps, type ElementCapture, type FrameResolver, type PromptOptions, type ScreenCapture, type SourceLocation, buildPrompt, createNextResolver };
|
|
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 };
|