styleproof 1.9.0 → 1.9.3

package/CHANGELOG.md

@@ -7,6 +7,29 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.9.3]
+
+### Changed
+
+- Maintainer contact moved off a personal email address: security issues now go
+  through GitHub's private vulnerability reporting and conduct reports through the
+  maintainer's GitHub profile, and the `package.json` `author` no longer carries an
+  email. The published package and its metadata are now contact-clean.
+- Canonical `StyleProof`-cased GitHub URLs in `package.json` (`homepage`,
+  `repository`, `bugs`).
+
+### Fixed
+
+- The README demo image now uses an absolute `raw.githubusercontent.com` URL so it
+  renders on the npm package page — relative paths don't resolve there, so the image
+  showed broken on npmjs.com.
+
+## [1.9.1]
+
+### Fixed
+
+- **Framework / non-visual DOM noise no longer registers as a change.** Capture now skips a built-in default set of selectors — `<meta>`, `<title>`, `<link>`, `<script>`, `<style>`, `<base>`, `<noscript>`, `<template>`, and `next-route-announcer` — merged into (not replaced by) the caller's `ignore`. These are elements frameworks stream into the body and reorder (Next.js app-router injects metadata then hoists it) or inject as live regions (Next's a11y route announcer), with no visual box to diff; their churn was surfacing as phantom DOM-added/removed findings on PRs that changed no CSS. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. _Note: this changes the captured element set slightly — re-baseline once after upgrading._
+
 ## [1.9.0]
 
 ### Added

package/README.md

@@ -23,7 +23,7 @@ On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base br
 
 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)
+![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)
 
 As it renders in the PR comment (a plain-English bullet first — naming the theme token and showing the hex with a live colour swatch — then the exact table inside the toggle):
 
@@ -127,6 +127,7 @@ jobs:
 - **Record / replay.** The base capture records each surface's data responses (anything matching `**/api/**`) to a HAR; the head capture replays them, so the head renders _its_ code against the _base's_ data — the app's own JS/CSS still load live. Backend down during a run? Both sides replay the same recording, so there's no phantom diff. Point the head capture at the base's recording with `STYLEPROOF_REPLAY_FROM=<base dir>` (see the CI step above); tune the data boundary with `STYLEPROOF_REPLAY_URL` / `replayUrl` if your API isn't under `/api`.
 - **Frozen clock.** `Date.now()` / `new Date()` are pinned to a fixed instant, so time-derived styling (`stale > 1h → red`) can't drift. Timers keep running, so settling still works.
 - **Self-check** (`STYLEPROOF_SELFCHECK=1`). Captures each surface twice and fails if they differ — a replay gap or unseeded randomness surfaces as a clear _"non-deterministic capture"_ error, never as a phantom change on an unrelated PR.
+- **Framework noise is skipped by default.** Non-visual and framework-injected elements never count as a change — `<meta>`/`<title>`/`<script>`/`<style>`/… (which Next.js streams into the body then hoists) and live regions like Next's `next-route-announcer`. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. Add your own selectors with `ignore` — they extend this default, they don't replace it.
 
 > Replay covers data the page _fetches_. If your app **server-renders** differently per environment (SSR feature flags, locale), still capture both sides with the same server env so the rendered HTML matches.
 
@@ -146,6 +147,31 @@ jobs:
 
 Outputs: `changed` (`"true"` when anything changed), `report-url`. Other inputs (`report-branch`, `inline-images`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/styleproof/blob/main/action.yml).
 
+**Capture spec `defineStyleMapCapture({ surfaces, … })`** — determinism is on by default; you rarely set more than `surfaces` and `dir`:
+
+| Option        | Default                     | Purpose                                                                                                          |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths, ignore?, height? }`. `go(page)` drives to a settled state.     |
+| `dir`         | `STYLEMAP_DIR`              | Output label (`base`/`head`); the spec is **inert until set**, so it sits safely beside your other specs.        |
+| `replayFrom`  | `STYLEPROOF_REPLAY_FROM`    | Baseline dir whose recorded responses to replay. Unset → this run **records** its HAR for the comparison to use. |
+| `replayUrl`   | `**/api/**` (`…REPLAY_URL`) | URL glob for the data boundary to record/replay; everything else (JS/CSS/fonts) loads live so the code runs.     |
+| `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.  |
+| `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                              |
+| `selfCheck`   | `STYLEPROOF_SELFCHECK=1`    | Capture each surface twice and fail on any difference — proves the capture is deterministic.                     |
+| `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                  |
+| `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                           |
+
+Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<style>`/… and `next-route-announcer`) are skipped automatically; a surface's `ignore` adds to that default, it doesn't replace it.
+
+**Capture env vars** (wire CI without editing the spec):
+
+| Env                      | Purpose                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| `STYLEMAP_DIR`           | Output label; the capture is skipped entirely when unset.                     |
+| `STYLEPROOF_REPLAY_FROM` | Baseline dir to replay recorded data from — set this on the **head** capture. |
+| `STYLEPROOF_REPLAY_URL`  | Override the `**/api/**` data-boundary glob.                                  |
+| `STYLEPROOF_SELFCHECK`   | `1` to capture each surface twice and fail if the two differ.                 |
+
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
 - `styleproof-init` — scaffold the capture spec (and a starter `playwright.config.ts` if none exists).

package/dist/capture.d.ts

@@ -65,9 +65,11 @@ export type StyleMap = {
 export type CaptureOptions = {
     /**
      * Selectors for nondeterministic regions (live data, embeds, ads). The
-     * matching elements and their descendants are skipped entirely. Usually
-     * unnecessary now that `stabilize` auto-detects live regions; use it to skip
-     * a region you know is volatile without paying the settle wait for it.
+     * matching elements and their descendants are skipped entirely. Added to a
+     * built-in default that skips framework/non-visual noise (`<meta>`/`<title>`/
+     * `<script>`/`<style>`/… and `next-route-announcer`), so you rarely need it —
+     * `stabilize` also auto-detects live regions. Use it to skip a region you know
+     * is volatile without paying the settle wait for it.
      */
     ignore?: string[];
     /**

package/dist/capture.js

@@ -5,6 +5,26 @@ const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"
 // Freeze motion so every captured value is a settled end state, not a frame
 // of an animation or a mid-flight transition after a forced :hover.
 const FREEZE_CSS = '*,*::before,*::after{animation:none!important;transition:none!important}';
+// Always skipped, merged into the caller's `ignore`. Two kinds of noise that
+// are never a visual change worth gating on but churn the DOM between runs:
+//   - non-rendered elements frameworks stream into <body> then hoist (Next.js
+//     app-router injects <meta>/<title>/<link>); they have no box to style, and
+//     their presence/order is nondeterministic. A real stylesheet change still
+//     shows up in the affected elements' computed styles, not in the <style> tag.
+//   - framework-injected live regions / overlays that mount and reorder on their
+//     own (Next.js's a11y route announcer — already a known source of CDP skew).
+const FRAMEWORK_IGNORE = [
+    'meta',
+    'title',
+    'link',
+    'script',
+    'style',
+    'base',
+    'noscript',
+    'template',
+    'next-route-announcer',
+    '[id="__next-route-announcer__"]',
+];
 /** True if `path` is one of `roots` or a structural descendant of one. Shared by
  *  the capture (excluding live regions) and the diff (skipping them). */
 export function isUnder(path, roots) {
@@ -328,6 +348,51 @@ function capturePageTokens() {
     probe.remove();
     return tokens;
 }
+/** Settle the page and return the paths of live regions to exclude. */
+async function detectVolatile(page, ignore, stabilize) {
+    if (stabilize === false)
+        return [];
+    const opt = typeof stabilize === 'object' ? stabilize : {};
+    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000);
+    if (volatile.length) {
+        // eslint-disable-next-line no-console
+        console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
+            'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
+            'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+    }
+    return volatile;
+}
+/** Drop live regions (and their subtrees) from the base capture, in Node so the
+ *  serialized capturePage stays a pure snapshot. */
+function dropVolatile(elements, volatile) {
+    if (!volatile.length)
+        return;
+    for (const p of Object.keys(elements))
+        if (isUnder(p, volatile))
+            delete elements[p];
+}
+/** Warn once when shadow roots / iframes were skipped (their styles aren't captured or diffed). */
+function warnUntraversed(shadowHosts, sameOriginFrames) {
+    if (!shadowHosts && !sameOriginFrames)
+        return;
+    // eslint-disable-next-line no-console
+    console.warn(`styleproof: ${shadowHosts} shadow host(s) and ${sameOriginFrames} same-origin iframe(s) were ` +
+        'NOT traversed — styles inside shadow roots and frames are not captured or diffed. A refactor inside ' +
+        'one would be reported as identical. See README "Limitations".');
+}
+/** Fold the pre-freeze motion longhands back onto the settled base capture. */
+function mergeMotion(elements, motion) {
+    for (const [p, entry] of Object.entries(elements)) {
+        const m = motion[p];
+        if (!m)
+            continue;
+        Object.assign(entry.style, m.style);
+        for (const [ps, props] of Object.entries(m.pseudo ?? {})) {
+            if (entry.pseudo?.[ps])
+                Object.assign(entry.pseudo[ps], props);
+        }
+    }
+}
 /**
  * Capture the page's complete style map. Drive the page to the state you want
  * first (navigate, open menus); by default the capture then auto-settles the
@@ -335,7 +400,9 @@ function capturePageTokens() {
  * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export async function captureStyleMap(page, options = {}) {
-    const ignore = options.ignore ?? [];
+    // Framework/non-visual noise is always skipped, so it can't read as a DOM
+    // change; the caller's `ignore` adds to it (not replaces it).
+    const ignore = [...FRAMEWORK_IGNORE, ...(options.ignore ?? [])];
     const captureStates = options.captureStates ?? true;
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
@@ -346,43 +413,11 @@ export async function captureStyleMap(page, options = {}) {
     // the same loaded state, and collect any region still changing on its own
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
-    let volatile = [];
-    if (stabilize !== false) {
-        const opt = typeof stabilize === 'object' ? stabilize : {};
-        const interval = opt.interval || 150;
-        const quietFor = opt.quietFor || 600;
-        const timeout = opt.timeout || 5000;
-        volatile = await stabilizePage(page, ignore, interval, quietFor, timeout);
-        if (volatile.length) {
-            // eslint-disable-next-line no-console
-            console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
-                'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
-                'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
-        }
-    }
+    const volatile = await detectVolatile(page, ignore, stabilize);
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false });
-    // Drop live regions (and their subtrees) detected by the settle pass — done
-    // here, in Node, so the serialized capturePage stays a pure snapshot.
-    if (volatile.length)
-        for (const p of Object.keys(base.elements))
-            if (isUnder(p, volatile))
-                delete base.elements[p];
-    if (base.shadowHosts || base.sameOriginFrames) {
-        // eslint-disable-next-line no-console
-        console.warn(`styleproof: ${base.shadowHosts} shadow host(s) and ${base.sameOriginFrames} same-origin iframe(s) were ` +
-            'NOT traversed — styles inside shadow roots and frames are not captured or diffed. A refactor inside ' +
-            'one would be reported as identical. See README "Limitations".');
-    }
-    for (const [p, entry] of Object.entries(base.elements)) {
-        const m = motion.elements[p];
-        if (!m)
-            continue;
-        Object.assign(entry.style, m.style);
-        for (const [ps, props] of Object.entries(m.pseudo ?? {})) {
-            if (entry.pseudo?.[ps])
-                Object.assign(entry.pseudo[ps], props);
-        }
-    }
+    dropVolatile(base.elements, volatile);
+    warnUntraversed(base.shadowHosts, base.sameOriginFrames);
+    mergeMotion(base.elements, motion.elements);
     let states = {};
     let statesSkipped = false;
     if (captureStates) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.9.0",
+  "version": "1.9.3",
   "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",
@@ -16,14 +16,14 @@
     "ci"
   ],
   "license": "MIT",
-  "author": "Ben Sheridan-Edwards <ben@codewalnut.com>",
-  "homepage": "https://github.com/BenSheridanEdwards/styleproof#readme",
+  "author": "Ben Sheridan-Edwards",
+  "homepage": "https://github.com/BenSheridanEdwards/StyleProof#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BenSheridanEdwards/styleproof.git"
+    "url": "git+https://github.com/BenSheridanEdwards/StyleProof.git"
   },
   "bugs": {
-    "url": "https://github.com/BenSheridanEdwards/styleproof/issues"
+    "url": "https://github.com/BenSheridanEdwards/StyleProof/issues"
   },
   "type": "module",
   "main": "./dist/index.js",