astro-annotate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jnikolov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# 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
+- **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
+
+```bash
+npx astro add astro-annotate
+```
+
+Or manually:
+
+```bash
+npm install astro-annotate
+```
+
+```js
+// 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 annotation button (bottom-right corner)
+3. Hover over elements to highlight them, click to annotate
+4. Annotations are saved to `annotations.json` in your project root
+
+### Reading annotations
+
+The `annotations.json` file is structured for both humans and machines:
+
+```json
+{
+  "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
+
+```js
+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

package/dist/chunk-QG2SIJB2.js

@@ -0,0 +1,18 @@
+// src/constants.ts
+var API_BASE = "/api/astro-annotate";
+var API_ANNOTATIONS = `${API_BASE}/annotations`;
+var SHADOW_ROOT_ID = "astro-annotate-root";
+var DEFAULT_ANNOTATIONS_PATH = "./annotations.json";
+var ANNOTATIONS_VERSION = "0.1";
+var VIRTUAL_MODULE_ID = "virtual:astro-annotate/config";
+var RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+
+export {
+  API_ANNOTATIONS,
+  SHADOW_ROOT_ID,
+  DEFAULT_ANNOTATIONS_PATH,
+  ANNOTATIONS_VERSION,
+  VIRTUAL_MODULE_ID,
+  RESOLVED_VIRTUAL_MODULE_ID
+};
+//# sourceMappingURL=chunk-QG2SIJB2.js.map

package/dist/chunk-QG2SIJB2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["export const API_BASE = '/api/astro-annotate';\nexport const API_ANNOTATIONS = `${API_BASE}/annotations`;\n\nexport const SHADOW_ROOT_ID = 'astro-annotate-root';\nexport const CSS_PREFIX = 'aa-';\n\nexport const DEFAULT_ANNOTATIONS_PATH = './annotations.json';\nexport const ANNOTATIONS_VERSION = '0.1';\n\nexport const VIRTUAL_MODULE_ID = 'virtual:astro-annotate/config';\nexport const RESOLVED_VIRTUAL_MODULE_ID = '\\0' + VIRTUAL_MODULE_ID;\n"],"mappings":";AAAO,IAAM,WAAW;AACjB,IAAM,kBAAkB,GAAG,QAAQ;AAEnC,IAAM,iBAAiB;AAGvB,IAAM,2BAA2B;AACjC,IAAM,sBAAsB;AAE5B,IAAM,oBAAoB;AAC1B,IAAM,6BAA6B,OAAO;","names":[]}