web-remarq 0.1.9 → 0.2.0

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/dist/index.cjs

@@ -735,6 +735,61 @@ var CSS = `
 .remarq-toast-fade {
   opacity: 0;
 }
+
+.remarq-spacing {
+  position: fixed;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+  z-index: 2147483646;
+}
+
+.remarq-spacing-margin {
+  position: fixed;
+  background: rgba(249, 115, 22, 0.2);
+  pointer-events: none;
+}
+
+.remarq-spacing-padding {
+  position: fixed;
+  background: rgba(34, 197, 94, 0.2);
+  pointer-events: none;
+}
+
+.remarq-spacing-content {
+  position: fixed;
+  background: rgba(59, 130, 246, 0.15);
+  border: 1px dashed rgba(59, 130, 246, 0.5);
+  pointer-events: none;
+}
+
+.remarq-spacing-gap {
+  position: fixed;
+  background: rgba(168, 85, 247, 0.25);
+  border: 1px dashed rgba(168, 85, 247, 0.5);
+  pointer-events: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.remarq-spacing-label {
+  position: fixed;
+  font-size: 11px;
+  font-weight: 700;
+  pointer-events: none;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  line-height: 1;
+  text-shadow: 0 0 3px var(--remarq-bg), 0 0 3px var(--remarq-bg);
+}
+
+.remarq-spacing-label-margin { color: #f97316; }
+.remarq-spacing-label-padding { color: #22c55e; }
+.remarq-spacing-label-content { color: #3b82f6; font-size: 10px; }
+.remarq-spacing-label-gap { color: #a855f7; font-size: 10px; }
+
+.remarq-toolbar-btn:disabled { opacity: 0.3; cursor: default; }
+.remarq-toolbar-btn:disabled:hover { background: transparent; }
 `;
 function injectStyles() {
   if (document.querySelector(`style[${STYLES_ID}]`)) return;
@@ -806,6 +861,7 @@ var ThemeManager = class {
 // src/ui/toolbar.ts
 var ICONS = {
   inspect: '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="7" cy="7" r="4"/><line x1="10" y1="10" x2="14" y2="14"/></svg>',
+  spacing: '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M2 2h12M2 14h12M2 2v12M14 2v12"/><path d="M5 5h6v6H5z" stroke-dasharray="2 1"/></svg>',
   copy: '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="5" y="5" width="8" height="9" rx="1"/><path d="M3 11V3a1 1 0 0 1 1-1h6"/></svg>',
   export: '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M8 2v8M4 6l4-4 4 4M2 12h12"/></svg>',
   import: '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M8 10V2M4 6l4 4 4-4M2 12h12"/></svg>',
@@ -827,6 +883,8 @@ var Toolbar = class {
     this.badgeEl.className = "remarq-badge";
     this.badgeEl.style.display = "none";
     this.inspectBtn.appendChild(this.badgeEl);
+    this.spacingBtn = this.createButton("spacing", ICONS.spacing, () => callbacks.onSpacingToggle());
+    this.spacingBtn.disabled = true;
     const copyBtn = this.createButton("copy", ICONS.copy, () => callbacks.onCopy());
     const exportBtn = this.createButton("export", ICONS.export, (e) => this.toggleExportMenu(e));
     this.fileInput = document.createElement("input");
@@ -841,8 +899,9 @@ var Toolbar = class {
     const clearBtn = this.createButton("clear", ICONS.clear, () => callbacks.onClear());
     const themeBtn = this.createButton("theme", ICONS.theme, () => callbacks.onThemeToggle());
     const minimizeBtn = this.createButton("minimize", ICONS.minimize, () => this.toggleMinimize());
-    this.buttons = [this.inspectBtn, copyBtn, exportBtn, importBtn, clearBtn, themeBtn];
+    this.buttons = [this.inspectBtn, this.spacingBtn, copyBtn, exportBtn, importBtn, clearBtn, themeBtn];
     this.toolbarEl.appendChild(this.inspectBtn);
+    this.toolbarEl.appendChild(this.spacingBtn);
     this.toolbarEl.appendChild(copyBtn);
     this.toolbarEl.appendChild(exportBtn);
     this.toolbarEl.appendChild(importBtn);
@@ -855,6 +914,15 @@ var Toolbar = class {
   setInspectActive(active) {
     this.inspectBtn.classList.toggle("remarq-active", active);
   }
+  setSpacingActive(active) {
+    this.spacingBtn.classList.toggle("remarq-active", active);
+  }
+  setSpacingEnabled(enabled) {
+    this.spacingBtn.disabled = !enabled;
+    if (!enabled) {
+      this.spacingBtn.classList.remove("remarq-active");
+    }
+  }
   setBadgeCount(count) {
     this.badgeEl.textContent = String(count);
     this.badgeEl.style.display = count > 0 ? "flex" : "none";
@@ -950,6 +1018,9 @@ var Overlay = class {
     this.tooltipEl.style.left = `${x + 12}px`;
     this.tooltipEl.style.top = `${y - 28}px`;
   }
+  hideHighlight() {
+    this.overlayEl.style.display = "none";
+  }
   hide() {
     this.overlayEl.style.display = "none";
     this.tooltipEl.style.display = "none";
@@ -997,6 +1068,229 @@ function getDirectText(el) {
   return text.slice(0, 30);
 }
 
+// src/ui/spacing-overlay.ts
+function parsePx(value) {
+  return parseFloat(value) || 0;
+}
+var SpacingOverlay = class {
+  constructor(parent) {
+    this.parent = parent;
+    this.labels = [];
+    this.gapEls = [];
+    this.lastTarget = null;
+    this.containerEl = document.createElement("div");
+    this.containerEl.className = "remarq-spacing";
+    this.containerEl.style.display = "none";
+    this.marginEl = document.createElement("div");
+    this.marginEl.className = "remarq-spacing-margin";
+    this.paddingEl = document.createElement("div");
+    this.paddingEl.className = "remarq-spacing-padding";
+    this.contentEl = document.createElement("div");
+    this.contentEl.className = "remarq-spacing-content";
+    this.containerEl.appendChild(this.marginEl);
+    this.containerEl.appendChild(this.paddingEl);
+    this.containerEl.appendChild(this.contentEl);
+    parent.appendChild(this.containerEl);
+  }
+  show(target) {
+    if (target === this.lastTarget) return;
+    this.lastTarget = target;
+    try {
+      const rect = target.getBoundingClientRect();
+      const cs = window.getComputedStyle(target);
+      const margin = this.readSides(cs, "margin");
+      const padding = this.readSides(cs, "padding");
+      const border = this.readBorderSides(cs);
+      const marginBox = {
+        top: rect.top - margin.top,
+        left: rect.left - margin.left,
+        width: rect.width + margin.left + margin.right,
+        height: rect.height + margin.top + margin.bottom
+      };
+      const paddingBox = {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height
+      };
+      const contentBox = {
+        top: rect.top + border.top + padding.top,
+        left: rect.left + border.left + padding.left,
+        width: rect.width - border.left - border.right - padding.left - padding.right,
+        height: rect.height - border.top - border.bottom - padding.top - padding.bottom
+      };
+      this.positionEl(this.marginEl, marginBox);
+      this.positionEl(this.paddingEl, paddingBox);
+      this.positionEl(this.contentEl, contentBox);
+      this.clearLabels();
+      this.clearGaps();
+      this.addSideLabels(margin, marginBox, paddingBox, "margin");
+      this.addSideLabels(padding, paddingBox, contentBox, "padding");
+      if (contentBox.width > 40 && contentBox.height > 14) {
+        this.addLabel(
+          `${Math.round(contentBox.width)} \xD7 ${Math.round(contentBox.height)}`,
+          contentBox.top + contentBox.height / 2 - 6,
+          contentBox.left + contentBox.width / 2,
+          "content"
+        );
+      }
+      this.showGaps(target);
+      this.containerEl.style.display = "block";
+    } catch (e) {
+      this.hide();
+    }
+  }
+  hide() {
+    this.containerEl.style.display = "none";
+    this.lastTarget = null;
+    this.clearLabels();
+    this.clearGaps();
+  }
+  destroy() {
+    this.clearLabels();
+    this.clearGaps();
+    this.containerEl.remove();
+  }
+  readSides(cs, prop) {
+    return {
+      top: parsePx(cs[`${prop}Top`]),
+      right: parsePx(cs[`${prop}Right`]),
+      bottom: parsePx(cs[`${prop}Bottom`]),
+      left: parsePx(cs[`${prop}Left`])
+    };
+  }
+  readBorderSides(cs) {
+    return {
+      top: parsePx(cs.borderTopWidth),
+      right: parsePx(cs.borderRightWidth),
+      bottom: parsePx(cs.borderBottomWidth),
+      left: parsePx(cs.borderLeftWidth)
+    };
+  }
+  positionEl(el, box) {
+    el.style.top = `${box.top}px`;
+    el.style.left = `${box.left}px`;
+    el.style.width = `${Math.max(0, box.width)}px`;
+    el.style.height = `${Math.max(0, box.height)}px`;
+  }
+  addSideLabels(sides, outerBox, innerBox, type) {
+    if (sides.top > 0) {
+      const y = outerBox.top + (innerBox.top - outerBox.top) / 2 - 6;
+      const x = outerBox.left + outerBox.width / 2;
+      this.addLabel(String(Math.round(sides.top)), y, x, type);
+    }
+    if (sides.bottom > 0) {
+      const innerBottom = innerBox.top + innerBox.height;
+      const outerBottom = outerBox.top + outerBox.height;
+      const y = innerBottom + (outerBottom - innerBottom) / 2 - 6;
+      const x = outerBox.left + outerBox.width / 2;
+      this.addLabel(String(Math.round(sides.bottom)), y, x, type);
+    }
+    if (sides.left > 0) {
+      const y = outerBox.top + outerBox.height / 2 - 6;
+      const x = outerBox.left + (innerBox.left - outerBox.left) / 2;
+      this.addLabel(String(Math.round(sides.left)), y, x, type);
+    }
+    if (sides.right > 0) {
+      const innerRight = innerBox.left + innerBox.width;
+      const outerRight = outerBox.left + outerBox.width;
+      const y = outerBox.top + outerBox.height / 2 - 6;
+      const x = innerRight + (outerRight - innerRight) / 2;
+      this.addLabel(String(Math.round(sides.right)), y, x, type);
+    }
+  }
+  addLabel(text, top, left, type) {
+    const label = document.createElement("div");
+    label.className = `remarq-spacing-label remarq-spacing-label-${type}`;
+    label.textContent = text;
+    label.style.top = `${top}px`;
+    label.style.left = `${left}px`;
+    label.style.transform = "translateX(-50%)";
+    this.containerEl.appendChild(label);
+    this.labels.push(label);
+  }
+  clearLabels() {
+    for (const label of this.labels) label.remove();
+    this.labels = [];
+  }
+  showGaps(target) {
+    const targetCs = window.getComputedStyle(target);
+    if (targetCs.display.includes("flex")) {
+      this.showContainerGaps(target, targetCs);
+      return;
+    }
+    const parent = target.parentElement;
+    if (!parent) return;
+    const parentCs = window.getComputedStyle(parent);
+    if (!parentCs.display.includes("flex")) return;
+    const rowGap = parsePx(parentCs.rowGap);
+    const columnGap = parsePx(parentCs.columnGap);
+    const direction = parentCs.flexDirection;
+    const isRow = direction === "row" || direction === "row-reverse";
+    const gap = isRow ? columnGap : rowGap;
+    if (gap <= 0) return;
+    const children = Array.from(parent.children);
+    const targetIndex = children.indexOf(target);
+    if (targetIndex === -1) return;
+    if (targetIndex > 0) {
+      this.renderGap(children[targetIndex - 1], target, gap, isRow);
+    }
+    if (targetIndex < children.length - 1) {
+      this.renderGap(target, children[targetIndex + 1], gap, isRow);
+    }
+  }
+  showContainerGaps(container, cs) {
+    const rowGap = parsePx(cs.rowGap);
+    const columnGap = parsePx(cs.columnGap);
+    const direction = cs.flexDirection;
+    const isRow = direction === "row" || direction === "row-reverse";
+    const gap = isRow ? columnGap : rowGap;
+    if (gap <= 0) return;
+    const children = Array.from(container.children);
+    for (let i = 0; i < children.length - 1; i++) {
+      this.renderGap(children[i], children[i + 1], gap, isRow);
+    }
+  }
+  renderGap(before, after, gap, isRow) {
+    const rectBefore = before.getBoundingClientRect();
+    const rectAfter = after.getBoundingClientRect();
+    const gapEl = document.createElement("div");
+    gapEl.className = "remarq-spacing-gap";
+    if (isRow) {
+      const left = Math.min(rectBefore.right, rectAfter.right);
+      const right = Math.max(rectBefore.left, rectAfter.left);
+      const top = Math.min(rectBefore.top, rectAfter.top);
+      const height = Math.max(rectBefore.height, rectAfter.height);
+      gapEl.style.top = `${top}px`;
+      gapEl.style.left = `${left}px`;
+      gapEl.style.width = `${Math.abs(right - left)}px`;
+      gapEl.style.height = `${height}px`;
+    } else {
+      const top = Math.min(rectBefore.bottom, rectAfter.bottom);
+      const bottom = Math.max(rectBefore.top, rectAfter.top);
+      const left = Math.min(rectBefore.left, rectAfter.left);
+      const width = Math.max(rectBefore.width, rectAfter.width);
+      gapEl.style.top = `${top}px`;
+      gapEl.style.left = `${left}px`;
+      gapEl.style.width = `${width}px`;
+      gapEl.style.height = `${Math.abs(bottom - top)}px`;
+    }
+    if (gap >= 10) {
+      const label = document.createElement("span");
+      label.className = "remarq-spacing-label-gap";
+      label.textContent = `gap: ${Math.round(gap)}`;
+      label.style.cssText = "font-size:10px;font-weight:700;pointer-events:none;";
+      gapEl.appendChild(label);
+    }
+    this.containerEl.appendChild(gapEl);
+    this.gapEls.push(gapEl);
+  }
+  clearGaps() {
+    for (const el of this.gapEls) el.remove();
+    this.gapEls = [];
+  }
+};
+
 // src/ui/popup.ts
 var POPUP_WIDTH = 300;
 var POPUP_MARGIN = 8;
@@ -1383,6 +1677,8 @@ var markers;
 var detachedPanel;
 var routeObserver;
 var inspecting = false;
+var spacingMode = false;
+var spacingOverlay;
 var mutationObserver = null;
 var unsubRoute = null;
 var refreshScheduled = false;
@@ -1476,7 +1772,6 @@ function handleInspectClick(e) {
   if (!target || target.closest("[data-remarq-theme]")) return;
   e.preventDefault();
   e.stopPropagation();
-  overlay.hide();
   setInspecting(false);
   const rect = target.getBoundingClientRect();
   popup.show(
@@ -1516,19 +1811,40 @@ function handleInspectHover(e) {
   if (!inspecting) return;
   const target = e.target;
   if (!target || target.closest("[data-remarq-theme]")) return;
-  overlay.show(target);
+  if (spacingMode) {
+    overlay.show(target);
+    overlay.hideHighlight();
+    spacingOverlay.show(target);
+  } else {
+    overlay.show(target);
+  }
   overlay.updateTooltipPosition(e.clientX, e.clientY);
 }
 function handleInspectKeydown(e) {
+  var _a, _b;
+  const tag = (_a = e.target) == null ? void 0 : _a.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || ((_b = e.target) == null ? void 0 : _b.isContentEditable)) return;
   if (e.key === "Escape" && inspecting) {
     setInspecting(false);
     overlay.hide();
+    spacingOverlay.hide();
+  }
+  if (e.key === "s" && inspecting) {
+    spacingMode = !spacingMode;
+    toolbar.setSpacingActive(spacingMode);
+    if (!spacingMode) spacingOverlay.hide();
   }
 }
 function setInspecting(value) {
   inspecting = value;
   toolbar.setInspectActive(value);
-  if (!value) overlay.hide();
+  toolbar.setSpacingEnabled(value);
+  if (!value) {
+    overlay.hide();
+    spacingOverlay == null ? void 0 : spacingOverlay.hide();
+    spacingMode = false;
+    toolbar.setSpacingActive(false);
+  }
 }
 function handleMarkerClick(annotationId) {
   var _a;
@@ -1660,6 +1976,7 @@ var WebRemarq = {
       storage = new AnnotationStorage();
       themeManager = new ThemeManager(document.body, options.theme);
       overlay = new Overlay(themeManager.container);
+      spacingOverlay = new SpacingOverlay(themeManager.container);
       popup = new Popup(themeManager.container);
       markers = new MarkerManager(themeManager.container, handleMarkerClick);
       detachedPanel = new DetachedPanel(themeManager.container, (id) => {
@@ -1669,6 +1986,12 @@ var WebRemarq = {
       });
       toolbar = new Toolbar(themeManager.container, {
         onInspect: () => setInspecting(!inspecting),
+        onSpacingToggle: () => {
+          if (!inspecting) return;
+          spacingMode = !spacingMode;
+          toolbar.setSpacingActive(spacingMode);
+          if (!spacingMode) spacingOverlay.hide();
+        },
         onCopy: copyToClipboard,
         onExportMd: exportMarkdown,
         onExportJson: exportJSON,
@@ -1718,11 +2041,13 @@ var WebRemarq = {
       detachedPanel == null ? void 0 : detachedPanel.destroy();
       popup == null ? void 0 : popup.destroy();
       overlay == null ? void 0 : overlay.destroy();
+      spacingOverlay == null ? void 0 : spacingOverlay.destroy();
       toolbar == null ? void 0 : toolbar.destroy();
       themeManager == null ? void 0 : themeManager.destroy();
       removeStyles();
       elementCache.clear();
       inspecting = false;
+      spacingMode = false;
       initialized = false;
     } catch (err) {
       console.error("[web-remarq] Destroy failed:", err);