styleproof 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -7,6 +7,33 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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,27 @@ 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.
+
+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/report.js

@@ -127,12 +127,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 +683,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 +747,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 +773,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 +790,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
@@ -789,12 +856,16 @@ function buildRegionImages(args) {
     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 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 = [
@@ -827,11 +898,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 +946,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 +1004,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 +1084,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 +1159,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 +1183,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.0.2",
   "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",