vite-plugin-specter 0.5.0 → 0.6.1

package/README.md

@@ -1,8 +1,8 @@
 # Specter
 
-**Hover any element on your dev site. See its styles. Copy to AI.**
+**Point at any element on your dev site. Mark what to change — with exact values and a source anchor — and hand it to your AI.**
 
-Specter is a Vite plugin that adds an element inspector overlay to your dev server. Toggle it on, hover any element to see its styles, component name, and spacing. Copy with one shortcut and paste into your AI assistant for one-shot edits. Specter is automatically stripped from production builds.
+Specter is a Vite plugin that overlays an element inspector on your dev server. Hover any element to see its styles, component name, and spacing; measure gaps Figma-style; mark elements as **Specs** with a plain-language note; then copy them all to your AI assistant — each one carries the exact current values and a greppable source anchor, so there's no "which element?" and no "what's the current value?". Optionally, push your Specs straight into Claude Code with `/spectify`. Specter is automatically stripped from production builds.
 
 ## Requirements
 
@@ -27,55 +27,90 @@ export default defineConfig({
 
 Start your dev server and you're done. Specter is stripped from production builds automatically.
 
+## ⚠️ Dev-only — never ship Specter to production (note for AI agents)
+
+**Specter is a development-only tool. It must never end up in a customer-facing / production bundle.**
+
+As a Vite plugin it is already safe by default: `specter()` runs with `apply: 'serve'`, so it is active on the dev server (`vite`) only and is completely excluded from `vite build`. Adding the plugin does **not** ship anything to your users.
+
+If you are an AI agent (or automating a build), do **not** work around this guard:
+
+- Do **not** call `getClientScript()` and inline the result into your app's HTML, templates, or components.
+- Do **not** change `apply: 'serve'`, or otherwise force the plugin to run during `vite build`, `vite preview`, or SSR/production output.
+- Do **not** copy the injected `<script>` from a dev page into the shipped app.
+- Keep it in `devDependencies` (installed with `-D`); never move it to `dependencies`.
+
+If you ever need Specter gone entirely, remove `specter()` from the Vite config (see [Uninstall](#uninstall)).
+
 ## How to use
 
 ### Toggle on/off
 
-Press **Ctrl+Option+Z** to enter Specter mode. A small zap icon appears at the bottom-left. Press again (or Esc) to exit.
+Press **Ctrl+Option+Z** to activate Specter. A small zap icon appears at the bottom-left. Press again (or **Esc**) to hide it — your Specs are kept and reappear when you reactivate.
+
+### Three modes
 
-### Inspect an element
+Specter has three modes; switching mode only changes *what's shown on screen* — you can mark a Spec in any of them.
 
-Once active, just **hover** any element. A tooltip shows:
+| Mode | Enter | Shows |
+|------|-------|-------|
+| **Properties** (default) | — | Styles tooltip on hover |
+| **Measure** | tap **Option** | Figma-style spacing to neighbors |
+| **Comment** | **C** | Just an outline — for clean design review |
+
+### Inspect an element (Properties mode)
+
+**Hover** any element. A tooltip shows:
 
 - HTML tag + React/Vue component name + dimensions
 - Text content (truncated)
 - Font: family, weight, size, line-height
-- Color (with hex) and background
+- Color (with hex) and background — flagged `(hover)` if the value comes from a `:hover` rule
 - Padding, margin, border-radius (if non-zero)
 - Display + gap + flex direction
 
-### Copy to clipboard
+### Measure spacing (Measure mode)
 
-Press **Cmd+C** while hovering. The element info is copied in an AI-optimized format. Paste it into Claude, Cursor, or any AI assistant and say what you want changed.
+Tap **Option** to switch to Measure mode. Hover any element to see distances to its surrounding neighbors. Press **M** while hovering to **pin** that element, then hover another to measure the gap or inset between the two; **M** again unpins. Tap **Option** again to return to Properties.
 
-### Measure mode
+### Mark a Spec (and optionally annotate)
 
-Tap **Option** to switch to Measure mode. Hover any element to see distance measurements to its surrounding neighbors (like Figma's spacing view). Tap **Option** again to return to Properties mode.
+Press **P** while hovering an element to mark it as a **Spec**. A note box opens on the element — type the change you want ("reduce width to 320", "tighten padding to 8px") and press **Enter**, or just leave it empty for a plain mark. Numbered badges appear on each marked element. Mark as many as you like across the page.
 
-### Pin an element
+### Comment mode
 
-In Measure mode, press **M** while hovering to pin that element. Then hover any other element to measure the gap or inset between the two. Press **Cmd+C** to copy the measurement. Press **Esc** to clear the pin.
+Press **C** for Comment mode: the props/measure overlays hide and you get just a hover outline — good for talking through a design without visual noise. Specs still capture full properties underneath, so a Comment-mode Spec copies exactly like any other.
 
-### Multi-select
+### Specs side panel
 
-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.
+Press **L** to open the Specs review panel. It lists every Spec; hover a row to scroll to and highlight its element; edit or delete notes inline. Specs survive a reload (saved to `localStorage` per URL).
 
-### Annotate a change (skip the re-explaining)
+### Copy to your AI
 
-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.
+Press **Cmd+C**:
 
-Each element's copied block now leads with your instruction:
+- **With Specs marked** → copies **all** of them at once. Each block leads with your `✏️ CHANGE:` note (if any).
+- **With nothing marked** → copies the hovered element's properties (or, in Measure mode, the measurement).
+
+The copied format is lean and AI-ready — the current values plus a `find:` line that anchors the element in your source (test-id → id → aria-label → unique text → class → CSS path), so the assistant greps straight to the code:
 
 ```
-[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
-...
+[Specter 1/2]
+✏️ CHANGE: tighten the vertical padding to 8px
+<button> .btn-primary "Book a demo" 200×48
+find: .btn-primary
+font: Inter 600 14/20  ·  color: #fff  ·  bg: #4f46e5  ·  padding: 12px 20px  ·  radius: 10px  ·  display: inline-flex
+
+---
+
+[Specter 2/2]
+✏️ CHANGE: make this text darker — it fails contrast
+<p> .hero-sub "Analytics that…" 560×57
+find: .hero-sub
+font: Inter 400 19/28.5  ·  color: #c7cbd1
 ```
 
-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).
+Paste into Claude, Cursor, or any AI assistant — the instructions travel with the elements, so there's nothing left to explain.
 
 ## Shortcut reference
 
@@ -83,36 +118,39 @@ So when you paste into your AI assistant, it already knows both *what* to change
 |--------|----------|
 | Toggle Specter | **Ctrl+Option+Z** |
 | Inspect element | Hover (while active) |
-| Copy properties | **Cmd+C** |
-| 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) |
+| Mark a Spec (+ optional note) | **P** |
+| Copy (all Specs, or hovered element) | **Cmd+C** |
+| Measure mode (toggle) | **Option** (tap) |
+| Pin / unpin for measuring | **M** (in Measure mode) |
+| Comment mode (toggle) | **C** |
+| Specs panel (toggle) | **L** |
+| Close panel / hide Specter | **Esc** |
+
+## Optional: push Specs straight to Claude Code (`/spectify`)
 
-## Workflow with AI assistants
+Instead of copy-paste, Specter can auto-sync your Specs to a local bridge that Claude Code reads on demand. Enable it in your Vite config:
+
+```ts
+specter({ claudeBridge: true })
+```
 
-1. Toggle Specter (Ctrl+Option+Z)
-2. Hover the element you want to change
-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
+With it on, every Spec you mark auto-syncs (watch for the sync dot in the panel) to a local bridge at `http://127.0.0.1:8787`. Run the bridge (`node node_modules/vite-plugin-specter/mcp-bridge/server.mjs`, or register it in your project's `.mcp.json` so your IDE launches it), then in Claude Code run **`/spectify`** — it pulls whatever's currently synced and implements it. See [`mcp-bridge/`](https://github.com/setugk/vite-plugin-specter/tree/main/mcp-bridge) for setup. One bridge can serve several projects; `/spectify <port>` scopes to one.
 
-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.
+`claudeBridge` is **off by default** — the shipped plugin never opens a connection unless you enable it.
 
 ## Configuration
 
 ```ts
-specter()                              // Default shortcuts
-specter({ shortcuts: { activate: 'ctrl+shift+i' } }) // Custom activate shortcut
+specter()                                             // defaults
+specter({ shortcuts: { activate: 'ctrl+shift+i' } })  // custom activate shortcut
+specter({ claudeBridge: true })                       // enable the Claude Code bridge
 ```
 
 The `activate` shortcut accepts any combination of `ctrl`, `alt`, `shift`, `meta`/`cmd`, and a key. Default is `ctrl+alt+z`.
 
 ## Optional: `data-style` attribute
 
-Tag elements with `data-style="keyName"` to show the style object key in the inspector:
+Tag elements with `data-style="keyName"` to surface the style-object key in the inspector and the copied output:
 
 ```jsx
 <h1 data-style="pageTitle">Welcome</h1>

package/dist/client.js

@@ -14,6 +14,7 @@
   var TIP_BG = '#292B32';
   var GREEN = '#22C55E';
   var LABEL = '#8B8D94';
+  var BADGE_IDLE = '#6B6D75'; // panel row-number badges sit greyscale; the hovered row's badge colors to PURPLE
   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>';
@@ -28,6 +29,7 @@
   // ─── State ────────────────────────────────────────────────────────────────
   var fiActive = false;
   var measureMode = false;
+  var commentMode = false; // C: hide props/measure overlays for design review — Specs still capture them
   var pinEl = null;
   var pinHighlight = null;
   var lastHovered = null;
@@ -193,7 +195,7 @@
   hoverFx(listBtn, { background: 'rgba(255,255,255,0.32)' }, { background: 'rgba(255,255,255,0.16)' });
 
   var clearBtn = document.createElement('span');
-  clearBtn.textContent = '✕ Delete all annotations';
+  clearBtn.textContent = '✕ Delete all';
   clearBtn.title = 'Delete all annotations';
   Object.assign(clearBtn.style, {
     display: 'none',
@@ -225,7 +227,18 @@
   chevron.addEventListener('click', function (e) { e.stopPropagation(); moveSide(); });
   hoverFx(chevron, { opacity: '1', transform: 'scale(1.2)' }, { opacity: '0.8', transform: 'scale(1)' });
 
+  // Sync status in the control bar (only when a bridge is configured): spinner while
+  // syncing, green when synced, red on error — so you always know what's staged.
+  var pillSync = document.createElement('span');
+  Object.assign(pillSync.style, {
+    display: 'none', width: '8px', height: '8px', borderRadius: '999px',
+    background: '#6B7280', flexShrink: '0', boxSizing: 'border-box',
+  });
+  pillSync.title = 'Sync status — click to re-sync';
+  pillSync.addEventListener('click', function (e) { e.stopPropagation(); if (BRIDGE) doSync(); });
+
   pill.appendChild(iconBtn);
+  pill.appendChild(pillSync);
   pill.appendChild(pillText);
   pill.appendChild(listBtn);
   pill.appendChild(clearBtn);
@@ -233,6 +246,30 @@
   pillWrap.appendChild(pill);
   document.body.appendChild(pillWrap);
 
+  // Keyframes for the sync spinner (injected once).
+  var spinStyle = document.createElement('style');
+  spinStyle.textContent = '@keyframes __specterSpin{to{transform:rotate(360deg)}}';
+  markUI(spinStyle);
+  document.head.appendChild(spinStyle);
+
+  // Shared dot styling for the control-bar AND side-panel sync indicators, so they
+  // always match: spinner while syncing, green when synced, red on error.
+  function applyDotState(el, state) {
+    el.style.boxSizing = 'border-box';
+    if (state === 'syncing') {
+      Object.assign(el.style, { width: '10px', height: '10px', background: 'transparent', border: '2px solid rgba(255,255,255,0.35)', borderTopColor: '#fff', animation: '__specterSpin 0.6s linear infinite' });
+    } else if (state === 'synced') {
+      Object.assign(el.style, { width: '8px', height: '8px', background: GREEN, border: 'none', animation: 'none' });
+    } else { // offline / error
+      Object.assign(el.style, { width: '8px', height: '8px', background: '#F26D6D', border: 'none', animation: 'none' });
+    }
+  }
+  function setPillSync(state) {
+    if (!BRIDGE) { pillSync.style.display = 'none'; return; }
+    pillSync.style.display = 'inline-block';
+    applyDotState(pillSync, state);
+  }
+
   pillWrap.addEventListener('mouseenter', function () {
     clearMeasureOverlay();
     clearMeasureTargetHL();
@@ -262,6 +299,12 @@
     }
   }
 
+  // The mode is shown at all times (persistent prefix), so you always know whether
+  // hovering shows properties, measurements, or nothing (Comment).
+  function modeLabel() {
+    return commentMode ? 'Comment' : (measureMode ? 'Measure' : 'Properties');
+  }
+
   function expandPill(text) {
     pill.style.maxWidth = '820px';
     pillText.style.display = 'inline';
@@ -269,19 +312,17 @@
     listBtn.style.display = specs.length > 0 ? 'inline-flex' : 'none';
     clearBtn.style.display = specs.length > 0 ? 'inline' : 'none';
     pillExpanded = true;
-    if (text) { pillText.textContent = text; return; }
-    if (specs.length > 0) {
-      pillText.textContent = specs.length + (specs.length === 1 ? ' Spec' : ' Specs') + ' · P add · L panel · Cmd+C copy';
-    } else if (measureMode) {
-      pillText.textContent = 'Measure · hover distances · P mark · M pin · Cmd+C copy · Option toggle';
-    } else {
-      pillText.textContent = 'Properties · P mark / annotate · Cmd+C copy · Option measure';
-    }
+    // Just the mode (+ the action buttons when Specs exist). Shortcuts live in the
+    // side panel now, so the pill stays short.
+    pillText.textContent = text || modeLabel();
   }
 
+  // "Collapsed" = the compact resting state: mode label only, no hints/buttons.
+  // Still shows the mode so it's visible at all times.
   function collapsePill() {
-    pill.style.maxWidth = '32px';
-    pillText.style.display = 'none';
+    pillText.textContent = modeLabel();
+    pillText.style.display = 'inline';
+    pill.style.maxWidth = '220px';
     chevron.style.display = 'none';
     listBtn.style.display = 'none';
     clearBtn.style.display = 'none';
@@ -290,7 +331,7 @@
 
   function flashMode() {
     if (pillExpanded && pillWrap.matches(':hover')) return;
-    var text = measureMode ? '⬡ Measure mode' : '◉ Properties mode';
+    var text = commentMode ? 'Comment mode' : (measureMode ? 'Measure mode' : 'Properties mode');
     expandPill(text);
     clearTimeout(flashTimer);
     flashTimer = setTimeout(function () {
@@ -311,11 +352,13 @@
   function activate() {
     fiActive = true;
     measureMode = false;
+    commentMode = false;
     pillWrap.style.display = 'block';
     document.body.style.cursor = 'crosshair';
     updatePill();
     startLoop();
     reflowSpecs();
+    if (BRIDGE) doSync(); // resolve the control-bar sync dot (green if reachable, red if not)
   }
 
   function deactivate() {
@@ -599,24 +642,37 @@
     return ['[Specter]', head, 'find: ' + resolveLocator(data.el), props.join('  ·  ')].join('\n');
   }
 
+  // Group Specs on the SAME element so their identical properties aren't emitted
+  // twice — several comments on one thing share ONE property block, each with its
+  // own change note. Measure Specs always stand alone (each is a distinct reading).
+  function groupSpecs() {
+    var groups = [];
+    for (var i = 0; i < specs.length; i++) {
+      var s = specs[i], g = null;
+      if (s.kind === 'element' && s.el) {
+        for (var j = 0; j < groups.length; j++) { if (groups[j].kind === 'element' && groups[j].el === s.el) { g = groups[j]; break; } }
+      }
+      if (g) g.specs.push(s);
+      else groups.push({ kind: s.kind, el: s.el, specs: [s] });
+    }
+    return groups;
+  }
+
   // Copy every Spec — using each Spec's body snapshotted at mark time, so Specs
   // whose element is currently hidden (e.g. inside a closed modal) still copy.
+  // Same-element Specs collapse into one block (properties once, notes stacked).
   function buildSpecsCopyText() {
-    var n = specs.length;
-    return specs.map(function (spec, i) {
-      var tag = spec.kind === 'measure' ? 'Specter Measure' : 'Specter';
+    var groups = groupSpecs();
+    var n = groups.length;
+    return groups.map(function (g, i) {
+      var tag = g.kind === 'measure' ? 'Specter Measure' : 'Specter';
       var header = n > 1 ? '[' + tag + ' ' + (i + 1) + '/' + n + ']' : '[' + tag + ']';
-      if (spec.note) header += '\n✏️ CHANGE: ' + spec.note;
-      return spec.body.replace(/^\[Specter[^\]]*\]/, function () { return header; });
+      var notes = g.specs.filter(function (s) { return s.note; }).map(function (s) { return '✏️ CHANGE: ' + s.note; });
+      if (notes.length) header += '\n' + notes.join('\n');
+      return g.specs[0].body.replace(/^\[Specter[^\]]*\]/, function () { return header; });
     }).join('\n\n---\n\n');
   }
 
-  function linesToHTML(str) {
-    return str.split('\n').map(function (l) {
-      return '<div style="margin-bottom:4px;color:#fff">' + esc(l) + '</div>';
-    }).join('');
-  }
-
   // ─── Hover outline ──────────────────────────────────────────────────────────
   function setHoverOutline(el) {
     if (outlinedEl === el) return;
@@ -648,12 +704,14 @@
   }
 
   function reRenderTooltip() {
+    if (commentMode) { hideTooltip(); return; }
     if (measureMode) {
-      var text = (pinEl && pinEl !== lastHovered) ? measureBetween(pinEl, lastHovered) : measureToNeighbor(lastHovered);
-      tooltip.innerHTML = linesToHTML(text);
-    } else {
-      tooltip.innerHTML = buildHumanDisplay(buildInfo(lastHovered));
+      // Redraw the overlay on scroll/resize; readout box stays hidden (see hover handler).
+      if (pinEl && pinEl !== lastHovered) measureBetween(pinEl, lastHovered); else measureToNeighbor(lastHovered);
+      hideTooltip();
+      return;
     }
+    tooltip.innerHTML = buildHumanDisplay(buildInfo(lastHovered));
     positionTooltip(lastMouse.x, lastMouse.y);
   }
 
@@ -809,7 +867,7 @@
 
   function updateBadgeContent(spec) {
     spec.num.textContent = String(specs.indexOf(spec) + 1);
-    if (spec.note) spec.noteSpan.textContent = '✏️ ' + spec.note;
+    if (spec.note) spec.noteSpan.textContent = spec.note;
     else spec.noteSpan.textContent = spec.kind === 'measure' ? '⬡ measure' : '';
   }
 
@@ -854,10 +912,6 @@
     updateBadgeContent(spec);
   }
 
-  function findElementSpec(el) {
-    for (var i = 0; i < specs.length; i++) if (specs[i].kind === 'element' && specs[i].el === el) return specs[i];
-    return null;
-  }
 
   // If the element sits inside a dialog/modal/drawer/menu, produce a hint for how to
   // bring it back when it's later hidden — a declarative opener (aria-controls /
@@ -896,7 +950,9 @@
       if (pinEl && lastHovered && lastHovered !== pinEl) { el = pinEl; body = buildMeasureCopyText(pinEl, lastHovered); }
       else { el = anchorEl; body = buildNeighborCopyText(anchorEl); }
     } else {
-      if (findElementSpec(anchorEl)) return; // P over an already-Spec'd element → nothing
+      // Multiple Specs per element are allowed in every mode — clustering fans the badges
+      // out and same-element output collapses to one property block. Mode only changes
+      // what's shown on screen, never whether you can add an annotation.
       body = buildLLMClipboard(buildInfo(anchorEl));
     }
     clearHoverOutline();
@@ -1134,14 +1190,74 @@
   }
 
   var panelList = document.createElement('div');
-  Object.assign(panelList.style, { flex: '1', overflowY: 'auto', overflowX: 'hidden' });
+  // overscroll-behavior:contain stops the panel's scroll from chaining into the page.
+  Object.assign(panelList.style, { flex: '1', overflowY: 'auto', overflowX: 'hidden', overscrollBehavior: 'contain' });
+
+  // Keyboard shortcuts reference — collapsible, collapsed by default, lives here (not
+  // in the pill) so the pill stays short.
+  var panelKeys = document.createElement('div');
+  Object.assign(panelKeys.style, {
+    flexShrink: '0', fontSize: '11px', lineHeight: '18px', color: LABEL,
+    borderTop: '1px solid rgba(255,255,255,0.08)',
+  });
+  (function () {
+    var rows = [
+      ['P', 'mark / comment the hovered element'],
+      ['C', 'toggle Comment mode (hide properties)'],
+      ['\u2325 Option', 'toggle Measure mode'],
+      ['M', 'pin an element to measure from'],
+      ['Cmd/Ctrl+C', 'copy all Specs'],
+      ['L', 'toggle this panel'],
+    ];
+    var head = document.createElement('div');
+    Object.assign(head.style, { display: 'flex', alignItems: 'center', gap: '6px', color: '#8A8D96', fontWeight: '700', letterSpacing: '0.04em', textTransform: 'uppercase', fontSize: '11px', padding: '10px 16px', cursor: 'pointer', userSelect: 'none' });
+    var caret = document.createElement('span');
+    caret.textContent = '\u203A'; // ›
+    Object.assign(caret.style, { display: 'inline-block', fontSize: '16px', lineHeight: '1', transition: 'transform 0.15s ease', transform: 'rotate(0deg)' });
+    var headText = document.createElement('span');
+    headText.textContent = 'Keyboard shortcuts';
+    head.appendChild(caret);
+    head.appendChild(headText);
+    var body = document.createElement('div');
+    Object.assign(body.style, { display: 'none', padding: '0 16px 12px' }); // collapsed by default
+    rows.forEach(function (r) {
+      var row = document.createElement('div');
+      Object.assign(row.style, { display: 'flex', gap: '8px', marginBottom: '2px' });
+      var k = document.createElement('span');
+      k.textContent = r[0];
+      Object.assign(k.style, { color: '#E0A3F5', fontWeight: '700', minWidth: '78px', flexShrink: '0' });
+      var d = document.createElement('span');
+      d.textContent = r[1];
+      row.appendChild(k); row.appendChild(d);
+      body.appendChild(row);
+    });
+    var open = false;
+    head.addEventListener('click', function (e) {
+      e.stopPropagation();
+      open = !open;
+      body.style.display = open ? 'block' : 'none';
+      caret.style.transform = open ? 'rotate(90deg)' : 'rotate(0deg)';
+    });
+    panelKeys.appendChild(head);
+    panelKeys.appendChild(body);
+  })();
 
   panelWrap.appendChild(panelHead);
   panelWrap.appendChild(panelTools);
   panelWrap.appendChild(panelHint);
   panelWrap.appendChild(panelList);
+  panelWrap.appendChild(panelKeys);
   document.body.appendChild(panelWrap);
 
+  // Panel scroll and page scroll are mutually exclusive: wheel over the scrollable list
+  // scrolls it natively (overscroll-behavior:contain stops it chaining at the bounds);
+  // wheel over any non-scrolling part of the panel never scrolls the page behind it.
+  panelWrap.addEventListener('wheel', function (e) {
+    var canScroll = panelList.scrollHeight > panelList.clientHeight;
+    if (panelList.contains(e.target) && canScroll) return; // let the list scroll natively
+    e.preventDefault();
+  }, { passive: false });
+
   // ── Auto-sync: mirror the browser's current Specs to the local bridge ──
   // Debounced so rapid edits/typing collapse into one POST. The bridge replaces
   // its snapshot for this URL, so it always reflects what's in the panel — no
@@ -1149,24 +1265,33 @@
   var syncTimer = null;
   function setSyncState(s) {
     if (!BRIDGE) return;
-    if (s === 'syncing') { dot.style.background = '#F59E0B'; dotLabel.textContent = 'Syncing…'; }
-    else if (s === 'synced') { dot.style.background = GREEN; dotLabel.textContent = specs.length ? (specs.length + (specs.length === 1 ? ' Spec synced' : ' Specs synced')) : 'Synced'; }
-    else { dot.style.background = '#6B7280'; dotLabel.textContent = 'Bridge offline'; }
+    setPillSync(s);     // control-bar dot
+    applyDotState(dot, s); // side-panel dot — same spinner/green/red
+    if (s === 'syncing') { dotLabel.textContent = 'Syncing…'; }
+    else if (s === 'synced') { dotLabel.textContent = specs.length ? (specs.length + (specs.length === 1 ? ' Spec synced' : ' Specs synced')) : 'Synced'; }
+    else { dotLabel.textContent = 'Bridge offline'; }
   }
   function doSync() {
     if (!BRIDGE) return;
     setSyncState('syncing');
+    // Keep the spinner up for at least 1s even on an instant localhost sync, so the
+    // feedback is actually perceptible instead of flashing by.
+    var started = Date.now();
+    var settle = function (state) {
+      var wait = Math.max(0, 1000 - (Date.now() - started));
+      setTimeout(function () { setSyncState(state); }, wait);
+    };
     var payload = {
       url: location.href,
       text: buildSpecsCopyText(),
-      specs: specs.map(function (s, i) {
-        return { num: i + 1, note: s.note || '', kind: s.kind, body: s.body };
+      specs: groupSpecs().map(function (g, i) {
+        return { num: i + 1, note: g.specs.map(function (s) { return s.note; }).filter(Boolean).join('\n'), kind: g.kind, body: g.specs[0].body };
       }),
     };
     fetch(BRIDGE + '/specs', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
       .then(function (r) { if (!r.ok) throw 0; return r.json(); })
-      .then(function () { setSyncState('synced'); })
-      .catch(function () { setSyncState('offline'); });
+      .then(function () { settle('synced'); })
+      .catch(function () { settle('offline'); });
   }
   function scheduleSync() {
     if (!BRIDGE) return;
@@ -1202,9 +1327,10 @@
       badge.textContent = String(i + 1);
       Object.assign(badge.style, {
         flexShrink: '0', width: '20px', height: '20px', borderRadius: '999px',
-        background: PURPLE, color: '#fff', fontSize: '11px', fontWeight: '700',
-        border: '2px solid #fff', boxSizing: 'border-box',
+        background: BADGE_IDLE, color: '#fff', fontSize: '11px', fontWeight: '700',
+        border: '1px solid #fff', boxSizing: 'border-box',
         display: 'flex', alignItems: 'center', justifyContent: 'center',
+        transition: 'background 0.12s ease',
       });
       var content = document.createElement('div');
       Object.assign(content.style, { flex: '1', minWidth: '0', display: 'flex', flexDirection: 'column', gap: '6px', paddingRight: '30px' });
@@ -1310,7 +1436,7 @@
           Object.assign(hbar.style, { display: 'flex', alignItems: 'center', gap: '7px', marginTop: '2px', flexWrap: 'wrap' });
           var tag = document.createElement('span');
           tag.textContent = 'HIDDEN';
-          Object.assign(tag.style, { fontSize: '9px', fontWeight: '700', letterSpacing: '0.05em', color: '#3A2A05', background: '#F59E0B', borderRadius: '4px', padding: '2px 6px', flexShrink: '0' });
+          Object.assign(tag.style, { fontSize: '11px', fontWeight: '700', letterSpacing: '0.05em', color: '#3A2A05', background: '#F59E0B', borderRadius: '4px', padding: '2px 6px', flexShrink: '0' });
           var hint = document.createElement('span');
           hint.textContent = spec.locate || 'Not on the page right now';
           Object.assign(hint.style, { fontSize: '11px', color: '#C9CBD2', overflow: 'hidden', textOverflow: 'ellipsis' });
@@ -1326,12 +1452,14 @@
         note.addEventListener('click', function (e) { if (spec.note) { e.stopPropagation(); spec._expanded = !spec._expanded; renderPanel(); } });
         row.addEventListener('mouseenter', function () {
           row.style.background = 'rgba(255,255,255,0.05)';
+          badge.style.background = PURPLE;
           editBtn.style.display = delBtn.style.display = 'flex';
           actions.style.background = 'linear-gradient(to right, rgba(52,54,60,0) 0, rgba(52,54,60,1) 22px)';
           if (visible) { highlightSpec = spec; revealSpec(spec); }
         });
         row.addEventListener('mouseleave', function () {
           row.style.background = 'transparent';
+          badge.style.background = BADGE_IDLE;
           editBtn.style.display = delBtn.style.display = 'none';
           actions.style.background = 'transparent';
           if (highlightSpec === spec) highlightSpec = null;
@@ -1574,9 +1702,9 @@
         position: 'absolute',
         background: RED,
         color: '#fff',
-        fontSize: '10px',
+        fontSize: '12px',
         fontFamily: MONO,
-        padding: '1px 4px',
+        padding: '2px 5px',
         borderRadius: '3px',
         pointerEvents: 'none',
         whiteSpace: 'nowrap',
@@ -1776,12 +1904,24 @@
 
     lastHovered = target;
 
+    // Comment mode: outline only (so you know what you're commenting on), no
+    // properties/measure overlay on screen. The Spec still captures everything.
+    if (commentMode) {
+      clearMeasureOverlay();
+      clearMeasureTargetHL();
+      setHoverOutline(target);
+      hideTooltip();
+      return;
+    }
+
     if (measureMode) {
       clearHoverOutline();
       showMeasureTargetHL(target);
-      var text = (pinEl && pinEl !== target) ? measureBetween(pinEl, target) : measureToNeighbor(target);
-      tooltip.innerHTML = linesToHTML(text);
-      positionTooltip(e.clientX, e.clientY);
+      // Draw the on-screen measurement overlay (the px badges + lines) but keep
+      // the dark readout box hidden — it occludes the very measurements it reports.
+      // The full readout still copies with Cmd+C. (Properties mode keeps its box.)
+      if (pinEl && pinEl !== target) measureBetween(pinEl, target); else measureToNeighbor(target);
+      hideTooltip();
       if (pinEl) updatePinHL();
     } else {
       clearMeasureOverlay();
@@ -1863,6 +2003,21 @@
       return;
     }
 
+    // C — toggle Comment mode (outline only; props/measure hidden but still captured).
+    // Plain c only — Cmd/Ctrl+C copy was handled above and returned.
+    if ((e.key === 'c' || e.key === 'C') && !e.metaKey && !e.ctrlKey) {
+      e.preventDefault();
+      commentMode = !commentMode;
+      if (commentMode && measureMode) { measureMode = false; clearPin(); }
+      clearMeasureOverlay();
+      clearMeasureTargetHL();
+      clearHoverOutline();
+      hideTooltip();
+      if (lastHovered && commentMode) setHoverOutline(lastHovered);
+      flashMode();
+      return;
+    }
+
     // Esc only HIDES the plugin — Specs persist and return on reactivate.
     if (e.key === 'Escape') {
       if (panelOpen) { hidePanel(); return; }