tux-review 0.1.1 → 0.1.3

package/client/tux-review.js

@@ -131,27 +131,69 @@
   }
   function locate(target) {
     if (!target) return null;
-    if (target.tux_id) {
-      const el = document.querySelector(`[data-tux-id="${cssEscape(target.tux_id)}"]`);
-      if (el) return el;
+    // Fingerprint validation: when a resolution strategy yields several
+    // candidates (nth-child paths drift after DOM changes), pick the one
+    // that best matches the stored fingerprint — component/instance scope,
+    // captured text, role. Score 0 keeps the first candidate (SPC 16).
+    function scoreCandidate(el) {
+      let score = 0;
+      if (target.component && el.closest(`[data-tux-component="${cssEscape(target.component)}"]`)) score += 4;
+      if (target.component_instance && el.closest(`[data-tux-instance="${cssEscape(target.component_instance)}"]`)) score += 3;
+      if (target.text) {
+        const t = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 80);
+        if (t === target.text) score += 2;
+        else if (target.text.length > 12 && t.includes(target.text.slice(0, 40))) score += 1;
+      }
+      if (target.role && el.getAttribute('role') === target.role) score += 1;
+      return score;
     }
-    if (target.test_id) {
-      const el = document.querySelector(`[data-testid="${cssEscape(target.test_id)}"], [data-test-id="${cssEscape(target.test_id)}"]`);
-      if (el) return el;
+    function pickBest(nodes) {
+      let best = null, bestScore = -1;
+      for (const n of nodes) {
+        const s = scoreCandidate(n);
+        if (s > bestScore) { bestScore = s; best = n; }
+      }
+      return best;
     }
-    if (target.css_selector) {
-      try {
-        const el = document.querySelector(target.css_selector);
-        if (el) return el;
-      } catch (e) { /* invalid selector */ }
+    function resolveByPath() {
+      if (target.css_selector) {
+        try {
+          const nodes = document.querySelectorAll(target.css_selector);
+          if (nodes.length) return pickBest(nodes);
+        } catch (e) { /* invalid selector */ }
+      }
+      if (target.dom_path) {
+        try {
+          const snapshot = document.evaluate(target.dom_path, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+          if (snapshot.snapshotLength) {
+            const nodes = [];
+            for (let i = 0; i < snapshot.snapshotLength; i++) nodes.push(snapshot.snapshotItem(i));
+            return pickBest(nodes);
+          }
+        } catch (e) { /* invalid path */ }
+      }
+      return null;
     }
-    if (target.dom_path) {
-      try {
-        const el = document.evaluate(target.dom_path, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
-        if (el) return el;
-      } catch (e) { /* invalid path */ }
+
+    const byTest = target.test_id
+      ? document.querySelector(`[data-testid="${cssEscape(target.test_id)}"], [data-test-id="${cssEscape(target.test_id)}"]`)
+      : null;
+    if (byTest) return byTest; // explicit test hook: exact element (SPC 16)
+
+    const byPath = resolveByPath();
+    const byId = target.tux_id
+      ? document.querySelector(`[data-tux-id="${cssEscape(target.tux_id)}"]`)
+      : null;
+
+    // A tux_id on a CONTAINER must not coarsen the target: when the path
+    // resolves to an element inside the id element, the path is the finer,
+    // correct target. Only trust the id over a path that drifted outside
+    // of it (SPC 16: multiple independent signals, finest wins).
+    if (byId) {
+      if (byPath && (byId === byPath || byId.contains(byPath))) return byPath;
+      return byId;
     }
-    return null;
+    return byPath;
   }
 
   // ─── route + state tracking (SPC 13–15, 59) ───
@@ -333,20 +375,22 @@
   function clearHover() {
     if (hoverEl) { hoverEl.classList.remove('tux-hover'); hoverEl = null; }
   }
-  // TUX's own chrome (overlay root, editor, markers) is never reviewable —
-  // independent of any user-set [data-tux-ui] scope markers (SPC 16, 66).
+  // TUX's own chrome (overlay root, float, sidebar, layer, toast, editor,
+  // markers) is never reviewable — independent of any user-set [data-tux-ui]
+  // scope markers (SPC 16, 66). The attribute selectors also match while the
+  // float/sidebar/toast reparent into a dialog's top layer.
+  const TUX_CHROME = '#tux-root, [data-tux-float], [data-tux-sidebar], [data-tux-toast], [data-tux-layer], .tux-editor, .tux-marker';
   function inChrome(el) {
-    if (el.closest && el.closest('.tux-editor,.tux-marker,.tux-toast')) return true;
-    const r = root();
-    return !!(r && (r === el || r.contains(el)));
+    return !!(el.closest && el.closest(TUX_CHROME));
   }
-  // [data-tux-ui] marks reviewable scopes. With no scope on the page the
-  // whole document is reviewable; with scopes, only inside them.
+  // [data-tux-ui] marks reviewable scopes. With no user-set scope on the
+  // page the whole document is reviewable; with scopes, only inside them.
+  // TUX's own chrome never counts as a scope — it carries data-tux-ui too
+  // and would otherwise make every page element unreachable (SPC 16, 66).
   function inScope(el) {
-    const scopes = document.querySelectorAll('[data-tux-ui]');
+    const scopes = [...document.querySelectorAll('[data-tux-ui]')].filter((s) => !inChrome(s));
     if (!scopes.length) return true;
-    for (const s of scopes) if (s.contains(el)) return true;
-    return false;
+    return scopes.some((s) => s.contains(el));
   }
   function onMouseOver(e) {
     if (!mode) return;
@@ -489,23 +533,15 @@
   function renderMarkers() {
     const layer = root().querySelector('[data-tux-layer]');
     layer.querySelectorAll('.tux-marker').forEach((m) => m.remove());
-    document.querySelectorAll('dialog[open] > .tux-marker, [role="dialog"] > .tux-marker').forEach((m) => m.remove());
+    document.querySelectorAll('dialog .tux-marker, [role="dialog"] .tux-marker').forEach((m) => m.remove());
+    pinRegistry = [];
     for (const item of items) {
       const target = locate(item.target);
       if (!target) continue; // target temporarily gone; feedback stays persisted (SPC 60)
       const host = overlayHostFor(target);
       const inTopLayer = host !== layer;
-      const rect = target.getBoundingClientRect();
       const pin = el('button', 'tux-marker', String(item.feedback.type[0].toUpperCase()));
       pin.dataset.id = item.id;
-      if (inTopLayer) {
-        pin.style.position = 'fixed';
-        pin.style.left = `${rect.left + rect.width - 12}px`;
-        pin.style.top = `${Math.max(0, rect.top - 8)}px`;
-      } else {
-        pin.style.left = `${rect.left + window.scrollX + rect.width - 12}px`;
-        pin.style.top = `${rect.top + window.scrollY - 8}px`;
-      }
       pin.classList.toggle('tux-resolved', item.status !== 'open');
       pin.title = `${item.feedback.type}: ${item.feedback.text}`;
       pin.setAttribute('data-tux-ui', '');
@@ -514,7 +550,61 @@
         openEditor({ el: target, mode: 'edit', item });
       });
       host.appendChild(pin);
+      pinRegistry.push({ target, pin, inTopLayer, lastKey: '' });
     }
+    positionPins();
+    bindReposition();
+  }
+
+  // Markers are anchored to the element's CURRENT rect — never to
+  // coordinates captured at creation time. positionPins() runs on
+  // resize/scroll/DOM mutations (rAF-throttled) so markers follow layout
+  // changes: splitter drag, carousel transforms, dialogs opening and
+  // closing, route-level reflows. Invisible targets hide their pin and
+  // reveal it again when the element becomes visible (SPC 60).
+  let pinRegistry = [];
+  function positionPins() {
+    for (const entry of pinRegistry) {
+      const { pin, target, inTopLayer } = entry;
+      const rects = target.getClientRects();
+      const rect = target.getBoundingClientRect();
+      const visible = rects.length > 0 && rect.width > 0 && rect.height > 0;
+      const key = visible
+        ? `${Math.round(rect.left)},${Math.round(rect.top)},${Math.round(rect.width)}x${Math.round(rect.height)}|${Math.round(window.scrollX)},${Math.round(window.scrollY)}`
+        : 'hidden';
+      if (entry.lastKey === key) continue;
+      entry.lastKey = key;
+      if (!visible) { pin.style.display = 'none'; continue; }
+      pin.style.display = '';
+      if (inTopLayer) {
+        pin.style.position = 'fixed';
+        pin.style.left = `${rect.left + rect.width - 12}px`;
+        pin.style.top = `${Math.max(0, rect.top - 8)}px`;
+      } else {
+        pin.style.left = `${rect.left + window.scrollX + rect.width - 12}px`;
+        pin.style.top = `${rect.top + window.scrollY - 8}px`;
+      }
+    }
+  }
+  let rafPending = false;
+  function scheduleReposition() {
+    if (rafPending) return;
+    rafPending = true;
+    requestAnimationFrame(() => { rafPending = false; positionPins(); });
+  }
+  let repositionBound = false;
+  function bindReposition() {
+    if (repositionBound) return;
+    repositionBound = true;
+    window.addEventListener('resize', scheduleReposition);
+    document.addEventListener('scroll', scheduleReposition, true);
+    const start = () => {
+      new MutationObserver(scheduleReposition).observe(document.documentElement, {
+        childList: true, subtree: true, attributes: true,
+      });
+    };
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start);
+    else start();
   }
 
   async function refresh() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tux-review",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TUX - TUX UIX review system: attach structured, machine-readable feedback directly to running web UIs (pages, routes, components, elements, states) with a deterministic CLI, canonical JSON and LLM-friendly skills.",
   "license": "MIT",
   "author": {