styleproof 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ 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
+
+- The before/after composite no longer draws coloured accent strips (grey for
+  before, blue for after) above each crop. They were a font-free before/after
+  cue, but a strip that differs between the two sides reads as a _second_ change
+  in the pair. Now the only thing that differs across the composite is the actual
+  change; before/after stays conveyed by position (left = before) and the caption.
+
 ## [1.3.0]
 
 Clearer reports: one section per screenshot.

package/README.md

@@ -16,9 +16,35 @@ 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_.
 
-A second mode certifies a refactor changed _nothing_: any diff fails the job (use it for CSS-to-Tailwind migrations, design-system swaps, build-tooling changes).
+## What a report looks like
+
+One change — the hero CTA recoloured cyan → amber — posts as a single section: a side-by-side before/after cropped screenshot, a one-line summary, then the exact property change folded under a toggle.
+
+![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](docs/demo-composite.png)
+
+As it renders in the PR comment (colours become live swatches; the full table sits inside the toggle):
+
+```text
+### `a.btn-solid` · 1 element restyled
+_landing @ 1280_
+
+`background-color` `rgb(95, 202, 219)` → `rgb(245, 158, 11)`
+
+▾ Show the property change
+   | Property         | Before            | After             |
+   | background-color | rgb(95, 202, 219) | rgb(245, 158, 11) |
+```
+
+## Works with any styling system
+
+StyleProof reads the browser's **computed styles** — the values it actually resolves — never your source CSS. Tailwind, CSS Modules, styled-components, Sass, vanilla CSS, inline styles: all produce the same computed output, and that's what it diffs. Elements are keyed by **DOM structure, not class name**, so a refactor that rewrites every `class` still lines up element-for-element.
+
+## Certify a refactor
+
+The same engine has a second mode that proves a change touched _nothing_ visual: with `fail-on-diff: true`, any difference at all fails the job. It's the job StyleProof was born for — certifying a CSS-to-Tailwind migration rendered byte-for-byte identical. Reach for it on any change whose whole promise is "the output is unchanged": a utility-class migration, a design-system swap, a dependency or build-tooling bump. Zero diff is the contract; one drifting longhand is a regression to investigate, not a change to approve.
 
 ## Install
 

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) => {
@@ -80,28 +84,26 @@ function fillRect(png, x, y, w, h, [r, g, b]) {
     }
 }
 /**
- * One labelled before|after image: the two equal-size crops on a dark canvas,
- * a divider between them, and a top accent bar per side (grey = before,
- * blue = after) as a font-free before/after cue. Left is always before.
+ * One before|after image: the two equal-size crops on a dark canvas with a
+ * neutral divider between them. Left is always before; before/after is labelled
+ * by the caption under the image. The divider is identical on both sides, so the
+ * ONLY thing that differs across the pair is the actual change — no extra chrome
+ * (e.g. a coloured accent strip) that reads as a second diff.
  */
 function compositePair(before, after) {
     const PAD = 20;
     const GAP = 28;
-    const BAR = 6; // accent strip height
     const w = Math.max(before.width, after.width);
     const h = Math.max(before.height, after.height);
     const width = PAD + w + GAP + w + PAD;
-    const height = PAD + BAR + h + PAD;
+    const height = PAD + h + PAD;
     const canvas = new PNG({ width, height });
     fillRect(canvas, 0, 0, width, height, [13, 17, 23]); // GitHub dark
     const leftX = PAD;
     const rightX = PAD + w + GAP;
-    const top = PAD + BAR;
-    fillRect(canvas, leftX, PAD, w, BAR, [110, 118, 129]); // before: grey
-    fillRect(canvas, rightX, PAD, w, BAR, [88, 166, 255]); // after: blue
-    PNG.bitblt(before, canvas, 0, 0, before.width, before.height, leftX, top);
-    PNG.bitblt(after, canvas, 0, 0, after.width, after.height, rightX, top);
-    fillRect(canvas, PAD + w + GAP / 2 - 1, PAD, 2, BAR + h, [48, 54, 61]); // divider
+    PNG.bitblt(before, canvas, 0, 0, before.width, before.height, leftX, PAD);
+    PNG.bitblt(after, canvas, 0, 0, after.width, after.height, rightX, PAD);
+    fillRect(canvas, PAD + w + GAP / 2 - 1, PAD, 2, h, [48, 54, 61]); // divider
     return canvas;
 }
 function readPng(file) {
@@ -565,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);
@@ -574,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;
@@ -648,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,7 +1,7 @@
 {
   "name": "styleproof",
-  "version": "1.3.0",
-  "description": "Certify CSS refactors with the browser's computed styles: capture every resolved longhand, pseudo-element, and forced hover/focus/active state, then diff before against after.",
+  "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",
     "css",
@@ -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"
   }
 }