viewgate-wrapper 1.9.2 → 1.9.4

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.
Files changed (10) hide show
  1. package/README.md +60 -25
  2. package/dist/components/ShadowRootWrapper.d.ts +8 -0
  3. package/dist/components/ShadowRootWrapper.d.ts.map +1 -0
  4. package/dist/components/ViewGateOverlay.d.ts.map +1 -1
  5. package/dist/components/ViewGateProvider.d.ts +77 -3
  6. package/dist/components/ViewGateProvider.d.ts.map +1 -1
  7. package/dist/viewgate-wrapper.js +5914 -1095
  8. package/dist/viewgate-wrapper.umd.cjs +16 -6
  9. package/package.json +54 -53
  10. package/CLIENT_SETUP_GUIDE.md +0 -64
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # ViewGate Wrapper
1
+ # 🛡️ ViewGate Wrapper
2
2
 
3
- A React wrapper and Vite plugin for the ViewGate feedback system. It allows clients to leave annotations directly on the UI and developers to apply those changes instantly via AI (MCP Server).
3
+ A professional, high-fidelity React feedback system and Vite/Next.js plugin. ViewGate allows clients to leave visual annotations directly on your live UI, which developers can then resolve instantly using AI-powered automation (MCP Server).
4
4
 
5
5
  ## 📦 Installation
6
6
 
@@ -8,13 +8,13 @@ A React wrapper and Vite plugin for the ViewGate feedback system. It allows clie
8
8
  npm install viewgate-wrapper
9
9
  ```
10
10
 
11
- ## 🚀 Getting Started
11
+ ---
12
12
 
13
- ### 1. Framework Setup (Required for Smart Source Mapping)
13
+ ## 🚀 Framework Configuration
14
14
 
15
- To allow the AI to find the exact line of code to edit, you must configure ViewGate for your framework:
15
+ To enable **Smart Source Mapping** (allowing AI to pinpoint the exact file and line of code for a change), you must configure the plugin for your specific framework.
16
16
 
17
- #### ⚡ Vite
17
+ ### ⚡ Vite
18
18
  Add the plugin to your `vite.config.ts`:
19
19
 
20
20
  ```typescript
@@ -28,52 +28,87 @@ export default defineConfig({
28
28
  });
29
29
  ```
30
30
 
31
- #### 🌑 Next.js
32
- If you are using Next.js, you can add our custom loader to your `next.config.js` (Webpack-based):
31
+ ### 🌑 Next.js
32
+ Add the custom loader to your `next.config.js` (Webpack-based):
33
33
 
34
34
  ```javascript
35
35
  module.exports = {
36
36
  webpack: (config) => {
37
37
  config.module.rules.push({
38
38
  test: /\.(tsx|jsx)$/,
39
- use: [
40
- {
41
- loader: 'viewgate-wrapper/next-loader',
42
- },
43
- ],
39
+ use: [{ loader: 'viewgate-wrapper/next-loader' }],
44
40
  });
45
41
  return config;
46
42
  },
47
43
  };
48
44
  ```
49
- *Note: Full SWC support for Next.js is coming soon.*
45
+ *Note: SWC support for Next.js 13+ is in development.*
50
46
 
51
- ### 2. Wrap your application
47
+ ---
52
48
 
53
- In your main entry file (e.g., `main.tsx` or `_app.tsx`):
49
+ ## 🛠️ Usage
50
+
51
+ ### 1. Wrap your Application
52
+ In your main entry point (e.g., `main.tsx` or `_app.tsx`), wrap your app with the `ViewGate` provider.
54
53
 
55
54
  ```tsx
56
55
  import { ViewGate } from 'viewgate-wrapper';
57
56
  import 'viewgate-wrapper/dist/viewgate-wrapper.css';
58
57
 
59
- // ...
60
- <ViewGate language="es" apiKey="YOUR_PROJECT_API_KEY">
61
- <App />
62
- </ViewGate>
58
+ function Root() {
59
+ return (
60
+ <ViewGate
61
+ apiKey="VG-YOUR-PROJECT-KEY"
62
+ language="es"
63
+ >
64
+ <App />
65
+ </ViewGate>
66
+ );
67
+ }
63
68
  ```
64
69
 
65
- ### 3. Setup the MCP Server (For AI Integration)
70
+ ### 2. Component Props (`<ViewGate />`)
71
+
72
+ | Prop | Type | Default | Description |
73
+ | :--- | :--- | :--- | :--- |
74
+ | **`apiKey`** | `string` | **Required** | Your project's unique API key from the ViewGate dashboard. |
75
+ | **`language`** | `'en' \| 'es'` | `'es'` | The UI language for the feedback overlay. |
76
+ | **`baseUrl`** | `string` | `https://view-gate.vercel.app` | The backend API URL if using a self-hosted instance. |
77
+
78
+ ---
66
79
 
67
- To allow an AI assistant (like Claude Desktop or Cursor) to apply the feedback changes automatically, you need to configure the MCP server in your local environment:
80
+ ## 🤖 AI Integration (MCP Server)
81
+
82
+ ViewGate includes a **Model Context Protocol (MCP)** server that allows AI assistants (like Claude Desktop, Cursor, or Antigravity) to read your UI feedback and apply requested code changes automatically.
83
+
84
+ ### Setup
85
+ Run the automatic configuration tool in your project root:
68
86
 
69
87
  ```bash
70
88
  npx viewgate-wrapper setup
71
89
  ```
72
90
 
73
- **Note:** After running the setup, remember to **refresh or restart** your MCP server in your IDE to load the new tools.
91
+ ### ⚡ Example Commands
92
+ Once configured, you can simply ask your AI assistant:
93
+ - *"Read ViewGate annotations and apply the changes"*
94
+ - *"Review UI feedback and resolve pending tasks"*
95
+ - *"Apply ViewGate changes"*
74
96
 
97
+ ---
75
98
 
76
- ## License
77
99
 
78
- ISC
100
+ ## 💡 Troubleshooting
101
+
102
+ ### Layering Issues (Z-Index)
103
+ ViewGate's background elements (pins and selection highlights) are configured with a low `z-index` to avoid overlapping with your application's primary UI.
104
+ - **Pins**: `50`
105
+ - **Selection Highlights**: `100`
106
+ - **Modals**: `2,000,000`
107
+
108
+ If pins are appearing over your headers, ensure your app's headers have a `z-index` higher than `100`.
109
+
110
+ ---
111
+
112
+ ## License
79
113
 
114
+ ISC © [Mauro Aceituno](https://github.com/mauroaceituno)
package/dist/components/ShadowRootWrapper.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ import { type ReactNode, type FC } from 'react';
2
+ interface ShadowRootWrapperProps {
3
+ children: ReactNode;
4
+ cssContent?: string;
5
+ }
6
+ export declare const ShadowRootWrapper: FC<ShadowRootWrapperProps>;
7
+ export {};
8
+ //# sourceMappingURL=ShadowRootWrapper.d.ts.map
package/dist/components/ShadowRootWrapper.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ShadowRootWrapper.d.ts","sourceRoot":"","sources":["../../src/components/ShadowRootWrapper.tsx"],"names":[],"mappings":"AAAA,OAAc,EAA+B,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAGpF,UAAU,sBAAsB;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAiCxD,CAAC"}
package/dist/components/ViewGateOverlay.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ViewGateOverlay.d.ts","sourceRoot":"","sources":["../../src/components/ViewGateOverlay.tsx"],"names":[],"mappings":"AACA,OAAO,EAAoC,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAGlE,OAAO,wBAAwB,CAAC;AA+GhC,eAAO,MAAM,eAAe,EAAE,EAipB7B,CAAC"}
1
+ {"version":3,"file":"ViewGateOverlay.d.ts","sourceRoot":"","sources":["../../src/components/ViewGateOverlay.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAoB1E,OAAO,wBAAwB,CAAC;AA0ThC,eAAO,MAAM,eAAe,EAAE,EAmyB7B,CAAC"}
package/dist/components/ViewGateProvider.d.ts CHANGED
@@ -28,11 +28,23 @@ declare const translations: {
28
28
  reopen: string;
29
29
  review: string;
30
30
  confirmDelete: string;
31
+ markReadyConfirm: string;
32
+ confirmMarkReady: string;
33
+ reopenConfirm: string;
34
+ confirmReopen: string;
31
35
  yes: string;
32
36
  no: string;
33
37
  deleteSuccess: string;
34
38
  updateSuccess: string;
35
39
  navigating: string;
40
+ selectToComment: string;
41
+ feedbackSubheader: string;
42
+ sendFeedback: string;
43
+ edit: string;
44
+ save: string;
45
+ commentDetails: string;
46
+ annotations: string;
47
+ viewAll: string;
36
48
  };
37
49
  es: {
38
50
  enterMode: string;
@@ -60,11 +72,23 @@ declare const translations: {
60
72
  reopen: string;
61
73
  review: string;
62
74
  confirmDelete: string;
75
+ markReadyConfirm: string;
76
+ confirmMarkReady: string;
77
+ reopenConfirm: string;
78
+ confirmReopen: string;
63
79
  yes: string;
64
80
  no: string;
65
81
  deleteSuccess: string;
66
82
  updateSuccess: string;
67
83
  navigating: string;
84
+ selectToComment: string;
85
+ feedbackSubheader: string;
86
+ sendFeedback: string;
87
+ edit: string;
88
+ save: string;
89
+ commentDetails: string;
90
+ annotations: string;
91
+ viewAll: string;
68
92
  };
69
93
  };
70
94
  export interface SemanticReference {
@@ -79,10 +103,60 @@ export interface SemanticReference {
79
103
  signature?: string;
80
104
  source?: string;
81
105
  attributes?: Record<string, string>;
82
- metadata?: {
83
- hint?: string;
84
- closestSource?: string;
106
+ normalizedOffset?: {
107
+ x: number;
108
+ y: number;
109
+ };
110
+ fallbackSelectors?: string[];
111
+ domPath?: string[];
112
+ viewportSize?: {
113
+ width: number;
114
+ height: number;
85
115
  };
116
+ uiContext?: {
117
+ target: {
118
+ tag: string;
119
+ text: string;
120
+ role?: string | undefined;
121
+ type?: string | undefined;
122
+ location?: string | undefined;
123
+ };
124
+ parent?: {
125
+ tag: string;
126
+ text: string;
127
+ role?: string | undefined;
128
+ type?: string | undefined;
129
+ } | undefined;
130
+ siblings?: Array<{
131
+ tag: string;
132
+ text: string;
133
+ role?: string | undefined;
134
+ type?: string | undefined;
135
+ }> | undefined;
136
+ } | undefined;
137
+ fingerprint?: {
138
+ tag: string;
139
+ classHash: string;
140
+ ariaLabel?: string | undefined;
141
+ role?: string | undefined;
142
+ name?: string | undefined;
143
+ textSnippet: string;
144
+ parentTag?: string | undefined;
145
+ neighborCount: number;
146
+ } | undefined;
147
+ metadata?: {
148
+ hint?: string | undefined;
149
+ closestSource?: string | undefined;
150
+ screenshotUrl?: string | undefined;
151
+ elementScreenshot?: string | undefined;
152
+ computedStyles?: Record<string, string> | undefined;
153
+ viewportBreakpoint?: 'mobile' | 'tablet' | 'desktop' | undefined;
154
+ outerHtml?: string | undefined;
155
+ scrollPosition?: {
156
+ x: number;
157
+ y: number;
158
+ } | undefined;
159
+ } | undefined;
86
160
  }
87
161
  interface ViewGateContextType {
88
162
  addToast: (message: string, type: 'success' | 'error') => void;
package/dist/components/ViewGateProvider.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ViewGateProvider.d.ts","sourceRoot":"","sources":["../../src/components/ViewGateProvider.tsx"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAErF,OAAO,wBAAwB,CAAC;AAEhC,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnC,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEjB,CAAC;AAQF,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACL;AAED,UAAU,mBAAmB;IACzB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,KAAK,IAAI,CAAC;IAC/D,QAAQ,EAAE,QAAQ,CAAC;IACnB,CAAC,EAAE,OAAO,YAAY,CAAC,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,eAAO,MAAM,WAAW,2BAIvB,CAAC;AAEF,UAAU,aAAa;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,aAAa,CA8BtC,CAAC"}
1
+ {"version":3,"file":"ViewGateProvider.d.ts","sourceRoot":"","sources":["../../src/components/ViewGateProvider.tsx"],"names":[],"mappings":"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"}