@ui-annotate/react-vite 0.1.0 → 0.1.1
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 +88 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# @ui-annotate/react-vite
|
|
2
|
+
|
|
3
|
+
Annotate React UI issues directly in a Vite dev server and hand the captured UI targets to a coding agent.
|
|
4
|
+
|
|
5
|
+
`@ui-annotate/react-vite` is a development-only Vite plugin for React apps. It injects inspector metadata, mounts the UI Annotate Runtime into your running page, lets you select real UI targets, records comments, and writes an agent-readable `ui.annotate.json` file.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install -D @ui-annotate/react-vite
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
With pnpm:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pnpm add -D @ui-annotate/react-vite
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Add the Vite plugin
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import react from "@vitejs/plugin-react";
|
|
23
|
+
import { uiAnnotate } from "@ui-annotate/react-vite";
|
|
24
|
+
import { defineConfig } from "vite";
|
|
25
|
+
|
|
26
|
+
export default defineConfig({
|
|
27
|
+
plugins: [
|
|
28
|
+
react(),
|
|
29
|
+
uiAnnotate()
|
|
30
|
+
]
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Start your Vite dev server as usual:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm run dev
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The plugin only runs during Vite development. Production builds do not include the UI Annotate Runtime.
|
|
41
|
+
|
|
42
|
+
## Use Annotate Mode
|
|
43
|
+
|
|
44
|
+
When the dev server page loads, UI Annotate adds a floating toolbar to the page.
|
|
45
|
+
|
|
46
|
+
- Press `D` or click the toolbar Annotate button to enter annotate mode.
|
|
47
|
+
- Hover the host page to highlight selectable UI targets.
|
|
48
|
+
- Click a target to add it to the annotate task.
|
|
49
|
+
- Add comments in the Annotate window.
|
|
50
|
+
- Use `Cmd/Ctrl + click` on a target or trace node to open the source location in VS Code.
|
|
51
|
+
- Use `Cmd/Ctrl + S` to save immediately.
|
|
52
|
+
- Press `Escape` to leave annotate mode.
|
|
53
|
+
|
|
54
|
+
While annotate mode is active, UI Annotate intercepts host-page clicks, form submissions, drag starts, focus changes, and related interactions so selecting UI does not trigger real app behavior. When annotate mode is off, the host page works normally.
|
|
55
|
+
|
|
56
|
+
## Agent Handoff
|
|
57
|
+
|
|
58
|
+
UI Annotate writes the selected targets and comments to `ui.annotate.json` in your project root.
|
|
59
|
+
|
|
60
|
+
After recording the UI issue, hand that file to your coding agent. A typical prompt is:
|
|
61
|
+
|
|
62
|
+
```txt
|
|
63
|
+
Read ui.annotate.json and update the referenced React UI according to the comments.
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The task file is the handoff artifact. It records the selected UI targets, trace information, source locations, dimensions, style details, and user comments that the agent should use while editing the code.
|
|
67
|
+
|
|
68
|
+
## Options
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
uiAnnotate({
|
|
72
|
+
enabled: true,
|
|
73
|
+
root: process.cwd()
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- `enabled`: Set to `false` to disable both inspector transforms and runtime injection.
|
|
78
|
+
- `root`: Project root used for source paths and `ui.annotate.json`. Defaults to the Vite config root.
|
|
79
|
+
|
|
80
|
+
## Runtime Boundaries
|
|
81
|
+
|
|
82
|
+
- Supported host apps: React 18 or 19 with Vite 8.
|
|
83
|
+
- The runtime is development-only and is injected by the Vite dev server.
|
|
84
|
+
- The runtime creates `#__ui_annotate_root__` under `document.body`; your app does not need to provide a mount point.
|
|
85
|
+
- The UI is isolated in a shadow root.
|
|
86
|
+
- Highlights and overlays are drawn outside the host app and do not directly mutate host DOM classes, styles, or structure.
|
|
87
|
+
- Component trace depends on React Fiber plus inspector metadata injected by the plugin.
|
|
88
|
+
- The package is for React + Vite apps; it is not a production feedback widget, Next.js plugin, or Webpack plugin.
|