styleproof 1.0.0

package/bin/styleproof-diff.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Diff two computed-style map captures (see styleproof).
+ *
+ *   styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]
+ *
+ * Reports, per surface:
+ *   - DOM changes (elements added/removed/retagged) — a CSS-only refactor
+ *     must produce none; class attributes are deliberately NOT compared.
+ *   - Style changes: any computed longhand that resolved differently,
+ *     including ::before/::after/::marker/::placeholder.
+ *   - State changes: anything :hover/:focus/:active used to change but no
+ *     longer does (or now changes differently) — the classic dropped
+ *     `hover:` variant a screenshot can never catch.
+ *
+ * Custom properties (--*) are ignored: they are inputs, not outcomes (see
+ * README). Exit code 0 = identical, 1 = differences, 2 = usage/capture error.
+ */
+import fs from 'node:fs';
+import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
+
+const HELP = `styleproof-diff — certify a CSS refactor by diffing two computed-style captures
+
+usage: styleproof-diff <beforeDir> <afterDir> [options]
+
+options:
+  --max <n>        max lines printed per surface before truncating (default: 40)
+  --json <file>    also write the full structured diff to <file>
+  -h, --help       show this help
+
+exit: 0 identical (certified), 1 differences found, 2 usage/capture error.
+`;
+
+const argv = process.argv.slice(2);
+const args = [];
+let MAX = 40;
+let jsonOut = null;
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '-h' || argv[i] === '--help') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  } else if (argv[i] === '--max') MAX = Number(argv[++i]);
+  else if (argv[i].startsWith('--max=')) MAX = Number(argv[i].slice(6));
+  else if (argv[i] === '--json') jsonOut = argv[++i];
+  else if (argv[i].startsWith('--json=')) jsonOut = argv[i].slice(7);
+  else if (argv[i].startsWith('--')) {
+    console.error(`unknown flag: ${argv[i]}`);
+    process.exit(2);
+  } else args.push(argv[i]);
+}
+if (args.length !== 2 || !Number.isFinite(MAX)) {
+  console.error('usage: styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]  (--help for all options)');
+  process.exit(2);
+}
+const [dirA, dirB] = args;
+for (const d of [dirA, dirB]) {
+  if (!fs.existsSync(d)) {
+    console.error(`no capture at ${d}`);
+    process.exit(2);
+  }
+}
+
+let result;
+try {
+  result = diffStyleMapDirs(dirA, dirB);
+} catch (e) {
+  console.error(e.message);
+  process.exit(2);
+}
+const { surfaces, counts } = result;
+
+for (const sd of surfaces) {
+  if (sd.missing) {
+    console.log(`\n${sd.surface}: captured in only one set — re-run both captures`);
+    continue;
+  }
+  const lines = [];
+  for (const f of sd.findings) {
+    if (f.kind === 'dom') {
+      lines.push(
+        f.change === 'retagged'
+          ? `  DOM retagged: ${f.path} ${f.detail}`
+          : `  DOM ${f.change}: ${findingLabel(f.path, f.cls)}`,
+      );
+    } else if (f.kind === 'style') {
+      lines.push(`  ${findingLabel(f.path, f.cls)}${f.pseudo || ''}`);
+      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
+    } else {
+      lines.push(`  [:${f.state}] ${findingLabel(f.path, f.cls)}${f.sub !== f.path ? ` ⇒ ${f.sub}` : ''}`);
+      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
+    }
+  }
+  console.log(`\n${sd.surface}: ${lines.filter((l) => !l.startsWith('    ')).length} element(s) differ`);
+  for (const line of lines.slice(0, MAX)) console.log(line);
+  if (lines.length > MAX) console.log(`  ... and ${lines.length - MAX} more lines (re-run with --max ${lines.length})`);
+}
+
+if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces }, null, 2));
+
+const total = counts.dom + counts.style + counts.state;
+const surfaceCount = new Set([
+  ...fs.readdirSync(dirA).filter((f) => /\.json(\.gz)?$/.test(f)),
+  ...fs.readdirSync(dirB).filter((f) => /\.json(\.gz)?$/.test(f)),
+]).size;
+console.log(
+  total === 0
+    ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces`,
+);
+process.exit(total === 0 ? 0 : 1);

package/bin/styleproof-init.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Scaffold a styleproof capture spec into a project.
+ *
+ *   styleproof-init [--dir <path>] [--base-url <url>] [--force] [-h|--help]
+ *
+ * Writes:
+ *   - <dir> (default e2e/styleproof.spec.ts): a starter capture spec with a
+ *     robust settle() helper (waits fonts + neutralises scroll-reveal and CSS
+ *     animation/transition) and one sample Surface.
+ *   - playwright.config.ts: only if one does not already exist, so an existing
+ *     Playwright project is never disturbed.
+ *
+ * Idempotent: re-running never overwrites an existing spec (use --force) and
+ * never touches an existing playwright.config.ts. Exit 0 = done (or nothing to
+ * do), 2 = usage error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HELP = `styleproof-init — scaffold a styleproof capture spec
+
+usage: styleproof-init [options]
+
+options:
+  --dir <path>        spec output path (default: e2e/styleproof.spec.ts)
+  --base-url <url>    baseURL for a generated playwright.config.ts
+                      (default: http://localhost:3000)
+  --force             overwrite the spec if it already exists
+  -h, --help          show this help
+
+What it writes:
+  - the spec at --dir, with a settle() helper (fonts + reveal/animation freeze)
+    and one sample Surface sweeping widths [1280, 768, 390]
+  - playwright.config.ts, only if absent (an existing one is left untouched)
+
+After running, capture a baseline against a PRODUCTION build:
+  STYLEMAP_DIR=baseline npx playwright test styleproof
+  git add e2e/__stylemaps__/baseline && git commit -m "chore: stylemap baseline"
+
+To certify a refactor:
+  STYLEMAP_DIR=before npx playwright test styleproof
+  # ...refactor your CSS...
+  STYLEMAP_DIR=after  npx playwright test styleproof
+  npx styleproof-diff __stylemaps__/before __stylemaps__/after
+`;
+
+const argv = process.argv.slice(2);
+let specPath = 'e2e/styleproof.spec.ts';
+let baseUrl = 'http://localhost:3000';
+let force = false;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '-h' || a === '--help') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  } else if (a === '--dir') specPath = argv[++i];
+  else if (a.startsWith('--dir=')) specPath = a.slice(6);
+  else if (a === '--base-url') baseUrl = argv[++i];
+  else if (a.startsWith('--base-url=')) baseUrl = a.slice(11);
+  else if (a === '--force') force = true;
+  else {
+    console.error(`unknown argument: ${a}\n`);
+    process.stderr.write(HELP);
+    process.exit(2);
+  }
+}
+if (!specPath) {
+  console.error('--dir requires a path');
+  process.exit(2);
+}
+
+const SPEC = `import type { Page } from '@playwright/test';
+import { defineStyleMapCapture, type Surface } from 'styleproof';
+
+/**
+ * styleproof capture spec (generated by \`styleproof-init\`).
+ *
+ * Each surface is one deterministic page state; widths sweep one viewport per
+ * @media band so breakpoint rules are certified too. Capture against a
+ * PRODUCTION build — dev servers inject their own styles.
+ *
+ *   STYLEMAP_DIR=before npx playwright test styleproof   # capture baseline
+ *   ...refactor your CSS...
+ *   STYLEMAP_DIR=after  npx playwright test styleproof   # capture again
+ *   npx styleproof-diff __stylemaps__/before __stylemaps__/after
+ */
+
+// Captures read whatever is in front of them, so the page must be settled and
+// deterministic first. settle() (1) waits for web fonts, (2) freezes CSS
+// animations/transitions and forces common scroll-reveal markers to their final
+// state so nothing is mid-fade, then (3) scrolls the page to trigger any
+// IntersectionObserver-driven reveals and returns to the top. Tune the reveal
+// selectors below to match your project.
+async function settle(page: Page) {
+  await page.addStyleTag({
+    content: \`
+      *, *::before, *::after {
+        animation: none !important;
+        transition: none !important;
+        animation-duration: 0s !important;
+        transition-duration: 0s !important;
+      }
+      .reveal, [data-reveal], .fade-in, .animate-in {
+        opacity: 1 !important;
+        transform: none !important;
+        visibility: visible !important;
+      }
+    \`,
+  });
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    for (let y = 0; y < document.body.scrollHeight; y += window.innerHeight) {
+      window.scrollTo(0, y);
+      await new Promise((r) => setTimeout(r, 60));
+    }
+    window.scrollTo(0, 0);
+  });
+  await page.waitForTimeout(300);
+}
+
+const SURFACES: Surface[] = [
+  {
+    key: 'home',
+    go: async (page) => {
+      await page.goto('/', { waitUntil: 'networkidle' });
+      await settle(page);
+    },
+    ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
+    widths: [1280, 768, 390],
+  },
+  // Add one surface per distinct page state: open menus, dialogs, selected
+  // tabs, form errors — anything whose styling you want certified.
+];
+
+defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
+`;
+
+const CONFIG = `import { defineConfig, devices } from '@playwright/test';
+
+// Generated by styleproof-init. Point BASE_URL at a PRODUCTION build of the site
+// to capture — dev servers inject their own styles.
+export default defineConfig({
+  timeout: 120_000,
+  use: {
+    baseURL: process.env.BASE_URL || '${baseUrl}',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+});
+`;
+
+function writeFileSafe(file, contents, { force: f } = {}) {
+  const exists = fs.existsSync(file);
+  if (exists && !f) return { wrote: false, exists: true };
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  fs.writeFileSync(file, contents);
+  return { wrote: true, exists };
+}
+
+let wroteSomething = false;
+
+const spec = writeFileSafe(specPath, SPEC, { force });
+if (spec.wrote) {
+  console.log(`${spec.exists ? 'overwrote' : 'created'} ${specPath}`);
+  wroteSomething = true;
+} else {
+  console.log(`${specPath} already exists — left untouched (use --force to overwrite)`);
+}
+
+const configPath = 'playwright.config.ts';
+if (fs.existsSync(configPath) || fs.existsSync('playwright.config.js')) {
+  console.log('playwright.config exists — left untouched; ensure its baseURL points at a production build');
+} else {
+  fs.writeFileSync(configPath, CONFIG);
+  console.log(`created ${configPath} (baseURL ${baseUrl})`);
+  wroteSomething = true;
+}
+
+console.log('\nNext steps (run against a PRODUCTION build, not a dev server):');
+console.log('  1. capture the baseline:');
+console.log('       STYLEMAP_DIR=baseline npx playwright test styleproof');
+console.log('  2. commit it:');
+console.log('       git add __stylemaps__/baseline && git commit -m "chore: stylemap baseline"');
+console.log('  3. after a CSS change, certify it:');
+console.log('       STYLEMAP_DIR=after npx playwright test styleproof');
+console.log('       npx styleproof-diff __stylemaps__/baseline __stylemaps__/after');
+console.log('     an empty diff is the certificate; a non-empty one names every drift.');
+
+if (!wroteSomething) console.log('\nnothing to write — project already scaffolded.');
+process.exit(0);

package/bin/styleproof-report.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Visual diff report: side-by-side before/after crops of every changed
+ * region, plus the exact property changes, as markdown ready for a PR
+ * comment.
+ *
+ *   styleproof-report <beforeDir> <afterDir> --out <dir> [options]
+ *
+ * Both capture dirs need the .json.gz maps; side-by-side images additionally
+ * need the .png screenshots that `defineStyleMapCapture` saves by default.
+ * Exit code 0 = no changes, 1 = report generated, 2 = usage error.
+ */
+import { generateStyleMapReport } from '../dist/report.js';
+
+const HELP = `styleproof-report — reviewable before/after report from two captures
+
+usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]
+
+options:
+  --out <dir>               output directory (default: styleproof-report)
+  --image-base-url <url>    prefix for image URLs in report.md (default: relative)
+  --pad <px>                padding around changed rects when cropping (default: 24)
+  --max-crops <n>           max crop regions per surface before collapsing (default: 6)
+  --min-width <px>          minimum crop width, for context (default: 320)
+  --min-height <px>         minimum crop height, for context (default: 180)
+  --include-layout-noise    keep size/position-derived longhands (height, width,
+                            transform-origin, top…) that a reflow changes up the
+                            whole ancestor chain (off by default)
+  -h, --help                show this help
+
+exit: 0 no changes, 1 report generated, 2 usage error.
+`;
+
+const argv = process.argv.slice(2);
+const args = [];
+const flags = { out: 'styleproof-report', imageBaseUrl: '' };
+let pad;
+let maxCrops;
+let minWidth;
+let minHeight;
+let includeLayoutNoise = false;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '-h' || a === '--help') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  } else if (a === '--out') flags.out = argv[++i];
+  else if (a.startsWith('--out=')) flags.out = a.slice(6);
+  else if (a === '--image-base-url') flags.imageBaseUrl = argv[++i];
+  else if (a.startsWith('--image-base-url=')) flags.imageBaseUrl = a.slice(17);
+  else if (a === '--pad') pad = Number(argv[++i]);
+  else if (a.startsWith('--pad=')) pad = Number(a.slice(6));
+  else if (a === '--max-crops') maxCrops = Number(argv[++i]);
+  else if (a.startsWith('--max-crops=')) maxCrops = Number(a.slice(12));
+  else if (a === '--min-width') minWidth = Number(argv[++i]);
+  else if (a.startsWith('--min-width=')) minWidth = Number(a.slice(12));
+  else if (a === '--min-height') minHeight = Number(argv[++i]);
+  else if (a.startsWith('--min-height=')) minHeight = Number(a.slice(13));
+  else if (a === '--include-layout-noise') includeLayoutNoise = true;
+  else if (a.startsWith('--include-layout-noise=')) includeLayoutNoise = a.slice(23) !== 'false';
+  else if (a.startsWith('--')) {
+    console.error(`unknown flag: ${a}`);
+    process.exit(2);
+  } else args.push(a);
+}
+if (args.length !== 2) {
+  console.error('usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]  (--help for all options)');
+  process.exit(2);
+}
+for (const [name, val] of [
+  ['--pad', pad],
+  ['--max-crops', maxCrops],
+  ['--min-width', minWidth],
+  ['--min-height', minHeight],
+]) {
+  if (val !== undefined && !Number.isFinite(val)) {
+    console.error(`${name} must be a number`);
+    process.exit(2);
+  }
+}
+
+let result;
+try {
+  result = generateStyleMapReport({
+    beforeDir: args[0],
+    afterDir: args[1],
+    outDir: flags.out,
+    imageBaseUrl: flags.imageBaseUrl || undefined,
+    pad,
+    maxCrops,
+    minWidth,
+    minHeight,
+    includeLayoutNoise,
+  });
+} catch (e) {
+  console.error(e.message);
+  process.exit(2);
+}
+
+console.log(
+  result.changedSurfaces === 0
+    ? '✓ no changes — empty report written'
+    : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)`,
+);
+console.log(`report: ${result.reportMdPath}`);
+process.exit(result.changedSurfaces === 0 ? 0 : 1);

package/dist/capture.d.ts

@@ -0,0 +1,79 @@
+import type { Page } from '@playwright/test';
+/**
+ * Computed-style capture: the browser's final resolved value for every CSS
+ * longhand on every element, keyed by DOM structure (never by class name, so
+ * a CSS-to-Tailwind migration can rewrite classes freely while the map stays
+ * comparable). Three layers per capture:
+ *
+ *   elements — every element's computed style, pruned against per-tag UA
+ *              defaults (measured in a clean iframe) to keep files small,
+ *              plus ::before / ::after / ::marker / ::placeholder.
+ *   states   — for interactive elements, what :hover, :focus(-visible) and
+ *              :active change (forced via CDP, no mouse involved), captured
+ *              as a delta over the element's subtree. Screenshots cannot see
+ *              these; this is where dropped `hover:` variants get caught.
+ *   motion   — transition/animation longhands are captured before the
+ *              freeze-CSS below nulls them, so declared motion is verified
+ *              too, while every other captured value is a settled end state.
+ *
+ * LIMITATIONS (documented, and warned at capture time):
+ *   - Shadow DOM (open or closed) is NOT traversed: styles inside a web
+ *     component's shadow root are invisible to the diff. A refactor inside a
+ *     shadow tree would be falsely certified identical, so capture emits a
+ *     one-time warning naming the shadow hosts it skipped.
+ *   - Iframe content (same- or cross-origin) is NOT traversed for the same
+ *     reason; same-origin frames are listed in the same warning.
+ */
+type Props = Record<string, string>;
+/** Document-space bounding box: [x, y, width, height], rounded. */
+export type Rect = [number, number, number, number];
+export type ElementEntry = {
+    tag: string;
+    cls: string;
+    rect?: Rect;
+    style: Props;
+    pseudo?: Record<string, Props>;
+};
+export type StyleMap = {
+    defaults: Record<string, Props>;
+    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".
+     */
+    statesSkipped?: boolean;
+};
+export type CaptureOptions = {
+    /**
+     * Selectors for nondeterministic regions (live data, embeds, ads). The
+     * matching elements and their descendants are skipped entirely.
+     */
+    ignore?: string[];
+    /**
+     * Capture forced :hover/:focus/:active state deltas (default true). This is
+     * the expensive layer — O(interactive elements × 3 states) with a subtree
+     * evaluate each. Set false to skip it on surfaces where you don't need
+     * state certification, or where the page has thousands of interactive nodes.
+     */
+    captureStates?: boolean;
+    /**
+     * Cap on interactive elements forced-state-captured per surface (default
+     * 800). Beyond this the capture warns and truncates rather than hanging for
+     * minutes; raise it deliberately if you need full coverage of a huge page.
+     */
+    maxInteractive?: number;
+};
+/**
+ * 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 declare function captureStyleMap(page: Page, options?: CaptureOptions): Promise<StyleMap>;
+/** Write a style map to disk; gzipped when the path ends in `.gz`. */
+export declare function saveStyleMap(filePath: string, map: StyleMap): void;
+/** Read a style map written by {@link saveStyleMap} (`.json` or `.json.gz`). */
+export declare function loadStyleMap(filePath: string): StyleMap;
+export {};