Release Notes

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)
    • v1.4.0 — Manual Design Edits

    Introducing Manual Design Edits 🎉🎊

    You can now visually edit CSS properties directly from the annotation popover! Click any annotation badge to open the design toolbar — all fields are pre-populated with the element's current computed styles. Changes are applied live and persist across page reloads as long as the annotation exists. Supported properties:
  • Content — edit text content directly with live preview (auto-growing textarea, supports multi-line)
  • Font — size, weight, line height, text alignment
  • Sizing — width, height, min/max constraints
  • Spacing — padding & margin (vertical/horizontal or split per-side)
  • Layout — display mode (block, flex, grid), alignment matrix, gap, reverse order, wrap, space-between
  • Appearance — border radius, border width, border color, background color
  • Raw CSS — freeform CSS editing for any property not covered by the toolbar
    • Design changes are stored as pending_changes on each annotation and transmitted to AI coding agents via MCP, so agents know exactly what visual adjustments you want applied in code. Text content changes are stored as copyChange so agents know exactly what copy to update.

    Smarter Text Element Detection

    The extension now detects text-like containers — elements like
    Welcome
     that aren't semantic text tags but contain only inline text content. These elements now correctly show the Content and Font tabs instead of being treated as layout containers.

    Draggable Annotation Popover

    The annotation popover now has a drag handle — grab the top bar to reposition it anywhere on screen.

    Improved Hotkey Binding

    Set your trigger hotkeys inside the settings, find what works best for you.

    Badge Numbering Fix

    Provisional badge numbering now correctly accounts for all annotations (including unanchored ones), keeping numbers consistent with the toolbar count.

    Vibe Annotations now opened new usecases for collaboration

    Since the extension now works on any URL, you can ask for feedback on a project you are working on to anyone without any coding agent or MCP server setup. You just need to ask them to drop annotations, make changes however they want, and copy them over to you 🎉 --- Full Changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.3.0...v1.4.0
    Watch on GitHub
    v1.3.0 — Unified Popup, Per-Site Enabling & UX Improvements

    What's New

    Extension Popup Menu

    Clicking the extension icon now opens a popup menu on every site. From there you can:
  • Show / Hide Vibe Annotations overlay
  • Enable annotation on public sites — grant per-site permission without blanket access
    • image image
  • See update notifications — "Version X.X.X installed" banner with link to release notes

    • Per-Site URL Enabling (Beta)

    Annotate on any website — not just localhost. Click the extension icon on any public URL and enable it for that specific site. Each site requires individual opt-in to avoid accidental annotation clutter.

    Empty Annotations as Anchor Points

    Annotations can now be saved without a comment. Use them as visual anchor points to pass element context to AI agents — add a description later or leave them empty. image

    SPA Route Change Fix

    Annotations now properly swap when navigating between pages in single-page applications. Badges from other routes are cleared immediately and the toolbar count resets on navigation.

    "Don't Ask Again" on Delete

    The delete confirmation dialog now has a "Don't ask again" checkbox. Once opted in, deleting annotations (single or bulk) skips the confirmation permanently.

    Update Notifications Rework

  • "Version X.X.X installed" banner in popup with "Learn more" and dismiss
  • NEW badge on extension icon clears when popup is opened
  • Replaces the old behavior of hijacking the icon click to auto-open the release page

    • Bug Fixes

  • Provisional badge numbering now matches toolbar count (not just anchored badges)
  • Content script init failures are caught and logged to console
  • Dynamic content scripts persist across browser and service worker restarts
    • --- > Note: This release adds the scripting permission for dynamic content script registration on user-enabled sites. This may require additional Chrome Web Store review. Full Changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.2.3...v1.3.0
    Watch on GitHub
    Watch on GitHub
    Watch on GitHub
    v1.2.3 — Framework Compatibility Optimizations

    What's New

    SPA Route Detection

    Annotations now automatically reload when navigating between pages in single-page applications. Intercepts history.pushState/replaceState, listens for popstate (back/forward) and hashchange — works with React Router, Vue Router, Next.js, SvelteKit, Angular Router, and hash-based routers.

    Smarter Selector Generation

    Selectors now aggressively prefer stable test attributes (data-testid, data-cy, data-qa, data-e2e, data-automation-id, data-component) over class names. Also walks up to 5 ancestor elements to find a stable attribute to scope the selector — making annotations survive CSS-in-JS hash changes, CSS Modules rebuilds, and HMR reloads.

    Framework Re-render Resilience

    A new MutationObserver detects when framework re-renders (React, Vue, Angular, Svelte) replace annotated DOM elements with new nodes. Badges automatically re-match to the replacement element instead of going stale.

    Lazy-Loaded Component Support

    After initial retries, a persistent MutationObserver watches for late-arriving DOM elements from code-split routes, React.lazy, dynamic imports, and similar patterns. Badges appear as soon as the component loads, up to 30 seconds after page load.

    Framework Compatibility

    | Framework | Status | |-----------|--------| | React / CRA | ✅ Improved | | Next.js | ✅ Improved | | Vue 3 / Nuxt | ✅ Excellent | | Svelte / SvelteKit | ✅ Excellent | | Angular | ✅ Improved | | Astro | ✅ Good | | HTMX | ✅ Improved | | Vanilla JS | ✅ No regressions | | Web Components (Shadow DOM) | ⚠️ Not yet supported |

    Files Changed

  • extension/manifest.json — version bump to 1.2.3
  • extension/content/content.js — SPA route detection + lazy element observer
  • extension/content/modules/badge-manager.js — MutationObserver re-matching
  • extension/content/modules/element-context.js — expanded stable attribute selectors with ancestor walking
    • Full Changelog: https://github.com/RaphaelRegnier/vibe-annotations/compare/v1.2.2...v1.2.3