styleproof 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-06-23
+
+### Added
+
+- **Newly-added elements now report their full resting computed style**, not just
+  interaction-state deltas. Previously an added element surfaced only its
+  `:hover`/`:focus` changes (the diff short-circuited added elements before the
+  style loop); its background, padding, font, radius, etc. were captured but never
+  shown. The diff now emits the new element's full style as `(unset) → value`
+  findings and the report renders them value-only (no bogus "Before" column), in
+  both the PR report and the `styleproof-diff` CLI. The element already gated via
+  its `added` finding, so this enriches detail without changing what gates.
+- **`captureComponent` (opt-in, default off): surface the React component + props**
+  behind each element. With it on, capture reads the React fiber in-page
+  (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on
+  ≤16) to record the component display name and a sanitized subset of its props
+  (primitives only; `children`/handlers/objects dropped) on `ElementEntry.component`.
+  The report names it — `React component: Button (variant=primary, size=sm)` —
+  instead of a bare `<button>`. **Advisory only**, exactly like the content layer:
+  never fed to the certification diff or its blocking counts, so captures stay
+  deterministic. Names are mangled in minified prod builds, so it's most useful
+  against dev/non-minified output; a no-op on non-React pages.
+
 ## [2.1.0] - 2026-06-23
 
 ### Added

package/README.md

@@ -228,6 +228,23 @@ The report then carries a separate **📝 Content changes (advisory)** section:
 
 Notes: only an element's _own_ text is recorded (so a parent and child never double-report the same string); text churn in a live region is auto-excluded by the same settle pass that guards styles; and the certification CLI (`styleproof-diff`) is deliberately left content-blind.
 
+## Optional: React component layer (advisory)
+
+For a React app, knowing _which component_ rendered an element is often the fastest way to read a change. Off by default, opt in with `captureComponent`:
+
+```ts
+// styleproof.spec.ts — record the React component + props behind each element
+defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR, captureComponent: true });
+```
+
+Capture reads the React fiber in-page (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on ≤16) and records the component display name plus a **sanitized** subset of its props (primitives only — `children`, handlers, and objects are dropped) on `ElementEntry.component`. The report then names the element — **`React component: Button (variant=primary, size=sm)`** — instead of showing a bare `<button>`.
+
+Like the content layer it is **advisory**: never fed to the certification diff or the gate, so captures stay deterministic. Component names are mangled in minified production builds, so it's most useful against a dev / non-minified target; on a non-React page the fiber keys are absent and the field is simply omitted.
+
+## Newly-added elements show their full style
+
+When a PR **adds** an element, StyleProof now reports its **full resting computed style** (background, padding, font, radius, …), value-only, in addition to any interaction-state deltas — previously an added element surfaced only its `:hover`/`:focus` changes. The new element already gates via its `added` finding; this only enriches what you see, in both the report and the `styleproof-diff` CLI.
+
 ## Reference
 
 **Action `BenSheridanEdwards/StyleProof@v2`** — key inputs:

package/dist/capture.d.ts

@@ -42,6 +42,18 @@ export type ElementEntry = {
      * advisory, not a computed-style outcome. See README "Optional: content layer".
      */
     text?: string;
+    /**
+     * The React component that rendered this element, and a sanitized subset of its
+     * props — present only when capture ran with `captureComponent: true` (opt-in,
+     * off by default). Extracted in-page from the React fiber. ADVISORY: never fed
+     * to the certification diff or its counts (like {@link ElementEntry.text}); it
+     * only enriches the report so a reviewer sees `Button (variant=primary)` rather
+     * than a bare `<button>`. Best in dev/non-minified builds (prod mangles names).
+     */
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 };
 export type StyleMap = {
     defaults: Record<string, Props>;
@@ -137,6 +149,19 @@ export type CaptureOptions = {
      * guards styles, since text now participates in change detection.
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). When true, each element records the React
+     * component that rendered it (display name) and a sanitized subset of its props
+     * on {@link ElementEntry.component}, read in-page from the React fiber
+     * (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*`
+     * on ≤16). Lets the report name `Button (variant=primary)` instead of a bare
+     * `<button>`. ADVISORY — like `captureText` it never feeds the certification
+     * diff or its blocking counts. Only primitive props (string/number/boolean) are
+     * kept (children/handlers/objects dropped); names are mangled in minified prod
+     * builds, so this is most useful against dev/non-minified output. No-op on
+     * non-React pages (fiber keys absent → field omitted).
+     */
+    captureComponent?: boolean;
     /**
      * Advanced/internal: a getter for the count of in-flight data requests, supplied by
      * a tracker ({@link trackInflightRequests}) armed BEFORE navigation so the page's own

package/dist/capture.js

@@ -30,15 +30,12 @@ const FRAMEWORK_IGNORE = [
 export function isUnder(path, roots) {
     return roots.some((r) => path === r || path.startsWith(r + ' > '));
 }
-// Serialized into the browser by page.evaluate; cannot call module helpers.
-// Pre-existing, grandfathered in the health baseline; the content layer adds
-// one small captureText block, not new structure.
-// fallow-ignore-next-line complexity
-function capturePage({ ignore, motionOnly, captureText }) {
-    const MOTION = /^(transition|animation)/;
-    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
-    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    const pathOf = (el) => {
+// Defines the structural-path helper on `window` once so the two functions
+// serialized into the page (capturePage, markInteractiveElements) share ONE
+// implementation — page.evaluate can't reference a module-scope helper, so the
+// alternative is an identical copy in each. Injected at the top of captureStyleMap.
+function injectPathOf() {
+    window.__spPathOf = (el) => {
         if (el === document.documentElement)
             return 'html';
         if (el === document.body)
@@ -54,6 +51,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return 'body > ' + parts.join(' > ');
     };
+}
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+// Pre-existing, grandfathered in the health baseline; the content layer adds
+// one small captureText block, not new structure.
+// fallow-ignore-next-line complexity
+function capturePage({ ignore, motionOnly, captureText, captureComponent }) {
+    const MOTION = /^(transition|animation)/;
+    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const pathOf = window.__spPathOf;
     // Per-tag (and per-tag-per-pseudo) UA defaults from a stylesheet-free iframe,
     // used to prune the maps. A pseudo-element's UA defaults are NOT the host
     // element's defaults, so they are measured and cached separately under a
@@ -96,6 +103,53 @@ function capturePage({ ignore, motionOnly, captureText }) {
         }
         return o;
     };
+    // Display name from a fiber `type`: function/class, or a forwardRef/memo wrapper
+    // object; '' for host fibers (string type), which keeps the walk going upward.
+    const nameOfType = (t) => {
+        if (typeof t === 'function') {
+            const f = t;
+            return f.displayName || f.name || '';
+        }
+        if (t && typeof t === 'object') {
+            const w = t;
+            const inner = w.render || w.type;
+            return w.displayName || inner?.displayName || inner?.name || '';
+        }
+        return '';
+    };
+    // Keep only primitive props (drop children/className/style/handlers/objects),
+    // capped — advisory, so never anything that could be huge or non-serializable.
+    const sanitizeProps = (mp) => {
+        const props = {};
+        for (const k of Object.keys(mp)) {
+            if (k === 'children' || k === 'className' || k === 'style')
+                continue;
+            const ty = typeof mp[k];
+            if (ty === 'string' || ty === 'number' || ty === 'boolean')
+                props[k] = String(mp[k]).slice(0, 80);
+        }
+        return props;
+    };
+    const reactComponent = (el) => {
+        const fiberKey = Object.keys(el).find((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'));
+        if (!fiberKey)
+            return undefined;
+        let fiber = el[fiberKey] ?? null;
+        for (let hops = 0; fiber && hops < 30; fiber = fiber.return, hops++) {
+            const name = nameOfType(fiber.type);
+            if (!name || name === 'Symbol(react.fragment)')
+                continue;
+            const out = { name };
+            const mp = fiber.memoizedProps;
+            if (mp && typeof mp === 'object') {
+                const props = sanitizeProps(mp);
+                if (Object.keys(props).length)
+                    out.props = props;
+            }
+            return out;
+        }
+        return undefined;
+    };
     const elements = {};
     const all = [document.documentElement, document.body, ...document.querySelectorAll('body *')];
     // Surface untraversed shadow roots and same-origin iframes so a refactor
@@ -147,6 +201,16 @@ function capturePage({ ignore, motionOnly, captureText }) {
                 if (t)
                     entry.text = t;
             }
+            if (captureComponent) {
+                try {
+                    const comp = reactComponent(el);
+                    if (comp)
+                        entry.component = comp;
+                }
+                catch {
+                    // non-React node or inaccessible fiber — component stays absent
+                }
+            }
         }
         for (const ps of PSEUDOS) {
             if (ps === '::marker' && getComputedStyle(el).display !== 'list-item')
@@ -233,22 +297,7 @@ const STATE_ID_ATTR = 'data-styleproof-state-id';
  * but different ordering, which produces phantom forced-state diffs.
  */
 function markInteractiveElements({ selector, skipSel, attr }) {
-    const pathOf = (el) => {
-        if (el === document.documentElement)
-            return 'html';
-        if (el === document.body)
-            return 'body';
-        const parts = [];
-        let n = el;
-        while (n && n !== document.body) {
-            const parent = n.parentElement;
-            if (!parent)
-                break;
-            parts.unshift(`${n.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, n) + 1})`);
-            n = parent;
-        }
-        return 'body > ' + parts.join(' > ');
-    };
+    const pathOf = window.__spPathOf;
     let i = 0;
     return [...document.querySelectorAll(selector)].flatMap((el) => {
         if (skipSel && el.matches(skipSel))
@@ -497,6 +546,7 @@ export async function captureStyleMap(page, options = {}) {
     const maxInteractive = options.maxInteractive ?? 800;
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
+    const captureComponent = options.captureComponent ?? false;
     // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
     // whatever element holds focus so every read below is the no-interaction
     // resting state. Real :focus is nondeterministic across runs (autofocus, late
@@ -507,6 +557,11 @@ export async function captureStyleMap(page, options = {}) {
     // deterministic" failure). Interaction states are certified deterministically
     // via CDP forcePseudoState below, never via whatever happened to be focused.
     await page.evaluate(() => document.activeElement?.blur?.());
+    // Inject the structural-path helper once so both capturePage and
+    // markInteractiveElements (each serialized into the page by page.evaluate, which
+    // can't share a module-scope function) call ONE definition — no duplicated source.
+    // It persists on `window` for every evaluate below (no navigation between them).
+    await page.evaluate(injectPathOf);
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
     // Motion never carries text — it's a settled end state of declared motion.
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
@@ -516,7 +571,7 @@ export async function captureStyleMap(page, options = {}) {
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
     const volatile = await detectVolatile(page, ignore, stabilize, captureText, options.pendingRequests);
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText });
+    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);
     mergeMotion(base.elements, motion.elements);

package/dist/diff.d.ts

@@ -15,6 +15,10 @@ export type Finding = {
     cls: string;
     change: 'added' | 'removed' | 'retagged';
     detail?: string;
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 } | {
     kind: 'style';
     path: string;

package/dist/diff.js

@@ -35,11 +35,39 @@ export function diffStyleMaps(a, b) {
         const ea = a.elements[p];
         const eb = b.elements[p];
         if (!ea || !eb) {
-            findings.push({ kind: 'dom', path: p, cls: (ea ?? eb).cls, change: !ea ? 'added' : 'removed' });
+            const present = (ea ?? eb);
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: present.cls,
+                change: !ea ? 'added' : 'removed',
+                ...(!ea && eb.component ? { component: eb.component } : {}),
+            });
+            // An added element has no "before", so the style loop below is skipped —
+            // surface its full resting computed style (+ pseudos) as (unset)→value so a
+            // new element's styling is reviewable, not just its interaction-state
+            // deltas. Removed elements get none (there is no "after" to show).
+            if (!ea && eb) {
+                const defsB = b.defaults[eb.tag] ?? {};
+                for (const pseudo of [null, ...Object.keys(eb.pseudo ?? {})]) {
+                    const propsB = pseudo ? (eb.pseudo?.[pseudo] ?? {}) : eb.style;
+                    const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
+                    const props = diffProps({}, propsB, {}, pdefsB, '(unset)', '(unset)');
+                    if (props.length)
+                        findings.push({ kind: 'style', path: p, cls: eb.cls, pseudo, props });
+                }
+            }
             continue;
         }
         if (ea.tag !== eb.tag) {
-            findings.push({ kind: 'dom', path: p, cls: ea.cls, change: 'retagged', detail: `<${ea.tag}> → <${eb.tag}>` });
+            findings.push({
+                kind: 'dom',
+                path: p,
+                cls: ea.cls,
+                change: 'retagged',
+                detail: `<${ea.tag}> → <${eb.tag}>`,
+                ...(eb.component ? { component: eb.component } : {}),
+            });
             continue;
         }
         const defsA = a.defaults[ea.tag] ?? {};

package/dist/report.js

@@ -432,12 +432,51 @@ function beforeAfterTable(rows) {
         ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.before)} | ${cell(r.after)} |`),
     ];
 }
+// A brand-new element has no meaningful "before", so its resting style renders
+// value-only (the After column), mirroring the added-element interaction-states table.
+function valueTable(rows) {
+    return ['| Property | Value |', '| --- | --- |', ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.after)} |`)];
+}
+/** `Button (variant=primary, size=sm)` — the React component + sanitized props
+ *  the element captured (advisory; present only with captureComponent). */
+function renderComponent(c) {
+    const entries = Object.entries(c.props ?? {});
+    const props = entries.length ? ` (${entries.map(([k, v]) => `${k}=${v}`).join(', ')})` : '';
+    return `\`${c.name}\`${props}`;
+}
 /** One element's heading + body lines (no leading blank, no ×N suffix). */
+// Base/pseudo style rows. Added elements render value-only (no meaningful before).
+function styleSection(styles, added) {
+    const out = [];
+    for (const s of styles) {
+        const rows = summarizeProps(s.props);
+        if (rows.length)
+            out.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...(added ? valueTable(rows) : beforeAfterTable(rows)));
+    }
+    return out;
+}
+// Forced :hover/:focus/:active rows. Added: value-only; changed: before → after.
+function statesSection(states, added) {
+    const rows = [];
+    for (const st of states)
+        for (const c of summarizeProps(st.props))
+            rows.push(added
+                ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
+                : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
+    if (!rows.length)
+        return [];
+    return [
+        '',
+        added ? 'Interactive states:' : 'Interactive-state changes:',
+        '',
+        added ? '| State | Property | Value |' : '| State | Property | Before → After |',
+        '| --- | --- | --- |',
+        ...rows,
+    ];
+}
 function renderOneElement(group) {
     const label = prettyLabel(group[0].path, group[0].cls);
     const dom = group.find((f) => f.kind === 'dom');
-    const styles = group.filter((f) => f.kind === 'style');
-    const states = group.filter((f) => f.kind === 'state');
     if (dom?.change === 'removed')
         return { head: `**Removed** \`${label}\``, body: [] };
     const added = dom?.change === 'added';
@@ -447,21 +486,12 @@ function renderOneElement(group) {
             ? `**Retagged** \`${label}\` ${dom.detail ?? ''}`
             : `**\`${label}\`**`;
     const body = [];
-    for (const s of styles) {
-        const rows = summarizeProps(s.props);
-        if (rows.length)
-            body.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...beforeAfterTable(rows));
-    }
-    if (states.length) {
-        const rows = [];
-        for (const st of states)
-            for (const c of summarizeProps(st.props))
-                rows.push(added
-                    ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
-                    : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
-        if (rows.length)
-            body.push('', added ? 'Interactive states:' : 'Interactive-state changes:', '', added ? '| State | Property | Value |' : '| State | Property | Before → After |', '| --- | --- | --- |', ...rows);
-    }
+    // React component that rendered the element (added/retagged carry it on the dom
+    // finding) — surfaced first so a reviewer sees `Button (variant=primary)`.
+    if (dom?.component)
+        body.push('', `React component: ${renderComponent(dom.component)}`);
+    body.push(...styleSection(group.filter((f) => f.kind === 'style'), added));
+    body.push(...statesSection(group.filter((f) => f.kind === 'state'), added));
     // Existing element with nothing left to show (all derived) → skip; an
     // added/removed/retagged element always renders its heading.
     if (!dom && !body.length)
@@ -584,6 +614,10 @@ function cleanFindings(findings) {
     for (const group of groupByPath(findings)) {
         const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
         const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        // For an ADDED element the base style is a full (unset)→value snapshot, not a
+        // delta — so a forced-state value is never an "echo" of a base *change*; keep
+        // every state row (suppressing them would drop a real :hover/:focus value).
+        const isAdded = group.some((f) => f.kind === 'dom' && f.change === 'added');
         for (const f of group) {
             if (f.kind === 'dom') {
                 out.push(f);
@@ -591,7 +625,9 @@ function cleanFindings(findings) {
             }
             const props = f.kind === 'style'
                 ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
-                : f.props.filter((p) => !STATE_STRIP.has(p.prop) && !baseChanged.has(p.prop) && !(isNonValue(p.before) && isNonValue(p.after)));
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) &&
+                    (isAdded || !baseChanged.has(p.prop)) &&
+                    !(isNonValue(p.before) && isNonValue(p.after)));
             if (props.length)
                 out.push({ ...f, props });
         }

package/dist/runner.d.ts

@@ -98,6 +98,12 @@ export type DefineOptions = {
      * `CaptureOptions.captureText` and the README's "Optional: content layer".
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). Record the component + sanitized props that
+     * rendered each element so the report can name `Button (variant=primary)`.
+     * Advisory only — never gates. See `CaptureOptions.captureComponent`.
+     */
+    captureComponent?: boolean;
 };
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
@@ -135,4 +141,4 @@ export declare function defaultSelfCheck(replayFrom: string | undefined, env?: s
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, expected, exclude, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;
+export declare function defineStyleMapCapture({ surfaces, expected, exclude, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, captureComponent, }: DefineOptions): void;

package/dist/runner.js

@@ -96,6 +96,7 @@ async function captureSurface(page, surface, width, s) {
         const map = await captureStyleMap(page, {
             ignore: surface.ignore ?? [],
             captureText: s.captureText,
+            captureComponent: s.captureComponent,
             pendingRequests: requests.pending,
         });
         if (s.selfCheck)
@@ -135,7 +136,7 @@ export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCH
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = defaultSelfCheck(replayFrom), captureText = false, }) {
+export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = defaultSelfCheck(replayFrom), captureText = false, captureComponent = false, }) {
     const settings = {
         dir: dir,
         baseDir,
@@ -146,6 +147,7 @@ export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, b
         clockTime,
         selfCheck,
         captureText,
+        captureComponent,
     };
     // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
     // a route added without a surface fails the app's own tests — long before, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.1.0",
+  "version": "2.2.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",
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",