styleproof 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.4.0]
+
+New surfaces (present on only one side, no baseline to diff) are shown for
+reference and never block the review gate.
+
+### Fixed
+
+- **A surface captured on only one side is now treated as a _new surface_, not a
+  change.** Previously every one-sided surface counted as a DOM change, so a
+  bootstrap PR (base branch has no capture spec yet → empty baseline) rendered a
+  self-contradicting report — a `0 DOM change(s) · 0 … · 0 … across 0 distinct
+change(s) in N surface(s)` headline sitting above N "re-run both captures"
+  warnings, each with an approval checkbox that could turn the gate green on a
+  capture set that has no baseline at all.
+
+### Changed
+
+- **New surfaces are shown, not blocked.** A surface present on only one side is
+  rendered with its captured-side screenshot under a `🆕 new surface` heading,
+  summarised on its own headline line (`🆕 N new surface(s) … don't block the
+check`), and excluded from the change tallies. In review-gate mode it gets an
+  **optional** `Approve this new surface` checkbox that the approve workflow
+  deliberately ignores — so a new surface never holds the `StyleProof` status red.
+  Real before↔after changes still gate exactly as before.
+- **`styleproof-diff` exit codes:** `0` identical, `1` reviewable differences,
+  `2` usage/capture error (unchanged), and new **`3`** = only new surfaces (no
+  baseline to diff). The Action reports on `1` or `3` but only gates on `1`;
+  certify mode (`fail-on-diff`) still fails on either, since "nothing changed"
+  means the capture set didn't grow either.
+- The Action `changed` output is now `"false"` for a brand-new surface with no
+  baseline (it was a change before). `generateStyleMapReport` returns a new
+  `newSurfaces` count alongside `changedSurfaces`.
+
 ## [1.3.1]
 
 ### Changed

package/README.md

@@ -16,6 +16,7 @@ On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base br
 
 - A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot and the property changes folded under a toggle.
 - An **approval checkbox per change**, driving a `StyleProof` commit status: red until every change is signed off, green when there are none.
+- **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown with its screenshot under a `🆕 new surface` heading and an _optional_ approval box, but it never holds the status red. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
 
 ## What a report looks like

package/bin/styleproof-diff.mjs

@@ -14,7 +14,8 @@
  *     `hover:` variant a screenshot can never catch.
  *
  * Custom properties (--*) are ignored: they are inputs, not outcomes (see
- * README). Exit code 0 = identical, 1 = differences, 2 = usage/capture error.
+ * README). Exit code 0 = identical, 1 = reviewable differences, 2 = usage/capture
+ * error, 3 = only new surfaces (present on one side, no baseline to diff against).
  */
 import fs from 'node:fs';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
@@ -28,7 +29,8 @@ options:
   --json <file>    also write the full structured diff to <file>
   -h, --help       show this help
 
-exit: 0 identical (certified), 1 differences found, 2 usage/capture error.
+exit: 0 identical (certified), 1 differences found, 2 usage/capture error,
+      3 only new surfaces (present on one side, no baseline to diff against).
 `;
 
 const argv = process.argv.slice(2);
@@ -71,7 +73,8 @@ const { surfaces, counts } = result;
 
 for (const sd of surfaces) {
   if (sd.missing) {
-    console.log(`\n${sd.surface}: captured in only one set — re-run both captures`);
+    const side = sd.missing === 'before' ? 'after' : 'before';
+    console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
     continue;
   }
   const lines = [];
@@ -98,13 +101,19 @@ for (const sd of surfaces) {
 if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces }, null, 2));
 
 const total = counts.dom + counts.style + counts.state;
+const newSurfaces = surfaces.filter((s) => s.missing).length;
 const surfaceCount = new Set([
   ...fs.readdirSync(dirA).filter((f) => /\.json(\.gz)?$/.test(f)),
   ...fs.readdirSync(dirB).filter((f) => /\.json(\.gz)?$/.test(f)),
 ]).size;
+const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 console.log(
   total === 0
-    ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces`,
+    ? newSurfaces === 0
+      ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
+      : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — shown for reference, no reviewable change`
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}`,
 );
-process.exit(total === 0 ? 0 : 1);
+// 0 = identical, 1 = reviewable differences, 3 = only new surfaces (no baseline,
+// nothing to review). 2 stays reserved for usage/capture errors.
+process.exit(total > 0 ? 1 : newSurfaces > 0 ? 3 : 0);

package/bin/styleproof-report.mjs

@@ -108,10 +108,13 @@ try {
   process.exit(2);
 }
 
+const newNote = result.newSurfaces ? ` (+${result.newSurfaces} new surface(s) with no baseline)` : '';
 console.log(
   result.changedSurfaces === 0
-    ? '✓ no changes — empty report written'
-    : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)`,
+    ? result.newSurfaces === 0
+      ? '✓ no changes — empty report written'
+      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for reference`
+    : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)${newNote}`,
 );
 console.log(`report: ${result.reportMdPath}`);
-process.exit(result.changedSurfaces === 0 ? 0 : 1);
+process.exit(result.changedSurfaces === 0 && result.newSurfaces === 0 ? 0 : 1);

package/dist/capture.js

@@ -310,7 +310,7 @@ export function loadStyleMap(filePath) {
         raw = fs.readFileSync(filePath);
     }
     catch (e) {
-        throw new Error(`styleproof: cannot read capture ${filePath}: ${e.message}`);
+        throw new Error(`styleproof: cannot read capture ${filePath}: ${e.message}`, { cause: e });
     }
     try {
         const text = filePath.endsWith('.gz') ? gunzipSync(raw).toString('utf8') : raw.toString('utf8');
@@ -318,6 +318,6 @@ export function loadStyleMap(filePath) {
     }
     catch (e) {
         throw new Error(`styleproof: capture ${filePath} is corrupt or truncated (${e.message}). ` +
-            'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.');
+            'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.', { cause: e });
     }
 }

package/dist/diff.js

@@ -94,8 +94,11 @@ export function diffStyleMapDirs(dirA, dirB) {
     const counts = { dom: 0, style: 0, state: 0 };
     for (const surface of names) {
         if (!indexA[surface] || !indexB[surface]) {
+            // A surface present on only one side has no baseline to diff against — it's
+            // a NEW surface, not a style change. It does NOT count toward the change
+            // tallies (those drive the review gate); the consumer flags it separately
+            // off the `missing` marker and shows it for reference without blocking.
             surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
-            counts.dom++;
             continue;
         }
         const findings = diffStyleMaps(loadStyleMap(indexA[surface]), loadStyleMap(indexB[surface]));

package/dist/report.d.ts

@@ -41,7 +41,10 @@ export type ReportOptions = {
     includeLayoutNoise?: boolean;
 };
 export type ReportResult = {
+    /** Surfaces carrying a reviewable change (excludes new, one-sided surfaces). */
     changedSurfaces: number;
+    /** New surfaces present on only one side, with no baseline to compare. */
+    newSurfaces: number;
     totalFindings: number;
     reportMdPath: string;
     reportJsonPath: string;

package/dist/report.js

@@ -3,6 +3,10 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
+// Hidden marker appended to a new-surface heading. Invisible in rendered
+// markdown; lets the PR-comment layer attach an OPTIONAL "approve" box to a new
+// surface (vs the required box on a real change), so new surfaces never gate.
+const NEW_SURFACE_MARKER = '<!-- styleproof-new -->';
 const rectToBox = (r) => ({ x: r[0], y: r[1], w: r[2], h: r[3] });
 const pad = (b, by) => ({ x: b.x - by, y: b.y - by, w: b.w + 2 * by, h: b.h + 2 * by });
 const union = (a, b) => {
@@ -563,7 +567,10 @@ export function generateStyleMapReport(opts) {
             else
                 shown.state += summarizeProps(f.props).length;
         }
-    const surfaceCount = changeGroups.reduce((acc, g) => acc + g.surfaces.length, 0) + missing.length;
+    // Surfaces carrying a reviewable change — NOT the new (one-sided) ones, which
+    // have no baseline to compare and are summarised on their own line below so the
+    // headline never reads "0 changes" while warnings sit beneath it.
+    const changedSurfaceCount = changeGroups.reduce((acc, g) => acc + g.surfaces.length, 0);
     const md = [];
     const json = [];
     const img = (rel) => (imageBaseUrl ? `${imageBaseUrl.replace(/\/$/, '')}/${rel}` : rel);
@@ -572,8 +579,16 @@ export function generateStyleMapReport(opts) {
         md.push('✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
     }
     else {
-        md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
-            `across ${changeGroups.length} distinct change(s) in ${surfaceCount} surface(s).`);
+        if (changeGroups.length > 0) {
+            md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
+                `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 reference. ` +
+                `New surfaces don't block the check.`);
+        }
     }
     let totalFindings = 0;
     let cropSeq = 0;
@@ -646,15 +661,41 @@ export function generateStyleMapReport(opts) {
         surfaceJson.findings = surfaceFindings;
         json.push(surfaceJson);
     }
+    // New surfaces: present on only one side, so there's nothing to diff. Show the
+    // captured side as a single screenshot for reference and mark the heading so the
+    // PR comment can attach an OPTIONAL approval box — these never gate the check.
     for (const p of missing) {
-        md.push('', `### \`${p.sd.surface}\``, '', `⚠️ captured only in the **${p.sd.missing === 'before' ? 'after' : 'before'}** set — re-run both captures.`);
-        json.push({ surface: p.sd.surface, missing: p.sd.missing });
+        const side = p.sd.missing === 'before' ? 'after' : 'before';
+        const srcDir = side === 'after' ? afterDir : beforeDir;
+        const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
+        md.push('', `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`, '', `_${formatSurfaceList([p.sd.surface])}_`);
+        const surfaceJson = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
+        if (png) {
+            cropSeq++;
+            const h = Math.min(maxHeight, png.height);
+            const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h);
+            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} · ${p.sd.surface}${png.height > h ? ' (top of page)' : ''}</sub>`);
+            surfaceJson.image = `${stem}.png`;
+        }
+        else {
+            md.push('', `_Captured only in the **${side}** set; no screenshot saved (run captures with \`screenshots: true\`)._`);
+        }
+        md.push('', `_No baseline to compare against — this surface is new, so it doesn't block the check. It becomes part of the baseline once this merges._`);
+        json.push(surfaceJson);
     }
     const reportMdPath = path.join(outDir, 'report.md');
     const reportJsonPath = path.join(outDir, 'report.json');
     fs.writeFileSync(reportMdPath, md.join('\n') + '\n');
     fs.writeFileSync(reportJsonPath, JSON.stringify({ counts: shown, surfaces: json }, null, 2));
-    return { changedSurfaces: prepared.length, totalFindings, reportMdPath, reportJsonPath };
+    return {
+        changedSurfaces: prepared.length - missing.length,
+        newSurfaces: missing.length,
+        totalFindings,
+        reportMdPath,
+        reportJsonPath,
+    };
 }
 function findCapture(dir, surface) {
     for (const ext of ['.json.gz', '.json']) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.3.1",
+  "version": "1.4.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",
@@ -63,7 +63,7 @@
     "test:watch": "node --test --watch test/*.test.mjs",
     "test:e2e": "npm run build && playwright test test/smoke.e2e.spec.ts",
     "init": "node ./bin/styleproof-init.mjs",
-    "prepare": "npm run build",
+    "prepare": "npm run build && husky",
     "prepublishOnly": "npm run clean && npm run build && npm run typecheck"
   },
   "peerDependencies": {
@@ -73,14 +73,16 @@
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
+    "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.9.3",
     "@types/pngjs": "^6.0.5",
-    "eslint": "^9.17.0",
-    "globals": "^15.14.0",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
     "prettier": "^3.4.2",
-    "typescript": "^5.6.2",
-    "typescript-eslint": "^8.18.0"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.18.0",
+    "husky": "^9.1.7",
+    "fallow": "^2.96.0"
   }
 }