@flighthq/capture 0.1.0

package/dist/captureBaseline.d.ts

@@ -0,0 +1,24 @@
+import type { CaptureBaseline, CaptureColumnBaseline } from '@flighthq/types';
+/** Allocates an empty baseline record. Columns are added via setCaptureBaselineField. */
+export declare function createCaptureBaseline(): CaptureBaseline;
+/**
+ * Serializes a baseline to its committed text form: JSON with columns in sorted key order, each
+ * column's fields in canonical `fingerprint` then `sha256` order, 2-space indent, and a trailing
+ * newline. Matches the tooling's on-disk baseline store byte-for-byte, so a re-baseline of one column
+ * produces a minimal diff and the format gate stays green. Only defined fields are emitted.
+ */
+export declare function formatCaptureBaseline(baseline: Readonly<CaptureBaseline>): string;
+/**
+ * The value of one column's field, or `null` when the column or field is absent. `field` is
+ * `'fingerprint'` or `'sha256'`.
+ */
+export declare function getCaptureBaselineField(baseline: Readonly<CaptureBaseline>, column: string, field: keyof CaptureColumnBaseline): string | null;
+/**
+ * Parses the text form produced by formatCaptureBaseline. Returns `null` for malformed input — invalid
+ * JSON, or a top-level value that is not a plain object — so a corrupt baseline reads as "no baseline"
+ * rather than crashing.
+ */
+export declare function parseCaptureBaseline(text: string): CaptureBaseline | null;
+/** Sets one column's field to `value`, creating the column entry if it does not yet exist. */
+export declare function setCaptureBaselineField(baseline: CaptureBaseline, column: string, field: keyof CaptureColumnBaseline, value: string): void;
+//# sourceMappingURL=captureBaseline.d.ts.map

package/dist/captureBaseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureBaseline.d.ts","sourceRoot":"","sources":["../src/captureBaseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE9E,yFAAyF;AACzF,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,MAAM,CAUjF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,CAAC,eAAe,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,qBAAqB,GACjC,MAAM,GAAG,IAAI,CAEf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CASzE;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,qBAAqB,EAClC,KAAK,EAAE,MAAM,GACZ,IAAI,CAEN"}

package/dist/captureBaseline.js

@@ -0,0 +1,52 @@
+/** Allocates an empty baseline record. Columns are added via setCaptureBaselineField. */
+export function createCaptureBaseline() {
+    return {};
+}
+/**
+ * Serializes a baseline to its committed text form: JSON with columns in sorted key order, each
+ * column's fields in canonical `fingerprint` then `sha256` order, 2-space indent, and a trailing
+ * newline. Matches the tooling's on-disk baseline store byte-for-byte, so a re-baseline of one column
+ * produces a minimal diff and the format gate stays green. Only defined fields are emitted.
+ */
+export function formatCaptureBaseline(baseline) {
+    const sorted = {};
+    for (const column of Object.keys(baseline).sort()) {
+        const entry = baseline[column];
+        const out = {};
+        if (entry.fingerprint !== undefined)
+            out.fingerprint = entry.fingerprint;
+        if (entry.sha256 !== undefined)
+            out.sha256 = entry.sha256;
+        sorted[column] = out;
+    }
+    return JSON.stringify(sorted, null, 2) + '\n';
+}
+/**
+ * The value of one column's field, or `null` when the column or field is absent. `field` is
+ * `'fingerprint'` or `'sha256'`.
+ */
+export function getCaptureBaselineField(baseline, column, field) {
+    return baseline[column]?.[field] ?? null;
+}
+/**
+ * Parses the text form produced by formatCaptureBaseline. Returns `null` for malformed input — invalid
+ * JSON, or a top-level value that is not a plain object — so a corrupt baseline reads as "no baseline"
+ * rather than crashing.
+ */
+export function parseCaptureBaseline(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    return parsed;
+}
+/** Sets one column's field to `value`, creating the column entry if it does not yet exist. */
+export function setCaptureBaselineField(baseline, column, field, value) {
+    (baseline[column] ??= {})[field] = value;
+}
+//# sourceMappingURL=captureBaseline.js.map

package/dist/captureBaseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureBaseline.js","sourceRoot":"","sources":["../src/captureBaseline.ts"],"names":[],"mappings":"AAEA,yFAAyF;AACzF,MAAM,UAAU,qBAAqB;IACnC,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,MAAM,GAAG,GAA0B,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;YAAE,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACzE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC1D,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAmC,EACnC,MAAc,EACd,KAAkC;IAElC,OAAO,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,OAAO,MAAyB,CAAC;AACnC,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,uBAAuB,CACrC,QAAyB,EACzB,MAAc,EACd,KAAkC,EAClC,KAAa;IAEb,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;AAC3C,CAAC"}

package/dist/captureComparison.d.ts

@@ -0,0 +1,26 @@
+import type { CaptureCheckResult } from '@flighthq/types';
+export declare const CAPTURE_PARITY_TOLERANCE = 15;
+export declare const CAPTURE_REGRESSION_TOLERANCE = 5;
+/**
+ * The tolerant distance between two coarse render fingerprints in `<gridSize>:<hex>` text form (see
+ * formatSurfaceFingerprint): the mean absolute per-channel difference (0..255), where ~0 is identical
+ * and larger values mean a real visual change. Returns `Number.POSITIVE_INFINITY` as a sentinel when
+ * either string fails to parse, or when the two fingerprints use different grid sizes and so are not
+ * comparable — Infinity fails any finite tolerance, so a corrupt or mismatched baseline reads as a
+ * failing check rather than crashing.
+ */
+export declare function compareCaptureFingerprints(a: string, b: string): number;
+/**
+ * Parity: whether two render backends rendering the same scene in the same run agree within
+ * `tolerance`. Environment-independent — it needs no committed baseline, only the two live
+ * fingerprints. `difference` is the tolerant distance (Infinity when either fingerprint is
+ * unparseable); `pass` is `difference <= tolerance`.
+ */
+export declare function evaluateCaptureParity(a: string, b: string, tolerance?: number): CaptureCheckResult;
+/**
+ * Regression: whether a freshly captured `fingerprint` still matches its own committed
+ * `baselineFingerprint` within `tolerance`. `difference` is the tolerant distance (Infinity when
+ * either fingerprint is unparseable); `pass` is `difference <= tolerance`.
+ */
+export declare function evaluateCaptureRegression(fingerprint: string, baselineFingerprint: string, tolerance?: number): CaptureCheckResult;
+//# sourceMappingURL=captureComparison.d.ts.map

package/dist/captureComparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureComparison.d.ts","sourceRoot":"","sources":["../src/captureComparison.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAI1D,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAK3C,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,SAA2B,GAAG,kBAAkB,CAGpH;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,EAC3B,SAAS,SAA+B,GACvC,kBAAkB,CAGpB"}

package/dist/captureComparison.js

@@ -0,0 +1,43 @@
+import { compareSurfaceFingerprints, parseSurfaceFingerprint } from '@flighthq/surface';
+// Default parity tolerance (mean absolute per-channel difference, 0..255). Cross-backend agreement is
+// ≤ ~6.5 even for antialiasing-heavy scenes, so real divergence between two backends is well over 15.
+export const CAPTURE_PARITY_TOLERANCE = 15;
+// Default regression tolerance (mean absolute per-channel difference, 0..255). Same-backend run-to-run
+// noise for a stable test is well under 5, so a target that drifts past this against its own committed
+// baseline is a real visual regression, not antialiasing jitter.
+export const CAPTURE_REGRESSION_TOLERANCE = 5;
+/**
+ * The tolerant distance between two coarse render fingerprints in `<gridSize>:<hex>` text form (see
+ * formatSurfaceFingerprint): the mean absolute per-channel difference (0..255), where ~0 is identical
+ * and larger values mean a real visual change. Returns `Number.POSITIVE_INFINITY` as a sentinel when
+ * either string fails to parse, or when the two fingerprints use different grid sizes and so are not
+ * comparable — Infinity fails any finite tolerance, so a corrupt or mismatched baseline reads as a
+ * failing check rather than crashing.
+ */
+export function compareCaptureFingerprints(a, b) {
+    const fa = parseSurfaceFingerprint(a);
+    const fb = parseSurfaceFingerprint(b);
+    if (fa === null || fb === null || fa.gridSize !== fb.gridSize)
+        return Number.POSITIVE_INFINITY;
+    return compareSurfaceFingerprints(fa, fb);
+}
+/**
+ * Parity: whether two render backends rendering the same scene in the same run agree within
+ * `tolerance`. Environment-independent — it needs no committed baseline, only the two live
+ * fingerprints. `difference` is the tolerant distance (Infinity when either fingerprint is
+ * unparseable); `pass` is `difference <= tolerance`.
+ */
+export function evaluateCaptureParity(a, b, tolerance = CAPTURE_PARITY_TOLERANCE) {
+    const difference = compareCaptureFingerprints(a, b);
+    return { pass: difference <= tolerance, difference, tolerance };
+}
+/**
+ * Regression: whether a freshly captured `fingerprint` still matches its own committed
+ * `baselineFingerprint` within `tolerance`. `difference` is the tolerant distance (Infinity when
+ * either fingerprint is unparseable); `pass` is `difference <= tolerance`.
+ */
+export function evaluateCaptureRegression(fingerprint, baselineFingerprint, tolerance = CAPTURE_REGRESSION_TOLERANCE) {
+    const difference = compareCaptureFingerprints(fingerprint, baselineFingerprint);
+    return { pass: difference <= tolerance, difference, tolerance };
+}
+//# sourceMappingURL=captureComparison.js.map

package/dist/captureComparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureComparison.js","sourceRoot":"","sources":["../src/captureComparison.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAGxF,sGAAsG;AACtG,sGAAsG;AACtG,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,uGAAuG;AACvG,uGAAuG;AACvG,iEAAiE;AACjE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,CAAS,EAAE,CAAS;IAC7D,MAAM,EAAE,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,EAAE,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;IACtC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,QAAQ;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAC/F,OAAO,0BAA0B,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS,EAAE,CAAS,EAAE,SAAS,GAAG,wBAAwB;IAC9F,MAAM,UAAU,GAAG,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,EAAE,IAAI,EAAE,UAAU,IAAI,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAmB,EACnB,mBAA2B,EAC3B,SAAS,GAAG,4BAA4B;IAExC,MAAM,UAAU,GAAG,0BAA0B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAChF,OAAO,EAAE,IAAI,EAAE,UAAU,IAAI,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAClE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './captureBaseline';
+export * from './captureComparison';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './captureBaseline';
+export * from './captureComparison';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/capture",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/surface": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Deterministic render capture verification policy and baseline format — tolerant fingerprint comparison and the committed baseline store shape",
+  "sideEffects": false
+}

package/src/captureBaseline.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createCaptureBaseline,
+  formatCaptureBaseline,
+  getCaptureBaselineField,
+  parseCaptureBaseline,
+  setCaptureBaselineField,
+} from './captureBaseline';
+
+describe('createCaptureBaseline', () => {
+  it('allocates an empty record', () => {
+    const baseline = createCaptureBaseline();
+    expect(baseline).toEqual({});
+    expect(getCaptureBaselineField(baseline, 'canvas', 'fingerprint')).toBeNull();
+  });
+
+  it('allocates a distinct record each call', () => {
+    const a = createCaptureBaseline();
+    const b = createCaptureBaseline();
+    setCaptureBaselineField(a, 'canvas', 'fingerprint', '1:000000');
+    expect(getCaptureBaselineField(b, 'canvas', 'fingerprint')).toBeNull();
+  });
+});
+
+describe('formatCaptureBaseline', () => {
+  it('sorts columns, orders fields, indents by two spaces, and ends with a newline', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'flight:webgl', 'sha256', 'aaa');
+    setCaptureBaselineField(baseline, 'flight:webgl', 'fingerprint', '1:ffffff');
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    expect(formatCaptureBaseline(baseline)).toBe(
+      '{\n' +
+        '  "canvas": {\n' +
+        '    "fingerprint": "1:000000"\n' +
+        '  },\n' +
+        '  "flight:webgl": {\n' +
+        '    "fingerprint": "1:ffffff",\n' +
+        '    "sha256": "aaa"\n' +
+        '  }\n' +
+        '}\n',
+    );
+  });
+
+  it('omits undefined fields', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'canvas', 'sha256', 'hash');
+    expect(formatCaptureBaseline(baseline)).toBe('{\n  "canvas": {\n    "sha256": "hash"\n  }\n}\n');
+  });
+
+  it('serializes the empty baseline as an empty object with a trailing newline', () => {
+    expect(formatCaptureBaseline(createCaptureBaseline())).toBe('{}\n');
+  });
+});
+
+describe('getCaptureBaselineField', () => {
+  it('returns null for absent columns and fields', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    expect(getCaptureBaselineField(baseline, 'canvas', 'sha256')).toBeNull();
+    expect(getCaptureBaselineField(baseline, 'webgl', 'fingerprint')).toBeNull();
+  });
+
+  it('reads a set field across independent columns', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    setCaptureBaselineField(baseline, 'webgl', 'fingerprint', '1:ffffff');
+    expect(getCaptureBaselineField(baseline, 'canvas', 'fingerprint')).toBe('1:000000');
+    expect(getCaptureBaselineField(baseline, 'webgl', 'fingerprint')).toBe('1:ffffff');
+  });
+});
+
+describe('parseCaptureBaseline', () => {
+  it('round-trips format output to a stable, equal record', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'flight:webgl', 'fingerprint', '1:ffffff');
+    setCaptureBaselineField(baseline, 'flight:webgl', 'sha256', 'aaa');
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    const text = formatCaptureBaseline(baseline);
+    const parsed = parseCaptureBaseline(text);
+    expect(parsed).toEqual(baseline);
+    expect(parsed).not.toBeNull();
+    expect(formatCaptureBaseline(parsed!)).toBe(text);
+  });
+
+  it('returns null for malformed JSON', () => {
+    expect(parseCaptureBaseline('{not json')).toBeNull();
+  });
+
+  it('returns null for a non-object top-level value', () => {
+    expect(parseCaptureBaseline('42')).toBeNull();
+    expect(parseCaptureBaseline('[]')).toBeNull();
+    expect(parseCaptureBaseline('null')).toBeNull();
+  });
+});
+
+describe('setCaptureBaselineField', () => {
+  it('creates the column entry on first write and merges later fields', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    setCaptureBaselineField(baseline, 'canvas', 'sha256', 'hash');
+    expect(getCaptureBaselineField(baseline, 'canvas', 'fingerprint')).toBe('1:000000');
+    expect(getCaptureBaselineField(baseline, 'canvas', 'sha256')).toBe('hash');
+  });
+
+  it('overwrites an existing field in place', () => {
+    const baseline = createCaptureBaseline();
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:000000');
+    setCaptureBaselineField(baseline, 'canvas', 'fingerprint', '1:ffffff');
+    expect(getCaptureBaselineField(baseline, 'canvas', 'fingerprint')).toBe('1:ffffff');
+  });
+});

package/src/captureComparison.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CAPTURE_PARITY_TOLERANCE,
+  CAPTURE_REGRESSION_TOLERANCE,
+  compareCaptureFingerprints,
+  evaluateCaptureParity,
+  evaluateCaptureRegression,
+} from './captureComparison';
+
+// Short 1x1 fingerprints: `1:<rr><gg><bb>`, three RGB bytes as six hex chars. The per-channel mean
+// distance is (|dR| + |dG| + |dB|) / 3, so a single channel offset of N produces a distance of N / 3.
+const BLACK = '1:000000';
+const NUDGE_15 = '1:0f0000'; // dR = 15 -> distance 5   (== regression tolerance)
+const NUDGE_18 = '1:120000'; // dR = 18 -> distance 6   (>  regression tolerance)
+const NUDGE_45 = '1:2d0000'; // dR = 45 -> distance 15  (== parity tolerance)
+const NUDGE_48 = '1:300000'; // dR = 48 -> distance 16  (>  parity tolerance)
+const WHITE = '1:ffffff'; // distance 255 from black
+
+describe('compareCaptureFingerprints', () => {
+  it('is 0 for identical fingerprints', () => {
+    expect(compareCaptureFingerprints(BLACK, BLACK)).toBe(0);
+    expect(compareCaptureFingerprints(WHITE, WHITE)).toBe(0);
+  });
+
+  it('measures the mean absolute per-channel distance', () => {
+    expect(compareCaptureFingerprints(BLACK, NUDGE_15)).toBe(5);
+    expect(compareCaptureFingerprints(BLACK, WHITE)).toBe(255);
+  });
+
+  it('returns Infinity when either fingerprint is unparseable', () => {
+    expect(compareCaptureFingerprints('not-a-fingerprint', BLACK)).toBe(Number.POSITIVE_INFINITY);
+    expect(compareCaptureFingerprints(BLACK, '')).toBe(Number.POSITIVE_INFINITY);
+  });
+
+  it('returns Infinity when the grid sizes differ and are not comparable', () => {
+    const twoByTwo = '2:' + '00'.repeat(2 * 2 * 3);
+    expect(compareCaptureFingerprints(BLACK, twoByTwo)).toBe(Number.POSITIVE_INFINITY);
+  });
+});
+
+describe('evaluateCaptureParity', () => {
+  it('defaults to the parity tolerance and passes at the boundary', () => {
+    const result = evaluateCaptureParity(BLACK, NUDGE_45);
+    expect(result.tolerance).toBe(CAPTURE_PARITY_TOLERANCE);
+    expect(result.difference).toBe(15);
+    expect(result.pass).toBe(true);
+  });
+
+  it('fails just past the parity tolerance', () => {
+    const result = evaluateCaptureParity(BLACK, NUDGE_48);
+    expect(result.difference).toBe(16);
+    expect(result.pass).toBe(false);
+  });
+
+  it('fails on an unparseable fingerprint via the Infinity sentinel', () => {
+    const result = evaluateCaptureParity(BLACK, 'broken');
+    expect(result.difference).toBe(Number.POSITIVE_INFINITY);
+    expect(result.pass).toBe(false);
+  });
+
+  it('honors an explicit tolerance override', () => {
+    expect(evaluateCaptureParity(BLACK, NUDGE_48, 20).pass).toBe(true);
+  });
+});
+
+describe('evaluateCaptureRegression', () => {
+  it('defaults to the regression tolerance and passes at the boundary', () => {
+    const result = evaluateCaptureRegression(BLACK, NUDGE_15);
+    expect(result.tolerance).toBe(CAPTURE_REGRESSION_TOLERANCE);
+    expect(result.difference).toBe(5);
+    expect(result.pass).toBe(true);
+  });
+
+  it('passes for an identical fingerprint', () => {
+    const result = evaluateCaptureRegression(WHITE, WHITE);
+    expect(result.difference).toBe(0);
+    expect(result.pass).toBe(true);
+  });
+
+  it('fails just past the regression tolerance', () => {
+    const result = evaluateCaptureRegression(BLACK, NUDGE_18);
+    expect(result.difference).toBe(6);
+    expect(result.pass).toBe(false);
+  });
+
+  it('fails on an unparseable baseline via the Infinity sentinel', () => {
+    const result = evaluateCaptureRegression(BLACK, 'no-baseline');
+    expect(result.difference).toBe(Number.POSITIVE_INFINITY);
+    expect(result.pass).toBe(false);
+  });
+
+  it('honors an explicit tolerance override', () => {
+    expect(evaluateCaptureRegression(BLACK, NUDGE_18, 10).pass).toBe(true);
+  });
+});