styleproof 1.0.0

package/dist/capture.js

@@ -0,0 +1,323 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { gzipSync, gunzipSync } from 'node:zlib';
+const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"], [tabindex]';
+// 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}';
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+function capturePage({ ignore, motionOnly }) {
+    const MOTION = /^(transition|animation)/;
+    const PSEUDOS = ['::before', '::after', '::marker', '::placeholder'];
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    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(' > ');
+    };
+    // 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
+    // composite key (e.g. `li::marker`) — pruning a pseudo against the wrong
+    // baseline can both drop real changes and bloat the file.
+    const frame = document.createElement('iframe');
+    frame.style.cssText = 'position:absolute;left:-9999px;width:100px;height:100px;border:0';
+    document.body.appendChild(frame);
+    const fdoc = frame.contentDocument;
+    const defaults = {};
+    const probeCache = {};
+    const probeFor = (tag) => {
+        if (!(tag in probeCache)) {
+            const probe = fdoc.createElement(tag);
+            fdoc.body.appendChild(probe);
+            probeCache[tag] = probe;
+        }
+        return probeCache[tag];
+    };
+    const defaultFor = (tag, pseudo) => {
+        const key = pseudo ? `${tag}${pseudo}` : tag;
+        if (!(key in defaults)) {
+            const cs = fdoc.defaultView.getComputedStyle(probeFor(tag), pseudo ?? null);
+            const o = {};
+            for (let i = 0; i < cs.length; i++)
+                o[cs.item(i)] = cs.getPropertyValue(cs.item(i));
+            defaults[key] = o;
+        }
+        return defaults[key];
+    };
+    const snap = (cs, def) => {
+        const o = {};
+        for (let i = 0; i < cs.length; i++) {
+            const p = cs.item(i);
+            if (motionOnly !== MOTION.test(p))
+                continue;
+            const v = cs.getPropertyValue(p);
+            if (!def || def[p] !== v)
+                o[p] = v;
+        }
+        return o;
+    };
+    const elements = {};
+    const all = [document.documentElement, document.body, ...document.querySelectorAll('body *')];
+    // Surface untraversed shadow roots and same-origin iframes so a refactor
+    // inside one is not silently certified identical (see file header).
+    let shadowHosts = 0;
+    let sameOriginFrames = 0;
+    for (const el of all) {
+        if (el === frame || (skipSel && el.matches(skipSel)))
+            continue;
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'script' || tag === 'style' || tag === 'link' || tag === 'noscript')
+            continue;
+        if (!motionOnly && el.shadowRoot)
+            shadowHosts++;
+        if (!motionOnly && (tag === 'iframe' || tag === 'frame')) {
+            try {
+                if (el.contentDocument)
+                    sameOriginFrames++;
+            }
+            catch {
+                // cross-origin: genuinely untraversable, not counted
+            }
+        }
+        const entry = {
+            tag,
+            cls: el.getAttribute('class') || '',
+            style: snap(getComputedStyle(el), defaultFor(tag)),
+        };
+        if (!motionOnly) {
+            // Document-space box so report crops can locate the element in a
+            // full-page screenshot regardless of scroll position at capture time.
+            const r = el.getBoundingClientRect();
+            entry.rect = [
+                Math.round(r.x + window.scrollX),
+                Math.round(r.y + window.scrollY),
+                Math.round(r.width),
+                Math.round(r.height),
+            ];
+        }
+        for (const ps of PSEUDOS) {
+            if (ps === '::marker' && getComputedStyle(el).display !== 'list-item')
+                continue;
+            if (ps === '::placeholder' && !(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement))
+                continue;
+            const cs = getComputedStyle(el, ps);
+            if ((ps === '::before' || ps === '::after') && cs.getPropertyValue('content') === 'none')
+                continue;
+            const props = snap(cs, defaultFor(tag, ps));
+            if (Object.keys(props).length)
+                (entry.pseudo ??= {})[ps] = props;
+        }
+        elements[pathOf(el)] = entry;
+    }
+    frame.remove();
+    return { defaults, elements, shadowHosts, sameOriginFrames };
+}
+/** Full (unpruned) computed styles for an element and its descendants, pseudo-elements included. */
+// Serialized into the browser by page.evaluate; cannot call module helpers.
+function snapSubtree({ selector, index }) {
+    const el = document.querySelectorAll(selector)[index];
+    const pathOf = (n) => {
+        if (n === document.documentElement)
+            return 'html';
+        if (n === document.body)
+            return 'body';
+        const parts = [];
+        let c = n;
+        while (c && c !== document.body) {
+            const parent = c.parentElement;
+            if (!parent)
+                break;
+            parts.unshift(`${c.tagName.toLowerCase()}:nth-child(${Array.prototype.indexOf.call(parent.children, c) + 1})`);
+            c = parent;
+        }
+        return 'body > ' + parts.join(' > ');
+    };
+    const out = {};
+    if (!el)
+        return out;
+    for (const n of [el, ...el.querySelectorAll('*')]) {
+        for (const ps of [null, '::before', '::after']) {
+            const cs = getComputedStyle(n, ps);
+            if (ps && cs.getPropertyValue('content') === 'none')
+                continue;
+            const o = {};
+            for (let i = 0; i < cs.length; i++) {
+                const p = cs.item(i);
+                if (/^(transition|animation)/.test(p))
+                    continue; // frozen by FREEZE_CSS
+                o[p] = cs.getPropertyValue(p);
+            }
+            out[pathOf(n) + (ps || '')] = o;
+        }
+    }
+    return out;
+}
+function deltaBetween(base, forced) {
+    const delta = {};
+    for (const key of new Set([...Object.keys(base), ...Object.keys(forced)])) {
+        const a = base[key] || {};
+        const b = forced[key] || {};
+        const d = {};
+        for (const p of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            if (a[p] !== b[p])
+                d[p] = b[p] ?? '(gone)';
+        }
+        if (Object.keys(d).length)
+            delta[key] = d;
+    }
+    return delta;
+}
+const STATE_SETS = {
+    hover: ['hover'],
+    focus: ['focus', 'focus-visible'],
+    active: ['active'],
+};
+/** Structural paths for every selector match, index-aligned with CDP's DOM.querySelectorAll. */
+function pathsForSelector({ selector, skipSel }) {
+    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(' > ');
+    };
+    return [...document.querySelectorAll(selector)].map((el) => (skipSel && el.matches(skipSel) ? null : pathOf(el)));
+}
+// Forced pseudo-class states on interactive elements, via CDP so no real
+// mouse or focus is involved and parent-state descendant rules still apply.
+async function captureForcedStates(page, ignore, maxInteractive) {
+    const client = await page.context().newCDPSession(page);
+    await client.send('DOM.enable');
+    await client.send('CSS.enable');
+    const { root } = await client.send('DOM.getDocument');
+    const { nodeIds } = await client.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector: INTERACTIVE });
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const paths = await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel });
+    // The CDP DOM snapshot and the live querySelectorAll are two separate,
+    // non-atomic reads. They can legitimately disagree — display:contents,
+    // nodes detached or injected between the two calls (next-route-announcer,
+    // Playwright internals, late hydration adding [tabindex]). A mismatch is NOT
+    // a fatal error: positional nodeId↔path alignment is only valid when the
+    // counts agree, so on skew we warn and skip the forced-state layer for this
+    // surface rather than aborting the whole capture (base + pseudo layers,
+    // the load-bearing certification, still succeed).
+    if (paths.length !== nodeIds.length) {
+        // eslint-disable-next-line no-console
+        console.warn(`styleproof: interactive-element count skew (CDP saw ${nodeIds.length}, page saw ${paths.length}); ` +
+            'skipping forced :hover/:focus/:active capture for this surface. This is usually a benign, ' +
+            'transient DOM difference (display:contents, injected/detached nodes). Re-run if it persists.');
+        await client.detach();
+        return { states: {}, skipped: true };
+    }
+    const limit = Math.min(nodeIds.length, maxInteractive);
+    if (nodeIds.length > maxInteractive) {
+        // eslint-disable-next-line no-console
+        console.warn(`styleproof: ${nodeIds.length} interactive elements exceeds maxInteractive=${maxInteractive}; ` +
+            `forced-state capture truncated to the first ${maxInteractive}. Raise maxInteractive to cover them all.`);
+    }
+    const states = {};
+    for (let i = 0; i < limit; i++) {
+        const p = paths[i];
+        if (!p)
+            continue;
+        const baseSnap = await page.evaluate(snapSubtree, { selector: INTERACTIVE, index: i });
+        for (const [stateName, forcedPseudoClasses] of Object.entries(STATE_SETS)) {
+            await client.send('CSS.forcePseudoState', { nodeId: nodeIds[i], forcedPseudoClasses });
+            const forcedSnap = await page.evaluate(snapSubtree, { selector: INTERACTIVE, index: i });
+            await client.send('CSS.forcePseudoState', { nodeId: nodeIds[i], forcedPseudoClasses: [] });
+            const delta = deltaBetween(baseSnap, forcedSnap);
+            if (Object.keys(delta).length)
+                (states[p] ??= {})[stateName] = delta;
+        }
+    }
+    await client.detach();
+    return { states, skipped: false };
+}
+/**
+ * Capture the page's complete style map. Drive the page to the state you
+ * want first (navigate, open menus, settle fonts/animations) — the capture
+ * reads whatever is in front of it.
+ */
+export async function captureStyleMap(page, options = {}) {
+    const ignore = options.ignore ?? [];
+    const captureStates = options.captureStates ?? true;
+    const maxInteractive = options.maxInteractive ?? 800;
+    // Motion longhands first (FREEZE_CSS would null them), then everything else.
+    const motion = await page.evaluate(capturePage, { ignore, motionOnly: true });
+    await page.addStyleTag({ content: FREEZE_CSS });
+    const base = await page.evaluate(capturePage, { ignore, motionOnly: false });
+    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);
+        }
+    }
+    let states = {};
+    let statesSkipped = false;
+    if (captureStates) {
+        const forced = await captureForcedStates(page, ignore, maxInteractive);
+        states = forced.states;
+        statesSkipped = forced.skipped;
+    }
+    return {
+        defaults: base.defaults,
+        elements: base.elements,
+        states,
+        ...(statesSkipped ? { statesSkipped: true } : {}),
+    };
+}
+/** Write a style map to disk; gzipped when the path ends in `.gz`. */
+export function saveStyleMap(filePath, map) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const json = JSON.stringify(map);
+    fs.writeFileSync(filePath, filePath.endsWith('.gz') ? gzipSync(json) : json);
+}
+/** Read a style map written by {@link saveStyleMap} (`.json` or `.json.gz`). */
+export function loadStyleMap(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch (e) {
+        throw new Error(`styleproof: cannot read capture ${filePath}: ${e.message}`);
+    }
+    try {
+        const text = filePath.endsWith('.gz') ? gunzipSync(raw).toString('utf8') : raw.toString('utf8');
+        return JSON.parse(text);
+    }
+    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.');
+    }
+}

package/dist/diff.d.ts

@@ -0,0 +1,51 @@
+import { type StyleMap } from './capture.js';
+/**
+ * Structured diff between two style maps. Custom properties (--*) are
+ * ignored: they are inputs, not outcomes — every visual effect of a variable
+ * lands in a real longhand which is compared in full.
+ */
+export type PropChange = {
+    prop: string;
+    before: string;
+    after: string;
+};
+export type Finding = {
+    kind: 'dom';
+    path: string;
+    cls: string;
+    change: 'added' | 'removed' | 'retagged';
+    detail?: string;
+} | {
+    kind: 'style';
+    path: string;
+    cls: string;
+    pseudo: string | null;
+    props: PropChange[];
+} | {
+    kind: 'state';
+    path: string;
+    cls: string;
+    state: string;
+    sub: string;
+    props: PropChange[];
+};
+export type SurfaceDiff = {
+    surface: string;
+    /** Set when the surface was captured in only one of the two sets. */
+    missing?: 'before' | 'after';
+    findings: Finding[];
+};
+export type DiffCounts = {
+    dom: number;
+    style: number;
+    state: number;
+};
+/** Diff two style maps of the same surface. */
+export declare function diffStyleMaps(a: StyleMap, b: StyleMap): Finding[];
+/** Diff every same-named capture between two directories. */
+export declare function diffStyleMapDirs(dirA: string, dirB: string): {
+    surfaces: SurfaceDiff[];
+    counts: DiffCounts;
+};
+/** Human label: structural path plus a truncated class hint. */
+export declare function findingLabel(path: string, cls: string): string;

package/dist/diff.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadStyleMap } from './capture.js';
+function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
+    const changed = [];
+    for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
+        if (prop.startsWith('--'))
+            continue;
+        const before = propsA[prop] ?? fallbackA[prop] ?? unsetA;
+        const after = propsB[prop] ?? fallbackB[prop] ?? unsetB;
+        if (before !== after)
+            changed.push({ prop, before, after });
+    }
+    return changed;
+}
+/** Diff two style maps of the same surface. */
+export function diffStyleMaps(a, b) {
+    const findings = [];
+    for (const p of [...new Set([...Object.keys(a.elements), ...Object.keys(b.elements)])].sort()) {
+        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' });
+            continue;
+        }
+        if (ea.tag !== eb.tag) {
+            findings.push({ kind: 'dom', path: p, cls: ea.cls, change: 'retagged', detail: `<${ea.tag}> → <${eb.tag}>` });
+            continue;
+        }
+        const defsA = a.defaults[ea.tag] ?? {};
+        const defsB = b.defaults[eb.tag] ?? {};
+        for (const pseudo of [null, ...new Set([...Object.keys(ea.pseudo ?? {}), ...Object.keys(eb.pseudo ?? {})])]) {
+            const propsA = pseudo ? (ea.pseudo?.[pseudo] ?? {}) : ea.style;
+            const propsB = pseudo ? (eb.pseudo?.[pseudo] ?? {}) : eb.style;
+            // A pseudo-element is pruned against its own UA defaults (capture stores
+            // them under a composite `tag::pseudo` key); fall back to the element's
+            // tag defaults for maps written before that fix.
+            const pdefsA = pseudo ? (a.defaults[ea.tag + pseudo] ?? defsA) : defsA;
+            const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
+            const props = diffProps(propsA, propsB, pdefsA, pdefsB, '(unset)', '(unset)');
+            if (props.length)
+                findings.push({ kind: 'style', path: p, cls: ea.cls, pseudo, props });
+        }
+    }
+    // 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".
+    if (!!a.statesSkipped !== !!b.statesSkipped) {
+        findings.push({
+            kind: 'state',
+            path: '(surface)',
+            cls: '',
+            state: 'forced-state capture',
+            sub: '(surface)',
+            props: [
+                {
+                    prop: 'forced :hover/:focus/:active layer',
+                    before: a.statesSkipped ? 'skipped (CDP skew)' : 'captured',
+                    after: b.statesSkipped ? 'skipped (CDP skew)' : 'captured',
+                },
+            ],
+        });
+    }
+    for (const p of new Set([...Object.keys(a.states ?? {}), ...Object.keys(b.states ?? {})])) {
+        const sa = a.states?.[p] ?? {};
+        const sb = b.states?.[p] ?? {};
+        const cls = (a.elements[p] ?? b.elements[p])?.cls ?? '';
+        for (const state of new Set([...Object.keys(sa), ...Object.keys(sb)])) {
+            const da = sa[state] ?? {};
+            const db = sb[state] ?? {};
+            for (const sub of new Set([...Object.keys(da), ...Object.keys(db)])) {
+                const props = diffProps(da[sub] ?? {}, db[sub] ?? {}, {}, {}, '(state does not change it)', '(state no longer changes it)');
+                if (props.length)
+                    findings.push({ kind: 'state', path: p, cls, state, sub, props });
+            }
+        }
+    }
+    return findings;
+}
+function indexDir(dir) {
+    return Object.fromEntries(fs
+        .readdirSync(dir)
+        .filter((f) => /\.json(\.gz)?$/.test(f))
+        .map((f) => [f.replace(/\.json(\.gz)?$/, ''), path.join(dir, f)]));
+}
+/** Diff every same-named capture between two directories. */
+export function diffStyleMapDirs(dirA, dirB) {
+    const indexA = indexDir(dirA);
+    const indexB = indexDir(dirB);
+    const names = [...new Set([...Object.keys(indexA), ...Object.keys(indexB)])].sort();
+    if (names.length === 0)
+        throw new Error(`no .json(.gz) captures found in ${dirA} or ${dirB}`);
+    const surfaces = [];
+    const counts = { dom: 0, style: 0, state: 0 };
+    for (const surface of names) {
+        if (!indexA[surface] || !indexB[surface]) {
+            surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
+            counts.dom++;
+            continue;
+        }
+        const findings = diffStyleMaps(loadStyleMap(indexA[surface]), loadStyleMap(indexB[surface]));
+        for (const f of findings) {
+            if (f.kind === 'dom')
+                counts.dom++;
+            else if (f.kind === 'style')
+                counts.style += f.props.length;
+            else
+                counts.state += f.props.length;
+        }
+        if (findings.length)
+            surfaces.push({ surface, findings });
+    }
+    return { surfaces, counts };
+}
+/** Human label: structural path plus a truncated class hint. */
+export function findingLabel(path, cls) {
+    if (!cls)
+        return path;
+    const classes = cls.split(' ').filter(Boolean);
+    return `${path}  (.${classes.slice(0, 3).join('.')}${classes.length > 3 ? '…' : ''})`;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
+export { defineStyleMapCapture } from './runner.js';
+export type { Surface, DefineOptions } from './runner.js';
+export { diffStyleMaps, diffStyleMapDirs, findingLabel } from './diff.js';
+export type { Finding, PropChange, SurfaceDiff, DiffCounts } from './diff.js';
+export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';
+export type { ReportOptions, ReportResult } from './report.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export { defineStyleMapCapture } from './runner.js';
+export { diffStyleMaps, diffStyleMapDirs, findingLabel } from './diff.js';
+export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/report.d.ts

@@ -0,0 +1,45 @@
+import { type PropChange } from './diff.js';
+/**
+ * Visual diff report: for every surface with findings, crop the before/after
+ * full-page screenshots around the changed elements and write a markdown
+ * report with side-by-side images plus the exact property changes.
+ *
+ * Cropping zooms out to the OUTERMOST changed element: changed paths that are
+ * descendants of other changed paths are folded into their ancestor, nearby
+ * regions are merged, and both sides are cropped at identical dimensions
+ * (centered on each side's own coordinates) so the pair stays comparable
+ * even when the change moved things around.
+ */
+export type ReportOptions = {
+    beforeDir: string;
+    afterDir: string;
+    outDir: string;
+    /** Prefix for image URLs in report.md (default: relative paths). */
+    imageBaseUrl?: string;
+    /** Padding around the union of changed rects (default 24px). */
+    pad?: number;
+    /** Minimum crop size, for context around tiny changes (default 320×180). */
+    minWidth?: number;
+    minHeight?: number;
+    /** Crops taller than this are clamped (default 1600px). */
+    maxHeight?: number;
+    /** Max crop regions per surface before collapsing into one union crop (default 6). */
+    maxCrops?: number;
+    /**
+     * Include size/position-derived longhands (height, width, transform-origin…)
+     * in the report. Off by default: on a reflow they change up the whole ancestor
+     * chain and would anchor crops to the entire page. The certification differ
+     * (`styleproof-diff`) always keeps them.
+     */
+    includeLayoutNoise?: boolean;
+};
+export type ReportResult = {
+    changedSurfaces: number;
+    totalFindings: number;
+    reportMdPath: string;
+    reportJsonPath: string;
+};
+export declare function summarizeProps(props: PropChange[]): PropChange[];
+/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
+export declare function prettyLabel(p: string, cls: string): string;
+export declare function generateStyleMapReport(opts: ReportOptions): ReportResult;