Annotate is the tool for feedback that isn't ready to become an instruction yet — a note, a bug flag, a “this should move” — pinned to the exact spot it's about. Here's how pins, persistence, and the agent handoff actually work.

Five types, one color language

Every annotation has a type, and each type owns one color, used consistently everywhere it shows up — the pin, the border, the filter chip:

Placement and Rearrange exist as distinct types because “this is in the wrong spot” and “swap the order of these” are different instructions to hand an agent than a general comment — the type itself carries intent, not just severity.

Pins: collapsed by default, expand on hover

A pin renders as a 20×20 type-colored marker at the element's top-right corner, clamped so it never renders off-screen. Hover or click it and it expands into a 200px frosted card — real backdrop-filter blur over the live page — with the full note and edit controls. Resolved pins fade, but only while collapsed; once you're looking at one, it's shown at full opacity regardless of status.

That blur is the reason pins render as a portal straight to document.body instead of inside the toolbar's shadow root: backdrop-filter doesn't compose the way you'd want across a shadow boundary, so the toolbar's isolated rendering — normally a feature — would work against the visual here.

Where a pin's position comes from

An annotation stores a CSS selector and, when available, a source file path and line number for the element it's pinned to — not just raw screen coordinates. That's what lets a pin re-anchor to the right spot after a reload instead of drifting if the page's layout shifts slightly between visits.

Annotations survive reloads — scoped to the page

Annotations persist in localStorage, keyed by a normalized version of the page's URL (host plus path plus query, with www. and trailing slashes stripped so https://www.site.com/pricing/ and https://site.com/pricing share one bucket). Reload the page, come back tomorrow — your pins are still there, still attached to the right elements, scoped to that page and not leaking into notes left on a different route.

Freehand sketches, not just pins

You're not limited to annotating a single element. A freehand draw mode lets you sketch directly on the page over any region — the result becomes a PNG attachment rather than an element-anchored pin, for feedback that's about a layout relationship or a visual detail that doesn't belong to one DOM node. Once you finish a sketch, you choose where it goes: Add to chat hands it to the Agent panel, Add to comment attaches it to the next annotation you compose. Same capture pipeline, two different destinations — pick per sketch.

Filtering the list

The annotation panel filters by All, Comment, Bug, or Todo (Placement and Rearrange stay visible under All, styled by their own color, without a dedicated filter chip). There's also a copy all action that bundles every open annotation into one prompt-ready block — useful when you've collected feedback across a page and want to hand it all to an agent in a single pass instead of one capture per pin.

What happens after you send one to an agent

Sending an annotation links it to the MCP capture it was bundled into. From there, the agent's own status updates flow back onto the pin: it can mark an annotation acknowledged, resolved, or dismissed, attach a message (a reply, a resolution summary, or a reason for dismissing it), and — if the fix genuinely closes the loop — auto-resolve it, which timestamps resolvedAt the same as if you'd clicked resolve yourself. You get a written trail of what the agent did about each specific piece of feedback, not just a general “done.”

Tips

• Use Placement and Rearrange instead of a generic comment when the ask is really “move this” — the type itself is part of the instruction the agent receives, not just a label for your own filtering.
• Don't feel like every note needs an element under it — freehand-sketch a region when the feedback is about a relationship between things, not one thing.
• Batch feedback with copy all before opening an agent session, instead of sending pins one at a time, if you've collected several notes across one pass over a page.
• Check back on pins after an agent run — the status and message it left are often enough to confirm a fix without re-testing yourself.
• Remember annotations are page-scoped by URL: notes left on /pricing won't show up while you're looking at /docs, even in the same session.