vite-plugin-specter 0.6.1 → 0.7.0

package/dist/index.cjs

@@ -55,6 +55,8 @@ function getClientScript(options) {
   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 = ${JSON.stringify(activateShortcut)};
   var BRIDGE = ${JSON.stringify(bridgeUrl)}; // Claude MCP bridge URL, or '' if disabled
 
@@ -341,7 +343,7 @@ function getClientScript(options) {
     pill.style.maxWidth = '820px';
     pillText.style.display = 'inline';
     chevron.style.display = 'inline';
-    listBtn.style.display = specs.length > 0 ? 'inline-flex' : 'none';
+    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';
     pillExpanded = true;
     // Just the mode (+ the action buttons when Specs exist). Shortcuts live in the
@@ -826,19 +828,31 @@ function getClientScript(options) {
     var mx = lastMouse.x, my = lastMouse.y;
     var hoverBadge = fiActive ? badgeUnderCursor(mx, my) : null;
 
-    // Pass 1 \u2014 resolve visibility + base anchor for each spec.
+    // Pass 1 \u2014 resolve visibility + base anchor for each spec. _liveVis tracks the
+    // panel's HIDDEN semantics (isVisible after re-anchor recovery, IGNORING occlusion \u2014
+    // 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; }
+      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 \u2014 cluster badges whose anchors coincide (within ~16px).
     var clusters = [];
     for (var a = 0; a < vis.length; a++) {
@@ -1026,7 +1040,7 @@ function getClientScript(options) {
   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
   }
@@ -1036,11 +1050,247 @@ 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: 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();
+  }
+
+  // \u2500\u2500\u2500 Share Comments (human\u2194human) \u2014 Steps 1-2 \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 shared comment is a LOCATOR, not a coordinate: on import we re-find the
+  // element and place a badge, exactly like restoreSpecs. Comments only \u2014 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 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.
+  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('|');
+    var txt = (el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 50);
+    return el.tagName.toLowerCase() + '#' + cls + '#' + attrs + '#' + txt;
+  }
+  // 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).
+  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);
+  }
+
+  // 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;
+    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; }
+    }
+    return hit;
+  }
+
+  // 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;
+    var c = find.charAt(0);
+    if (c === '#' || c === '.' || c === '[') return uniqueSel(find) ? safeQuery(find) : null;
+    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;
+    }
+    return uniqueSel(find) ? safeQuery(find) : null; // a bare CSS path \u2014 only if unambiguous
+  }
+
+  // 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 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;
+  }
+
+  // URL gate: two people must be on the SAME page for a shared comment to place.
+  // Match by origin + pathname only \u2014 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 \u2192 decline rather than anchor onto whatever happens to match here.
+    if (srcUrl && pageKey(srcUrl) !== pageKey()) {
+      console.warn('[Specter] These comments are for ' + pageKey(srcUrl) + ' \u2014 not this page (' + pageKey() + '). Not imported.');
+      return 0;
+    }
+    var added = 0;
+    comments.forEach(function (item) {
+      if (!item) return;
+      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 };
       specs.push(spec);
       createBadge(spec);
+      added++;
     });
     renumber();
+    reflowSpecs();
+    updatePill();
+    if (panelOpen) renderPanel();
+    saveSpecs();
+    return added;
+  }
+
+  // \u2500\u2500 Transport: share link (#spx=) with a file fallback \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // The link is destination AND payload \u2014 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= \u2014 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 \u2192 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 \u2014 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
@@ -1062,6 +1312,11 @@ function getClientScript(options) {
     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; }
+
   // \u2500\u2500\u2500 Specs side panel (in-session review) \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 panelWrap = markUI(document.createElement('div'));
   Object.assign(panelWrap.style, {
@@ -1149,10 +1404,40 @@ function getClientScript(options) {
   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\u2194human): 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('\u2713 Link copied \u2014 paste it to your reviewer. They see your comments on the same page.', GREEN);
+          setTimeout(resetShareIcon, 1400);
+        }).catch(function () { flashHint('Copy failed \u2014 check clipboard permission for this site.', '#ED8FA6'); });
+      } else if (res.kind === 'file') {
+        share.icon.innerHTML = CHECK; share.btn.style.color = GREEN;
+        flashHint('\u2713 Saved comments.specter.json \u2014 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);
 
@@ -1220,6 +1505,16 @@ function getClientScript(options) {
       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.
@@ -1333,21 +1628,24 @@ function getClientScript(options) {
 
   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 \u2014 hover an element and press P.';
+      empty.textContent = 'No comments yet \u2014 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 \u2014 it would re-anchor via path
       var editing = (panelEditSpec === spec);
       var row = document.createElement('div');
       Object.assign(row.style, {
@@ -1461,9 +1759,25 @@ function getClientScript(options) {
         content.appendChild(note);
         content.appendChild(meta);
 
+        // 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) {
+          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');
@@ -1516,6 +1830,7 @@ function getClientScript(options) {
       }
     });
     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(); }
@@ -2096,8 +2411,9 @@ function getClientScript(options) {
     });
   }
 
-  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\u{1F47B} Specter \u2014 Ctrl+Option+Z to toggle', 'color:#aaa;font-size:11px;');
 })();`;