styleproof 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ 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
+
+- **Inserting a semantic sibling no longer turns every following element into a
+  false restyle.** Capture paths now prefer privacy-safe hashed identities from
+  stable attributes (`data-styleproof-key`, IDs, test IDs, link destinations,
+  and form names) when they are unique among siblings, falling back to
+  `:nth-child()` only when no stable identity exists. Raw attribute values never
+  enter the map.
+- **Reports no longer publish an unchanged image as a misleading highlighted
+  twin.** The annotated crop is omitted when every changed rectangle falls
+  outside the rendered crop.
+- **New-surface screenshots no longer preserve a blank full-page tail.** New
+  captures record their viewport and reports show that top viewport when the
+  full-page screenshot is taller.
+- **Shared changes now choose exposed proof and suppress misleading crops.** When
+  the same change appears on an ordinary page and a modal-open state, the report
+  excludes modal-background DOM content before viewport width; if no captured
+  state visibly paints the change, it retains the audit details without images.
+
+### Changed
+
+- **New pages, states, and surfaces render before element-level diffs.** A new
+  page can no longer be buried beneath shared-frame changes in the report.
+- StyleProof reports now lead with named new surfaces in the summary that PR comments quote, and render new-surface screenshots before existing-surface diff groups so new-page PRs do not read like broad restyle churn.
+
 ## [4.0.1] - 2026-07-07
 
 ### Fixed

package/README.md

@@ -209,7 +209,33 @@ element's whole look is reviewable, not just its `:hover` changes.
 
 ### What a report looks like
 
-One change — the hero CTA recoloured cyan → amber — appears as a single section in the report: a side-by-side before/after cropped screenshot, the same crop again with magenta boxes marking exactly what changed, a one-line summary, then 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.
+New pages, states, and surfaces appear first, before lower-level element diffs, and
+show the captured top viewport when there is no baseline side to compare. Existing
+surfaces then render one change per section: a side-by-side before/after crop, an
+annotated twin when a visible changed element can actually be boxed, a one-line
+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
+content is excluded; if no captured state visibly paints the change, the report keeps
+the audit details but omits a misleading identical before/after crop.
+
+Element identity is stable across ordinary list insertions. StyleProof prefers a
+privacy-safe hash of a unique `data-styleproof-key`, ID, test ID, link destination,
+or form name for each sibling and falls back to `:nth-child()` only when the DOM
+offers no stable semantic identity. Attribute values are never written into the
+map. This keeps inserting one navigation link from falsely restyling every link
+after it; add `data-styleproof-key` when repeated controls have no other stable
+attribute.
 
 ![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](https://raw.githubusercontent.com/BenSheridanEdwards/StyleProof/main/docs/demo-composite.png)
 

package/dist/capture.d.ts

@@ -84,6 +84,11 @@ export type CapturedOverlay = {
 export type StyleMap = {
     /** Optional runner-supplied context; ignored by the certification diff. */
     metadata?: CaptureMetadata;
+    /** Browser viewport used for this capture. Report-only; ignored by the certification diff. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
     defaults: Record<string, Props>;
     elements: Record<string, ElementEntry>;
     states: Record<string, Record<string, Record<string, Props>>>;

package/dist/capture.js

@@ -62,14 +62,42 @@ function injectPathOf() {
             return 'html';
         if (el === document.body)
             return 'body';
+        const identityCandidates = (element) => {
+            const tag = element.tagName.toLowerCase();
+            const attributes = [
+                ['styleproof', element.getAttribute('data-styleproof-key')],
+                ['id', element.getAttribute('id')],
+                ['testid', element.getAttribute('data-testid')],
+                ['test', element.getAttribute('data-test')],
+                ...(tag === 'a' ? [['href', element.getAttribute('href')]] : []),
+                ...(['input', 'select', 'textarea'].includes(tag)
+                    ? [['name', element.getAttribute('name')]]
+                    : []),
+            ];
+            return attributes.flatMap(([name, value]) => (value ? [`${name}:${value}`] : []));
+        };
+        const privacySafeHash = (value) => {
+            let hash = 2166136261;
+            for (let characterIndex = 0; characterIndex < value.length; characterIndex++) {
+                hash ^= value.charCodeAt(characterIndex);
+                hash = Math.imul(hash, 16777619);
+            }
+            return (hash >>> 0).toString(36);
+        };
+        const stableSegment = (element, parent) => {
+            const candidate = identityCandidates(element).find((identity) => [...parent.children].filter((sibling) => identityCandidates(sibling).includes(identity)).length === 1);
+            if (candidate)
+                return `${element.tagName.toLowerCase()}:sp-key(${privacySafeHash(candidate)})`;
+            return `${element.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, element) + 1})`;
+        };
         const parts = [];
-        let n = el;
-        while (n && n !== document.body) {
-            const parent = n.parentElement;
+        let element = el;
+        while (element && element !== document.body) {
+            const parent = element.parentElement;
             if (!parent)
                 break;
-            parts.unshift(`${n.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, n) + 1})`);
-            n = parent;
+            parts.unshift(stableSegment(element, parent));
+            element = parent;
         }
         return 'body > ' + parts.join(' > ');
     };
@@ -361,22 +389,7 @@ function detectOverlayCandidates({ ignore }) {
 // fallow-ignore-next-line complexity
 function snapSubtree({ selector, index }) {
     const el = document.querySelectorAll(selector)[index];
-    const pathOf = (n) => {
-        if (n === document.documentElement)
-            return 'html';
-        if (n === document.body)
-            return 'body';
-        const parts = [];
-        let c = n;
-        while (c && c !== document.body) {
-            const parent = c.parentElement;
-            if (!parent)
-                break;
-            parts.unshift(`${c.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, c) + 1})`);
-            c = parent;
-        }
-        return 'body > ' + parts.join(' > ');
-    };
+    const pathOf = window.__spPathOf;
     const out = {};
     if (!el)
         return out;
@@ -773,6 +786,7 @@ export async function captureStyleMap(page, options = {}) {
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
     const captureComponent = options.captureComponent ?? false;
+    const viewport = page.viewportSize();
     // Neutralise real hover/focus the same way FREEZE_CSS neutralises motion: park
     // the pointer over an ignored 1px sink and blur whatever element holds focus so
     // every read below is the no-interaction resting state. Real :hover/:focus is
@@ -841,6 +855,7 @@ export async function captureStyleMap(page, options = {}) {
         const inventory = await harvestInventoryFor(page, options.inventory);
         return {
             ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(viewport ? { viewport } : {}),
             defaults: base.defaults,
             elements: base.elements,
             states,

package/dist/change-groups.js

@@ -204,7 +204,10 @@ export function summarizeProps(props) {
 }
 /** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
 export function prettyLabel(p, cls) {
-    const tag = (p.split('>').pop() ?? '').trim().replace(/:nth-child\(\d+\)/, '') || 'el';
+    const tag = (p.split('>').pop() ?? '')
+        .trim()
+        .replace(/:nth-child\(\d+\)/, '')
+        .replace(/:sp-key\([a-z0-9]+\)/, '') || 'el';
     const first = cls.split(/\s+/)[0] ?? '';
     return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
 }

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 = [];
@@ -127,12 +193,20 @@ function strokeRect(png, x, y, w, h, t = 2, color = HILITE) {
 function annotateCrop(crop, rects) {
     const out = new PNG({ width: crop.png.width, height: crop.png.height });
     PNG.bitblt(crop.png, out, 0, 0, crop.png.width, crop.png.height, 0, 0);
+    let highlighted = false;
     for (const [rx, ry, rw, rh] of rects) {
         if (rw <= 0 || rh <= 0)
             continue;
-        strokeRect(out, rx - crop.ox, ry - crop.oy, rw, rh);
+        const left = Math.max(0, rx - crop.ox);
+        const top = Math.max(0, ry - crop.oy);
+        const right = Math.min(crop.png.width, rx - crop.ox + rw);
+        const bottom = Math.min(crop.png.height, ry - crop.oy + rh);
+        if (right <= left || bottom <= top)
+            continue;
+        strokeRect(out, left, top, right - left, bottom - top, Math.min(2, right - left, bottom - top));
+        highlighted = true;
     }
-    return out;
+    return { png: out, highlighted };
 }
 /**
  * One before|after image: the two equal-size crops on a dark canvas with a
@@ -675,11 +749,63 @@ function certificationLines(beforeDir, afterDir) {
         '',
     ];
 }
+/** A changed element can anchor useful visual proof only when the browser paints it. */
+function isPaintedEntry(entry) {
+    if (!entry?.rect || !visible(rectToBox(entry.rect)))
+        return false;
+    if (entry.style.display === 'none' || entry.style.visibility === 'hidden')
+        return false;
+    return Number(entry.style.opacity ?? '1') > 0;
+}
+function isSameOrDescendantPath(candidatePath, ancestorPath) {
+    return candidatePath === ancestorPath || candidatePath.startsWith(`${ancestorPath} > `);
+}
+/** A modal leaves its background in the DOM but makes it unsuitable as visual proof.
+ * A change inside the modal itself is foreground content and remains eligible. */
+function isBackgroundBehindActiveModal(map, changedPath) {
+    return (map.overlays ?? []).some((overlay) => overlay.ariaModal === 'true' && !isSameOrDescendantPath(changedPath, overlay.path));
+}
+function isExposedChangedEntry(map, changedPath) {
+    return isPaintedEntry(map.elements[changedPath]) && !isBackgroundBehindActiveModal(map, changedPath);
+}
+function hasExposedChangedEntry(mapA, mapB, changedPaths) {
+    return changedPaths.some((changedPath) => isExposedChangedEntry(mapA, changedPath) || isExposedChangedEntry(mapB, changedPath));
+}
+/** Prefer proof a reviewer can see: an exposed changed element, then a non-modal
+ * ordinary page over a popup state that can leave shared chrome in the background,
+ * then the widest width. */
+function representativeScore(candidate, beforeDir, afterDir) {
+    const beforeMap = loadStyleMap(findCapture(beforeDir, candidate.sd.surface));
+    const afterMap = loadStyleMap(findCapture(afterDir, candidate.sd.surface));
+    const changedPaths = [...new Set(candidate.findings.map((finding) => finding.path))];
+    const hasExposedChange = hasExposedChangedEntry(beforeMap, afterMap, changedPaths);
+    const hasActiveModal = [...(beforeMap.overlays ?? []), ...(afterMap.overlays ?? [])].some((overlay) => overlay.ariaModal === 'true');
+    const isPopup = beforeMap.metadata?.variantKind === 'popup' || afterMap.metadata?.variantKind === 'popup';
+    return { hasExposedChange, hasActiveModal, isPopup, width: surfaceWidth(candidate.sd.surface) };
+}
+function isBetterRepresentative(candidate, current) {
+    if (candidate.hasExposedChange !== current.hasExposedChange)
+        return candidate.hasExposedChange;
+    if (candidate.hasActiveModal !== current.hasActiveModal)
+        return !candidate.hasActiveModal;
+    if (candidate.isPopup !== current.isPopup)
+        return !candidate.isPopup;
+    return candidate.width > current.width;
+}
 // Group surfaces that changed in the SAME way (the rects differ per width; the change
-// itself does not) so an identical change shows once, not once per surface — keeping
-// the widest surface as the representative image.
-function groupBySignature(prepared) {
+// itself does not) so an identical change shows once, not once per surface. Select
+// the representative by visible proof first; width only breaks otherwise-equal ties.
+function groupBySignature(prepared, beforeDir, afterDir) {
     const bySig = new Map();
+    const scoreBySurface = new Map();
+    const score = (candidate) => {
+        const existing = scoreBySurface.get(candidate.sd.surface);
+        if (existing)
+            return existing;
+        const computed = representativeScore(candidate, beforeDir, afterDir);
+        scoreBySurface.set(candidate.sd.surface, computed);
+        return computed;
+    };
     for (const p of prepared) {
         if (p.sd.missing)
             continue;
@@ -687,7 +813,7 @@ function groupBySignature(prepared) {
         const existing = bySig.get(sig);
         if (existing) {
             existing.surfaces.push(p.sd.surface);
-            if (surfaceWidth(p.sd.surface) > surfaceWidth(existing.rep.sd.surface))
+            if (isBetterRepresentative(score(p), score(existing.rep)))
                 existing.rep = p;
         }
         else {
@@ -713,6 +839,13 @@ function countShownChanges(changeGroups) {
 }
 // The identical / changed / new-surface summary line(s). Split out (with an early
 // return for the all-identical case) so reportHeadline stays flat.
+function newSurfaceSummary(missing, maxNamed = 8) {
+    const bases = [...new Set(missing.map((p) => surfaceBase(p.sd.surface)))].sort();
+    const shownBases = new Set(bases.slice(0, maxNamed));
+    const shownSurfaces = missing.map((p) => p.sd.surface).filter((surface) => shownBases.has(surfaceBase(surface)));
+    const more = bases.length > maxNamed ? `, +${bases.length - maxNamed} more` : '';
+    return '`' + formatSurfaceList(shownSurfaces) + '`' + more;
+}
 function summaryLines(args) {
     const { changeGroups, missing, shown, changedSurfaceCount, contentCount } = args;
     if (changeGroups.length === 0 && missing.length === 0) {
@@ -723,15 +856,15 @@ function summaryLines(args) {
         ];
     }
     const md = [];
-    if (changeGroups.length > 0) {
-        md.push(`**${changeCountLabel(shown)}** across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
-    }
     if (missing.length > 0) {
-        if (changeGroups.length > 0)
-            md.push('');
-        md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for review. ` +
+        md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare: ${newSurfaceSummary(missing)}. ` +
             `Approve them before they become the baseline.`);
     }
+    if (changeGroups.length > 0) {
+        if (md.length > 0)
+            md.push('');
+        md.push(`**${changeCountLabel(shown)}** across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} existing surface(s).`);
+    }
     return md;
 }
 // The headline summary lines between the certification block and the per-surface
@@ -786,20 +919,26 @@ 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 annotated = compositePair(annotateCrop(before, rectsA), annotateCrop(after, rectsB));
-    writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
+    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 = {
         composite: `${stem}-composite.png`,
-        annotated: `${stem}-annotated.png`,
     };
+    if (annotatedBefore.highlighted || annotatedAfter.highlighted) {
+        const annotated = compositePair(annotatedBefore.png, annotatedAfter.png);
+        writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
+        images.annotated = `${stem}-annotated.png`;
+    }
     // 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);
@@ -827,11 +966,10 @@ function buildRegionImages(args) {
         `![before ◀ │ ▶ after](${img(images.composite)})`,
         '',
         `<sub>◀ before  ·  after ▶ — ${ctxLabel}</sub>`,
-        '',
-        `![highlighted before ◀ │ ▶ after](${img(images.annotated)})`,
-        '',
-        `<sub>🔍 magenta boxes mark each change${changedLabel}</sub>`,
     ];
+    if (images.annotated) {
+        md.push('', `![highlighted before ◀ │ ▶ after](${img(images.annotated)})`, '', `<sub>🔍 magenta boxes mark each change${changedLabel}</sub>`);
+    }
     if (images.zoom) {
         md.push('', `![zoomed before ◀ │ ▶ after](${img(images.zoom)})`, '', `<sub>🔬 magnified ${zoomFactor}× — change too small to see at 1:1${changedLabel}</sub>`);
     }
@@ -876,9 +1014,25 @@ function renderChangeGroup(cg, ctx, maxCrops, cropSeq) {
     const mapB = loadStyleMap(findCapture(ctx.afterDir, sd.surface));
     // Theme-token reverse-indexes so colour changes can name `red-200` per side.
     const describeCtx = { tokensBefore: tokenIndex(mapA.tokens), tokensAfter: tokenIndex(mapB.tokens) };
+    const changedPaths = outermost([...new Set(surfaceFindings.map((f) => f.path))]);
+    if (!hasExposedChangedEntry(mapA, mapB, changedPaths)) {
+        const reason = 'The changed element is not visibly painted in this representative state (it is hidden at this breakpoint or is background content behind an active modal), so a before/after crop would be misleading.';
+        return {
+            md: ['', `_${reason}_`, '', ...renderCropChanges(surfaceFindings, ctx.foldDetailsAt, describeCtx)],
+            json: {
+                surfaces: cg.surfaces,
+                representative: sd.surface,
+                regions: [],
+                findings: surfaceFindings,
+                visualEvidence: 'not-rendered',
+                reason,
+            },
+            findingCount: surfaceFindings.length,
+            cropSeq,
+        };
+    }
     const pngA = readPng(path.join(ctx.beforeDir, `${sd.surface}.png`));
     const pngB = readPng(path.join(ctx.afterDir, `${sd.surface}.png`));
-    const changedPaths = outermost([...new Set(surfaceFindings.map((f) => f.path))]);
     let groups = groupRegions(changedPaths, mapA, mapB, ctx.padBy);
     if (groups.length > maxCrops)
         groups = collapseGroups(groups);
@@ -918,11 +1072,11 @@ function renderNewSurface(p, ctx, cropSeq) {
     const json = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
     if (png) {
         cropSeq++;
-        const h = Math.min(maxHeight, png.height);
+        const h = Math.min(maxHeight, png.height, map.viewport?.height ?? png.height);
         const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h).png;
         const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
         writePng(path.join(outDir, `${stem}.png`), crop);
-        md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${formatSurfaceWithContext(p.sd.surface, map)}${png.height > h ? ' (top of page)' : ''}</sub>`);
+        md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${formatSurfaceWithContext(p.sd.surface, map)}${png.height > h ? ' (top viewport of page)' : ''}</sub>`);
         json.image = `${stem}.png`;
     }
     else {
@@ -998,7 +1152,7 @@ export function generateStyleMapReport(opts) {
     }))
         .filter((p) => p.sd.missing || p.findings.length > 0);
     const missing = prepared.filter((p) => p.sd.missing);
-    const changeGroups = groupBySignature(prepared);
+    const changeGroups = groupBySignature(prepared, beforeDir, afterDir);
     // Shared-chrome tier (#193): promote a change that rode the frame every view
     // draws (nav rail, header) to a callout, so the reviewer reads "the nav changed
     // everywhere" once instead of inferring it from a long surface list on several
@@ -1073,6 +1227,18 @@ export function generateStyleMapReport(opts) {
     const totalSurfaceBases = new Set(surfaceKeysIn(afterDir).map(surfaceBase)).size;
     const chromeSet = new Set(chrome);
     let chromeHeaderEmitted = false;
+    if (missing.length > 0) {
+        md.push('', '## 🆕 New pages, states, or surfaces — review first');
+    }
+    for (const p of missing) {
+        const r = renderNewSurface(p, ctx, cropSeq);
+        json.push(r.json);
+        cropSeq = r.cropSeq;
+        emitDetail(r.md, `- \`${safeKey(p.sd.surface)}\` · new surface`);
+    }
+    if (orderedGroups.length > 0) {
+        md.push('', '## Element-level changes');
+    }
     for (const cg of orderedGroups) {
         const r = renderChangeGroup(cg, ctx, maxCrops, cropSeq);
         json.push(r.json);
@@ -1085,12 +1251,6 @@ export function generateStyleMapReport(opts) {
             : r.md;
         emitDetail(detail, compactChangeSummary(cg, r.json, img));
     }
-    for (const p of missing) {
-        const r = renderNewSurface(p, ctx, cropSeq);
-        json.push(r.json);
-        cropSeq = r.cropSeq;
-        emitDetail(r.md, `- \`${safeKey(p.sd.surface)}\` · new surface`);
-    }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');
     const reportJsonPath = path.join(outDir, 'report.json');

package/package.json

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