web-remarq 0.3.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Visual annotation tool for design review workflows. Framework-agnostic, zero dependencies.
 
-Designer annotates UI elements on staging/dev, exports a report. Developer imports the report and sees markers on the exact elements. Copy annotations as agent-friendly markdown with search hints for AI coding agents.
+Designer annotates UI elements on staging/dev, exports a report. Developer imports the report and sees markers on the exact elements. Export as agent-friendly JSON with source locations and search hints for AI coding agents.
 
 ## Install
 
@@ -10,6 +10,18 @@ Designer annotates UI elements on staging/dev, exports a report. Developer impor
 npm install web-remarq
 ```
 
+### Build plugins (optional)
+
+For precise source location injection (`file:line:col` on every element):
+
+```bash
+# Babel (React, Preact, Solid)
+npm install -D @web-remarq/babel-plugin
+
+# Vite / webpack / Rollup / esbuild / Rspack
+npm install -D @web-remarq/unplugin
+```
+
 ## Quick Start
 
 ```ts
@@ -47,14 +59,18 @@ Remove all DOM nodes, event listeners, and observers. Full cleanup.
 
 Switch between `'light'` and `'dark'` themes.
 
-### `WebRemarq.copy()`
+### `WebRemarq.copy(format?)`
 
-Copy annotations as agent-friendly markdown to clipboard. Includes ranked search hints (CSS selectors, class names, text content, DOM path) so AI coding agents can grep and locate the source code.
+Copy annotations to clipboard.
+
+- `'md'` (default) — agent-friendly markdown with search hints
+- `'agent'` — structured JSON with source locations and grep queries
 
 ### `WebRemarq.export(format)`
 
-- `'md'` — downloads `.md` file with search hints (same content as `copy()`)
-- `'json'` — downloads `.json` file with full annotation data
+- `'md'` — downloads `.md` file with search hints
+- `'json'` — downloads `.json` file with full annotation data (for import)
+- `'agent'` — downloads `.json` with source locations, grep queries, and confidence levels
 
 ### `WebRemarq.import(file)`
 
@@ -70,15 +86,49 @@ const result = await WebRemarq.import(input.files[0])
 
 Get all annotations, or filter by route.
 
-```ts
-WebRemarq.getAnnotations()          // all
-WebRemarq.getAnnotations('/casino') // by route
-```
-
 ### `WebRemarq.clearAll()`
 
 Remove all annotations.
 
+## Agent Export Format
+
+The `export('agent')` format is optimized for AI coding agents:
+
+```jsonc
+{
+  "version": 1,
+  "format": "agent",
+  "viewportBucket": 1200,
+  "annotations": [{
+    "id": "a1b2c3d4",
+    "route": "/dashboard",
+    "comment": "Increase button padding",
+    "status": "pending",
+    "source": {
+      "file": "src/components/ActionBar.tsx",
+      "line": 24,
+      "column": 6,
+      "component": "ActionBar"
+    },
+    "searchHints": {
+      "grepQueries": [
+        { "query": "data-testid=\"save-btn\"", "glob": "*.{tsx,jsx,vue}", "confidence": "high" },
+        { "query": "\"Save changes\"", "glob": "*.{tsx,jsx,vue}", "confidence": "medium" }
+      ],
+      "domContext": "div.action-bar > button",
+      "tagName": "button",
+      "classes": ["action-button"]
+    }
+  }]
+}
+```
+
+Source detection uses a 3-level fallback:
+
+1. **Build plugin** — exact `file:line:col` from [`@web-remarq/babel-plugin`](https://www.npmjs.com/package/@web-remarq/babel-plugin) or [`@web-remarq/unplugin`](https://www.npmjs.com/package/@web-remarq/unplugin)
+2. **Runtime detection** — `data-source` attrs (locator.js), React fiber `_debugSource` (dev mode)
+3. **Heuristic** — grep queries ranked by confidence (`high` / `medium` / `low`)
+
 ## Core-only usage
 
 For programmatic access without UI:
@@ -95,57 +145,29 @@ When a user clicks an element, a multi-signal fingerprint is captured:
 
 - **Stable anchors** — `data-annotate`, `data-testid`, `id`
 - **Semantics** — tag name, text content, ARIA role/label
-- **Structure** — stable CSS classes (hashes stripped), DOM path with parent classes, sibling index
-- **Parent context** — nearest ancestor's `data-annotate` value
-- **Agent export** — raw classes, CSS Module decomposition (module hint + local class name)
+- **Structure** — stable CSS classes (hashes stripped), DOM path, sibling index
+- **Source location** — from build plugin or runtime detection
 
 ### Matching
 
-When loading annotations, elements are found via a fallback chain:
+Elements are found via a fallback chain:
 
 1. Exact match by `data-annotate` or `data-testid`
 2. Exact match by `id`
 3. Fuzzy match using weighted scoring (text similarity, ARIA, classes, DOM path)
-4. Unmatched annotations sorted into "other viewport" or "detached" panels
+4. Unmatched annotations go to "other viewport" or "detached" panels
 
 ### Viewport Breakpoints
 
-Annotations are tagged with a viewport bucket (width rounded to 100px). When resizing:
-
-- **Attached** — element found in current viewport
-- **Other viewport** — element not found, but annotation belongs to a different breakpoint (not an error)
-- **Detached** — element not found even in its native breakpoint (real problem)
-
-Automatic reconnection when returning to the annotation's native viewport.
-
-### Agent-Friendly Copy
-
-The Copy button produces markdown with ranked search hints:
-
-```markdown
-### 1. [pending] "Button too small on mobile"
-Element: <button> "Submit"
-Viewport: 300px
-
-Search hints:
-- `data-testid="submit-btn"` — in template files
-- `"Submit"` — text content in templates
-- `.submitButton` — in CSS Module file (likely `form.module.*`)
-- DOM: div.form-wrapper > form > button.submit
-- Classes: form__submitButton__cEqts flex items-center
-```
-
-### Hash Detection
-
-Automatically strips hashed classes from CSS Modules, styled-components, Emotion, and pure hash patterns.
+Annotations are tagged with a viewport bucket (width rounded to 100px). Automatic reconnection when returning to the annotation's native viewport.
 
 ### SPA Support
 
-Listens for `popstate`, `hashchange`, and intercepts `history.pushState`/`replaceState`. Annotations are scoped per route (`pathname + hash`).
+Intercepts `history.pushState`/`replaceState` and listens for `popstate`/`hashchange`. Annotations are scoped per route.
 
 ## Stable Selectors
 
-Works without any markup changes, but for guaranteed stable matching add `data-annotate` to key components:
+Works without any markup changes, but for guaranteed stable matching add `data-annotate`:
 
 ```html
 <CasinoTabs data-annotate="casino-tabs" />
@@ -154,21 +176,11 @@ Works without any markup changes, but for guaranteed stable matching add `data-a
 
 ## UI Components
 
-- **Toolbar** — fixed bottom-right panel with inspect, copy, export, import, clear, theme, minimize
+- **Toolbar** — fixed bottom-right panel with inspect, spacing, copy, export, import, clear, theme, minimize
 - **Inspect mode** — hover to highlight, click to annotate
+- **Spacing inspector** — visualizes margin, padding, content, flex gap on hover
 - **Markers** — numbered circles (orange = pending, green = resolved)
-- **Popup** — comment input for new annotations, detail view with Resolve/Delete for existing
-- **Other viewport panel** — annotations from different breakpoints, click to see required viewport
-- **Detached panel** — annotations whose elements can't be found in their native viewport
-
-## Build Outputs
-
-| Format | File | Use |
-|--------|------|-----|
-| ESM | `dist/index.js` | Bundlers |
-| CJS | `dist/index.cjs` | `require()` |
-| IIFE | `dist/web-remarq.global.global.js` | `<script>` tag |
-| Types | `dist/index.d.ts` | TypeScript |
+- **Popup** — comment input / detail view with Resolve/Delete
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-remarq",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Visual annotation tool for design review workflows",
   "type": "module",
   "main": "dist/index.cjs",