@geonosis/visual-diff 1.0.0 → 1.1.0

package/bin/geonosis-visual-diff.mjs

@@ -1,4 +1,27 @@
 #!/usr/bin/env node
 // Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
 // produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
-import '../dist/cli.js'
+//
+// In the repo, `src/` sits beside `dist/`, and a dist older than src answered for a fix it did not
+// carry once (#62). The published package ships no src, so there the check is skipped.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const newest = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true }).reduce((most, entry) => {
+        const at = join(dir, entry.name)
+        return Math.max(most, entry.isDirectory() ? newest(at) : statSync(at).mtimeMs)
+      }, 0)
+    : 0
+const src = join(here, '..', 'src')
+if (existsSync(src) && newest(src) > newest(join(here, '..', 'dist'))) {
+  process.stderr.write(
+    'geonosis-visual-diff: dist is older than src — run pnpm build before trusting this bin.\n',
+  )
+  process.exit(2)
+}
+
+await import('../dist/cli.js')

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The per-pixel colour threshold handed to pixelmatch, 0–1, smaller is stricter.
+ *
+ * `0` is strict per-pixel equality: any channel that moved by one unit is a difference. That is
+ * what a parity claim ("these two renders are the same") has to be measured at.
+ * `0.1` — pixelmatch's own default, and this one — absorbs the sub-pixel noise two renders of the
+ * same layout produce on different machines.
+ */
+declare const DEFAULT_THRESHOLD = 0.1;
+/**
+ * The fraction of a frame allowed to differ before the frame FAILS. A SECOND, orthogonal knob:
+ * `threshold` decides whether ONE pixel counts, `mismatchRatio` decides how many counted pixels a
+ * frame may carry. Folding them into one number loses the distinction.
+ */
+declare const DEFAULT_MISMATCH_RATIO = 0.005;
+interface CompareOptions {
+    /** Per-pixel colour threshold, 0–1. Defaults to {@link DEFAULT_THRESHOLD}. */
+    readonly threshold?: number;
+    /** Count anti-aliased pixels as differences. Off by default, as in pixelmatch. */
+    readonly includeAA?: boolean;
+}
+interface CompareResult {
+    /** The height of the actual frame. */
+    readonly actualHeight: number;
+    /** The width of the actual frame. */
+    readonly actualWidth: number;
+    /** True when both frames decode to the same width × height. */
+    readonly dimensionsMatch: boolean;
+    /** The rendered diff PNG — null when the dimensions differ and there is nothing to render. */
+    readonly diff: Buffer | null;
+    /** The height of the baseline frame. */
+    readonly height: number;
+    /** Pixels counted as different. 0 when the dimensions differ — read `dimensionsMatch` first. */
+    readonly mismatch: number;
+    /** mismatch / total, as a fraction 0–1. 1 when the dimensions differ. */
+    readonly ratio: number;
+    /** The baseline frame's pixel count. */
+    readonly total: number;
+    /** The width of the baseline frame. */
+    readonly width: number;
+}
+/**
+ * Decode and pixel-diff two PNG buffers.
+ *
+ * A dimension mismatch is a hard fail — `dimensionsMatch: false`, `ratio: 1`, no diff image. It is
+ * reported, not thrown, because the frame-by-frame caller wants an outcome per frame rather than an
+ * exception that ends the run.
+ */
+declare function comparePng(baseline: Buffer, actual: Buffer, options?: CompareOptions): CompareResult;
+/** Decide pass/fail from a compare result against the frame budget. A dimension mismatch fails at
+ *  every budget, including 1 — a frame that changed shape is not a frame that drifted a little. */
+declare function isWithinBudget(result: CompareResult, mismatchRatio?: number): boolean;
+
+type FrameStatus = 'created' | 'fail' | 'missing-baseline' | 'pass' | 'updated';
+interface BaselineDirs {
+    /** Where the failing actual and diff PNGs are written. */
+    readonly artifactsDir: string;
+    /** Where the committed baseline PNGs live. */
+    readonly baselineDir: string;
+}
+interface ReconcileOptions extends CompareOptions {
+    /** The fraction of the frame allowed to differ. Defaults to {@link DEFAULT_MISMATCH_RATIO}. */
+    readonly mismatchRatio?: number;
+    /** Write the baseline instead of checking against it. */
+    readonly update?: boolean;
+}
+interface FrameOutcome {
+    readonly baselinePath: string;
+    readonly name: string;
+    /** The comparison, when one was run — null in update mode and when no baseline exists. */
+    readonly result: CompareResult | null;
+    readonly status: FrameStatus;
+}
+/**
+ * Reconcile one captured frame against the baseline stored under its name.
+ *
+ * `update` writes the baseline — `created` when there was none, `updated` when there was. Without
+ * it the frame is compared: `missing-baseline` when nothing is stored (never a silent pass), then
+ * `pass` or `fail`. A failure leaves `<name>.actual.png` and `<name>.diff.png` in `artifactsDir`.
+ */
+declare function reconcileFrame(name: string, actual: Buffer, dirs: BaselineDirs, options?: ReconcileOptions): FrameOutcome;
+/** One line saying what happened to a frame, and what to do about it. */
+declare function describeOutcome(outcome: FrameOutcome): string;
+
+/** A named viewport. `height` matters only for above-the-fold captures; a full-page screenshot
+ *  ignores it, but a fixed value keeps a partial capture deterministic. */
+interface Breakpoint {
+    readonly height: number;
+    readonly name: string;
+    readonly width: number;
+}
+/** A surface to capture. `waitFor` and `mask` are consumer-defined selectors — the kit passes them
+ *  through and never interprets them. */
+interface VisualTarget {
+    /** An optional per-target grid. Omitted → the fallback grid. */
+    readonly breakpoints?: readonly Breakpoint[];
+    /** A stable id used to build the baseline filename. */
+    readonly id: string;
+    /** Selectors for regions to blank before capture, so a volatile region cannot redden a frame. */
+    readonly mask?: readonly string[];
+    /** Where the surface lives, in whatever form the consumer's capture step understands. */
+    readonly path: string;
+    /** A selector proving the surface finished rendering. */
+    readonly waitFor: string;
+}
+/** A five-width fallback grid, at the widths CSS frameworks converge on. A DEFAULT, not a fact
+ *  about any repo — pass your own grid to `breakpointsFor` when yours differs. */
+declare const DEFAULT_BREAKPOINTS: readonly Breakpoint[];
+/** The breakpoints a target commits baselines for: its own, or the fallback grid. */
+declare function breakpointsFor(target: VisualTarget, fallback?: readonly Breakpoint[]): readonly Breakpoint[];
+/** The baseline filename for a surface at a breakpoint. */
+declare function baselineName(surface: string, breakpoint: string): string;
+
+type Verdict = 'IDENTICAL' | 'MINOR_DIFF' | 'NEAR_IDENTICAL' | 'SIGNIFICANT_DIFF' | 'SIMILAR';
+interface DiffOptions extends CompareOptions {
+    /** Where to write the rendered diff PNG. Omitted → no diff image is written. */
+    readonly outputPath?: string;
+}
+interface CompareInput {
+    readonly image1: string;
+    readonly image2: string;
+    readonly options?: DiffOptions;
+}
+interface DiffResult {
+    readonly analysis: string;
+    readonly diffImagePath: string | null;
+    /** The difference as a PERCENTAGE, 0–100 — not the 0–1 ratio `comparePng` returns. */
+    readonly diffPercent: number;
+    readonly diffPercentFormatted: string;
+    readonly differentPixels: number;
+    readonly dimensions: {
+        readonly height: number;
+        readonly width: number;
+    };
+    readonly identical: boolean;
+    readonly totalPixels: number;
+    readonly verdict: Verdict;
+}
+/**
+ * Compare two PNG FILES.
+ *
+ * Throws when an input is missing and when the two differ in size — the caller asked about two
+ * frames of the same thing, and two different sizes means the question was wrong, not the answer.
+ */
+declare function compare({ image1, image2, options }: CompareInput): Promise<DiffResult>;
+/** The printable block a human reads in a terminal or a CI log. */
+declare function formatReport(result: DiffResult): string;
+
+export { type BaselineDirs, type Breakpoint, type CompareInput, type CompareOptions, type CompareResult, DEFAULT_BREAKPOINTS, DEFAULT_MISMATCH_RATIO, DEFAULT_THRESHOLD, type DiffOptions, type DiffResult, type FrameOutcome, type FrameStatus, type ReconcileOptions, type Verdict, type VisualTarget, baselineName, breakpointsFor, compare, comparePng, describeOutcome, formatReport, isWithinBudget, reconcileFrame };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@geonosis/visual-diff",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "types": "./dist/index.d.ts",
   "description": "Pixel comparison, reporting and baseline management for visual regression — the union of dielime's and during.day's forks. Capture stays with the consumer; nothing here launches a browser.",
   "keywords": [
     "visual-regression",
@@ -23,7 +24,10 @@
     "geonosis-visual-diff": "bin/geonosis-visual-diff.mjs"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
     "bin",