astro-annotate

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.

Features

• 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 (Claude Code, Cursor, etc.)
• Shadow DOM isolation — overlay UI is fully isolated from your site's styles
• Zero dependencies — vanilla TypeScript client, ~24KB bundle
• Device detection — automatically tags annotations as mobile/tablet/desktop

Installation

npx astro add astro-annotate

Or manually:

npm install astro-annotate

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

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

Usage

1. Start astro dev
2. Click the crosshair button (top of FAB stack, bottom-right) to enter annotation mode
3. Hover over elements to highlight them, click to annotate
4. Click the speech bubble button (bottom of FAB stack) to open the annotations panel
5. Drag the panel header to freely reposition — drag to viewport edges to snap/dock
6. Drag the bottom-right corner of a floating panel to resize
7. Annotations are saved to annotations.json in your project root

Reading annotations

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 }
    }
  ]
}

Configuration

annotate({
  enabled: true,              // default: true in dev
  storage: 'local',           // default: 'local' (JSON file)
  annotationsPath: './annotations.json',  // default
})

Roadmap

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

License

MIT