Popmelt

v0.36.0

Popmelt

v0.36.0
© 2026 Popmelt
HelpPrivacyTerms
Docs

  • Getting started with Popmelt Core
  • Creating annotations with the Chat tool
  • Comparing and refining options with Explore
  • Tweaking styles with the Steer tool
  • Helping your AI understand your taste with the Imprint tool
  • Using Popmelt with Three.js and react-three-fiber
  • Add custom context to Popmelt annotations and threads
  • Recovering an annotation that won’t send
  • Inviting a teammate to a local session
  • Where Popmelt saves and sends your data

  • Annotating static objects in images
  • Annotating moving objects in video
Docs/Core

Creating annotations with the Chat tool

Pin feedback, hand off a bundle of changes, and keep the conversation beside your UI.

Annotations give your agent a specific target and your intent. Chat lets you discuss the work, and threads keep the feedback, replies, and follow-ups together so you can iterate without re-explaining the page.

Leave a comment

Choose Chat (C) and click an element. Type your feedback, then press Enter to finish the draft. Shift+Enter adds a new line. Paste an image into the comment to attach a visual reference.

Shake your mouse to quickly switch between Chat and Steer, so you can move between leaving feedback and tweaking styles.

You can leave several comments before sending. Command/Control+Enter hands off the whole pending bundle, including staged Steer changes and direct text edits, as one thread. See Tweaking styles with the Steer tool for the styling workflow.

Draft comments are not submitted instructions. Finishing a draft or previewing a change does not start an agent run.

If a send stalls or a reply shows Not sent, check the thread and recover the note.

Edit text directly

In Chat, double-click the words you want to change. Type their replacement and press Enter to stage the edit. For example, replace “Ask your agent” with “Ask your coding agent.” Press Command/Control+Enter when you want the agent to implement the pending change.

The text edit stays with its target until you send the pending work.

Annotate images and paused video

Manual media annotation is part of Core and is enabled by default. It does not require See, object segmentation, or a vision-model download.

On desktop, drag in Chat to draw a lasso around a region. To create a named object on an image or paused video, hold Option on macOS or Alt on Windows or Linux while you drag a box around it. Release the mouse, give the object a name, and press Enter to save the box.

Once saved, the cloud can receive its own comments.
  • Single-click an object to comment on it.
  • Double-click an object to rename or resize it.
  • Right-click its label to delete it.

Image targets stay aligned as the image resizes. A manual video box stays at its saved position unless a perception extension supplies motion tracking. To add recognition with See, read Annotating static objects in images. To follow an object through video, read Annotating moving objects in video.

Configure media annotation

Use imageAnnotation={false} or videoAnnotation={false} on PopmeltProvider to disable either capability. To limit eligible images:

<PopmeltProvider imageAnnotation={{ selector: 'img[data-popmelt-media]' }}>
  {children}
</PopmeltProvider>

Give media a stable identity when its URL may change or the same source appears more than once:

<img data-popmelt-media-id="hero-product" src={imageUrl} alt="Product" />
<video data-popmelt-media-id="hero-reel" src={videoUrl} controls />

Media-object stores are browser-local by default. Supply imageAnnotation.store or videoAnnotation.store when targets must survive browser-site-data removal or move between origins. Extension-produced tracks remain replayable through Core after the extension is disabled.

For objects in a Three.js scene, see Using Popmelt with Three.js and react-three-fiber.

Continue the conversation

Click an annotation or status badge to reopen its thread. The thread keeps the original targets and evidence with the replies, so a follow-up such as “A little less padding” has context.

In the thread composer, Enter sends a reply and Shift+Enter adds a line. During an active run, Enter redirects the agent to your new message after the current run stops. If it has just finished, your message starts a follow-up. To let the current run finish and queue your message, use Cmd+Enter on macOS or Ctrl+Enter on Windows and Linux.

With the reply field empty, press Stop to interrupt a run. The control changes to Continue (the play icon). Press it to pick up where you left off, or type a new instruction to bring back Send.

An empty composer offers Continue after a stop. Typing a different instruction brings back Send.
  • Use the header chevrons to cycle through visible threads.
  • Drag the header to reposition a thread; double-click it to restore its default position.
  • Press Escape to close the panel without archiving the conversation.
  • If a follow-up is queued, use its pencil or trash button to edit or delete that message before it starts. Save an edit with the checkmark or Command/Control+Enter; Escape cancels it.

Compare options with Explore

On an annotation for a single element, type /explore and describe the alternatives you want to see. Each option appears in the preview card as it becomes ready. Step back to Original to compare with the element you annotated, or use the eye to preview an option on the page.

For a worked example, compare three treatments for a button, refine one, and apply it in code.

Annotate from your phone

Connect your phone and computer to the same Wi-Fi. In the desktop Popmelt toolbar, open the guide and select Pair Phone (the phone icon to the left of History). Opening Pair your phone starts a local HTTPS listener for your dev site. Scan the QR code with your phone’s camera.

Each code works once. A fresh code appears when the five-minute countdown ends. To pair another phone sooner, select the refresh icon in the top right. Each paired phone opens the same project, threads, and Imprint, even with multiplayer off.

If your dev site already has an HTTPS address your phone trusts, you can also create a single-use link from the project directory.

npx @popmelt.com/core phone https://my-mac.local:3000
  • Annotate. In Chat, tap an element, type your note, and tap Send. Use the × in the thread title to return to the page, or the archive icon to move the conversation to History.
  • Review. Swipe across the option counter to step between options. Expand the preview to put the canvas above the reply field. After zooming in, drag the canvas to pan. Tap an element to attach it to a reply. Steer requires a fine pointer.
  • Reconnect. The browser remembers the pairing for up to seven days or until the bridge stops. After a restart, select Pair Phone and scan a fresh code. To disconnect all paired phones, run npx @popmelt.com/core phone revoke on your computer.
On a phone, the expanded canvas and reply field share the screen.

Approvals and review

To review work from another person before it goes to the agent, invite them with Suggest access.

Codex permission requests appear in the thread. Expand the request to inspect the command or file changes, then choose Allow once or Deny. Answered requests remain in the conversation history.

Typing “go ahead” in chat is not a permission grant. Existing Codex permission rules still apply; previously allowed actions may not show a new approval card. Interactive approvals require a compatible Codex CLI.

Your agent can edit files and run commands. Review the diff and run your project's tests before shipping.

Clear a draft, dismiss a rail, or archive a thread

These actions do different things:

  • Remove a draft: right-click a draft comment or staged change in its rail to remove only that item.
  • Dismiss a replied rail: right-click it to hide it from the canvas without deleting history or reverting implemented changes. Command/Control+Z outside a text editor restores it before a reload. Fresh drafts and active runs are protected.
  • Archive a thread: press Backspace/Delete while its panel is open or a historical annotation is selected. Archiving hides it from the active canvas but retains the stored conversation.

Delete shortcuts leave focused text fields alone.

What is saved

Thread history, screenshots, and Imprint live with the project under .popmelt/. Explore also saves each option’s text and style edits with its thread. You can edit a label on your computer, open the same project on a paired phone, and apply that option with its edited label. Reviewed previews from new rounds remain available in History after Apply and archive.

Unsent page annotations stay in the browser where you drafted them. When you send work, the relevant context goes to your chosen AI provider.

For storage across browsers, project history, and usage reporting in older releases, see Where Popmelt saves and sends your data.

For application-owned context such as document IDs, data revisions, or video frame times, see Add custom context to Popmelt annotations and threads. Core can attach a snapshot to the corresponding human turn with getCommentMeta.

Next: Tweaking styles with the Steer tool or Helping your AI understand your taste with the Imprint tool.

Didn't find the answer? Have an idea?

Ask a question