@popmelt.com/core 0.8.1 → 0.8.3
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 +202 -122
- package/dist/bridge-entry.mjs +57 -57
- package/dist/cli.mjs +57 -57
- package/dist/index.d.mts +34 -0
- package/dist/index.mjs +52 -24
- package/dist/plugin-astro.mjs +1 -1
- package/dist/plugin-vite.mjs +1 -1
- package/dist/server-2X6UD5RQ.mjs +421 -0
- package/dist/server.mjs +56 -56
- package/package.json +3 -3
- package/dist/server-AGXQFGSU.mjs +0 -421
package/README.md
CHANGED
|
@@ -1,226 +1,306 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="src/assets/bar - popmelt.png" alt="Popmelt" width="360"
|
|
2
|
+
<img src="src/assets/bar - popmelt.png" alt="Popmelt" width="360" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
# Popmelt
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Popmelt is a design collaboration layer for AI coding agents. It gives you a visual toolbar inside your running React app so you can annotate UI, adjust it directly, and hand the result to Claude Code, Codex, or GitHub Copilot without translating every design decision into a written prompt.
|
|
8
8
|
|
|
9
|
-
Popmelt is
|
|
9
|
+
Popmelt is local-first. Your project, annotations, screenshots, conversations, decisions, models, and evals remain in your development environment.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Install
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
<img src="src/assets/bar - annotations.png" alt="Popmelt annotations on a running app" width="720" style="border-radius: 6px;" />
|
|
15
|
-
</p>
|
|
16
|
-
|
|
17
|
-
**Popmelt is free to use and completely local**. It runs inside your codebase, with your existing AI CLI tools handling code changes behind the scenes. You don't need an account to use it and we never see your data.
|
|
18
|
-
|
|
19
|
-
## Quick start
|
|
20
|
-
|
|
21
|
-
### Install
|
|
13
|
+
Install Popmelt and its icon peer dependency:
|
|
22
14
|
|
|
23
15
|
```bash
|
|
24
|
-
npm install @popmelt.com/core
|
|
16
|
+
npm install @popmelt.com/core lucide-react
|
|
25
17
|
```
|
|
26
18
|
|
|
27
|
-
|
|
19
|
+
Popmelt requires React 18+ and Node.js 18+. At least one supported AI CLI must be installed and authenticated:
|
|
28
20
|
|
|
29
|
-
|
|
21
|
+
- Claude Code
|
|
22
|
+
- Codex CLI
|
|
23
|
+
- GitHub Copilot CLI
|
|
30
24
|
|
|
31
|
-
|
|
25
|
+
### Add the provider
|
|
26
|
+
|
|
27
|
+
Wrap your application with `PopmeltProvider`. The component that calls `useRouter()` must be a client component in Next.js.
|
|
32
28
|
|
|
33
29
|
```tsx
|
|
34
|
-
|
|
30
|
+
'use client';
|
|
31
|
+
|
|
35
32
|
import { useRouter } from 'next/navigation';
|
|
36
33
|
|
|
37
|
-
|
|
34
|
+
import { PopmeltProvider } from '@popmelt.com/core';
|
|
35
|
+
|
|
36
|
+
export function Providers({ children }: { children: React.ReactNode }) {
|
|
38
37
|
const router = useRouter();
|
|
39
38
|
|
|
40
|
-
return
|
|
41
|
-
<PopmeltProvider navigate={router.push}>
|
|
42
|
-
{/* your app */}
|
|
43
|
-
</PopmeltProvider>
|
|
44
|
-
);
|
|
39
|
+
return <PopmeltProvider navigate={router.push}>{children}</PopmeltProvider>;
|
|
45
40
|
}
|
|
46
41
|
```
|
|
47
42
|
|
|
48
|
-
|
|
43
|
+
`navigate` is optional for single-page use. Pass your router's navigation function to support annotations and screenshots across routes.
|
|
44
|
+
|
|
45
|
+
### Next.js
|
|
46
|
+
|
|
47
|
+
For Next.js, both steps below are required.
|
|
49
48
|
|
|
50
|
-
|
|
49
|
+
1. Run the dev server through the Popmelt wrapper. Update the existing `dev` script while preserving any flags your project already uses:
|
|
51
50
|
|
|
52
|
-
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"scripts": {
|
|
54
|
+
"dev": "popmelt wrap -- next dev"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
53
58
|
|
|
54
|
-
|
|
59
|
+
For example, a Turbopack project can use:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
"dev": "popmelt wrap -- next dev --turbopack"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
2. Wrap the Next config:
|
|
55
66
|
|
|
56
67
|
```ts
|
|
57
68
|
// next.config.ts
|
|
58
69
|
import { withPopmelt } from '@popmelt.com/core/next';
|
|
70
|
+
|
|
71
|
+
const nextConfig = {};
|
|
72
|
+
|
|
59
73
|
export default withPopmelt(nextConfig);
|
|
60
74
|
```
|
|
61
75
|
|
|
62
|
-
|
|
76
|
+
The command wrapper starts the bridge for this project. The Next config wrapper connects the browser UI to that bridge. Using only one of these two pieces is not a complete setup.
|
|
77
|
+
|
|
78
|
+
### Vite
|
|
79
|
+
|
|
80
|
+
Add the Vite plugin. It starts and connects the bridge with the Vite dev server.
|
|
63
81
|
|
|
64
82
|
```ts
|
|
65
83
|
// vite.config.ts
|
|
66
84
|
import { popmelt } from '@popmelt.com/core/vite';
|
|
67
|
-
|
|
85
|
+
import react from '@vitejs/plugin-react';
|
|
86
|
+
import { defineConfig } from 'vite';
|
|
87
|
+
|
|
88
|
+
export default defineConfig({
|
|
89
|
+
plugins: [react(), popmelt()],
|
|
90
|
+
});
|
|
68
91
|
```
|
|
69
92
|
|
|
70
|
-
|
|
93
|
+
### Astro
|
|
71
94
|
|
|
72
|
-
|
|
95
|
+
Add the Astro integration. It starts and connects the bridge with the Astro dev server.
|
|
96
|
+
|
|
97
|
+
```js
|
|
73
98
|
// astro.config.mjs
|
|
74
99
|
import { popmelt } from '@popmelt.com/core/astro';
|
|
75
|
-
|
|
100
|
+
import { defineConfig } from 'astro/config';
|
|
101
|
+
|
|
102
|
+
export default defineConfig({
|
|
103
|
+
integrations: [popmelt()],
|
|
104
|
+
});
|
|
76
105
|
```
|
|
77
106
|
|
|
78
|
-
|
|
107
|
+
### Other development servers
|
|
108
|
+
|
|
109
|
+
The wrapper works with any dev command:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"scripts": {
|
|
114
|
+
"dev": "popmelt wrap -- your-existing-dev-command"
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
You can also start the bridge from custom server startup code:
|
|
79
120
|
|
|
80
121
|
```ts
|
|
81
122
|
import { startPopmelt } from '@popmelt.com/core/server';
|
|
123
|
+
|
|
82
124
|
await startPopmelt();
|
|
83
125
|
```
|
|
84
126
|
|
|
85
|
-
|
|
127
|
+
## Verify the installation
|
|
86
128
|
|
|
87
|
-
|
|
129
|
+
Start the app using its normal development command:
|
|
88
130
|
|
|
89
131
|
```bash
|
|
90
|
-
|
|
91
|
-
npx @popmelt.com/core bridge
|
|
92
|
-
|
|
93
|
-
# bridge + dev server together
|
|
94
|
-
npx @popmelt.com/core wrap -- next dev
|
|
95
|
-
npx @popmelt.com/core wrap -- vite
|
|
132
|
+
npm run dev
|
|
96
133
|
```
|
|
97
134
|
|
|
98
|
-
|
|
135
|
+
You should see both the bridge URL and the application URL in the terminal. Open the app and double-tap Cmd on macOS or Ctrl on Windows/Linux. The Popmelt toolbar should appear.
|
|
99
136
|
|
|
100
|
-
|
|
137
|
+
If the toolbar opens but cannot reach an AI, check that:
|
|
101
138
|
|
|
102
|
-
|
|
139
|
+
- The dev script includes `popmelt wrap` when using Next.js.
|
|
140
|
+
- The framework plugin or config wrapper is installed.
|
|
141
|
+
- A supported AI CLI is available and authenticated.
|
|
142
|
+
- Another project is not using an old Popmelt bridge. Restart the dev command to reconnect the correct project.
|
|
103
143
|
|
|
104
|
-
|
|
105
|
-
|------|----------|-------------|
|
|
106
|
-
| **Comment** | `C` | Click any element to pin a comment. Captures tag, classes, React component name, and ancestor context. |
|
|
107
|
-
| **Handle** | `H` | Drag padding, gap, border-radius, font-size, and line-height handles directly on elements. Shift to snap to a scale. |
|
|
108
|
-
| **Model** | `M` | Hover elements to see component boundaries. Click to promote a component or token into your design model. |
|
|
109
|
-
| **Rectangle** | `R` | Draw a rectangle to highlight a region. Auto-prompts for a text label. |
|
|
110
|
-
| **Oval** | `O` | Draw an ellipse. |
|
|
111
|
-
| **Line** | `L` | Draw a straight line. |
|
|
112
|
-
| **Pen** | `P` | Freehand drawing. |
|
|
113
|
-
| **Text** | `T` | Click to place a text label anywhere. |
|
|
144
|
+
## Installing with an AI
|
|
114
145
|
|
|
115
|
-
|
|
116
|
-
<img src="src/assets/bar - comment.png" alt="Comment tool guidance" width="360" style="border-radius: 12px;" />
|
|
117
|
-
<img src="src/assets/bar - rectangle.png" alt="Rectangle tool guidance" width="360" style="border-radius: 12px;" />
|
|
118
|
-
<img src="src/assets/bar - text.png" alt="Text tool guidance" width="360" style="border-radius: 12px;" />
|
|
119
|
-
</p>
|
|
146
|
+
You can hand the following checklist to an AI coding agent:
|
|
120
147
|
|
|
121
|
-
|
|
148
|
+
> Install `@popmelt.com/core` and `lucide-react`. Add `PopmeltProvider` at the application root. Preserve the existing dev command, but for Next.js prefix it with `popmelt wrap --` and wrap `next.config` with `withPopmelt`. For Vite or Astro, add the corresponding Popmelt plugin. Start the app and verify that the toolbar opens after double-tapping Cmd/Ctrl and that the bridge belongs to this project.
|
|
122
149
|
|
|
123
|
-
|
|
150
|
+
The important Next.js detail is that `withPopmelt()` does not start the bridge by itself. The `dev` script must also use the Popmelt wrapper.
|
|
124
151
|
|
|
125
|
-
|
|
126
|
-
- **Gap** — drag between flex or grid children to adjust row/column gap.
|
|
127
|
-
- **Border radius** — drag element corners to round them.
|
|
128
|
-
- **Font size** — drag the right edge of a text element to resize.
|
|
129
|
-
- **Line height** — drag below a text element to adjust leading.
|
|
152
|
+
## Use Popmelt
|
|
130
153
|
|
|
131
|
-
|
|
154
|
+
Double-tap Cmd/Ctrl to open or collapse the toolbar. Hover any toolbar control to see its guidance panel.
|
|
132
155
|
|
|
133
|
-
|
|
156
|
+
| Tool | Shortcut | Use it to |
|
|
157
|
+
| --------- | -------- | ------------------------------------------------------------------------------------- |
|
|
158
|
+
| Comment | `C` | Pin feedback to a specific element and start a conversation with your AI. |
|
|
159
|
+
| Handle | `H` | Adjust layout, spacing, typography, color, borders, and effects directly on the page. |
|
|
160
|
+
| Rectangle | `R` | Mark a rectangular region. |
|
|
161
|
+
| Oval | `O` | Mark an oval region. |
|
|
162
|
+
| Line | `L` | Point at or connect parts of the UI. |
|
|
163
|
+
| Pen | `P` | Draw a freehand annotation. |
|
|
164
|
+
| Text | `T` | Add a label or edit existing page text inline. |
|
|
165
|
+
| Evals | `E` | Synthesize, review, and run checks inferred from project decisions. |
|
|
166
|
+
| Model | `M` | Review project patterns, components, and design-model suggestions. |
|
|
134
167
|
|
|
135
|
-
|
|
136
|
-
<img src="src/assets/bar - handle.png" alt="Handle tool guidance" width="360" style="border-radius: 12px;" />
|
|
137
|
-
</p>
|
|
168
|
+
### Hand off work
|
|
138
169
|
|
|
139
|
-
|
|
170
|
+
Create one or more annotations, then press Cmd/Ctrl+Enter. Popmelt sends the visual state, element context, requested edits, and relevant project history to the selected AI.
|
|
140
171
|
|
|
141
|
-
|
|
172
|
+
The conversation opens in a thread beside the page. You can continue working while jobs run, reopen threads from their status badges, answer questions, and send follow-up guidance. Messages sent while an active thread is working are staged and delivered together on its next run.
|
|
142
173
|
|
|
143
|
-
###
|
|
174
|
+
### Comment on elements
|
|
144
175
|
|
|
145
|
-
|
|
176
|
+
Select Comment and click an element. Type what should change, then hand it off with Cmd/Ctrl+Enter. The annotation remains attached to that element as the page scrolls and across supported route changes.
|
|
146
177
|
|
|
147
|
-
|
|
178
|
+
If the AI needs clarification, the annotation shows a Question badge. Open the thread, answer it, and send the reply.
|
|
148
179
|
|
|
149
|
-
|
|
180
|
+
### Adjust UI directly
|
|
150
181
|
|
|
151
|
-
|
|
182
|
+
Select Handle and hover an element. Depending on the element, you can adjust:
|
|
152
183
|
|
|
153
|
-
|
|
184
|
+
- Width, height, padding, and gap
|
|
185
|
+
- Flex and grid alignment
|
|
186
|
+
- Font family, weight, size, line height, letter spacing, and alignment
|
|
187
|
+
- Text and background colors
|
|
188
|
+
- Opacity, radius, borders, and effects
|
|
189
|
+
- Raw CSS for properties not represented by a dedicated control
|
|
154
190
|
|
|
155
|
-
|
|
191
|
+
Right-click the focused element to open the full Handle panel. Values inherited from the page appear as placeholders until you explicitly change them. Hover and scrub numeric field icons to tune values; use modifier keys shown in the panel guidance for snapping and finer control.
|
|
156
192
|
|
|
157
|
-
|
|
193
|
+
Handle changes are previews. They are recorded with the annotation so the AI can implement the corresponding source-code changes.
|
|
158
194
|
|
|
159
|
-
|
|
195
|
+
You can also drag supported elements to propose a new position, and use Cmd/Ctrl+C and Cmd/Ctrl+V in Handle mode to duplicate supported page structures as visual guidance.
|
|
160
196
|
|
|
161
|
-
|
|
197
|
+
### Edit text inline
|
|
162
198
|
|
|
163
|
-
|
|
164
|
-
<img src="src/assets/bar - model.png" alt="Model tool guidance" width="360" style="border-radius: 12px;" />
|
|
165
|
-
</p>
|
|
199
|
+
Select Text and hover page copy. Recognized text elements receive a bounding box. Click to edit the actual visible text in place, then finish the edit to retain it as a pending change.
|
|
166
200
|
|
|
167
|
-
|
|
201
|
+
Clicking outside editable page copy still creates a free-positioned text annotation.
|
|
168
202
|
|
|
169
|
-
|
|
203
|
+
### Draw visual guidance
|
|
170
204
|
|
|
171
|
-
|
|
205
|
+
Rectangle, Oval, Line, and Pen annotations are useful when the desired result is easier to show than describe. Add labels where useful, then submit them with the rest of the page context.
|
|
172
206
|
|
|
173
|
-
|
|
207
|
+
### Work across routes
|
|
174
208
|
|
|
175
|
-
|
|
209
|
+
Pass `navigate` to `PopmeltProvider` to enable route-aware annotations and multi-page capture. Annotation and status badges appear only on their relevant routes. When a handoff includes multiple routes, Popmelt captures each route and sends them together.
|
|
176
210
|
|
|
177
|
-
|
|
211
|
+
## AI providers and models
|
|
178
212
|
|
|
179
|
-
|
|
180
|
-
<PopmeltProvider
|
|
181
|
-
enabled={true} // default: process.env.NODE_ENV === 'development'
|
|
182
|
-
bridgeUrl="http://localhost:1111" // default
|
|
183
|
-
navigate={router.push} // optional: enables multi-page annotations
|
|
184
|
-
>
|
|
185
|
-
```
|
|
213
|
+
Popmelt detects supported AI CLIs available in the project environment. Click the provider icon to switch providers. Click the model name, or hover the provider controls, to choose among detected models.
|
|
186
214
|
|
|
187
|
-
|
|
215
|
+
When supported by the selected model, the model guidance panel also exposes:
|
|
188
216
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
217
|
+
- Thinking or reasoning effort
|
|
218
|
+
- Standard or faster service tiers
|
|
219
|
+
|
|
220
|
+
These settings persist per provider and model and apply to annotations, replies, model work, and evals.
|
|
221
|
+
|
|
222
|
+
## Threads and job status
|
|
223
|
+
|
|
224
|
+
Each handoff creates or continues a conversation thread. Status badges stay available while work is queued or running and return you to the associated element and conversation.
|
|
225
|
+
|
|
226
|
+
Use Cancel in the thread to stop the active job associated with that conversation. Closing a thread does not delete it. Delete its annotation to remove that thread, or use Cmd/Ctrl+Backspace to clear all local annotations and pending preview changes.
|
|
227
|
+
|
|
228
|
+
## Decisions and the project model
|
|
229
|
+
|
|
230
|
+
Completed annotation threads leave a decision history in the project. Popmelt uses that evidence to identify reusable design patterns rather than treating every edit as an isolated instruction.
|
|
231
|
+
|
|
232
|
+
When Popmelt finds a model opportunity, it places the proposal in the relevant annotation thread. Expand the proposal to inspect the exact changes, select only the entries you agree with, and apply or dismiss them. Applied changes contribute to the local project model.
|
|
233
|
+
|
|
234
|
+
Use the Model panel to inspect captured patterns and components or to synthesize model guidance from accumulated project history.
|
|
235
|
+
|
|
236
|
+
## Evals
|
|
237
|
+
|
|
238
|
+
Evals turn project decisions into explicit checks that can be rerun as the UI evolves.
|
|
239
|
+
|
|
240
|
+
1. Open Evals and select **Synthesize**.
|
|
241
|
+
2. Review the inferred drafts.
|
|
242
|
+
3. Edit titles or assertions inline.
|
|
243
|
+
4. Approve useful evals and reject the rest.
|
|
244
|
+
5. Run approved evals against the current page.
|
|
245
|
+
|
|
246
|
+
Eval results appear in their conversation threads and on each assertion in the Evals panel. Results are cleared when the eval changes or when project code changes, signaling that the eval needs a fresh run.
|
|
247
|
+
|
|
248
|
+
Model proposals can also create draft evals directly from approved model changes.
|
|
249
|
+
|
|
250
|
+
## Useful shortcuts
|
|
251
|
+
|
|
252
|
+
| Shortcut | Action |
|
|
253
|
+
| ------------------------- | --------------------------------------------------------------- |
|
|
254
|
+
| Double-tap Cmd/Ctrl | Open or collapse Popmelt |
|
|
255
|
+
| Cmd/Ctrl+Enter | Hand off pending work |
|
|
256
|
+
| Cmd/Ctrl+C | Copy an annotated screenshot, or copy an element in Handle mode |
|
|
257
|
+
| Cmd/Ctrl+V | Paste a copied element in Handle mode |
|
|
258
|
+
| Cmd/Ctrl+Z | Undo a pending change |
|
|
259
|
+
| Cmd/Ctrl+Shift+Z | Redo a pending change |
|
|
260
|
+
| Backspace/Delete | Delete the selected annotation |
|
|
261
|
+
| Cmd/Ctrl+Backspace/Delete | Clear all annotations and pending changes |
|
|
262
|
+
| Escape | Cancel the active edit or deselect the current annotation |
|
|
263
|
+
|
|
264
|
+
## Advanced setup
|
|
265
|
+
|
|
266
|
+
Run a bridge without wrapping another command:
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
npx @popmelt.com/core bridge
|
|
200
270
|
```
|
|
201
271
|
|
|
202
|
-
|
|
272
|
+
Stop a detached bridge for the current project:
|
|
203
273
|
|
|
204
|
-
|
|
274
|
+
```bash
|
|
275
|
+
npx @popmelt.com/core stop
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Start a configured bridge in server code:
|
|
205
279
|
|
|
206
280
|
```ts
|
|
207
|
-
|
|
281
|
+
await startPopmelt({
|
|
282
|
+
port: 1111,
|
|
283
|
+
projectRoot: '.',
|
|
284
|
+
devOrigin: 'http://localhost:3000',
|
|
285
|
+
provider: 'codex',
|
|
286
|
+
timeoutMs: undefined,
|
|
287
|
+
});
|
|
208
288
|
```
|
|
209
289
|
|
|
210
|
-
|
|
290
|
+
`startPopmelt()` returns the selected port, the stable project ID, and a `close()` function.
|
|
291
|
+
|
|
292
|
+
## Local project data
|
|
211
293
|
|
|
212
|
-
|
|
213
|
-
- Node.js 18+ (server)
|
|
214
|
-
- Claude CLI, Codex CLI, or GitHub Copilot CLI installed for AI integration
|
|
294
|
+
Popmelt writes project history under `.popmelt/`. Keep this directory when you want decisions, threads, the local model, and evals to survive across sessions. The browser also uses local storage for unsent annotations and preview edits.
|
|
215
295
|
|
|
216
296
|
## License
|
|
217
297
|
|
|
218
298
|
[PolyForm Shield 1.0.0](./LICENSE)
|
|
219
299
|
|
|
220
|
-
|
|
300
|
+
You may use and extend Popmelt for yourself and your team. You may not sell it, offer it as a managed service, or use the code to create a competing product or service. The software is provided as-is.
|
|
221
301
|
|
|
222
|
-
|
|
302
|
+
For custom licensing, contact [reb@popmelt.com](mailto:reb@popmelt.com).
|
|
223
303
|
|
|
224
304
|
<p align="center">
|
|
225
|
-
<img src="src/assets/popmelt-logo.svg" alt="Popmelt" width="64" />
|
|
305
|
+
<img src="src/assets/popmelt-logo.svg" alt="Popmelt" width="64" />
|
|
226
306
|
</p>
|