styleproof 3.1.1 → 3.1.2

package/CHANGELOG.md

@@ -7,6 +7,42 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.1.2] - 2026-06-28
+
+### Added
+
+- Documented the sound way to skip StyleProof work: skip the **entire** CI
+  workflow for docs-only / non-rendered paths with native path filters, but do
+  not skip individual surfaces based on changed-file guesses.
+
+### Fixed
+
+- **Live-region detection now respects the surface's `ignore` list.** A region
+  the caller ignored was still scanned for `aria-live`/`role` and surfaced (and
+  persisted into the committed map) as a live-state candidate, unlike every other
+  capture pass which honours the merged `ignore`. Ignored regions are now excluded
+  from `liveCandidates` too.
+- **The scaffolded CI workflow no longer blocks PRs that only add new surfaces.**
+  `styleproof init` generated a workflow that failed on any non-zero diff exit
+  code, so a new-surface-only diff (exit `3`) held the check red and the PR
+  receipt claimed "Visual changes detected" — contradicting the documented
+  contract that new surfaces never block. The gate now fails only on reviewable
+  diffs (exit `1`) and errors (exit `2`), matching `action.yml`, and the receipt
+  reports new surfaces explicitly.
+- **A truncated forced-state layer is no longer silently certified as
+  identical.** When a surface had more interactive elements than
+  `maxInteractive`, capture truncated the `:hover/:focus/:active` layer but left
+  `statesSkipped` unset, so the uncaptured states read as "identical" against a
+  fully-captured side — the exact false-certification the flag exists to prevent.
+  Truncation now sets `statesSkipped`, and the diff reports the layer as "not
+  fully captured" on the affected side.
+- **Release workflow no longer passes an empty `body_path` to the GitHub Release
+  step.** Previously a release whose CHANGELOG version section was absent (e.g. a
+  hotfix tag with no entry) passed `body_path: ''`, which `softprops/action-gh-release`
+  treats as a file to read and fails with ENOENT instead of auto-generating notes.
+  The step is now split into two mutually-exclusive steps: one with
+  `body_path: notes.md`, one with `generate_release_notes: true`.
+
 ## [3.1.1] - 2026-06-27
 
 ### Changed
@@ -922,7 +958,8 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.2...HEAD
+[3.1.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...v3.1.2
 [3.1.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.0...v3.1.1
 [3.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.1...v3.0.2

package/README.md

@@ -234,6 +234,24 @@ Then copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwar
 
 **Prefer to capture in CI instead of committing maps?** For a repo with many outside contributors on different machines, StyleProof can capture **both** base and head in CI and diff them there — no committed maps. See **[Forks and Dependabot](#forks-and-dependabot)** for that flow (it's also the fork-safe split). The committed-map flow above is the default because it's far faster and simpler for a single team.
 
+**Want to skip work safely?** Skip the **whole** StyleProof workflow only for
+changes that cannot affect rendered output, such as docs-only edits, using your
+CI provider's native path filters. Do not skip individual surfaces from a
+StyleProof run based on a changed-file guess: shared CSS, tokens, resets,
+themes, layout primitives, and runtime styling can repaint any surface, and a
+missed surface would certify green without being measured. If you want faster
+feedback, order the highest-signal surfaces first in your spec, but still let
+the full sweep finish before treating the gate as passed.
+
+```yaml
+on:
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - '.github/ISSUE_TEMPLATE/**'
+```
+
 ## Forks and Dependabot
 
 If you **capture in CI** rather than committing maps (the alternative noted at the end of the Quickstart — a better fit when many outside contributors push from different machines), the simplest setup runs the whole gate in one `pull_request` job that captures base + head and diffs them. That job needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.

package/bin/styleproof-init.mjs

@@ -381,8 +381,10 @@ ${PM.setup}
           echo "exit-code=\${code}" >> "$GITHUB_OUTPUT"
           if [ "$code" -eq 0 ]; then
             echo "result=clean" >> "$GITHUB_OUTPUT"
-          elif [ "$code" -eq 1 ] || [ "$code" -eq 3 ]; then
+          elif [ "$code" -eq 1 ]; then
             echo "result=changed" >> "$GITHUB_OUTPUT"
+          elif [ "$code" -eq 3 ]; then
+            echo "result=new" >> "$GITHUB_OUTPUT"
           else
             echo "result=error" >> "$GITHUB_OUTPUT"
           fi
@@ -397,10 +399,13 @@ ${PM.setup}
           script: |
             const issue_number = context.payload.pull_request.number;
             const marker = '<!-- styleproof-report -->';
-            const clean = '\${{ steps.diff.outputs.result }}' === 'clean';
-            const body = clean
-              ? marker + '\\n## 🗺️ StyleProof report\\n\\n✓ No visual changes detected.'
-              : marker + '\\n## 🗺️ StyleProof report\\n\\nVisual changes detected. See the StyleProof check logs for the computed-style diff.';
+            const result = '\${{ steps.diff.outputs.result }}';
+            const bodies = {
+              clean: '✓ No visual changes detected.',
+              new: '🆕 New surface(s) detected — no committed baseline to diff against yet, so nothing to approve. They will be certified once their map is committed.',
+              changed: 'Visual changes detected. See the StyleProof check logs for the computed-style diff.',
+            };
+            const body = marker + '\\n## 🗺️ StyleProof report\\n\\n' + (bodies[result] || bodies.changed);
             const { data: comments } = await github.rest.issues.listComments({
               ...context.repo,
               issue_number,
@@ -413,7 +418,9 @@ ${PM.setup}
               await github.rest.issues.createComment({ ...context.repo, issue_number, body });
             }
       - name: Fail on StyleProof diff
-        if: steps.diff.outputs.exit-code != '0'
+        # Exit 1 = reviewable diffs (gate red); 2 = error. Exit 3 (new surface,
+        # no baseline) never blocks — it has nothing to approve yet.
+        if: steps.diff.outputs.exit-code != '0' && steps.diff.outputs.exit-code != '3'
         shell: bash
         run: exit \${{ steps.diff.outputs.exit-code }}
 `;

package/dist/capture.d.ts

@@ -76,10 +76,11 @@ export type StyleMap = {
     elements: Record<string, ElementEntry>;
     states: Record<string, Record<string, Record<string, Props>>>;
     /**
-     * True when the forced :hover/:focus/:active layer was skipped for this
-     * capture because of CDP/page interactive-element count skew. Persisted so a
-     * diff against a fully-captured side flags that the state layer wasn't
-     * certified, instead of silently reading as "identical".
+     * True when the forced :hover/:focus/:active layer was not fully captured for
+     * this capture — either CDP/page interactive-element count skew, or because the
+     * interactive-element count exceeded `maxInteractive` and capture was truncated.
+     * Persisted so a diff against a fully-captured side flags that the state layer
+     * wasn't certified, instead of silently reading as "identical".
      */
     statesSkipped?: boolean;
     /**

package/dist/capture.js

@@ -375,7 +375,8 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
     const marked = (await page.evaluate(markInteractiveElements, { selector: INTERACTIVE, skipSel, attr: STATE_ID_ATTR })).filter((m) => !(skipPaths.length && isUnder(m.path, skipPaths)));
     const limit = Math.min(marked.length, maxInteractive);
-    if (marked.length > maxInteractive) {
+    const truncated = marked.length > maxInteractive;
+    if (truncated) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${marked.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
             `forced-state capture truncated to the first ${maxInteractive}. Raise maxInteractive to cover them all.`);
@@ -405,7 +406,10 @@ async function captureForcedStates(page, ignore, maxInteractive, skipPaths = [])
         await page.evaluate(clearInteractiveMarks, STATE_ID_ATTR).catch(() => undefined);
         await client.detach();
     }
-    return { states, skipped: false };
+    // When truncated, the elements past the limit have no forced-state delta —
+    // flag the layer so the diff reports it as uncertified instead of letting the
+    // missing states read as "identical" against a fully-captured side.
+    return { states, skipped: truncated };
 }
 /** Element paths that differ between two captures (added, removed, or restyled). */
 function changedElementPaths(a, b) {
@@ -630,7 +634,9 @@ export async function captureStyleMap(page, options = {}) {
     // Detect semantic live-state candidates automatically, but don't exclude them
     // merely for being live regions. Stable status/alert/log UI is product UI and
     // should still be captured; this metadata only improves reports and diagnostics.
-    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore: FRAMEWORK_IGNORE });
+    // Honour the caller's `ignore` too: a region the user excluded shouldn't be
+    // surfaced (or persisted) as a live candidate, matching every other capture pass.
+    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore });
     // Motion longhands (transition/animation) are read separately so declared
     // motion is verified even though every other value is a frozen end state.
     // Read them on the SETTLED DOM, not before it: capturing pre-settle missed any

package/dist/diff.js

@@ -101,8 +101,9 @@ export function diffStyleMaps(a, b) {
         }
     }
     // If the forced-state layer was skipped on exactly one side (CDP skew during
-    // that capture), the :hover/:focus/:active layer was not compared — flag it
-    // loudly rather than letting {} vs {} read as "identical".
+    // capture, or truncation past maxInteractive), the :hover/:focus/:active layer
+    // was not fully compared — flag it loudly rather than letting {} vs {} read as
+    // "identical".
     if (!!a.statesSkipped !== !!b.statesSkipped) {
         findings.push({
             kind: 'state',
@@ -113,8 +114,8 @@ export function diffStyleMaps(a, b) {
             props: [
                 {
                     prop: 'forced :hover/:focus/:active layer',
-                    before: a.statesSkipped ? 'skipped (CDP skew)' : 'captured',
-                    after: b.statesSkipped ? 'skipped (CDP skew)' : 'captured',
+                    before: a.statesSkipped ? 'not fully captured' : 'captured',
+                    after: b.statesSkipped ? 'not fully captured' : 'captured',
                 },
             ],
         });

package/package.json

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