@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 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
  [![CI](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml/badge.svg)](https://github.com/trungtnm/agent-annotator/actions/workflows/ci.yml)
12
+ [![npm](https://img.shields.io/npm/v/@trungtnm/agent-annotator)](https://www.npmjs.com/package/@trungtnm/agent-annotator)
12
13
  ![React 19](https://img.shields.io/badge/React-19-61dafb)
13
14
  ![Next.js and Vite](https://img.shields.io/badge/works%20with-Next.js%20%C2%B7%20Vite-6d4aff)
14
15
  ![License: MIT](https://img.shields.io/badge/license-MIT-green)
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 70-second walkthrough</a></sub>
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 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.
99
+ Comments stay on their elements as you scroll. Show them as numbered pins or in full.
102
100
 
103
- ### 3. Copy one prompt and paste it into your agent
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
- ### 4. Capture and mark up
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, 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.
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, PII redacted. */
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 };