web-remarq 0.1.9 → 0.1.10

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.
+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.
 
 ## Install
 
@@ -47,19 +47,23 @@ Remove all DOM nodes, event listeners, and observers. Full cleanup.
 
 Switch between `'light'` and `'dark'` themes.
 
+### `WebRemarq.copy()`
+
+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.
+
 ### `WebRemarq.export(format)`
 
-- `'md'` — copies markdown report to clipboard
+- `'md'` — downloads `.md` file with search hints (same content as `copy()`)
 - `'json'` — downloads `.json` file with full annotation data
 
 ### `WebRemarq.import(file)`
 
-Import annotations from a JSON file. Returns `Promise<{ total, matched, detached }>`.
+Import annotations from a JSON file. Returns `Promise<{ total, matched, otherBreakpoint, detached }>`.
 
 ```ts
 const input = document.querySelector('input[type="file"]')
 const result = await WebRemarq.import(input.files[0])
-// { total: 12, matched: 10, detached: 2 }
+// { total: 12, matched: 10, otherBreakpoint: 1, detached: 1 }
 ```
 
 ### `WebRemarq.getAnnotations(route?)`
@@ -91,8 +95,9 @@ 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, sibling index
+- **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)
 
 ### Matching
 
@@ -101,7 +106,34 @@ When loading annotations, 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 go to a "detached" panel
+4. Unmatched annotations sorted into "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
 
@@ -122,11 +154,12 @@ Works without any markup changes, but for guaranteed stable matching add `data-a
 
 ## UI Components
 
-- **Toolbar** — fixed bottom-right panel with inspect, export, import, clear, theme, minimize
+- **Toolbar** — fixed bottom-right panel with inspect, copy, export, import, clear, theme, minimize
 - **Inspect mode** — hover to highlight, click to annotate
 - **Markers** — numbered circles (orange = pending, green = resolved)
 - **Popup** — comment input for new annotations, detail view with Resolve/Delete for existing
-- **Detached panel** — shows annotations whose elements can't be found
+- **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-remarq",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Visual annotation tool for design review workflows",
   "type": "module",
   "main": "dist/index.cjs",
@@ -34,6 +34,18 @@
   "bugs": {
     "url": "https://github.com/DPostnik/web-remarq/issues"
   },
+  "keywords": [
+    "annotation",
+    "design-review",
+    "visual-feedback",
+    "ui-review",
+    "qa",
+    "element-inspector",
+    "ai-agent",
+    "design-handoff",
+    "web-annotation",
+    "dom-fingerprint"
+  ],
   "license": "MIT",
   "devDependencies": {
     "tsup": "^8.5.1",