styleproof 3.19.0 → 3.21.0

package/dist/runner.js

@@ -104,7 +104,7 @@ export function resolvePopupCaptureOptions(input) {
     };
 }
 async function popupDomSnapshot(page, options) {
-    return page.evaluate(({ popupSelector, triggerSelector, attr, max = 0 }) => {
+    return page.evaluate(({ popupSelector, triggerSelector, attr, max = 0, relocatePath, relocateLabel }) => {
         const qsa = (sel) => {
             try {
                 return [...document.querySelectorAll(sel)];
@@ -133,6 +133,13 @@ async function popupDomSnapshot(page, options) {
             }
             return parts.join(' > ');
         };
+        // The trigger's accessible name — mirrors crawl-surfaces' labelFor (aria-label
+        // || name || textContent || title). `path` is positional for an id-less trigger;
+        // this pins identity so a shifted same-tag sibling can't silently steal the bind.
+        const labelOf = (el) => (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || el.getAttribute('title') || '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 80) || el.tagName.toLowerCase();
         const popupKey = (el) => {
             const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 120);
             return [
@@ -150,7 +157,15 @@ async function popupDomSnapshot(page, options) {
         const popups = qsa(popupSelector).filter(visible);
         const keys = popups.map(popupKey);
         if (!triggerSelector || !attr)
-            return { keys, indexes: [] };
+            return { keys, candidates: [], found: false };
+        for (const el of qsa(`[${attr}]`))
+            el.removeAttribute(attr);
+        if (relocatePath) {
+            const target = qsa(triggerSelector).find((el) => pathOf(el) === relocatePath && labelOf(el) === relocateLabel);
+            if (target)
+                target.setAttribute(attr, 'target');
+            return { keys, candidates: [], found: Boolean(target) };
+        }
         const safeTrigger = (el) => {
             const tag = el.tagName.toLowerCase();
             if (el.matches(':disabled, [aria-disabled="true"]'))
@@ -161,24 +176,30 @@ async function popupDomSnapshot(page, options) {
                 return el.getAttribute('href')?.startsWith('#') ?? false;
             return true;
         };
-        for (const el of qsa(`[${attr}]`))
-            el.removeAttribute(attr);
-        const candidates = qsa(triggerSelector).filter((el) => visible(el) && !popups.some((popup) => popup !== el && popup.contains(el)) && safeTrigger(el));
-        candidates.slice(0, max).forEach((el, index) => el.setAttribute(attr, String(index)));
-        return { keys, indexes: candidates.slice(0, max).map((_, index) => index) };
+        const candidates = qsa(triggerSelector)
+            .filter((el) => visible(el) && !popups.some((popup) => popup !== el && popup.contains(el)) && safeTrigger(el))
+            .slice(0, max);
+        candidates.forEach((el, index) => el.setAttribute(attr, String(index)));
+        return {
+            keys,
+            candidates: candidates.map((el, index) => ({ index, path: pathOf(el), label: labelOf(el) })),
+            found: false,
+        };
     }, options);
 }
 async function visiblePopupKeys(page, selector) {
     return (await popupDomSnapshot(page, { popupSelector: selector })).keys;
 }
+/** Enumerate + mark the surface's popup triggers ONCE, and record the pristine
+ *  overlay keys in the same DOM snapshot — the reset baseline every reopen is
+ *  verified against. */
 async function markPopupCandidates(page, options) {
-    const snapshot = await popupDomSnapshot(page, {
+    return popupDomSnapshot(page, {
         triggerSelector: options.triggers,
         popupSelector: options.overlays,
         attr: POPUP_TRIGGER_ATTR,
         max: options.max,
     });
-    return snapshot.indexes.map((index) => ({ index }));
 }
 function expandOne(surface, variant, variantKind) {
     return {
@@ -308,16 +329,37 @@ async function assertDeterministic(page, surface, first, captureText, pending) {
         throw new Error(selfCheckErrorMessage(surface.key, drift, [...new Set([...(first.volatile ?? []), ...(again.volatile ?? [])])], liveCandidates));
     }
 }
-async function openPopupCandidate(page, surface, width, height, options, candidate) {
+/**
+ * Reset the surface (Escape + `go()`), then open ONE candidate's popup.
+ *
+ * Two guarantees the naive open loop lacked:
+ * - the reset is VERIFIED against the pristine overlay keys, not assumed —
+ *   Escape is not a universal close, and a non-navigating `go()` clears nothing;
+ * - the trigger is re-bound by the (path, label) identity recorded at first
+ *   enumeration, never by its position in a fresh enumeration (the trigger set can
+ *   shift between opens and silently key the popup under a different trigger; the
+ *   label pins identity where the path alone is still positional for id-less triggers).
+ * Either check failing is reported for the caller to skip loudly.
+ */
+async function openPopupCandidate(page, surface, width, height, options, candidate, pristine) {
     await page.setViewportSize({ width, height });
     await page.keyboard.press('Escape').catch(() => { });
     await surface.go(page);
-    const before = new Set(await visiblePopupKeys(page, options.overlays));
-    const candidates = await markPopupCandidates(page, options);
-    if (!candidates.some((c) => c.index === candidate.index))
-        return undefined;
+    const snapshot = await popupDomSnapshot(page, {
+        popupSelector: options.overlays,
+        triggerSelector: options.triggers,
+        attr: POPUP_TRIGGER_ATTR,
+        relocatePath: candidate.path,
+        relocateLabel: candidate.label,
+    });
+    const leaked = snapshot.keys.filter((key) => !pristine.has(key));
+    if (leaked.length)
+        return { status: 'leaked', leaked };
+    if (!snapshot.found)
+        return { status: 'missing' };
+    const before = new Set(snapshot.keys);
     await page
-        .locator(`[${POPUP_TRIGGER_ATTR}="${candidate.index}"]`)
+        .locator(`[${POPUP_TRIGGER_ATTR}="target"]`)
         .first()
         .click({ timeout: Math.max(500, options.timeoutMs), noWaitAfter: true })
         .catch(() => undefined);
@@ -325,10 +367,19 @@ async function openPopupCandidate(page, surface, width, height, options, candida
     do {
         const opened = (await visiblePopupKeys(page, options.overlays)).find((key) => !before.has(key));
         if (opened)
-            return opened;
+            return { status: 'opened', key: opened };
         await page.waitForTimeout(50);
     } while (Date.now() < deadline);
-    return undefined;
+    return { status: 'none' };
+}
+/** A popup candidate skipped instead of captured wrong must be NAMED — a silent
+ *  skip reads as "nothing to capture" when the truth is "couldn't capture safely". */
+function warnPopupSkipped(surface, popupId, width, reason) {
+    // eslint-disable-next-line no-console
+    console.warn(`styleproof: skipped ${surface.key}-${popupId}@${width} — ${reason}`);
+}
+function leakedOverlaysDesc(leaked) {
+    return `overlay(s) the reset (Escape + go()) could not clear: ${leaked.join('; ')}`;
 }
 function popupMetadata(surface, popupId) {
     return {
@@ -346,26 +397,52 @@ async function captureOpenedPopupMap(page, surface, s, pending, popupId) {
         metadata: popupMetadata(surface, popupId),
     });
 }
-async function assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, first, s, pending) {
-    const againKey = await openPopupCandidate(page, surface, width, height, options, candidate);
-    if (!againKey)
-        throw new Error(`styleproof self-check failed: ${surface.key}-${popupId} popup did not reopen`);
+/** Reopen the popup and throw on drift/no-reopen. Returns the leaked overlay keys
+ *  instead when the popup itself defeats the reset (e.g. it IS a toast Escape can't
+ *  dismiss) — the reopen can't run, so the caller discards the capture loudly
+ *  rather than saving a map whose determinism was never proven. */
+async function assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, first, s, pending, pristine) {
+    const reopened = await openPopupCandidate(page, surface, width, height, options, candidate, pristine);
+    if (reopened.status === 'leaked')
+        return reopened.leaked;
+    if (reopened.status !== 'opened') {
+        throw new Error(`styleproof self-check failed: ${surface.key}-${popupId} popup did not reopen` +
+            (reopened.status === 'missing' ? ' (its trigger disappeared from the DOM or changed identity)' : ''));
+    }
     const again = await captureOpenedPopupMap(page, surface, s, pending, popupId);
     const drift = diffStyleMaps(first, again);
     if (drift.length) {
         throw new Error(selfCheckErrorMessage(`${surface.key}-${popupId}`, drift, first.volatile, first.liveCandidates));
     }
+    return undefined;
 }
-async function capturePopupCandidate(page, surface, width, height, s, options, candidate) {
+async function capturePopupCandidate(page, surface, width, height, s, options, candidate, pristine) {
     const requests = trackInflightRequests(page);
+    const popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
     try {
-        const popupKey = await openPopupCandidate(page, surface, width, height, options, candidate);
-        if (!popupKey)
+        const opened = await openPopupCandidate(page, surface, width, height, options, candidate, pristine);
+        if (opened.status === 'none')
             return;
-        const popupId = `popup-${String(candidate.index + 1).padStart(2, '0')}`;
+        if (opened.status === 'leaked') {
+            warnPopupSkipped(surface, popupId, width, `${leakedOverlaysDesc(opened.leaked)} — capturing now would include the previous ` +
+                `popup's residue. Dismiss it in the surface's go(), or capture it as an explicit variant.`);
+            return;
+        }
+        if (opened.status === 'missing') {
+            warnPopupSkipped(surface, popupId, width, `its originally-enumerated trigger is no longer identifiable after the reset (Escape + go()) — ` +
+                `gone from the DOM, or a shifted same-tag sibling no longer matches its recorded label; ` +
+                `skipping rather than re-binding to a different trigger.`);
+            return;
+        }
         const map = await captureOpenedPopupMap(page, surface, s, requests.pending, popupId);
-        if (s.selfCheck)
-            await assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, map, s, requests.pending);
+        if (s.selfCheck) {
+            const leaked = await assertPopupDeterministic(page, surface, width, height, options, candidate, popupId, map, s, requests.pending, pristine);
+            if (leaked) {
+                warnPopupSkipped(surface, popupId, width, `reopening for the self-check found ${leakedOverlaysDesc(leaked)} — the popup itself ` +
+                    `defeats the reset, so its determinism can't be verified and the capture is discarded.`);
+                return;
+            }
+        }
         const stem = path.join(s.baseDir, s.dir, `${surface.key}-${popupId}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots)
@@ -380,9 +457,12 @@ async function capturePopupSurfaces(page, surface, width, height, s) {
     if (!options.enabled || options.max === 0)
         return;
     await surface.go(page);
-    const candidates = await markPopupCandidates(page, options);
+    const { keys, candidates } = await markPopupCandidates(page, options);
+    // Overlays legitimately visible in the surface's settled state (e.g. a permanent
+    // status region) — every reopen is verified back to this baseline before capture.
+    const pristine = new Set(keys);
     for (const candidate of candidates) {
-        await capturePopupCandidate(page, surface, width, height, s, options, candidate);
+        await capturePopupCandidate(page, surface, width, height, s, options, candidate, pristine);
     }
 }
 /** Drive one surface at one width to a settled state and save its style map (+ screenshot).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.19.0",
+  "version": "3.21.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",
@@ -90,6 +90,6 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.18.0",
     "husky": "^9.1.7",
-    "fallow": "^2.96.0"
+    "fallow": "^3.2.0"
   }
 }