Visual annotation overlay for Astro staging sites. Clients and stakeholders annotate HTML elements directly in the browser. Annotations are stored as structured JSON, readable by developers and LLMs.

Status: Phase 1 (MVP) — local dev mode. Works with astro dev.

• Built for Astro — npx astro add, Dev Toolbar icon, View Transitions support
• Zero dependencies — vanilla TypeScript client, ~15KB gzipped
• LLM-native — annotations saved as annotations.json with CSS selectors, feed directly to Claude Code or Cursor
• No SaaS, no account — everything stays in your repo, no third-party service
• Shadow DOM isolated — overlay UI never touches your site's styles

npx astro add astro-annotate

npm install astro-annotate

// astro.config.mjs
import { defineConfig } from 'astro/config';
import annotate from 'astro-annotate';

export default defineConfig({
  integrations: [annotate()],
});

• Element-based annotations — hover to highlight, click to annotate any HTML element
• Figma-style pins — small teardrops that point toward annotated elements with directional tilt
• Draggable panel — freely movable annotations panel with resize handle and snap-to-side docking
• CSS selector tracking — annotations reference elements by robust CSS selectors (IDs, data-testid, tag+class)
• JSON storage — annotations saved as annotations.json, directly readable by developers and LLMs
• Astro Dev Toolbar — native toolbar icon with notification badge for open annotations
• Device detection — automatically tags annotations as mobile/tablet/desktop

The annotations.json file is structured for both humans and machines:

{
  "version": "1.0",
  "annotations": [
    {
      "id": "abc123",
      "page": "/",
      "selector": "h1.hero-title",
      "text": "Make this headline shorter",
      "author": "Client Name",
      "status": "open",
      "device": "desktop",
      "viewport": { "width": 1440, "height": 900 }
    }
  ]
}

annotate({
  enabled: true,
  storage: 'local',
  annotationsPath: './annotations.json',
})

• Phase 2: Deployed mode on Cloudflare Pages with password auth
• Phase 3: Screenshots, CLI export, mobile UX, docs

Contributions welcome! See CONTRIBUTING.md for setup instructions.

MIT