styleproof 3.14.0 → 3.16.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.16.0] - 2026-07-05
+
+### Added
+
+- **The scaffolded PR workflow prunes its own report branch, out of the box.**
+  `styleproof-init`'s `.github/workflows/styleproof.yml` now also runs on
+  `pull_request: closed`: when a PR closes, a `prune` job removes that PR's `pr-<n>/`
+  folder from the report branch (`styleproof-reports`), so the branch no longer grows
+  without bound as PRs come and go — no adopter has to remember to garbage-collect it.
+  The report job is unchanged, only guarded to skip the close event. Covered by the
+  `styleproof-init` workflow test.
+
+## [3.15.0] - 2026-07-05
+
+### Changed
+
+- **Computed values are compared canonically, so a re-serialization isn't a change.** A
+  browser or build-tool version can serialize an _identical_ value differently — a Chromium
+  bump rewrites `rgba(8, 18, 32, 0.62)` as `#0812209e`, a Tailwind migration reformats a
+  font list's comma spacing — and StyleProof reported every one of those as a difference,
+  drowning a re-baseline in changes that aren't changes (and blowing up the report). The
+  diff now compares by a canonical form: colours are parsed to one `rgba()` (across
+  hex / `rgb()` / `rgba()` / `hsl()` / `hsla()`, short and long hex, comma and modern space
+  syntax) and comma/whitespace runs are normalised outside quotes. A green stops flickering
+  red across browser versions — captures are serialization-independent.
+
+  Safety: only _provably-equal_ values ever collapse. A value that can't be parsed with
+  confidence (or lives inside a quoted string) is left byte-for-byte, so a real change —
+  `#ff0000` → `#ff0001`, `0.5` → `0.6` alpha, a different font — always still surfaces. The
+  report shows the real captured strings; only the equality test is canonical.
+
 ## [3.14.0] - 2026-07-05
 
 ### Added

package/bin/styleproof-init.mjs

@@ -345,7 +345,9 @@ const CI_WORKFLOW = `name: StyleProof
 #   report without a browser;
 # - on cache miss, CI recaptures both sides in one pinned environment so the
 #   comparison stays valid.
-on: pull_request
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
 
 permissions:
   contents: write
@@ -355,6 +357,8 @@ permissions:
 
 jobs:
   styleproof:
+    # Report on open/update; the prune job below handles close.
+    if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -408,6 +412,41 @@ ${PM.setup}
           baseline-dir: __stylemaps__/base
           fresh-dir: __stylemaps__/head
           require-approval: true
+
+  prune:
+    # PR closed: drop its pr-<n>/ folder from the report branch so the branch
+    # never grows without bound. Keep BRANCH in sync with the report-branch
+    # input above (default: styleproof-reports).
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Prune this PR's report folder
+        shell: bash
+        env:
+          GH_TOKEN: \${{ github.token }}
+          BRANCH: styleproof-reports
+          PR: \${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          REMOTE="https://x-access-token:\${GH_TOKEN}@github.com/\${{ github.repository }}.git"
+          if ! git ls-remote --exit-code "$REMOTE" "refs/heads/$BRANCH" >/dev/null 2>&1; then
+            echo "No $BRANCH branch yet — nothing to prune."; exit 0
+          fi
+          TMP="$(mktemp -d)"
+          # Blobless clone keeps this fast; a very large report branch may prefer
+          # a --no-checkout plumbing rewrite instead.
+          git clone --filter=blob:none --single-branch --branch "$BRANCH" "$REMOTE" "$TMP"
+          cd "$TMP"
+          if [ ! -d "pr-$PR" ]; then
+            echo "No pr-$PR/ folder — nothing to prune."; exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git rm -r --quiet "pr-$PR"
+          git commit -m "chore(styleproof): prune report for closed PR #$PR"
+          git push origin "$BRANCH"
 `;
 
 function writeFileSafe(file, contents, { force: f } = {}) {

package/dist/canonicalize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonicalize a computed-style value: rewrite every parseable color to one `rgba(...)`
+ * form and normalize comma/whitespace runs outside quotes. Unparseable colors and quoted
+ * strings are left untouched, so only provably-equal values ever collapse.
+ */
+export declare function canonicalizeStyleValue(value: string): string;
+/** Two computed-style values are equal if they canonicalize to the same string. */
+export declare function styleValuesEqual(a: string, b: string): boolean;

package/dist/canonicalize.js

@@ -0,0 +1,154 @@
+// Canonicalize a computed-style value so two spellings of the SAME value don't read as a
+// change. Browsers and build tools serialize identical values differently — a Chromium
+// bump rewrites `rgba(8, 18, 32, 0.62)` as `#0812209e`, a Tailwind migration reformats a
+// font list's comma spacing — and StyleProof would otherwise report every one of those as
+// a diff, drowning a re-baseline in changes that aren't changes.
+//
+// SAFETY BAR: only ever collapse values that are PROVABLY equal. A token we can't parse
+// with confidence is left exactly as-is, so a real change always still diffs. Colors are
+// parsed to a single rgba() form; everything else only has its comma/whitespace runs
+// normalized (never inside quotes).
+const clamp255 = (n) => Math.min(255, Math.max(0, Math.round(n)));
+// Round alpha so the hex round-trip matches the decimal source: 0.62 → 0x9e (158) →
+// 158/255 = 0.6196… → 0.62 again. 3 dp is enough to reunite them without collapsing
+// genuinely different alphas (0.62 vs 0.625 stay apart).
+const roundAlpha = (n) => Math.round(Math.min(1, Math.max(0, n)) * 1000) / 1000;
+function fromHex(hex) {
+    let h = hex.slice(1);
+    if (h.length === 3 || h.length === 4) {
+        h = h
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    if (h.length !== 6 && h.length !== 8)
+        return null;
+    if (!/^[0-9a-fA-F]+$/.test(h))
+        return null;
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+    return { r, g, b, a };
+}
+// Parse one channel: a plain number, or a percentage of `max`. Alpha is just `max: 1`
+// (`50%` → 0.5, `0.5` → 0.5).
+function channel(tok, max) {
+    const t = tok.trim();
+    if (t.endsWith('%')) {
+        const n = Number(t.slice(0, -1));
+        return Number.isFinite(n) ? (n / 100) * max : null;
+    }
+    const n = Number(t);
+    return Number.isFinite(n) ? n : null;
+}
+function hslToRgb(h, s, l) {
+    h = ((h % 360) + 360) % 360;
+    s = Math.min(1, Math.max(0, s));
+    l = Math.min(1, Math.max(0, l));
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    const [r1, g1, b1] = h < 60
+        ? [c, x, 0]
+        : h < 120
+            ? [x, c, 0]
+            : h < 180
+                ? [0, c, x]
+                : h < 240
+                    ? [0, x, c]
+                    : h < 300
+                        ? [x, 0, c]
+                        : [c, 0, x];
+    return { r: (r1 + m) * 255, g: (g1 + m) * 255, b: (b1 + m) * 255 };
+}
+// Split `rgb(...)`/`hsl(...)` inner args on commas or the modern space + optional `/ alpha`.
+function args(inner) {
+    if (inner.includes(','))
+        return inner.split(',');
+    return inner.replace('/', ' ').split(/\s+/).filter(Boolean);
+}
+function parseColor(token) {
+    const t = token.trim();
+    if (t.startsWith('#'))
+        return fromHex(t);
+    const fn = t.match(/^(rgba?|hsla?)\((.*)\)$/i);
+    if (!fn)
+        return null;
+    const kind = fn[1].toLowerCase();
+    const parts = args(fn[2]);
+    if (parts.length < 3)
+        return null;
+    const a = parts.length >= 4 ? channel(parts[3], 1) : 1;
+    if (a === null)
+        return null;
+    if (kind.startsWith('rgb')) {
+        const r = channel(parts[0], 255);
+        const g = channel(parts[1], 255);
+        const b = channel(parts[2], 255);
+        if (r === null || g === null || b === null)
+            return null;
+        return { r: clamp255(r), g: clamp255(g), b: clamp255(b), a };
+    }
+    // hsl / hsla
+    const h = Number(parts[0].replace(/deg$/i, '').trim());
+    const s = channel(parts[1], 1); // s/l are percentages → 0..1
+    const l = channel(parts[2], 1);
+    if (!Number.isFinite(h) || s === null || l === null)
+        return null;
+    const { r, g, b } = hslToRgb(h, s, l);
+    return { r: clamp255(r), g: clamp255(g), b: clamp255(b), a };
+}
+const COLOR_TOKEN = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\([^)]*\)/gi;
+/**
+ * Canonicalize a computed-style value: rewrite every parseable color to one `rgba(...)`
+ * form and normalize comma/whitespace runs outside quotes. Unparseable colors and quoted
+ * strings are left untouched, so only provably-equal values ever collapse.
+ */
+export function canonicalizeStyleValue(value) {
+    // Colours first — but never inside a quoted string (a content: value could hold "#fff"),
+    // so operate only on the unquoted segments.
+    const segments = splitQuoted(value);
+    const canon = segments
+        .map((seg) => (seg.quoted ? seg.text : seg.text.replace(COLOR_TOKEN, (m) => canonColor(m))))
+        .join('');
+    // Normalize comma spacing and collapse whitespace runs — again, only outside quotes.
+    return splitQuoted(canon)
+        .map((seg) => (seg.quoted ? seg.text : seg.text.replace(/\s*,\s*/g, ', ').replace(/\s+/g, ' ')))
+        .join('')
+        .trim();
+}
+function canonColor(token) {
+    const c = parseColor(token);
+    if (!c)
+        return token;
+    return `rgba(${c.r}, ${c.g}, ${c.b}, ${roundAlpha(c.a)})`;
+}
+function splitQuoted(value) {
+    const segs = [];
+    let i = 0;
+    let buf = '';
+    while (i < value.length) {
+        const ch = value[i];
+        if (ch === '"' || ch === "'") {
+            if (buf) {
+                segs.push({ text: buf, quoted: false });
+                buf = '';
+            }
+            const end = value.indexOf(ch, i + 1);
+            const stop = end === -1 ? value.length : end + 1;
+            segs.push({ text: value.slice(i, stop), quoted: true });
+            i = stop;
+            continue;
+        }
+        buf += ch;
+        i++;
+    }
+    if (buf)
+        segs.push({ text: buf, quoted: false });
+    return segs;
+}
+/** Two computed-style values are equal if they canonicalize to the same string. */
+export function styleValuesEqual(a, b) {
+    return a === b || canonicalizeStyleValue(a) === canonicalizeStyleValue(b);
+}

package/dist/diff.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadStyleMap, isUnder } from './capture.js';
 import { isMapFile } from './map-store.js';
+import { styleValuesEqual } from './canonicalize.js';
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -9,7 +10,10 @@ function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
             continue;
         const before = propsA[prop] ?? fallbackA[prop] ?? unsetA;
         const after = propsB[prop] ?? fallbackB[prop] ?? unsetB;
-        if (before !== after)
+        // Compare by CANONICAL value, so an identical value serialized differently by a
+        // browser/build-tool version (`rgba(8, 18, 32, 0.62)` vs `#0812209e`, comma-spacing in
+        // a font list) is not reported as a change. The report still shows the real strings.
+        if (!styleValuesEqual(before, after))
             changed.push({ prop, before, after });
     }
     return changed;

package/package.json

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