npm - vite-plugin-specter - Versions diffs - 0.7.0 → 0.7.5 - Mend

vite-plugin-specter 0.7.0 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +42 -9
package/dist/client.js +406 -102
package/dist/extension-chrome/content.js +406 -102
package/dist/extension-chrome/manifest.json +1 -1
package/dist/extension-firefox/content.js +406 -102
package/dist/extension-firefox/manifest.json +1 -1
package/dist/index.cjs +406 -102
package/dist/index.js +406 -102
package/extension/content.js +406 -102
package/mcp-bridge/README.md +73 -0
package/mcp-bridge/package.json +10 -0
package/mcp-bridge/server.mjs +161 -0
package/package.json +3 -2

package/dist/index.js CHANGED Viewed

@@ -30,7 +30,17 @@ function getClientScript(options) {
   var CHECK = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>';
   var SHARE = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8"></path><polyline points="16 6 12 2 8 6"></polyline><line x1="12" y1="2" x2="12" y2="15"></line></svg>';
   var IMPORT = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v13"></path><polyline points="8 12 12 16 16 12"></polyline><path d="M4 21h16"></path></svg>';
-  var ACTIVATE = ${JSON.stringify(activateShortcut)};
+  // Toggle chord: the Vite-config value (or the built-in default) is the baseline; a
+  // per-origin localStorage override \u2014 set from the panel's rebind UI or window.__specter \u2014
+  // wins, so anyone can change it with no config edit and no dev-server restart.
+  var ACTIVATE_DEFAULT = ${JSON.stringify(activateShortcut)};
+  var ACTIVATE_KEY = '__specter_activate';
+  var ACTIVATE = ACTIVATE_DEFAULT;
+  try { var _actOv = localStorage.getItem(ACTIVATE_KEY); if (_actOv) ACTIVATE = _actOv; } catch (e) {}
+  function shortcutLabel(s) { return String(s || '').split('+').map(function (p) { return p.charAt(0).toUpperCase() + p.slice(1); }).join('+'); }
+  function setActivate(combo) { ACTIVATE = combo; try { localStorage.setItem(ACTIVATE_KEY, combo); } catch (e) {} }
+  function resetActivate() { ACTIVATE = ACTIVATE_DEFAULT; try { localStorage.removeItem(ACTIVATE_KEY); } catch (e) {} }
+  function activateOverridden() { try { return !!localStorage.getItem(ACTIVATE_KEY); } catch (e) { return false; } }
   var BRIDGE = ${JSON.stringify(bridgeUrl)}; // Claude MCP bridge URL, or '' if disabled
   // \u2500\u2500\u2500 State \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -70,6 +80,45 @@ function getClientScript(options) {
   function markUI(el) { el.setAttribute('data-specter-ui', ''); return el; }
   function isUI(el) { return !!(el && el.closest && el.closest('[data-specter-ui]')); }
+  // \u2500\u2500\u2500 Hydration-proof mounting \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // We inject at document_end, but frameworks that hydrate <body> (Next.js App
+  // Router / React 18-19, some Remix/Gatsby) then reconcile away DOM nodes they
+  // didn't render \u2014 silently deleting Specter's UI on those sites (pill/panel
+  // vanish; badges added later survive because they're created post-hydration).
+  // Track our persistent singletons and re-attach any that gets detached, so the
+  // UI survives the hydration pass and later SPA re-renders. The parent is resolved
+  // fresh on each remount so a wholesale body/head element swap is handled too.
+  var _mounted = [];
+  function mount(node, where) {
+    var parent = where === 'head' ? document.head : document.body;
+    if (parent) parent.appendChild(node);
+    _mounted.push({ node: node, where: where });
+    return node;
+  }
+  var _remountQueued = false;
+  function remountDetached() {
+    _remountQueued = false;
+    for (var i = 0; i < _mounted.length; i++) {
+      var m = _mounted[i];
+      if (m.node.isConnected) continue;
+      var p = m.where === 'head' ? document.head : document.body;
+      if (p) p.appendChild(m.node); // re-append; isConnected guard above prevents an observer loop
+    }
+  }
+  try {
+    var _defer = window.requestAnimationFrame ? function (fn) { requestAnimationFrame(fn); } : function (fn) { setTimeout(fn, 0); };
+    var _mo = new MutationObserver(function () {
+      if (_remountQueued) return;
+      _remountQueued = true;
+      _defer(remountDetached); // coalesce a burst of mutations into one restore pass
+    });
+    // childList on the roots is enough \u2014 every singleton is a direct child of
+    // body/head; watching documentElement too catches a body/head element swap.
+    _mo.observe(document.documentElement, { childList: true });
+    _mo.observe(document.body, { childList: true });
+    _mo.observe(document.head, { childList: true });
+  } catch (e) {}
   // Attach a hover effect to an interactive icon/button: apply the "on" styles
   // while hovered, restore the "off" styles on leave (keeps things clickable-feeling).
   function hoverFx(el, on, off) {
@@ -96,7 +145,7 @@ function getClientScript(options) {
     boxShadow: '0 4px 16px rgba(0,0,0,0.3)',
     display: 'none',
   });
-  document.body.appendChild(tooltip);
+  mount(tooltip);
   // Measure overlay
   var measureOverlay = document.createElement('div');
@@ -108,7 +157,7 @@ function getClientScript(options) {
     pointerEvents: 'none',
     display: 'none',
   });
-  document.body.appendChild(measureOverlay);
+  mount(measureOverlay);
   // \u2500\u2500\u2500 Pill \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   var pillWrap = document.createElement('div');
@@ -184,41 +233,34 @@ function getClientScript(options) {
   var pillText = document.createElement('span');
   Object.assign(pillText.style, { display: 'none', color: '#f3d9fb' });
+  // Panel toggle \u2014 icon + label so it's self-explanatory. Label reflects state
+  // (Open/Close) and always names the shortcut.
   var listBtn = document.createElement('span');
-  listBtn.innerHTML = LIST;
-  listBtn.title = 'Show Specs panel (L)';
+  listBtn.title = 'Toggle Specs panel (L)';
   Object.assign(listBtn.style, {
     display: 'none',
     alignItems: 'center',
+    gap: '6px',
     cursor: 'pointer',
     color: '#fff',
+    fontSize: '11px',
     flexShrink: '0',
-    padding: '4px 6px',
+    padding: '4px 10px',
     marginLeft: '2px',
     borderRadius: '999px',
     background: 'rgba(255,255,255,0.16)',
   });
+  var listIcon = document.createElement('span');
+  listIcon.innerHTML = LIST;
+  Object.assign(listIcon.style, { display: 'flex', alignItems: 'center' });
+  var listLabel = document.createElement('span');
+  listBtn.appendChild(listIcon);
+  listBtn.appendChild(listLabel);
+  function updateListBtn() { listLabel.textContent = (panelOpen ? 'Close' : 'Open') + ' sidebar [L]'; }
+  updateListBtn();
   listBtn.addEventListener('click', function (e) { e.stopPropagation(); togglePanel(); });
   hoverFx(listBtn, { background: 'rgba(255,255,255,0.32)' }, { background: 'rgba(255,255,255,0.16)' });
-  var clearBtn = document.createElement('span');
-  clearBtn.textContent = '\u2715 Delete all';
-  clearBtn.title = 'Delete all annotations';
-  Object.assign(clearBtn.style, {
-    display: 'none',
-    cursor: 'pointer',
-    color: '#fff',
-    fontSize: '11px',
-    fontWeight: '600',
-    flexShrink: '0',
-    padding: '2px 8px',
-    marginLeft: '2px',
-    borderRadius: '999px',
-    background: 'rgba(255,255,255,0.16)',
-  });
-  clearBtn.addEventListener('click', function (e) { e.stopPropagation(); removeAllSpecs(); });
-  hoverFx(clearBtn, { background: 'rgba(255,255,255,0.32)' }, { background: 'rgba(255,255,255,0.16)' });
   var chevron = document.createElement('span');
   chevron.textContent = '\u203A';
   chevron.title = 'Move to other side';
@@ -248,16 +290,15 @@ function getClientScript(options) {
   pill.appendChild(pillSync);
   pill.appendChild(pillText);
   pill.appendChild(listBtn);
-  pill.appendChild(clearBtn);
   pill.appendChild(chevron);
   pillWrap.appendChild(pill);
-  document.body.appendChild(pillWrap);
+  mount(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);
+  mount(spinStyle, 'head');
   // 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.
@@ -309,7 +350,7 @@ function getClientScript(options) {
   // 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');
+    return (commentMode ? 'Comment' : (measureMode ? 'Measure' : 'Properties')) + ' mode';
   }
   function expandPill(text) {
@@ -317,7 +358,7 @@ function getClientScript(options) {
     pillText.style.display = 'inline';
     chevron.style.display = 'inline';
     listBtn.style.display = 'inline-flex'; // always reachable \u2014 the panel is also where you Import a shared file
-    clearBtn.style.display = specs.length > 0 ? 'inline' : 'none';
+    updateListBtn();
     pillExpanded = true;
     // Just the mode (+ the action buttons when Specs exist). Shortcuts live in the
     // side panel now, so the pill stays short.
@@ -332,14 +373,12 @@ function getClientScript(options) {
     pill.style.maxWidth = '220px';
     chevron.style.display = 'none';
     listBtn.style.display = 'none';
-    clearBtn.style.display = 'none';
     pillExpanded = false;
   }
   function flashMode() {
     if (pillExpanded && pillWrap.matches(':hover')) return;
-    var text = commentMode ? 'Comment mode' : (measureMode ? 'Measure mode' : 'Properties mode');
-    expandPill(text);
+    expandPill(modeLabel());
     clearTimeout(flashTimer);
     flashTimer = setTimeout(function () {
       if (!pillWrap.matches(':hover') && specs.length === 0 && !pinEl) collapsePill();
@@ -465,10 +504,13 @@ function getClientScript(options) {
     var cur = el;
     for (var i = 0; i < 3 && cur && cur !== document.body; i++) {
       var part = cur.tagName.toLowerCase();
-      if (cur.id) { part += '#' + cur.id; parts.unshift(part); break; }
+      if (cur.id) { part += '#' + cssEsc(cur.id); parts.unshift(part); break; }
       var cls = Array.prototype.slice.call(cur.classList).filter(function (c) { return c.indexOf('__specter') !== 0; });
       if (cls.length) {
-        part += '.' + cls.slice(0, 2).join('.');
+        // Escape each class: Tailwind classes like lg:block / bg-[#f5f5dc] are
+        // invalid raw in a selector (the : reads as a pseudo, [# as an attr) and
+        // throw on query, so they must be CSS.escape-d first.
+        part += '.' + cls.slice(0, 2).map(cssEsc).join('.');
       } else if (cur.parentElement) {
         var sameTag = Array.prototype.slice.call(cur.parentElement.children).filter(function (c) { return c.tagName === cur.tagName; });
         if (sameTag.length > 1) {
@@ -548,13 +590,13 @@ function getClientScript(options) {
     var i, v;
     var testAttrs = ['data-testid', 'data-test-id', 'data-test', 'data-cy', 'data-qa'];
     for (i = 0; i < testAttrs.length; i++) { v = el.getAttribute(testAttrs[i]); if (v) { var ts = '[' + testAttrs[i] + '="' + cssEsc(v) + '"]'; if (uniqueSel(ts)) return ts; } }
-    if (el.id && !isHashedId(el.id) && uniqueSel('#' + cssEsc(el.id))) return '#' + el.id;
+    if (el.id && !isHashedId(el.id) && uniqueSel('#' + cssEsc(el.id))) return '#' + cssEsc(el.id);
     var attrs = ['aria-label', 'name', 'placeholder', 'alt', 'title'];
     for (i = 0; i < attrs.length; i++) { v = el.getAttribute(attrs[i]); if (v && v.trim()) { v = v.trim(); if (uniqueSel('[' + attrs[i] + '="' + cssEsc(v) + '"]')) return attrs[i] + ' "' + v.slice(0, 60) + '"'; } }
     var txt = ownText(el);
     if (txt && uniqueTextAnchor(el, txt)) return 'text "' + txt.slice(0, 40) + (txt.length > 40 ? '\u2026' : '') + '"';
     var cls = ownClass(el);
-    if (cls) return '.' + cls;
+    if (cls) return '.' + cssEsc(cls);
     return getSelector(el); // fallback: the CSS path
   }
@@ -656,6 +698,7 @@ function getClientScript(options) {
     var groups = [];
     for (var i = 0; i < specs.length; i++) {
       var s = specs[i], g = null;
+      if (s.resolved) continue; // done Specs drop out of both the Cmd+C copy and the bridge sync \u2014 so /spectify never re-applies them
       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; } }
       }
@@ -728,11 +771,20 @@ function getClientScript(options) {
   function elementPath(el) {
     if (!el || el.nodeType !== 1) return '';
     var parts = [], cur = el;
-    while (cur && cur.nodeType === 1 && cur !== document.body && parts.length < 6) {
-      if (cur.id) { try { parts.unshift('#' + CSS.escape(cur.id)); } catch (e) { parts.unshift('#' + cur.id); } break; }
+    // Root the path at <body> or a stable id, and index with nth-OF-TYPE rather than
+    // nth-child: a hydrated page injects <script>/<style> siblings that shift a raw
+    // child index (the old div:nth-child(11) bug \u2014 matched a different node, or
+    // none, on the recipient). nth-of-type counts only same-tag siblings, so it
+    // survives that. Deeper cap (12) so the chain reaches a rooting anchor.
+    while (cur && cur.nodeType === 1 && parts.length < 12) {
+      if (cur === document.body) { parts.unshift('body'); break; }
+      if (cur.id && !isHashedId(cur.id)) { parts.unshift('#' + cssEsc(cur.id)); break; }
       var seg = cur.tagName.toLowerCase();
       var parent = cur.parentElement;
-      if (parent) seg += ':nth-child(' + (Array.prototype.indexOf.call(parent.children, cur) + 1) + ')';
+      if (parent) {
+        var same = Array.prototype.filter.call(parent.children, function (c) { return c.tagName === cur.tagName; });
+        if (same.length > 1) seg += ':nth-of-type(' + (Array.prototype.indexOf.call(same, cur) + 1) + ')';
+      }
       parts.unshift(seg);
       cur = cur.parentElement;
     }
@@ -808,6 +860,11 @@ function getClientScript(options) {
     var vis = [];
     for (var i = 0; i < specs.length; i++) {
       var s = specs[i];
+      // Badges created at import-time can be wiped by a framework hydrating <body>
+      // (same cause as the singleton mount guard). Re-attach a detached wrap so the
+      // pin reappears; a removed spec is already out of the specs array, so this
+      // never resurrects a deleted badge.
+      if (s.wrap && !s.wrap.isConnected && document.body) document.body.appendChild(s.wrap);
       if (!fiActive) { s.wrap.style.display = 'none'; s._liveVis = false; continue; }
       if (s.missing) { s.wrap.style.display = 'none'; s._liveVis = false; continue; } // shared comment whose target is gone/changed
       if (!s.el || !s.el.isConnected) { var f = safeQuery(s.path); if (f) s.el = f; }
@@ -882,10 +939,17 @@ function getClientScript(options) {
   function startLoop() { if (rafId == null) (function loop() { reflowSpecs(); rafId = requestAnimationFrame(loop); })(); }
   function stopLoop() { if (rafId != null) { cancelAnimationFrame(rafId); rafId = null; } }
-  function renumber() { for (var i = 0; i < specs.length; i++) specs[i].num.textContent = String(i + 1); }
+  // Paint a badge's number/\u2713 + done tint. Called by renumber and updateBadgeContent so
+  // the on-page pin reflects resolved state everywhere (reflowSpecs never touches these).
+  function paintBadgeState(spec, i) {
+    spec.num.textContent = String(i + 1); // always the number (for wayfinding) \u2014 green tint carries the "done" signal
+    if (spec.cap) { spec.cap.style.background = spec.resolved ? GREEN : PURPLE; spec.cap.style.opacity = spec.resolved ? '0.65' : '1'; }
+  }
+  function renumber() { for (var i = 0; i < specs.length; i++) paintBadgeState(specs[i], i); }
   function updateBadgeContent(spec) {
-    spec.num.textContent = String(specs.indexOf(spec) + 1);
+    paintBadgeState(spec, specs.indexOf(spec));
     if (spec.note) spec.noteSpan.textContent = spec.note;
     else spec.noteSpan.textContent = spec.kind === 'measure' ? '\u2B21 measure' : '';
   }
@@ -1007,13 +1071,50 @@ function getClientScript(options) {
     saveSpecs();
   }
+  // \u2500\u2500 Resolved (done) lifecycle \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // A resolved Spec is NOT deleted \u2014 it stays as a record of what changed, greyed with
+  // a \u2713, and drops out of the copy + bridge sync (see groupSpecs) so it's never re-applied.
+  function resolvedCount() { var n = 0; for (var i = 0; i < specs.length; i++) if (specs[i].resolved) n++; return n; }
+  function toggleResolved(spec) {
+    spec.resolved = !spec.resolved;
+    if (spec.resolved && panelEditSpec === spec) panelEditSpec = null; // close an open editor on the one being marked done
+    updateBadgeContent(spec);
+    updatePill();      // re-renders the panel when open
+    saveSpecs();       // persists resolved + re-syncs the bridge (now excluding it)
+  }
+  // Sweep every resolved Spec once the user is satisfied \u2014 leaves open Specs untouched.
+  function clearResolved() {
+    for (var i = specs.length - 1; i >= 0; i--) {
+      if (!specs[i].resolved) continue;
+      if (highlightSpec === specs[i]) highlightSpec = null;
+      if (panelEditSpec === specs[i]) panelEditSpec = null;
+      if (specs[i].wrap) specs[i].wrap.remove();
+      specs.splice(i, 1);
+    }
+    renumber();
+    updatePill();
+    saveSpecs();
+  }
+  // Drop every imported (shared) spec, leaving the user's own local ones. Used by
+  // importComments so a received share replaces the prior set instead of stacking.
+  function removeSharedSpecs() {
+    if (highlightSpec && highlightSpec.shared) highlightSpec = null;
+    if (panelEditSpec && panelEditSpec.shared) panelEditSpec = null;
+    for (var i = specs.length - 1; i >= 0; i--) {
+      if (specs[i].shared) { if (specs[i].wrap) specs[i].wrap.remove(); specs.splice(i, 1); }
+    }
+  }
   // \u2500\u2500\u2500 Reload insurance (localStorage, per-URL, zero network) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   // Persist only the serializable parts of each Spec; the live element ref and
   // DOM nodes are rebuilt on restore (re-anchored best-effort via the CSS path).
   function saveSpecs() {
     try {
       if (!specs.length) localStorage.removeItem(STORAGE_KEY);
-      else localStorage.setItem(STORAGE_KEY, JSON.stringify(specs.map(function (s) { return { path: s.path, note: s.note, body: s.body, kind: s.kind, locate: s.locate, shared: s.shared, fp: s.fp, missing: s.missing, missReason: s.missReason }; })));
+      else localStorage.setItem(STORAGE_KEY, JSON.stringify(specs.map(function (s) { return { path: s.path, note: s.note, body: s.body, kind: s.kind, locate: s.locate, shared: s.shared, fp: s.fp, missing: s.missing, missReason: s.missReason, resolved: s.resolved }; })));
     } catch (e) {}
     scheduleSync(); // keep the Claude bridge mirrored to the current Specs
   }
@@ -1023,7 +1124,7 @@ function getClientScript(options) {
     try { data = JSON.parse(localStorage.getItem(STORAGE_KEY) || 'null'); } catch (e) { return; }
     if (!Array.isArray(data) || !data.length) return;
     data.forEach(function (d) {
-      var spec = { el: d.missing ? null : safeQuery(d.path), path: d.path, note: d.note || '', body: d.body || '', kind: d.kind || 'element', locate: d.locate || '', shared: !!d.shared, fp: d.fp || '', missing: !!d.missing, missReason: d.missReason || '' };
+      var spec = { el: d.missing ? null : safeQuery(d.path), path: d.path, note: d.note || '', body: d.body || '', kind: d.kind || 'element', locate: d.locate || '', shared: !!d.shared, fp: d.fp || '', missing: !!d.missing, missReason: d.missReason || '', resolved: !!d.resolved };
       specs.push(spec);
       createBadge(spec);
     });
@@ -1038,11 +1139,13 @@ function getClientScript(options) {
   // element is gone OR its signature changed, the comment shows as MISSING (panel
   // only, greyed, with a reason) instead of being drawn on a guessed spot.
-  // Normalized element signature for change-detection: stable structural identity,
-  // NOT raw outerHTML (which false-trips on any text/attr churn). tag + sorted own
-  // classes + a few structural attrs + a short trimmed-text slice. The text slice is
-  // the strictness knob \u2014 include it to catch content edits, at the cost of a
-  // false-MISSING when dynamic text (a price/timestamp) changes under a stable node.
+  // Normalized element signature \u2014 a STRUCTURAL identity used to disambiguate which
+  // element a shared comment belongs to (and to scan for it when selectors fail).
+  // Deliberately NO raw text: page-load-dynamic text (a clock, a random greeting, a
+  // price) was false-tripping this and blocking re-anchor on otherwise-identical
+  // pages. tag + sorted own classes + key attrs + child count identifies the node
+  // without that fragility. (Trade-off: pure text edits under a stable node no
+  // longer read as "changed" \u2014 placement is favoured over change-detection.)
   function normSig(el) {
     if (!el || el.nodeType !== 1) return '';
     var cls = Array.prototype.slice.call(el.classList)
@@ -1050,8 +1153,7 @@ function getClientScript(options) {
     var attrs = ['type', 'role', 'name', 'href', 'aria-label'].map(function (a) {
       var v = el.getAttribute(a); return v ? a + '=' + v.trim() : '';
     }).filter(Boolean).join('|');
-    var txt = (el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 50);
-    return el.tagName.toLowerCase() + '#' + cls + '#' + attrs + '#' + txt;
+    return el.tagName.toLowerCase() + '#' + cls + '#' + attrs + '#' + el.childElementCount;
   }
   // djb2 xor \u2192 short base36 hash. Zero-dep; collisions don't matter (a match just
   // means "unchanged enough", and the re-find already narrowed us to one element).
@@ -1063,51 +1165,91 @@ function getClientScript(options) {
     return (h >>> 0).toString(36);
   }
-  // Scan for an element whose OWN text matches (trunc = the stored anchor was cut to
-  // 40 chars). Ambiguous (>1 match) \u2192 null, so we fall through to the nth-child path
-  // rather than guess. Skips Specter's own UI.
-  function findByOwnText(val, trunc) {
-    var all = document.body ? document.body.getElementsByTagName('*') : [], hit = null;
+  function queryAll(sel) { try { return sel ? Array.prototype.slice.call(document.querySelectorAll(sel)) : []; } catch (e) { return []; } }
+  // Every element whose OWN text matches (trunc = the stored anchor was cut to 40
+  // chars). Returns ALL matches \u2014 the fingerprint picks among them in reFindShared,
+  // so a repeated label (e.g. two "Read more") no longer forces a MISSING. Skips UI.
+  function findAllByOwnText(val, trunc) {
+    var all = document.body ? document.body.getElementsByTagName('*') : [], out = [];
     for (var i = 0; i < all.length; i++) {
       var el = all[i];
       if (el.closest && el.closest('[data-specter-ui]')) continue;
       var t = ownText(el);
       if (!t) continue;
-      if (trunc ? (t.slice(0, 40) === val) : (t === val)) { if (hit) return null; hit = el; }
+      if (trunc ? (t.slice(0, 40) === val) : (t === val)) out.push(el);
     }
-    return hit;
+    return out;
   }
-  // Real resolver for a resolveLocator() anchor: #id/.class/[attr] query straight;
-  // 'attr "value"' rebuilds the attribute selector; 'text "value"' scans own-text.
-  // Only trusts an anchor that resolves to EXACTLY ONE element \u2014 a class or CSS path
-  // shared by siblings (e.g. three .card boxes) would otherwise silently match the
-  // first one, mis-anchoring every comment onto it.
-  function resolveFind(find) {
-    if (!find) return null;
+  // Candidate elements for a resolveLocator() anchor: #id/.class/[attr]/CSS-path via
+  // querySelectorAll; 'attr "value"' rebuilds the attribute selector; 'text "value"'
+  // scans own-text. Returns ALL matches (may be >1) \u2014 reFindShared narrows by
+  // fingerprint rather than rejecting anything ambiguous up front.
+  function resolveFindCandidates(find) {
+    if (!find) return [];
     var c = find.charAt(0);
-    if (c === '#' || c === '.' || c === '[') return uniqueSel(find) ? safeQuery(find) : null;
+    if (c === '#' || c === '.' || c === '[') return queryAll(find);
     var q = find.indexOf(' "');
     if (q > 0 && find.charAt(find.length - 1) === '"') {
       var attr = find.slice(0, q), val = find.slice(q + 2, -1), trunc = false;
       if (val.charAt(val.length - 1) === '\u2026') { trunc = true; val = val.slice(0, -1); }
-      if (attr === 'text') return findByOwnText(val, trunc);
-      if (val.indexOf('"') < 0) { var sel = '[' + attr + '="' + val + '"]'; return uniqueSel(sel) ? safeQuery(sel) : null; }
-      return null;
+      if (attr === 'text') return findAllByOwnText(val, trunc);
+      if (val.indexOf('"') < 0) return queryAll('[' + attr + '="' + val + '"]');
+      return [];
+    }
+    return queryAll(find); // a bare CSS path
+  }
+  // Re-find a shared comment's element. The fingerprint is the DISAMBIGUATOR, not
+  // just a change-detector: gather every candidate from the find anchor AND the
+  // nth-child path, then return the one whose signature matches \u2014 so a locator
+  // shared by siblings (e.g. div:nth-child(1)) still resolves on the same page
+  // instead of failing as ambiguous. With no fp match: hand back a lone candidate
+  // (so importComments can say "changed"), else null ("couldn't find").
+  // Whole-DOM scan for the one element whose structural signature matches \u2014 the
+  // last-resort re-finder when both the find anchor and the nth-of-type path fail
+  // (e.g. selectors that don't round-trip, or a shifted structure). >1 match \u2192 bail
+  // (ambiguous, don't guess). Skips Specter's own UI.
+  function findByFingerprint(fp) {
+    if (!fp) return null;
+    var all = document.body ? document.body.getElementsByTagName('*') : [], hit = null;
+    for (var i = 0; i < all.length; i++) {
+      var el = all[i];
+      if (el.closest && el.closest('[data-specter-ui]')) continue;
+      if (fingerprint(el) === fp) { if (hit) return null; hit = el; }
     }
-    return uniqueSel(find) ? safeQuery(find) : null; // a bare CSS path \u2014 only if unambiguous
+    return hit;
   }
-  // Re-find a shared comment's element, using the fingerprint to DISAMBIGUATE (not
-  // only to detect change): prefer whichever candidate \u2014 the find anchor or the
-  // nth-child path \u2014 actually matches the stored signature. Falls back to a
-  // best-effort element so importComments can still tell "changed" from "not found".
+  function fpOk(el, item) { return !item.fp || fingerprint(el) === item.fp; }
+  // Rank the signals rather than pooling them, so a specific locator always beats a
+  // vague one:
+  //   1. a find anchor that resolves to exactly ONE element (id / unique text / class)
+  //      \u2014 the strongest, most semantic signal;
+  //   2. the rooted nth-of-type path, if unique \u2014 this is what disambiguates repeated
+  //      structure (a class-path find matches every paragraph; the path pins the exact
+  //      one). Pooling let an ambiguous find shadow the unique path \u2014 the mis-anchor bug;
+  //   3. the structural fingerprint across the pooled candidates, then a DOM-wide scan;
+  //   4. any lone resolution.
+  // fp guards 1 and 2 so a drifted anchor can't win blindly, but a unique anchor with a
+  // changed signature is still trusted at step 4 (placement over false-MISSING).
   function reFindShared(item) {
-    var byFind = resolveFind(item.find);
-    if (byFind && (!item.fp || fingerprint(byFind) === item.fp)) return byFind;
-    var byPath = safeQuery(item.path);
-    if (byPath && (!item.fp || fingerprint(byPath) === item.fp)) return byPath;
-    return byFind || byPath || null;
+    var byFind = resolveFindCandidates(item.find);
+    if (byFind.length === 1 && fpOk(byFind[0], item)) return byFind[0];
+    var byPath = item.path ? queryAll(item.path) : [];
+    if (byPath.length === 1 && fpOk(byPath[0], item)) return byPath[0];
+    var cands = [], i, all = byFind.concat(byPath);
+    for (i = 0; i < all.length; i++) if (all[i] && cands.indexOf(all[i]) < 0) cands.push(all[i]);
+    if (item.fp) {
+      for (i = 0; i < cands.length; i++) if (fingerprint(cands[i]) === item.fp) return cands[i];
+      var scan = findByFingerprint(item.fp);       // selectors failed/ambiguous \u2192 find it by signature
+      if (scan) return scan;
+    }
+    if (byFind.length === 1) return byFind[0];      // unique anchor, fp drifted \u2014 trust the anchor
+    if (byPath.length === 1) return byPath[0];
+    return cands.length === 1 ? cands[0] : null;
   }
   // URL gate: two people must be on the SAME page for a shared comment to place.
@@ -1138,12 +1280,19 @@ function getClientScript(options) {
       console.warn('[Specter] These comments are for ' + pageKey(srcUrl) + ' \u2014 not this page (' + pageKey() + '). Not imported.');
       return 0;
     }
+    // A received share REPLACES the previously-imported set: re-opening the same
+    // link (or a refreshed one) gives exactly that set, never a stacked-up pile of
+    // duplicates across rounds. Your OWN local specs (shared:false) are untouched.
+    removeSharedSpecs();
     var added = 0;
     comments.forEach(function (item) {
       if (!item) return;
+      // reFindShared already used the fingerprint to pick/scan the right element, so
+      // trust its result: if it located a node, PLACE the comment. Only a genuine
+      // no-match is MISSING \u2014 we no longer hide a found element just because its
+      // signature drifted (that over-fired on dynamic pages and buried real pins).
       var el = reFindShared(item), missing = false, reason = '';
       if (!el) { missing = true; reason = 'Couldn\u2019t find this element on the page'; }
-      else if (item.fp && fingerprint(el) !== item.fp) { missing = true; reason = 'This element changed \u2014 can\u2019t place the comment'; }
       // body stays empty on purpose: comments-only, never the shared element's props.
       // A MISSING spec keeps el=null so it's never drawn or re-anchored via its path.
       var spec = { el: missing ? null : el, path: item.path || '', note: item.note || '', body: '', kind: item.kind || 'element', locate: '', shared: true, fp: item.fp || '', missing: missing, missReason: reason };
@@ -1504,7 +1653,7 @@ function getClientScript(options) {
     var rows = [
       ['P', 'mark / comment the hovered element'],
       ['C', 'toggle Comment mode (hide properties)'],
-      ['\\u2325 Option', 'toggle Measure mode'],
+      ['\\u2325 Option / Alt', 'toggle Measure mode'],
       ['M', 'pin an element to measure from'],
       ['Cmd/Ctrl+C', 'copy all Specs'],
       ['L', 'toggle this panel'],
@@ -1520,9 +1669,48 @@ function getClientScript(options) {
     head.appendChild(headText);
     var body = document.createElement('div');
     Object.assign(body.style, { display: 'none', padding: '0 16px 12px' }); // collapsed by default
+    // Rebindable toggle shortcut \u2014 the one chord you might have to change if it collides
+    // with a browser/extension binding. Click Change, press a new combo. Saved per origin,
+    // no restart. Works identically in the Vite plugin overlay and the browser extension.
+    (function () {
+      var rrow = document.createElement('div');
+      Object.assign(rrow.style, { display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '10px', paddingBottom: '10px', borderBottom: '1px solid rgba(255,255,255,0.06)' });
+      var chip = document.createElement('span');
+      Object.assign(chip.style, { color: '#E0A3F5', fontWeight: '700', minWidth: '78px', flexShrink: '0' });
+      var lbl = document.createElement('span');
+      Object.assign(lbl.style, { flex: '1', minWidth: '0' });
+      lbl.textContent = 'toggle Specter on/off';
+      var change = document.createElement('span');
+      Object.assign(change.style, { color: '#8AB4F8', cursor: 'pointer', flexShrink: '0', textDecoration: 'underline' });
+      change.textContent = 'Change';
+      var reset = document.createElement('span');
+      Object.assign(reset.style, { color: '#B9BBC2', cursor: 'pointer', flexShrink: '0', textDecoration: 'underline', display: 'none' });
+      reset.textContent = 'Reset';
+      function refresh() {
+        chip.textContent = shortcutLabel(ACTIVATE);
+        chip.style.color = '#E0A3F5';
+        change.style.display = 'inline';
+        reset.style.display = activateOverridden() ? 'inline' : 'none';
+      }
+      change.addEventListener('click', function (e) {
+        e.stopPropagation();
+        change.style.display = 'none';
+        reset.style.display = 'none';
+        startRebind(
+          function (text, color) { chip.textContent = text; chip.style.color = color; },
+          function () { refresh(); }
+        );
+      });
+      reset.addEventListener('click', function (e) { e.stopPropagation(); resetActivate(); refresh(); });
+      refresh();
+      rrow.appendChild(chip); rrow.appendChild(lbl); rrow.appendChild(change); rrow.appendChild(reset);
+      body.appendChild(rrow);
+    })();
     rows.forEach(function (r) {
       var row = document.createElement('div');
-      Object.assign(row.style, { display: 'flex', gap: '8px', marginBottom: '2px' });
+      Object.assign(row.style, { display: 'flex', gap: '8px', marginBottom: '8px' });
       var k = document.createElement('span');
       k.textContent = r[0];
       Object.assign(k.style, { color: '#E0A3F5', fontWeight: '700', minWidth: '78px', flexShrink: '0' });
@@ -1542,20 +1730,48 @@ function getClientScript(options) {
     panelKeys.appendChild(body);
   })();
+  // Footer \u2014 a quiet link out to the GitHub README so first-timers can find the docs.
+  var panelFoot = document.createElement('div');
+  Object.assign(panelFoot.style, {
+    flexShrink: '0', padding: '10px 16px', borderTop: '1px solid rgba(255,255,255,0.08)',
+    display: 'flex', alignItems: 'center',
+  });
+  var docsLink = document.createElement('a');
+  docsLink.href = 'https://github.com/setugk/vite-plugin-specter#readme';
+  docsLink.target = '_blank';
+  docsLink.rel = 'noopener noreferrer';
+  docsLink.textContent = 'Documentation \\u2197'; // \u2197
+  Object.assign(docsLink.style, { fontSize: '11px', fontWeight: '600', color: '#8AB4F8', textDecoration: 'none', cursor: 'pointer' });
+  hoverFx(docsLink, { color: '#fff' }, { color: '#8AB4F8' });
+  docsLink.addEventListener('click', function (e) { e.stopPropagation(); });
+  panelFoot.appendChild(docsLink);
   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.appendChild(panelFoot);
+  mount(panelWrap);
+  // A wheel anywhere over the panel must NEVER scroll the page behind it. Relying on
+  // overscroll-behavior alone still lets trackpad momentum chain into the page at the
+  // list bounds, so we take over: always swallow the event, and drive the list's own
+  // scroll ourselves. (The inline note editor auto-grows instead of scrolling, so the
+  // list is the only scrollable region inside the panel \u2014 nothing else needs the wheel.)
+  var listScrolling = false, listScrollTimer = null;
   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();
+    if (panelList.scrollHeight > panelList.clientHeight && panelList.contains(e.target)) {
+      var dy = e.deltaMode === 1 ? e.deltaY * 16 : (e.deltaMode === 2 ? e.deltaY * panelList.clientHeight : e.deltaY);
+      panelList.scrollTop += dy;
+      // Rows slide under a stationary cursor as the list scrolls, firing mouseenter \u2192
+      // revealSpec \u2192 scrollIntoView, which would drag the PAGE around. Mark the list as
+      // actively scrolling so those hover-reveals are suppressed until scrolling settles.
+      listScrolling = true;
+      clearTimeout(listScrollTimer);
+      listScrollTimer = setTimeout(function () { listScrolling = false; }, 200);
+    }
   }, { passive: false });
   // \u2500\u2500 Auto-sync: mirror the browser's current Specs to the local bridge \u2500\u2500
@@ -1568,7 +1784,7 @@ function getClientScript(options) {
     setPillSync(s);     // control-bar dot
     applyDotState(dot, s); // side-panel dot \u2014 same spinner/green/red
     if (s === 'syncing') { dotLabel.textContent = 'Syncing\u2026'; }
-    else if (s === 'synced') { dotLabel.textContent = specs.length ? (specs.length + (specs.length === 1 ? ' Spec synced' : ' Specs synced')) : 'Synced'; }
+    else if (s === 'synced') { var open = specs.length - resolvedCount(); dotLabel.textContent = open > 0 ? (open + (open === 1 ? ' Spec synced' : ' Specs synced')) : 'Synced'; }
     else { dotLabel.textContent = 'Bridge offline'; }
   }
   function doSync() {
@@ -1615,11 +1831,28 @@ function getClientScript(options) {
       panelList.appendChild(empty);
       return;
     }
+    // Summary of resolved Specs + a one-click sweep, pinned above the list.
+    var rc = resolvedCount();
+    if (rc > 0) {
+      var doneBar = document.createElement('div');
+      Object.assign(doneBar.style, { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '8px', padding: '8px 16px', borderBottom: '1px solid rgba(255,255,255,0.06)' });
+      var dlbl = document.createElement('span');
+      dlbl.textContent = '\u2713 ' + rc + (rc === 1 ? ' done' : ' done');
+      Object.assign(dlbl.style, { fontSize: '11px', color: GREEN, fontWeight: '700', letterSpacing: '0.04em', textTransform: 'uppercase' });
+      var clr = document.createElement('span');
+      clr.textContent = 'Clear done';
+      Object.assign(clr.style, { fontSize: '11px', color: '#B9BBC2', cursor: 'pointer', textDecoration: 'underline' });
+      clr.addEventListener('click', function (e) { e.stopPropagation(); clearResolved(); });
+      hoverFx(clr, { color: '#fff' }, { color: '#B9BBC2' });
+      doneBar.appendChild(dlbl); doneBar.appendChild(clr);
+      panelList.appendChild(doneBar);
+    }
     var focusEditor = null, measures = [];
     specs.forEach(function (spec, i) {
       var missing = !!spec.missing;
       var visible = missing ? false : specVisible(spec); // don't specVisible() a missing spec \u2014 it would re-anchor via path
       var editing = (panelEditSpec === spec);
+      var resolved = !!spec.resolved;
       var row = document.createElement('div');
       Object.assign(row.style, {
         position: 'relative', display: 'flex', alignItems: 'flex-start', gap: '12px', boxSizing: 'border-box',
@@ -1630,7 +1863,7 @@ function getClientScript(options) {
       badge.textContent = String(i + 1);
       Object.assign(badge.style, {
         flexShrink: '0', width: '20px', height: '20px', borderRadius: '999px',
-        background: BADGE_IDLE, color: '#fff', fontSize: '11px', fontWeight: '700',
+        background: resolved ? GREEN : 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',
@@ -1702,6 +1935,7 @@ function getClientScript(options) {
           cursor: spec.note ? 'pointer' : 'default',
         });
         note.textContent = spec.note || (spec.kind === 'measure' ? '\u2B21 measurement' : '\u2014 no note \u2014');
+        if (resolved) { note.style.textDecoration = 'line-through'; note.style.color = LABEL; note.style.cursor = spec.note ? 'pointer' : 'default'; }
         // Floated into the top-right corner so they don't reserve note width. On hover
         // they get a background that fades in from the left, masking the note text behind
@@ -1720,11 +1954,14 @@ function getClientScript(options) {
         // Show an expand toggle only when the collapsed note actually overflows.
         var chev = mkIcon(CHEV, expanded ? 'Collapse' : 'Expand', '#B9BBC2', function () { spec._expanded = !spec._expanded; renderPanel(); });
         chev.firstChild.style.transform = expanded ? 'rotate(180deg)' : 'rotate(0deg)';
+        var resolveBtn = mkIcon(CHECK, resolved ? 'Mark as not done' : 'Mark as done', resolved ? GREEN : '#9BE6B0', function () { toggleResolved(spec); }, { background: 'rgba(34,197,94,0.28)', color: '#fff' });
         var editBtn = mkIcon(PENCIL, 'Edit note', '#B9BBC2', function () { panelEditSpec = spec; spec._expanded = true; renderPanel(); });
         var delBtn = mkIcon(TRASH, 'Delete Spec', '#ED8FA6', function () { removeSpec(spec); }, { background: 'rgba(237,62,97,0.30)', color: '#fff' });
-        // Edit + delete reveal only on row hover; the expand chevron stays rightmost
-        // and fixed (edit/delete appear to its left, so it never shifts).
-        editBtn.style.display = delBtn.style.display = 'none';
+        // \u2713 / edit / delete all reveal only on row hover (the expand chevron stays rightmost
+        // and fixed). The done state reads from the green badge + strikethrough + "\u2713 DONE",
+        // so the row needs no persistent icon \u2014 it looks like any other list item.
+        editBtn.style.display = delBtn.style.display = resolveBtn.style.display = 'none';
+        actions.appendChild(resolveBtn);
         actions.appendChild(editBtn);
         actions.appendChild(delBtn);
         actions.appendChild(chev);
@@ -1732,9 +1969,27 @@ function getClientScript(options) {
         content.appendChild(note);
         content.appendChild(meta);
+        // Done: a green DONE tag + dimmed row. Supersedes HIDDEN/MISSING \u2014 once a Spec is
+        // resolved you don't care whether its element is currently on screen.
+        if (resolved) {
+          row.style.opacity = '0.6';
+          var rbar = document.createElement('div');
+          Object.assign(rbar.style, { display: 'flex', alignItems: 'center', gap: '5px', marginTop: '2px', flexWrap: 'wrap' });
+          var rcheck = document.createElement('span');
+          rcheck.innerHTML = CHECK;
+          Object.assign(rcheck.style, { display: 'inline-flex', alignItems: 'center', color: GREEN, flexShrink: '0' });
+          if (rcheck.firstChild) { rcheck.firstChild.setAttribute('width', '12'); rcheck.firstChild.setAttribute('height', '12'); }
+          var rtag = document.createElement('span');
+          rtag.textContent = 'DONE';
+          // Text-only status label (no fill/padding/radius) so it doesn't read as a clickable chip.
+          Object.assign(rtag.style, { fontSize: '10px', fontWeight: '700', letterSpacing: '0.08em', textTransform: 'uppercase', color: GREEN, flexShrink: '0' });
+          rbar.appendChild(rcheck);
+          rbar.appendChild(rtag);
+          content.appendChild(rbar);
+        }
         // Shared comment whose target is gone/changed: MISSING (greyed, reason shown,
         // never drawn on the page \u2014 design: show missing, don't guess a spot).
-        if (missing) {
+        else if (missing) {
           row.style.opacity = '0.7';
           var mbar = document.createElement('div');
           Object.assign(mbar.style, { display: 'flex', alignItems: 'center', gap: '7px', marginTop: '2px', flexWrap: 'wrap' });
@@ -1771,15 +2026,15 @@ function getClientScript(options) {
         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';
+          if (!resolved) badge.style.background = PURPLE;
+          editBtn.style.display = delBtn.style.display = resolveBtn.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); }
+          if (visible && !listScrolling) { highlightSpec = spec; revealSpec(spec); } // don't reveal on rows that merely slid under the cursor while scrolling
         });
         row.addEventListener('mouseleave', function () {
           row.style.background = 'transparent';
-          badge.style.background = BADGE_IDLE;
-          editBtn.style.display = delBtn.style.display = 'none';
+          badge.style.background = resolved ? GREEN : BADGE_IDLE;
+          editBtn.style.display = delBtn.style.display = resolveBtn.style.display = 'none';
           actions.style.background = 'transparent';
           if (highlightSpec === spec) highlightSpec = null;
         });
@@ -1806,8 +2061,8 @@ function getClientScript(options) {
     panelVisSig = liveVisSig(); // record what this render reflects, so reflow only re-renders on a real flip
   }
-  function showPanel() { panelOpen = true; renderPanel(); panelWrap.style.transform = 'translateX(0)'; if (BRIDGE) doSync(); }
-  function hidePanel() { panelOpen = false; panelEditSpec = null; panelWrap.style.transform = 'translateX(100%)'; }
+  function showPanel() { panelOpen = true; renderPanel(); panelWrap.style.transform = 'translateX(0)'; updateListBtn(); if (BRIDGE) doSync(); }
+  function hidePanel() { panelOpen = false; panelEditSpec = null; panelWrap.style.transform = 'translateX(100%)'; updateListBtn(); }
   function togglePanel() { if (panelOpen) hidePanel(); else if (fiActive) showPanel(); }
   // \u2500\u2500\u2500 Spec editor (annotation box: add / edit / delete) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -2207,6 +2462,41 @@ function getClientScript(options) {
     return eKey === key || eCode === 'key' + key || (key === 'period' && (eKey === '.' || eCode === 'period'));
   }
+  // Capture the next chord the user presses and make it the new toggle. Runs on the
+  // capture phase + stops propagation so a rebind keystroke (e.g. "L") can't leak into
+  // Specter's own shortcuts. Requires at least one modifier so the toggle can't be a bare
+  // key that fires while you type. onState(text, color) drives the prompt; onDone(committed).
+  var rebinding = false;
+  function startRebind(onState, onDone) {
+    if (rebinding) return;
+    rebinding = true;
+    onState('Press a key combo\u2026', GREEN);
+    function cap(e) {
+      e.preventDefault(); e.stopPropagation();
+      if (e.stopImmediatePropagation) e.stopImmediatePropagation();
+      var k = e.key;
+      if (k === 'Escape') { finish(false); return; }
+      if (k === 'Control' || k === 'Alt' || k === 'Shift' || k === 'Meta') return; // wait for the real key
+      var parts = [];
+      if (e.ctrlKey) parts.push('ctrl');
+      if (e.altKey) parts.push('alt');
+      if (e.shiftKey) parts.push('shift');
+      if (e.metaKey) parts.push('meta');
+      if (!parts.length) { onState('Hold Ctrl / Alt / \\u2318 too\u2026', '#F59E0B'); return; }
+      var key = (e.key.length === 1 ? e.key : e.code.replace(/^Key/, '')).toLowerCase();
+      if (!key) return;
+      parts.push(key);
+      setActivate(parts.join('+'));
+      finish(true);
+    }
+    function finish(committed) {
+      document.removeEventListener('keydown', cap, true);
+      rebinding = false;
+      onDone(committed);
+    }
+    document.addEventListener('keydown', cap, true);
+  }
   // \u2500\u2500\u2500 Mouse \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   function onMouseMove(e) {
     if (!fiActive) return;
@@ -2388,7 +2678,21 @@ function getClientScript(options) {
   importFromHash(); // if arrived via a #spx= share link, import + reveal the shared comments
   scheduleSync();   // mirror restored Specs to the Claude bridge on load
-  console.log('%c\u{1F47B} Specter \u2014 Ctrl+Option+Z to toggle', 'color:#aaa;font-size:11px;');
+  // Dev-only console API \u2014 the escape hatch when the toggle chord collides with a browser
+  // shortcut so you can't even open the overlay. Specter is stripped from prod, so this
+  // global never ships. Vite devs can run these straight from DevTools.
+  try {
+    window.__specter = {
+      toggle: function () { if (fiActive) deactivate(); else activate(); },
+      activate: activate,
+      deactivate: deactivate,
+      get shortcut() { return ACTIVATE; },
+      setShortcut: function (combo) { if (combo) { setActivate(String(combo).toLowerCase()); if (panelOpen) renderPanel(); console.log('%c\u{1F47B} Specter \u2014 toggle is now ' + shortcutLabel(ACTIVATE), 'color:#aaa'); } return ACTIVATE; },
+      resetShortcut: function () { resetActivate(); if (panelOpen) renderPanel(); console.log('%c\u{1F47B} Specter \u2014 toggle reset to ' + shortcutLabel(ACTIVATE), 'color:#aaa'); return ACTIVATE; },
+    };
+  } catch (e) {}
+  console.log('%c\u{1F47B} Specter \u2014 ' + shortcutLabel(ACTIVATE) + ' to toggle \xB7 change it: window.__specter.setShortcut("ctrl+alt+p")', 'color:#aaa;font-size:11px;');
 })();`;
 }