styleproof 4.0.2 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-07-12
+
+### Fixed
+
+- **Annotated report crops no longer paint path-shifted subtrees as visual
+  changes.** When an unkeyed sibling insertion renumbers `:nth-child()` paths,
+  the report reconciles exact-equivalent entries across paths for annotation
+  only. Genuine additions and removals stay highlighted, while exhaustive
+  structural findings remain in the certification and audit details.
+- **Pull-request captures and reports now stay bound to the real head commit.**
+  GitHub's synthetic merge SHA no longer becomes the map or report provenance,
+  and published report links point to the immutable report commit.
+- **Certify-mode report comments now carry their source head marker**, so stale
+  comments can be distinguished from the current PR head.
+
 ## [4.0.2] - 2026-07-11
 
 ### Fixed

package/README.md

@@ -217,6 +217,12 @@ summary, and the exact property change folded under a toggle. A change too small
 to see at 1:1 (say a 2px icon tweak) also gets a magnified zoom crop, so a
 sub-pixel change can't slip past a reviewer.
 
+Annotation boxes reconcile exact-equivalent elements that moved to a different
+structural path. When an unkeyed sibling insertion shifts unchanged descendants,
+the clean comparison still shows the complete rendered result and the audit keeps
+every structural finding, but magenta boxes mark only unmatched additions,
+removals, and restyles instead of painting the displaced subtree as changed.
+
 When one change appears both on an ordinary page and in an open popup, the report
 chooses a representative where the changed element is visibly exposed, then prefers
 the ordinary page before using viewport width as a tie-breaker. Modal-background DOM

package/dist/map-store.js

@@ -139,7 +139,23 @@ export function expectedCompatibilityKey(options = {}) {
     }))).slice(0, 16);
 }
 export function currentGitSha(cwd = process.cwd(), env = process.env) {
-    const fromEnv = env.GITHUB_SHA || env.GITHUB_HEAD_SHA;
+    const fromEvent = (() => {
+        if (!env.GITHUB_EVENT_PATH ||
+            !['pull_request', 'pull_request_target', 'workflow_run'].includes(env.GITHUB_EVENT_NAME ?? '')) {
+            return undefined;
+        }
+        try {
+            const event = JSON.parse(fs.readFileSync(env.GITHUB_EVENT_PATH, 'utf8'));
+            return event.pull_request?.head?.sha ?? event.workflow_run?.head_sha;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    // STYLEPROOF_SHA/GITHUB_HEAD_SHA are explicit overrides. On a pull_request
+    // run, GITHUB_SHA is the synthetic merge commit, so consult the trusted event
+    // payload before falling back to it.
+    const fromEnv = env.STYLEPROOF_SHA || env.GITHUB_HEAD_SHA || fromEvent || env.GITHUB_SHA;
     if (fromEnv && /^[0-9a-f]{7,40}$/i.test(fromEnv))
         return fromEnv;
     const sha = gitOutput(cwd, ['rev-parse', 'HEAD']);

package/dist/report.js

@@ -48,6 +48,72 @@ function outermost(paths) {
 function innermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(p + ' > ')));
 }
+function annotationIdentity(entry) {
+    const sortedPseudo = Object.fromEntries(Object.entries(entry.pseudo ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([pseudo, properties]) => [
+        pseudo,
+        Object.entries(properties).sort(([left], [right]) => left.localeCompare(right)),
+    ]));
+    return JSON.stringify([
+        entry.tag,
+        entry.cls,
+        entry.rect?.[2] ?? null,
+        entry.rect?.[3] ?? null,
+        Object.entries(entry.style).sort(([left], [right]) => left.localeCompare(right)),
+        sortedPseudo,
+    ]);
+}
+function indexAnnotationIdentities(map) {
+    const pathsByIdentity = new Map();
+    for (const [elementPath, entry] of Object.entries(map.elements)) {
+        const identity = annotationIdentity(entry);
+        pathsByIdentity.set(identity, [...(pathsByIdentity.get(identity) ?? []), elementPath]);
+    }
+    return pathsByIdentity;
+}
+function hasEquivalentEntryAtAnotherPath(elementPath, entry, samePathsByIdentity, otherPathsByIdentity) {
+    if (!entry)
+        return false;
+    const identity = annotationIdentity(entry);
+    const samePaths = samePathsByIdentity.get(identity) ?? [];
+    const otherPaths = otherPathsByIdentity.get(identity) ?? [];
+    // Reconcile only an unambiguous one-to-one move. If an identity is duplicated
+    // on either side, an arbitrary cross-path match can hide a real restyle or an
+    // inserted/removed sibling from the annotated proof.
+    return samePaths.length === 1 && otherPaths.length === 1 && otherPaths[0] !== elementPath;
+}
+function annotationSides(finding, beforeMoved, afterMoved, reconcileMoved) {
+    // A style/state finding already proves that the element at this path changed.
+    // Only reconcile it when the same surface also has structural churn; without a
+    // DOM finding, cross-path identity matching can erase a real style swap.
+    if (finding.kind !== 'dom')
+        return reconcileMoved ? { before: !beforeMoved, after: !afterMoved } : { before: true, after: true };
+    if (finding.change === 'removed')
+        return { before: !beforeMoved, after: false };
+    if (finding.change === 'added')
+        return { before: false, after: !afterMoved };
+    return { before: true, after: true };
+}
+function annotationPaths(findings, beforeMap, afterMap) {
+    const beforePathsByIdentity = indexAnnotationIdentities(beforeMap);
+    const afterPathsByIdentity = indexAnnotationIdentities(afterMap);
+    const reconcileMoved = findings.some((finding) => finding.kind === 'dom');
+    const beforePaths = new Set();
+    const afterPaths = new Set();
+    for (const finding of findings) {
+        const beforeEntry = beforeMap.elements[finding.path];
+        const afterEntry = afterMap.elements[finding.path];
+        const beforeMoved = hasEquivalentEntryAtAnotherPath(finding.path, beforeEntry, beforePathsByIdentity, afterPathsByIdentity);
+        const afterMoved = hasEquivalentEntryAtAnotherPath(finding.path, afterEntry, afterPathsByIdentity, beforePathsByIdentity);
+        const sides = annotationSides(finding, beforeMoved, afterMoved, reconcileMoved);
+        if (sides.before)
+            beforePaths.add(finding.path);
+        if (sides.after)
+            afterPaths.add(finding.path);
+    }
+    return { before: innermost([...beforePaths]), after: innermost([...afterPaths]) };
+}
 /** Headline counts with the zeros dropped — `0 state-delta difference(s)` is noise. */
 function changeCountLabel(shown) {
     const parts = [];
@@ -853,9 +919,9 @@ function buildRegionImages(args) {
     // cards) on each side — not the merged container the crop anchors on, whose box would
     // just trace the whole frame. An element present on only one side (added/removed) is
     // boxed only there.
-    const markPaths = innermost([...new Set(regionFindings.map((f) => f.path))]);
-    const rectsA = markPaths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
-    const rectsB = markPaths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
+    const markedPaths = annotationPaths(regionFindings, mapA, mapB);
+    const rectsA = markedPaths.before.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
+    const rectsB = markedPaths.after.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
     const annotatedBefore = annotateCrop(before, rectsA);
     const annotatedAfter = annotateCrop(after, rectsB);
     const images = {
@@ -869,8 +935,10 @@ function buildRegionImages(args) {
     // Name the changed element(s) so the reviewer knows where to look without expanding
     // anything (e.g. `changed: span.caret`).
     const changedNames = [
-        ...new Set(markPaths
-            .map((p) => mapA.elements[p] ?? mapB.elements[p])
+        ...new Set([
+            ...markedPaths.before.map((elementPath) => mapA.elements[elementPath]),
+            ...markedPaths.after.map((elementPath) => mapB.elements[elementPath]),
+        ]
             .filter((e) => !!e)
             .map((e) => (e.cls ? `${e.tag}.${e.cls.split(/\s+/)[0]}` : e.tag))),
     ].slice(0, 3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "4.0.2",
+  "version": "4.1.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",