npm - vite-plugin-specter - Versions diffs - 0.6.1 → 0.7.1 - Mend

vite-plugin-specter 0.6.1 → 0.7.1

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 (10) hide show

package/README.md +13 -0
package/dist/client.js +457 -55
package/dist/extension-chrome/content.js +457 -55
package/dist/extension-chrome/manifest.json +1 -1
package/dist/extension-firefox/content.js +457 -55
package/dist/extension-firefox/manifest.json +1 -1
package/dist/index.cjs +457 -55
package/dist/index.js +457 -55
package/extension/content.js +457 -55
package/package.json +1 -1

package/dist/extension-firefox/content.js CHANGED Viewed

@@ -23,6 +23,8 @@
   var CHEV = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg>';
   var COPY = '<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg>';
   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 = "ctrl+alt+z";
   var BRIDGE = ""; // Claude MCP bridge URL, or '' if disabled
@@ -63,6 +65,45 @@
   function markUI(el) { el.setAttribute('data-specter-ui', ''); return el; }
   function isUI(el) { return !!(el && el.closest && el.closest('[data-specter-ui]')); }
+  // ─── Hydration-proof mounting ───────────────────────────────────────────────
+  // 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 — 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 — 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) {
@@ -89,7 +130,7 @@
     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');
@@ -101,7 +142,7 @@
     pointerEvents: 'none',
     display: 'none',
   });
-  document.body.appendChild(measureOverlay);
+  mount(measureOverlay);
   // ─── Pill ─────────────────────────────────────────────────────────────────
   var pillWrap = document.createElement('div');
@@ -177,41 +218,34 @@
   var pillText = document.createElement('span');
   Object.assign(pillText.style, { display: 'none', color: '#f3d9fb' });
+  // Panel toggle — 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 = '✕ 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 = '›';
   chevron.title = 'Move to other side';
@@ -241,16 +275,15 @@
   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.
@@ -302,15 +335,15 @@
   // 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) {
     pill.style.maxWidth = '820px';
     pillText.style.display = 'inline';
     chevron.style.display = 'inline';
-    listBtn.style.display = specs.length > 0 ? 'inline-flex' : 'none';
-    clearBtn.style.display = specs.length > 0 ? 'inline' : 'none';
+    listBtn.style.display = 'inline-flex'; // always reachable — the panel is also where you Import a shared file
+    updateListBtn();
     pillExpanded = true;
     // Just the mode (+ the action buttons when Specs exist). Shortcuts live in the
     // side panel now, so the pill stays short.
@@ -325,14 +358,12 @@
     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();
@@ -458,10 +489,13 @@
     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) {
@@ -541,13 +575,13 @@
     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 ? '…' : '') + '"';
     var cls = ownClass(el);
-    if (cls) return '.' + cls;
+    if (cls) return '.' + cssEsc(cls);
     return getSelector(el); // fallback: the CSS path
   }
@@ -721,11 +755,20 @@
   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 — 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;
     }
@@ -794,19 +837,36 @@
     var mx = lastMouse.x, my = lastMouse.y;
     var hoverBadge = fiActive ? badgeUnderCursor(mx, my) : null;
-    // Pass 1 — resolve visibility + base anchor for each spec.
+    // Pass 1 — resolve visibility + base anchor for each spec. _liveVis tracks the
+    // panel's HIDDEN semantics (isVisible after re-anchor recovery, IGNORING occlusion —
+    // off-screen is fine, that's what the hover-scroll is for) so the panel can stay in
+    // sync with what's actually on the page instead of showing a stale HIDDEN.
     var vis = [];
     for (var i = 0; i < specs.length; i++) {
       var s = specs[i];
-      if (!fiActive) { s.wrap.style.display = 'none'; continue; }
+      // 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; }
-      if (!isVisible(s.el)) { s.wrap.style.display = 'none'; continue; }
+      if (!isVisible(s.el)) { s.wrap.style.display = 'none'; s._liveVis = false; continue; }
+      s._liveVis = true;
       var r = s.el.getBoundingClientRect();
-      if (isOccluded(s.el, r)) { s.wrap.style.display = 'none'; continue; } // covered (e.g. behind a modal)
+      if (isOccluded(s.el, r)) { s.wrap.style.display = 'none'; continue; } // covered / off-screen: no badge, but panel not HIDDEN
       s._bx = r.left - 10; s._by = r.top - 10; // -4 circle offset, -6 wrap padding
       vis.push(s);
     }
+    // Keep the open panel's HIDDEN labels live: if any spec's on-page visibility
+    // flipped since the panel last rendered, re-render it (debounced).
+    if (panelOpen) {
+      var g = liveVisSig();
+      if (g !== panelVisSig) { panelVisSig = g; clearTimeout(panelVisTimer); panelVisTimer = setTimeout(function () { if (panelOpen) renderPanel(); }, 150); }
+    }
     // Pass 2 — cluster badges whose anchors coincide (within ~16px).
     var clusters = [];
     for (var a = 0; a < vis.length; a++) {
@@ -988,13 +1048,23 @@
     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); }
+    }
+  }
   // ─── Reload insurance (localStorage, per-URL, zero network) ──────────────────
   // 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 }; })));
+      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 }; })));
     } catch (e) {}
     scheduleSync(); // keep the Claude bridge mirrored to the current Specs
   }
@@ -1004,13 +1074,279 @@
     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: safeQuery(d.path), path: d.path, note: d.note || '', body: d.body || '', kind: d.kind || 'element', locate: d.locate || '' };
+      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 || '' };
       specs.push(spec);
       createBadge(spec);
     });
     renumber();
   }
+  // ─── Share Comments (human↔human) — Steps 1-2 ────────────────────────────────
+  // A shared comment is a LOCATOR, not a coordinate: on import we re-find the
+  // element and place a badge, exactly like restoreSpecs. Comments only — we carry
+  // the note + how to re-find the element, NEVER the props/measurements (body).
+  // Step 2 adds change-detection: a fingerprint travels with each comment; if the
+  // 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 — 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" — placement is favoured over change-detection.)
+  function normSig(el) {
+    if (!el || el.nodeType !== 1) return '';
+    var cls = Array.prototype.slice.call(el.classList)
+      .filter(function (c) { return c.indexOf('__specter') !== 0; }).sort().join('.');
+    var attrs = ['type', 'role', 'name', 'href', 'aria-label'].map(function (a) {
+      var v = el.getAttribute(a); return v ? a + '=' + v.trim() : '';
+    }).filter(Boolean).join('|');
+    return el.tagName.toLowerCase() + '#' + cls + '#' + attrs + '#' + el.childElementCount;
+  }
+  // djb2 xor → 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).
+  function fingerprint(el) {
+    var s = normSig(el);
+    if (!s) return '';
+    var h = 5381, i = s.length;
+    while (i) h = (h * 33) ^ s.charCodeAt(--i);
+    return (h >>> 0).toString(36);
+  }
+  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 — 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)) out.push(el);
+    }
+    return out;
+  }
+  // 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) — 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 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) === '…') { trunc = true; val = val.slice(0, -1); }
+      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 — 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 — 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 → 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 hit;
+  }
+  function reFindShared(item) {
+    var cands = resolveFindCandidates(item.find).concat(queryAll(item.path));
+    var uniq = [], i;
+    for (i = 0; i < cands.length; i++) if (cands[i] && uniq.indexOf(cands[i]) < 0) uniq.push(cands[i]);
+    if (item.fp) {
+      for (i = 0; i < uniq.length; i++) if (fingerprint(uniq[i]) === item.fp) return uniq[i]; // fp picks the right candidate
+      var scan = findByFingerprint(item.fp);       // selectors failed/ambiguous → find it by signature
+      if (scan) return scan;
+    }
+    return uniq.length === 1 ? uniq[0] : null;      // last resort: a lone unambiguous candidate
+  }
+  // URL gate: two people must be on the SAME page for a shared comment to place.
+  // Match by origin + pathname only — hash AND query are dropped (the hash is the
+  // doSync fork bug; a trailing #route or ?ref shouldn't split the same page).
+  function pageKey(href) {
+    try { var u = new URL(href || location.href); return u.origin + u.pathname; }
+    catch (e) { return location.origin + location.pathname; }
+  }
+  function exportComments() {
+    return {
+      url: location.href, // gated on pageKey() at import; full href kept for reference
+      comments: specs.map(function (s) {
+        return { find: resolveLocator(s.el), path: s.path, fp: fingerprint(s.el), note: s.note || '', kind: s.kind || 'element' };
+      }),
+    };
+  }
+  function importComments(payload) {
+    if (typeof payload === 'string') { try { payload = JSON.parse(payload); } catch (e) { return 0; } }
+    var comments = null, srcUrl = '';
+    if (Array.isArray(payload)) comments = payload; // legacy pre-URL blob: no gate
+    else if (payload && Array.isArray(payload.comments)) { comments = payload.comments; srcUrl = payload.url || ''; }
+    if (!comments) return 0;
+    // Wrong page → decline rather than anchor onto whatever happens to match here.
+    if (srcUrl && pageKey(srcUrl) !== pageKey()) {
+      console.warn('[Specter] These comments are for ' + pageKey(srcUrl) + ' — 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 — 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’t find this element on the page'; }
+      // 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 };
+      specs.push(spec);
+      createBadge(spec);
+      added++;
+    });
+    renumber();
+    reflowSpecs();
+    updatePill();
+    if (panelOpen) renderPanel();
+    saveSpecs();
+    return added;
+  }
+  // ── Transport: share link (#spx=) with a file fallback ──────────────────────
+  // The link is destination AND payload — pasted into Slack it looks like a normal
+  // URL; clicked, it lands the recipient on the exact page, so the URL gate is
+  // satisfied automatically. Payload = <fmt><base64url>: fmt 'z' = gzip (Compression
+  // Stream, zero-dep), 'j' = plain UTF-8 when gzip is unavailable. split/join dodges
+  // regex escaping inside this template-literal client.
+  var LINK_MAX = 8000; // ~URL ceiling; beyond this we offer a .specter.json file
+  function bytesToB64url(bytes) {
+    var bin = '';
+    for (var i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+    var b = btoa(bin).split('+').join('-').split('/').join('_');
+    while (b.charAt(b.length - 1) === '=') b = b.slice(0, -1);
+    return b;
+  }
+  function b64urlToBytes(s) {
+    s = s.split('-').join('+').split('_').join('/');
+    while (s.length % 4) s += '=';
+    var bin = atob(s), bytes = new Uint8Array(bin.length);
+    for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes;
+  }
+  function gzipStr(str) {
+    var s = new Blob([str]).stream().pipeThrough(new CompressionStream('gzip'));
+    return new Response(s).arrayBuffer().then(function (buf) { return new Uint8Array(buf); });
+  }
+  function gunzipBytes(bytes) {
+    var s = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip'));
+    return new Response(s).text();
+  }
+  function encodePayload(str) {
+    if (typeof CompressionStream !== 'undefined') {
+      return gzipStr(str).then(function (gz) { return 'z' + bytesToB64url(gz); })
+        .catch(function () { return 'j' + bytesToB64url(new TextEncoder().encode(str)); });
+    }
+    return Promise.resolve('j' + bytesToB64url(new TextEncoder().encode(str)));
+  }
+  function decodePayload(s) {
+    var fmt = s.charAt(0);
+    if (fmt === 'z') return gunzipBytes(b64urlToBytes(s.slice(1)));
+    if (fmt === 'j') return Promise.resolve(new TextDecoder().decode(b64urlToBytes(s.slice(1))));
+    // legacy (no fmt prefix): raw base64url of the JSON string
+    return Promise.resolve(new TextDecoder().decode(b64urlToBytes(s)));
+  }
+  // Build on the current page (keep query, replace any existing hash).
+  function buildShareLink() {
+    return encodePayload(JSON.stringify(exportComments())).then(function (enc) {
+      return location.origin + location.pathname + location.search + '#spx=' + enc;
+    });
+  }
+  // A page that uses hash routing itself would collide with #spx= — treat any
+  // non-trivial existing hash (beyond a bare '#') as in-use and prefer the file.
+  function hashInUse() { return (location.hash || '').length > 1; }
+  // Download the comments as a .specter.json (the fallback when the link is too big
+  // or the page owns the hash). Same {url, comments} payload → same URL gate on import.
+  function downloadCommentsFile() {
+    var data = JSON.stringify(exportComments(), null, 2);
+    var url = URL.createObjectURL(new Blob([data], { type: 'application/json' }));
+    var a = document.createElement('a');
+    a.href = url; a.download = 'comments.specter.json';
+    document.body.appendChild(a); a.click(); a.remove();
+    setTimeout(function () { URL.revokeObjectURL(url); }, 1000);
+  }
+  // One coherent share action: a link by default, a file when it can't fit (or the
+  // page owns the hash). Returns a descriptor so the caller/UI can tell the user which.
+  function shareComments() {
+    if (!specs.length) return Promise.resolve({ kind: 'empty' });
+    if (hashInUse()) { downloadCommentsFile(); return Promise.resolve({ kind: 'file', reason: 'hash-routing' }); }
+    return buildShareLink().then(function (link) {
+      if (link.length > LINK_MAX) { downloadCommentsFile(); return { kind: 'file', reason: 'too-large', size: link.length }; }
+      return { kind: 'link', link: link };
+    });
+  }
+  // Pick a .specter.json (or any JSON) and import it — the file-fallback receiver.
+  function importCommentsFile() {
+    var input = document.createElement('input');
+    input.type = 'file';
+    input.accept = '.json,application/json';
+    input.addEventListener('change', function () {
+      var f = input.files && input.files[0];
+      if (!f) return;
+      var reader = new FileReader();
+      reader.onload = function () { var n = importComments(String(reader.result)); if (n > 0) { if (!fiActive) activate(); showPanel(); } };
+      reader.readAsText(f);
+    });
+    input.click();
+  }
+  // On load: if the URL carries #spx=, decode it, strip it from the address bar (so
+  // the URL goes clean and a plain reload won't re-import), import, and surface it.
+  function importFromHash() {
+    var h = location.hash || '', k = h.indexOf('spx=');
+    if (k < 0) return Promise.resolve(0);
+    var enc = h.slice(k + 4);
+    try { history.replaceState(null, '', location.pathname + location.search); } catch (e) {}
+    return decodePayload(enc).then(function (json) {
+      var n = importComments(json);
+      if (n > 0) { if (!fiActive) activate(); showPanel(); }
+      return n;
+    }).catch(function () { return 0; });
+  }
   // Re-anchor if the node detached, then scroll it into view. Returns false when
   // the element can't be shown (removed / hidden — e.g. behind a closed modal).
   // The badge enlargement is handled separately via highlightSpec (sustained
@@ -1030,6 +1366,11 @@
     return isVisible(spec.el);
   }
+  // Signature of on-page visibility across specs (from reflowSpecs' per-frame _liveVis),
+  // used to detect when the panel's HIDDEN labels have gone stale and re-render.
+  var panelVisSig = '', panelVisTimer = null;
+  function liveVisSig() { var s = ''; for (var i = 0; i < specs.length; i++) s += specs[i]._liveVis ? '1' : '0'; return s; }
   // ─── Specs side panel (in-session review) ────────────────────────────────────
   var panelWrap = markUI(document.createElement('div'));
   Object.assign(panelWrap.style, {
@@ -1117,10 +1458,40 @@
   var delAll = iconPill(TRASH, 'Delete all annotations', '#ED8FA6', '237,62,97');
   delAll.btn.addEventListener('click', function (e) { e.stopPropagation(); confirmDeleteAll(delAll.btn); });
+  // Share comments (human↔human): copies a link, or downloads a file when it can't
+  // fit / the page owns the hash. The hint line confirms which happened.
+  var share = iconPill(SHARE, 'Share comments to another person', '#8AB4F8', '138,180,248');
+  function resetShareIcon() { share.icon.innerHTML = SHARE; share.btn.style.color = share.btn.matches(':hover') ? '#fff' : '#8AB4F8'; }
+  share.btn.addEventListener('click', function (e) {
+    e.stopPropagation();
+    if (!specs.length) return;
+    shareComments().then(function (res) {
+      if (res.kind === 'link') {
+        navigator.clipboard.writeText(res.link).then(function () {
+          share.icon.innerHTML = CHECK; share.btn.style.color = GREEN;
+          flashHint('✓ Link copied — paste it to your reviewer. They see your comments on the same page.', GREEN);
+          setTimeout(resetShareIcon, 1400);
+        }).catch(function () { flashHint('Copy failed — check clipboard permission for this site.', '#ED8FA6'); });
+      } else if (res.kind === 'file') {
+        share.icon.innerHTML = CHECK; share.btn.style.color = GREEN;
+        flashHint('✓ Saved comments.specter.json — send that file (too many comments to fit a link).', GREEN);
+        setTimeout(resetShareIcon, 1400);
+      }
+    });
+  });
+  // Import a comments file someone sent (the file-fallback receiver).
+  var importTool = iconPill(IMPORT, 'Import a comments file', '#8AB4F8', '138,180,248');
+  importTool.btn.addEventListener('click', function (e) { e.stopPropagation(); importCommentsFile(); });
   var copyAllBtn = copyAll.btn; // renderPanel toggles these by spec count
   var deleteAllBtn = delAll.btn;
+  var shareBtn = share.btn;
+  var importToolBtn = importTool.btn;
   if (BRIDGE) panelTools.appendChild(syncDot);
   else { var sp = document.createElement('span'); sp.style.flex = '1'; panelTools.appendChild(sp); }
+  panelTools.appendChild(shareBtn);
+  panelTools.appendChild(importToolBtn);
   panelTools.appendChild(copyAllBtn);
   panelTools.appendChild(deleteAllBtn);
@@ -1188,6 +1559,16 @@
       panelHint.appendChild(document.createTextNode(' (or Copy all) and paste into Claude to apply these annotations. You can also edit or delete each one above.'));
     }
   }
+  // Briefly show a confirmation in the hint line (Share copied / file saved), then
+  // restore the normal guidance.
+  var hintFlashTimer = null;
+  function flashHint(msg, color) {
+    panelHint.style.display = 'block';
+    panelHint.textContent = msg;
+    panelHint.style.color = color || GREEN;
+    if (hintFlashTimer) clearTimeout(hintFlashTimer);
+    hintFlashTimer = setTimeout(function () { panelHint.style.color = LABEL; setHint(); }, 2800);
+  }
   var panelList = document.createElement('div');
   // overscroll-behavior:contain stops the panel's scroll from chaining into the page.
@@ -1222,7 +1603,7 @@
     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' });
+      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' });
@@ -1247,7 +1628,7 @@
   panelWrap.appendChild(panelHint);
   panelWrap.appendChild(panelList);
   panelWrap.appendChild(panelKeys);
-  document.body.appendChild(panelWrap);
+  mount(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);
@@ -1301,21 +1682,24 @@
   function renderPanel() {
     panelTitle.textContent = specs.length + (specs.length === 1 ? ' Spec' : ' Specs');
-    panelTools.style.display = (specs.length || BRIDGE) ? 'flex' : 'none';
+    panelTools.style.display = 'flex'; // always visible when the panel is open (Import needs no Specs)
+    shareBtn.style.display = specs.length ? 'inline-flex' : 'none';
     copyAllBtn.style.display = specs.length ? 'inline-flex' : 'none';
     deleteAllBtn.style.display = specs.length ? 'inline-flex' : 'none';
+    importToolBtn.style.display = 'inline-flex'; // receiving a shared file needs no existing Specs
     setHint();
     panelList.textContent = '';
     if (!specs.length) {
       var empty = document.createElement('div');
-      empty.textContent = 'No Specs yet — hover an element and press P.';
+      empty.textContent = 'No comments yet — hover an element and press P, or use the Import button above to open a comments file someone shared.';
       Object.assign(empty.style, { padding: '24px 16px', fontSize: '12px', lineHeight: '18px', color: LABEL });
       panelList.appendChild(empty);
       return;
     }
     var focusEditor = null, measures = [];
     specs.forEach(function (spec, i) {
-      var visible = specVisible(spec);
+      var missing = !!spec.missing;
+      var visible = missing ? false : specVisible(spec); // don't specVisible() a missing spec — it would re-anchor via path
       var editing = (panelEditSpec === spec);
       var row = document.createElement('div');
       Object.assign(row.style, {
@@ -1429,9 +1813,25 @@
         content.appendChild(note);
         content.appendChild(meta);
+        // Shared comment whose target is gone/changed: MISSING (greyed, reason shown,
+        // never drawn on the page — design: show missing, don't guess a spot).
+        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' });
+          var mtag = document.createElement('span');
+          mtag.textContent = 'MISSING';
+          Object.assign(mtag.style, { fontSize: '11px', fontWeight: '700', letterSpacing: '0.05em', color: '#fff', background: '#8B4A57', borderRadius: '4px', padding: '2px 6px', flexShrink: '0' });
+          var mhint = document.createElement('span');
+          mhint.textContent = spec.missReason || 'Not on this page';
+          Object.assign(mhint.style, { fontSize: '11px', color: '#C9CBD2', overflow: 'hidden', textOverflow: 'ellipsis' });
+          mbar.appendChild(mtag);
+          mbar.appendChild(mhint);
+          content.appendChild(mbar);
+        }
         // Hidden element (e.g. inside a closed modal): flag it and say how to reveal it,
         // so hidden Specs are findable in a long list instead of silently unreachable.
-        if (!visible) {
+        else if (!visible) {
           var hbar = document.createElement('div');
           Object.assign(hbar.style, { display: 'flex', alignItems: 'center', gap: '7px', marginTop: '2px', flexWrap: 'wrap' });
           var tag = document.createElement('span');
@@ -1484,10 +1884,11 @@
       }
     });
     if (focusEditor) setTimeout(focusEditor, 0);
+    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(); }
   // ─── Spec editor (annotation box: add / edit / delete) ───────────────────────
@@ -2064,8 +2465,9 @@
     });
   }
-  restoreSpecs(); // rebuild any Specs saved from a previous load of this URL
-  scheduleSync(); // mirror restored Specs to the Claude bridge on load
+  restoreSpecs();   // rebuild any Specs saved from a previous load of this URL
+  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👻 Specter — Ctrl+Option+Z to toggle', 'color:#aaa;font-size:11px;');
 })();