vite-plugin-specter 0.3.4 → 0.4.1

package/README.md

@@ -60,6 +60,23 @@ In Measure mode, press **M** while hovering to pin that element. Then hover any
 
 Press **P** while hovering an element to pick it. Numbered badges appear on each picked element. Press **Cmd+C** to copy all selected elements at once. Press **Esc** to clear the selection.
 
+### Annotate a change (skip the re-explaining)
+
+Press **N** while hovering an element to attach a change note to it. A small field opens on the element — type what you want ("reduce width to 320", "tighten padding to 8px"), press **Enter** to save. The element is added to the selection and its badge shows a chip with your note. Annotate as many issues across the page as you like, then press **Cmd+C** once.
+
+Each element's copied block now leads with your instruction:
+
+```
+[Specter 1/3]
+✏️ CHANGE: reduce width to 320, tighten vertical padding
+<button>.btn-primary Button 200×48
+font: Inter 600 14/20
+padding: 12px 20px
+...
+```
+
+So when you paste into your AI assistant, it already knows both *what* to change and *which element* — no follow-up typing. Notes are ephemeral (cleared on **Esc** or when you toggle Specter off).
+
 ## Shortcut reference
 
 | Action | Shortcut |
@@ -70,6 +87,7 @@ Press **P** while hovering an element to pick it. Numbered badges appear on each
 | Switch to Measure mode | **Option** (tap) |
 | Pin element for measuring | **M** (in Measure mode) |
 | Pick element (multi-select) | **P** (in Properties mode) |
+| Annotate a change | **N** (in Properties mode) |
 | Clear pin / clear selection | **Esc** |
 | Exit Specter | **Esc** (when nothing selected/pinned) |
 
@@ -77,11 +95,11 @@ Press **P** while hovering an element to pick it. Numbered badges appear on each
 
 1. Toggle Specter (Ctrl+Option+Z)
 2. Hover the element you want to change
-3. Press **Cmd+C** to copy
-4. Paste into your AI assistant's chat
-5. Say what you want: "make this blue", "increase spacing", "fix the font weight"
+3. Either press **Cmd+C** to copy its properties, or press **N** to annotate the exact change you want first
+4. Repeat **N** on every element you want to change, then **Cmd+C** once to copy them all
+5. Paste into your AI assistant's chat — the instructions travel with the elements, so there's nothing left to explain
 
-No more "which element?", no more "what's the current value?". One paste gives your assistant everything it needs.
+No more "which element?", no more "what's the current value?", and now no more re-typing the change. One paste gives your assistant everything it needs.
 
 ## Configuration
 

package/dist/client.js

@@ -1,6 +1,12 @@
 (function() {
   'use strict';
-  if (window.__specter) return; window.__specter = true;
+  // Guard against running twice on one page. Use a DOM marker (not just a
+  // window global) so the browser-extension build (isolated world) and the
+  // Vite-plugin build (page main world) can see each other and only one runs —
+  // they share the DOM but not window globals, so a per-world flag misses.
+  if (window.__specter || document.documentElement.hasAttribute('data-specter')) return;
+  window.__specter = true;
+  document.documentElement.setAttribute('data-specter', '');
 
   // ─── Constants ──────────────────────────────────────────────────────────────
   var PURPLE = '#AD24D3';
@@ -10,6 +16,7 @@
   var LABEL = '#8B8D94';
   var MONO = "'JetBrains Mono', 'SF Mono', 'Fira Code', monospace";
   var ZAP = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"></polygon></svg>';
+  var PENCIL = '<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"></path><path d="m15 5 4 4"></path></svg>';
   var ACTIVATE = "ctrl+alt+z";
 
   // ─── State ────────────────────────────────────────────────────────────────
@@ -29,6 +36,9 @@
   var lastMouse = { x: 0, y: 0 };
   var selectedEls = [];
   var selectedBadges = [];
+  var noteMap = new Map();
+  var noteInputEl = null;
+  var noteTargetEl = null;
 
   // ─── Tooltip ──────────────────────────────────────────────────────────────
   var tooltip = document.createElement('div');
@@ -188,11 +198,11 @@
     pillExpanded = true;
     if (text) { pillText.textContent = text; return; }
     if (selectedEls.length > 0) {
-      pillText.textContent = selectedEls.length + ' selected · Cmd+C copy all · Esc clear';
+      pillText.textContent = selectedEls.length + ' selected · N annotate · Cmd+C copy all · Esc clear';
     } else if (measureMode) {
       pillText.textContent = 'Measure · hover distances · M pin · Cmd+C copy · Option toggle';
     } else {
-      pillText.textContent = 'Properties · hover inspect · P pick · Cmd+C copy · Option measure';
+      pillText.textContent = 'Properties · hover · P pick · N annotate · Cmd+C copy · Option measure';
     }
   }
 
@@ -312,6 +322,55 @@
     return null;
   }
 
+  // Collapse a rule's declarations to their shortest lossless form: drop
+  // 'initial' (= default, no signal) and always-'normal' noise, and fold
+  // side/corner longhands back into shorthands (margin/padding/radius/gap/transition).
+  function cleanDecls(style) {
+    var m = {}, order = [];
+    for (var i = 0; i < style.length; i++) {
+      var p = style[i];
+      var v = style.getPropertyValue(p);
+      if (!v) continue;
+      if (v === 'initial') continue;
+      if (p === 'transition-behavior') continue;
+      if (!(p in m)) order.push(p);
+      m[p] = v;
+    }
+    var used = {}, collapses = {};
+    function four(name, t, r, b, l) {
+      if (m[t] === undefined || m[r] === undefined || m[b] === undefined || m[l] === undefined) return;
+      used[t] = used[r] = used[b] = used[l] = 1;
+      var a = m[t], c = m[r], d = m[b], e = m[l], sh;
+      if (a === c && c === d && d === e) sh = a;
+      else if (a === d && c === e) sh = a + ' ' + c;
+      else if (c === e) sh = a + ' ' + c + ' ' + d;
+      else sh = a + ' ' + c + ' ' + d + ' ' + e;
+      collapses[t] = name + ': ' + sh;
+    }
+    four('margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left');
+    four('padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left');
+    four('border-radius', 'border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius');
+    if (m['row-gap'] !== undefined && m['column-gap'] !== undefined) {
+      var g = m['row-gap'] === m['column-gap'] ? m['row-gap'] : m['row-gap'] + ' ' + m['column-gap'];
+      collapses['row-gap'] = 'gap: ' + g; used['row-gap'] = used['column-gap'] = 1;
+    }
+    if (m['transition-property'] !== undefined) {
+      var tr = 'transition: ' + m['transition-property'];
+      if (m['transition-duration'] !== undefined) tr += ' ' + m['transition-duration'];
+      if (m['transition-timing-function'] !== undefined) tr += ' ' + m['transition-timing-function'];
+      if (m['transition-delay'] !== undefined && m['transition-delay'] !== '0s') tr += ' ' + m['transition-delay'];
+      collapses['transition-property'] = tr;
+      used['transition-property'] = used['transition-duration'] = used['transition-timing-function'] = used['transition-delay'] = 1;
+    }
+    var out = [];
+    order.forEach(function (p) {
+      if (collapses[p]) { out.push('  ' + collapses[p] + ';'); return; }
+      if (used[p]) return;
+      out.push('  ' + p + ': ' + m[p] + ';');
+    });
+    return out;
+  }
+
   function getMatchingRules(el) {
     var results = [];
     try {
@@ -328,12 +387,7 @@
           if (/^[*,]|^:root|^html|^body$|^::before|^::after/.test(sel.trim())) continue;
           try {
             if (el.matches(sel)) {
-              var props = [];
-              for (var i = 0; i < rule.style.length; i++) {
-                var prop = rule.style[i];
-                var val = rule.style.getPropertyValue(prop);
-                if (val) props.push('  ' + prop + ': ' + val + ';');
-              }
+              var props = cleanDecls(rule.style);
               if (props.length) results.push(sel + ' {\n' + props.join('\n') + '\n}');
             }
           } catch (e) {}
@@ -453,9 +507,13 @@
   }
 
   function buildMultiSelectCopyText() {
+    var n = selectedEls.length;
     return selectedEls.map(function (el, i) {
       var body = buildLLMClipboard(buildInfo(el));
-      return body.replace('[Specter]', '[Specter ' + (i + 1) + '/' + selectedEls.length + ']');
+      var note = noteMap.get(el);
+      var header = n > 1 ? '[Specter ' + (i + 1) + '/' + n + ']' : '[Specter]';
+      if (note) header += '\n✏️ CHANGE: ' + note;
+      return body.replace('[Specter]', header);
     }).join('\n\n' + Array(41).join('─') + '\n\n');
   }
 
@@ -506,16 +564,25 @@
   }
 
   // ─── Multi-select ─────────────────────────────────────────────────────────
-  function makeBadge(el, index) {
+  function makeBadge(el, index, note) {
     var rect = el.getBoundingClientRect();
-    var badge = document.createElement('div');
-    badge.textContent = String(index + 1);
-    Object.assign(badge.style, {
+    var wrap = document.createElement('div');
+    Object.assign(wrap.style, {
       position: 'fixed',
       left: (rect.left - 4) + 'px',
       top: (rect.top - 4) + 'px',
+      zIndex: '2147483644',
+      pointerEvents: 'none',
+      display: 'flex',
+      alignItems: 'flex-start',
+      gap: '4px',
+    });
+    var badge = document.createElement('div');
+    badge.textContent = String(index + 1);
+    Object.assign(badge.style, {
       width: '20px',
       height: '20px',
+      flexShrink: '0',
       background: PURPLE,
       color: '#fff',
       fontSize: '11px',
@@ -525,19 +592,38 @@
       display: 'flex',
       alignItems: 'center',
       justifyContent: 'center',
-      zIndex: '2147483644',
-      pointerEvents: 'none',
       boxShadow: '0 2px 6px rgba(0,0,0,0.3)',
     });
-    document.body.appendChild(badge);
-    return badge;
+    wrap.appendChild(badge);
+    if (note) {
+      var chip = document.createElement('div');
+      chip.textContent = '✏️ ' + (note.length > 32 ? note.slice(0, 32) + '…' : note);
+      Object.assign(chip.style, {
+        maxWidth: '240px',
+        background: TIP_BG,
+        color: '#fff',
+        fontSize: '10px',
+        lineHeight: '16px',
+        fontFamily: MONO,
+        padding: '2px 6px',
+        borderRadius: '4px',
+        whiteSpace: 'nowrap',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+        border: '1px solid ' + PURPLE,
+        boxShadow: '0 2px 6px rgba(0,0,0,0.3)',
+      });
+      wrap.appendChild(chip);
+    }
+    document.body.appendChild(wrap);
+    return wrap;
   }
 
   function rebuildBadges() {
     selectedBadges.forEach(function (b) { b.remove(); });
     selectedBadges.length = 0;
     selectedEls.forEach(function (el, i) {
-      selectedBadges.push(makeBadge(el, i));
+      selectedBadges.push(makeBadge(el, i, noteMap.get(el)));
     });
   }
 
@@ -546,6 +632,7 @@
     if (idx >= 0) {
       selectedEls.splice(idx, 1);
       el.style.outline = '';
+      noteMap.delete(el);
     } else {
       selectedEls.push(el);
       el.style.outline = '2px solid ' + PURPLE;
@@ -556,10 +643,12 @@
   }
 
   function clearSelection() {
+    closeNoteInput();
     selectedEls.forEach(function (el) { el.style.outline = ''; el.style.outlineOffset = ''; });
     selectedEls.length = 0;
     selectedBadges.forEach(function (b) { b.remove(); });
     selectedBadges.length = 0;
+    noteMap.clear();
   }
 
   function updatePillForSelection() {
@@ -567,6 +656,142 @@
     else if (!pillWrap.matches(':hover')) collapsePill();
   }
 
+  // ─── Annotations (inline change notes) ──────────────────────────────────────
+  function openNoteInput(el) {
+    closeNoteInput();
+    if (selectedEls.indexOf(el) < 0) {
+      clearHoverOutline();
+      hideTooltip();
+      selectedEls.push(el);
+      el.style.outline = '2px solid ' + PURPLE;
+      el.style.outlineOffset = '-1px';
+    }
+    noteTargetEl = el;
+    var rect = el.getBoundingClientRect();
+
+    var box = document.createElement('div');
+    Object.assign(box.style, {
+      position: 'fixed',
+      zIndex: '2147483647',
+      display: 'inline-flex',
+      alignItems: 'flex-start',
+      gap: '8px',
+      boxSizing: 'border-box',
+      background: TIP_BG,
+      border: '1px solid ' + PURPLE,
+      borderRadius: '8px',
+      padding: '11px 12px',
+      boxShadow: '0 4px 16px rgba(0,0,0,0.35)',
+      fontFamily: MONO,
+    });
+    var pen = document.createElement('span');
+    pen.innerHTML = PENCIL;
+    Object.assign(pen.style, {
+      display: 'flex',
+      alignItems: 'center',
+      flexShrink: '0',
+      marginTop: '2px',
+      color: '#E0A3F5',
+    });
+    var input = document.createElement('textarea');
+    input.rows = 1;
+    input.placeholder = 'Describe the change… (Enter to save)';
+    input.value = noteMap.get(el) || '';
+    Object.assign(input.style, {
+      flexShrink: '0',
+      background: 'transparent',
+      border: 'none',
+      outline: 'none',
+      resize: 'none',
+      overflow: 'hidden',
+      color: '#fff',
+      fontFamily: MONO,
+      fontSize: '12px',
+      lineHeight: '18px',
+      padding: '0',
+      margin: '0',
+      whiteSpace: 'pre-wrap',
+      overflowWrap: 'anywhere',
+    });
+    // Hidden mirror to measure single-line text width so the field grows as you type.
+    var meas = document.createElement('span');
+    Object.assign(meas.style, {
+      position: 'absolute',
+      visibility: 'hidden',
+      whiteSpace: 'pre',
+      pointerEvents: 'none',
+      fontFamily: MONO,
+      fontSize: '12px',
+      left: '-9999px',
+      top: '0',
+    });
+    box.appendChild(pen);
+    box.appendChild(input);
+    box.appendChild(meas);
+    document.body.appendChild(box);
+    noteInputEl = box;
+
+    var margin = 8;
+    function textW(t) { meas.textContent = t; return meas.offsetWidth; }
+
+    // Anchor to the element; the box is repositioned around this as it grows.
+    var anchorL = rect.left, anchorT = rect.top, anchorB = rect.bottom;
+
+    function sizeAndPosition() {
+      var vw = window.innerWidth, vh = window.innerHeight;
+      var maxBoxW = Math.min(560, vw - margin * 2);
+      var maxTextW = Math.max(120, maxBoxW - 55);        // room for icon + gaps + padding
+      var placeholderW = textW(input.placeholder);
+      var minTextW = Math.min(placeholderW, maxTextW);
+      var maxTaH = Math.min(14 * 18, Math.max(18, (vh - margin * 2) - 24)); // cap ~14 lines, never past viewport
+
+      // Width: grow with content up to the max, then wrapping takes over.
+      var single = textW(input.value || input.placeholder) + 3;
+      input.style.width = Math.min(Math.max(single, minTextW), maxTextW) + 'px';
+      // Height: fit wrapped content, scroll only in the extreme case.
+      input.style.height = 'auto';
+      var h = input.scrollHeight;
+      if (h > maxTaH) { input.style.height = maxTaH + 'px'; input.style.overflowY = 'auto'; }
+      else { input.style.height = h + 'px'; input.style.overflowY = 'hidden'; }
+
+      // Keep the whole box on screen.
+      var bw = box.offsetWidth, bh = box.offsetHeight;
+      var left = Math.min(Math.max(anchorL, margin), Math.max(margin, vw - bw - margin));
+      var top = anchorT - bh - 8;                        // prefer sitting above the element
+      if (top < margin) top = anchorB + 8;               // otherwise below it
+      if (top + bh > vh - margin) top = Math.max(margin, vh - bh - margin);
+      box.style.left = left + 'px';
+      box.style.top = top + 'px';
+    }
+    sizeAndPosition();
+
+    input.addEventListener('input', sizeAndPosition);
+    input.addEventListener('keydown', function (ev) {
+      ev.stopPropagation();
+      if (ev.key === 'Enter' && !ev.shiftKey) { ev.preventDefault(); commitNote(input.value); }
+      else if (ev.key === 'Escape') { ev.preventDefault(); closeNoteInput(); }
+    });
+
+    rebuildBadges();
+    updatePillForSelection();
+    setTimeout(function () { input.focus(); }, 0);
+  }
+
+  function commitNote(val) {
+    val = (val || '').trim();
+    if (noteTargetEl) {
+      if (val) noteMap.set(noteTargetEl, val);
+      else noteMap.delete(noteTargetEl);
+    }
+    closeNoteInput();
+    rebuildBadges();
+  }
+
+  function closeNoteInput() {
+    if (noteInputEl) { noteInputEl.remove(); noteInputEl = null; }
+    noteTargetEl = null;
+  }
+
   // ─── Pin (measure) ──────────────────────────────────────────────────────────
   function setPin(el) {
     pinEl = el;
@@ -863,6 +1088,7 @@
     var target = e.target;
     if (!target || target === pillWrap || pillWrap.contains(target)) return;
     if (target === tooltip || tooltip.contains(target)) return;
+    if (noteInputEl && (target === noteInputEl || noteInputEl.contains(target))) return;
 
     lastHovered = target;
 
@@ -897,6 +1123,9 @@
 
     if (!fiActive) return;
 
+    // Note editor open: let the field handle its own keys (Enter/Esc) and native copy/paste.
+    if (noteInputEl) return;
+
     if (e.key === 'Alt' && !e.ctrlKey && !e.metaKey && !e.shiftKey) {
       optionHeld = true;
       return;
@@ -927,6 +1156,12 @@
       return;
     }
 
+    if (e.key === 'n' || e.key === 'N') {
+      if (!lastHovered) return;
+      openNoteInput(lastHovered);
+      return;
+    }
+
     if (e.key === 'm' || e.key === 'M') {
       if (!measureMode || !lastHovered) return;
       if (pinEl) {