Release Notes

v2.0.1 — Ask for variants
A small follow-up to v2.0.0 that makes the variants workflow feel more natural and keeps your annotation queue clean.

What's new

🧬 Just *ask* for variants

Typing something like *"make variants of this"* or *"show me a few versions"* straight into a normal comment will be recognized by your agent — routing the annotation through the same build-preview-and-pick flow, right in your codebase. *(Requires the MCP server.)* → Variants

🧹 Cleaner handoffs

Your agent now reliably clears each annotation once it's implemented, instead of leaving finished ones on the page. This fixes a rough edge with design edits: a leftover edit used to re-apply its live preview on top of your already-changed code on reload. Design edits are now closed out as soon as they land, and a variants request no longer stops the agent from tidying up everything else. --- The MCP server moves to v0.5.1 — update with npx vibe-annotations-server init (or npm i -g vibe-annotations-server). 📚 Full documentation: vibe-annotations.com/docs
v2.0.0 — Meet Vibo
Vibo, the Vibe Annotations mascot, waving hello

Say hello to Vibo 👋

Meet Vibo — our new Cursor-devil, detail-chasing mascot. Little horns, little wings, and an eye for the pixels you missed. Vibo is the face of our biggest release yet: v2.0.0 reworks how you annotate, edit, and hand work off to your coding agent, and rebuilds the extension from the ground up.

What's new

🧬 Component variants

Ask your agent for several variants of a component, preview them right on the page, and pick the winner. The agent builds each one in your real codebase — not a mockup — then finalizes your choice and strips the scaffolding for a clean diff. *(Requires the MCP server.)* → Variants

📸 Screenshots & reference images

Every pin can carry an automatic screenshot of the element you annotated, plus any reference images you paste or attach. Your agent receives both as real files and is told which is *current state* vs *design target*. → Screenshots & images

📤 Share a review in one file

Export a batch of annotations three ways: .md (offline, personal handoff), .html (self-contained, every image embedded — share with anyone, no extension needed), or .json (re-import onto another localhost). → Sharing a review

🧠 Richer element context

Every pin now resolves the React (or Vue) component and its source file from the page's real fiber tree, so your agent jumps straight to the right file instead of guessing from the DOM.

🎨 A single, unified popover

Comment, design edits, and variants now live in one panel with intent tabs, plus a + attachment menu. Design edits still preview live on the page — now a click away from everything else on the pin. → Design edits

⚙️ Under the hood: rebuilt on WXT

The extension is now built with WXT, a modern web-extension framework. What that means for you:
  • Hot reload while developing — WXT hot-reloads the extension UI and auto-reloads content scripts the moment you save. No more hunting for the "reload" button in chrome://extensions on every change.
  • A cleaner ES-module codebase and a modern build/zip pipeline for Chrome Web Store submissions.
  • Contributors: run pnpm dev in packages/extension/, load .output/chrome-mv3 once, and iterate with live reload. See the Architecture docs.
    • The MCP server moves to v0.5.0 — update with npx vibe-annotations-server init (or npm i -g vibe-annotations-server). --- 📚 Full documentation: vibe-annotations.com/docs
    v1.6.3 — Setup Wizard

    Setup Wizard

    One interactive command replaces the 4-step setup (install → start → configure agent → link extension): `bash npx vibe-annotations-server init ` Detects your package manager, installs the server globally, starts it in the background on port 3846, configures your AI coding agent (Claude Code, Cursor, Windsurf, Codex, OpenClaw, VS Code), and points you to the Chrome Web Store. Flags: --agent (repeatable), --project, --non-interactive, --skip-server, --skip-extension, --reset.

    What's new

    Server (0.4.0)
  • New init subcommand — interactive setup wizard built on @clack/prompts
  • Binary alias: vibe-annotations works alongside vibe-annotations-server
  • Unified agent config codepath: CLI when detected, direct JSON/TOML write otherwise, idempotent on re-run
  • Final summary surfaces status / logs -f / stop so users know the daemon is running
    • Extension (1.6.3)
  • In-extension setup card, MCP workflow, and multi-page workflow screens now lead with npx vibe-annotations-server init
  • Manual setup steps kept as a fallback below
    • Docs
  • Root README, server README, website docs (installation, MCP setup, workflows), llms.txt, and extension CLAUDE.md all lead with init as the recommended path
  • claude mcp add --scope user (global config) is now the default across all docs
    • Full changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.6.2...v1.6.3
    v1.6.2

    What's new

    UX & UI refresh, quality of life improvements

  • Clearer annotation bar with labeled actions, morphing with instructions when annotating
  • New gradient on buttons, active tabs, and badges (#E85B5C → #D03D68)
  • Pin color default updated — first option in the settings picker
  • Extension icon badge uses the same color

    • Clipboard improvements

  • Route grouping: Copy from View All now groups annotations by route with ## /path headers
  • Stylesheet annotations: Show as [Stylesheet change] instead of ?
  • Copy feedback: Green checkmark flashes on the copy button

    • Badge count fix

  • Extension icon badge now counts all annotations for the site (project-wide), matching the toolbar pill — previously only counted the current URL

    • Codebase refactoring

  • Split monolith modules: annotation-popover.js (2256→684 lines) and floating-toolbar.js (1807→1375 lines) into focused sub-modules
  • Removed 3,000+ lines of dead code including the unused popup/ directory from pre-v1.1.0
  • Storage layer consolidated — all mutations through background.js with lock, removing race-prone fallback writes

    • Server (vibe-annotations-server)

  • Removed dead applyAnnotationsUpdate() method
  • Extracted filterByUrlPattern() utility (was duplicated 3×)
  • Added max watcher limit (100) to prevent memory leaks
  • Removed unused node-persist dependency
    • Full changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.6.1...v1.6.2
    Watch on GitHub
    v1.6.1 — Leaner annotations, smarter context

    Before / After — MCP output for a comment-only annotation

    Before (v1.6.0) `json { "selector": "[data-vibe-id=\"vibe-annotation-...\"]", "element_context": { "tag": "div", "classes": ["rounded-2xl", "border", "border-border", "bg-surface-alt", "p-6"], "text": "📦Multi-Page Batching...", "styles": { "display": "block", "position": "static", "fontSize": "16px", "fontWeight": "400", "lineHeight": "24px", "textAlign": "start", "color": "rgb(248, 250, 252)", "backgroundColor": "rgb(15, 23, 42)", "margin": "0px", "padding": "24px", "paddingTop": "24px", "paddingRight": "24px", "paddingBottom": "24px", "paddingLeft": "24px", "marginTop": "0px", "marginRight": "0px", "marginBottom": "0px", "marginLeft": "0px", "flexDirection": "row", "flexWrap": "nowrap", "justifyContent": "normal", "alignItems": "normal", "gap": "normal", "columnGap": "normal", "rowGap": "normal", "gridTemplateColumns": "none", "gridTemplateRows": "none", "borderTopWidth": "1px", "borderRadius": "16px", "borderStyle": "solid", "borderColor": "rgb(30, 41, 59)", "width": "504px", "minWidth": "auto", "maxWidth": "none", "height": "175.5px", "minHeight": "auto", "maxHeight": "none" }, "position": { "..." : "..." } }, "context_hints": ["UI section: main-content", "Next.js app detected", "CSS-in-JS styling detected"], "_synced": true, "badge_offset": { "x": 138.94, "y": 23.49 }, "source_file_path": null, "source_line_range": null, "source_map_available": false, "has_screenshot": true } ` After (v1.6.1) `json { "selector": "[data-vibe-id=\"vibe-annotation-...\"]", "selector_preview": "
    ", "element_context": { "tag": "div", "classes": ["rounded-2xl", "border", "border-border", "bg-surface-alt", "p-6"], "text": "📦Multi-Page Batching...", "path": "div[class=\"mx-auto max-w-7xl px-6\"] > div[class=\"mx-auto max-w-5xl\"] > div[class=\"grid gap-4\"] > div[class=\"rounded-2xl border border-border\"]", "position": { "..." : "..." } }, "has_screenshot": true } `

    What changed

  • Stripped computed styles from MCP — 38 CSS properties like flexWrap: "nowrap" and gridTemplateColumns: "none" were token waste. Agents use classes and pending_changes, not browser-computed values.
  • New selector_preview — readable HTML tag (
    ) instead of raw data-vibe-id selectors
  • New path — 4-level DOM breadcrumb for structural context
  • Framework class filtering — ng-tns-*, cdk-*, css-*, jsx-*, sc-* noise stripped at capture time
  • Stripped noise fields — _synced, badge_offset, context_hints, and null fields removed from MCP responses
  • Bridge API parity — annotations created by in-browser agents now include selector_preview and path
  • CSS rule placeholder — shows a useful example instead of a data-vibe-id selector

    • Credits

    Selector preview, DOM path, and framework class filtering built on work by @tulindesign (#63).
    v1.6.0 — Watch Mode

    Watch Mode

    Coding agents can now automatically pick up and implement annotations as you drop them: no copy-paste, no manual triggering. It feels like getting pursued by a front-end developer, give a try, and enjoy editing your web apps faster than ever 🏎️ 💨

    How it works

    1. Make sure the MCP server is running and connected to your agent 2. Tell your agent: "Start watching Vibe Annotations" 3. Annotate elements in the browser — the agent picks them up, implements changes, and deletes them automatically 4. An eye icon appears on the toolbar and badges while an agent is watching 5. Click the eye to stop, or it auto-stops after 5 minutes of inactivity

    What's new

    Server (0.2.0)
  • watch_annotations MCP tool — long-polls for new annotations with configurable timeout
  • /api/watchers endpoint for the extension to detect active watchers
  • /api/watchers/stop endpoint to let the extension stop watch mode
  • delete_annotation now succeeds gracefully when the annotation is already gone
    • Extension (1.6.0)
  • Eye icon replaces the copy button when an agent is watching the current page
  • Badges show eyes instead of numbers during watch mode
  • Pending design changes are preserved when the agent deletes resolved annotations (no style flicker before hot reload)
  • MCP Server item in settings is now clickable — opens a setup guide with install commands, agent connection tabs, and watch mode documentation
  • Enter key selects the highlighted element in inspection mode, allowing a more intuitive experience when using up/down key arrows for element inspection in the DOM tree.
    • Fix
  • Element styles no longer reset when saving, deleting, or cancelling annotations with pending design changes
    • v1.5.2

    Bug Fixes

  • Full URL display for hash routers and query params — Annotations, route labels, and clipboard exports now show the complete path including search params and hash fragments (/app#/settings?tab=2) instead of just the pathname (/app). Fixes incorrect context in hash-routed apps (Vue, React Router hash mode, etc.). Thanks @mikeozornin (#56)

    • New feature

    Pressing ↑/↓ in Annotation mode now travels to parent elements in the DOM. Press enter to confirm selection and create your annotation.

    Community

    Shoutout to @mikeozornin for the issue and the feature idea.
    v1.5.1

    Bug Fixes

  • Fixed annotations being silently deleted beyond 50 — The background sync fetched server annotations with a default limit of 50, causing any annotations beyond that to be interpreted as "deleted on server" and wiped on the next sync cycle. Both the extension and server now handle unlimited fetches during sync.

    • Changes

  • Extension sync now requests all annotations from the server during bidirectional sync
  • Server API now treats limit=0 as "no limit" instead of returning an empty array
  • Requires server update (npm install -g vibe-annotations-server) for full fix
    • v1.5.0 — Agent Collaboration & Bridge API

    What's new in 1.5.0

    This release transforms Vibe Annotations from a human-only annotation tool into a collaborative platform where AI agents can annotate alongside you.

    🤖 Bridge API

    AI agents with browser access can now create annotations directly via window.__vibeAnnotations. Works with:
  • Claude Chrome extension — direct page access via JavaScript tool
  • OpenClaw — CDP evaluate to run JS on the page
  • Claude Code, Cursor, Windsurf — via DevTools MCP server or Playwright
    • Call window.__vibeAnnotations.help() to discover the full API.

    🎨 Stylesheet annotations

    Agents can now create stylesheet annotations for bulk CSS changes that apply across the page — separate from element-anchored annotations. Great for restyling, theme adjustments, and design system tweaks.

    📦 Import & export

  • Export annotations as JSON to share with teammates or across machines
  • Import with automatic URL remapping — importing annotations from a public URL into localhost? The extension remaps them automatically

    • ✏️ CSS rules on annotations

    Element-anchored annotations now support CSS rules — :hover, ::before, @media queries and more. Write CSS that goes beyond inline style overrides.

    🌐 Public URL support

    New "Enable for all sites" toggle lets you use Vibe Annotations on any website, not just localhost. The bridge API is also available on public pages when enabled.

    📖 Restructured settings

  • Settings now open into a Documentation panel with nested navigation
  • Get started guide, workflow tips (single page, multi-page, collaborating, annotating with agents), Contribute, and Release notes all accessible from one place
  • Version number in header links directly to these release notes

    • 🔧 Fixes & improvements

  • CORS hardened — server now validates origins dynamically instead of a hardcoded allowlist
  • Cancel safety — cancelling an annotation no longer destroys element styles or child nodes
  • Atomic bulk delete — deleting all annotations uses a single write operation
  • Sync reliability — syncing no longer resurrects annotations deleted via MCP
  • Content textarea — properly wraps and auto-sizes long text on popover open
  • Chrome Web Store — updated extension name and description for better discoverability

    • Server changes (auto-published via npm)

  • Dynamic CORS origin validation
  • 5MB request body limit
  • Updated MCP tool descriptions with design system mapping guidance
    • --- Full changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.4.1...v1.5.0

    Licensing

    Now under Polyfield shield 1.0.0, welcoming contributors, but preventing cloners without best practices (like pointa.dev).
    v1.4.1

    Shadow DOM Support

    Vibe Annotations now works with web components and shadow DOM. Elements inside open shadow roots can be hovered, selected, annotated, and re-found across page reloads — including nested shadow roots (e.g. micro-frontend architectures). Supported frameworks and libraries: Lit, Shoelace, Vaadin, Ionic, Material Web, Stencil.js, Salesforce LWC, Angular Elements, and any custom attachShadow({ mode: 'open' }) usage. Selectors use a compound host >> inner format that chains through shadow boundaries. Design token scanning now reads CSS variables from shadow root stylesheets. Semantic role detection crosses shadow boundaries for accurate context hints.

    Sync & Offline Fixes

    Fixed: annotations lost when MCP server reconnects. The sync engine previously overwrote local storage with server state, destroying any annotations created while the server was down. Sync is now bidirectional — merges by updated_at timestamp, with tombstone tracking to prevent deleted annotations from resurrecting. Fixed: save button disabled when MCP server is offline. Annotations save to chrome.storage.local and never required the MCP server. The blocking health check and "Server offline — cannot save" warning have been removed. Popovers now open instantly.

    Performance

  • Inspection mode hover uses throttled pointermove (~60fps cap) instead of unthrottled events
  • Selector uniqueness checks use early-exit counting (stops as soon as count > 1)