@flighthq/tool-capture 0.3.0-next.906.07cea63 → 0.3.0

package/dist/captureSuite.js.map

@@ -1 +1 @@
-{"version":3,"file":"captureSuite.js","sourceRoot":"","sources":["../src/captureSuite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"captureSuite.js","sourceRoot":"","sources":["../src/captureSuite.ts"],"names":[],"mappings":"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"}

package/dist/captureTimeout.d.ts

@@ -0,0 +1,4 @@
+export declare function getCaptureTimeoutMs(): number;
+export declare function resolveCaptureTimeoutMs(timeoutFlag: string | undefined, environmentOverride: string | undefined): number;
+export declare function setCaptureTimeoutMs(timeoutMs: number | null): void;
+//# sourceMappingURL=captureTimeout.d.ts.map

package/dist/captureTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureTimeout.d.ts","sourceRoot":"","sources":["../src/captureTimeout.ts"],"names":[],"mappings":"AAUA,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAQD,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,mBAAmB,EAAE,MAAM,GAAG,SAAS,GACtC,MAAM,CAER;AAKD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAElE"}

package/dist/captureTimeout.js

@@ -0,0 +1,39 @@
+// The wall-clock budget for a single capture wait — a page load, a frame-reached poll, or a wait for
+// the in-page verifier to reach a terminal state. One number governs all of them on purpose: they are
+// the same question ("how long may one page take before we call it stalled?"), and a run that has to
+// be given more room on a slow or contended machine needs every one of them to move together.
+//
+// It is resolved from a flag or the environment rather than edited in source because the value is a
+// property of the MACHINE, not of the code: the same budget that is generous on a developer laptop is
+// tight on a CI runner sharing one software adapter between concurrent workers. A constant that has to
+// be edited to run somewhere else is a constant that gets edited and committed for one environment,
+// then silently governs every other.
+export function getCaptureTimeoutMs() {
+    return captureTimeoutMs ?? resolveCaptureTimeoutMs(undefined, process.env['FLIGHT_CAPTURE_TIMEOUT_MS']);
+}
+// The flag wins over the environment, which wins over the default — the same precedence
+// resolveCaptureWorkerCount uses, so the two knobs are configured the same way.
+//
+// A value that is not a positive finite number is ignored rather than honored: a zero or negative
+// budget would make every wait expire immediately and report every page as stalled, which reads as a
+// fleet-wide rendering failure rather than as the typo it is.
+export function resolveCaptureTimeoutMs(timeoutFlag, environmentOverride) {
+    return parseCaptureTimeoutMs(timeoutFlag) ?? parseCaptureTimeoutMs(environmentOverride) ?? DEFAULT_CAPTURE_TIMEOUT_MS;
+}
+// Pins the budget for the rest of the process, so a CLI flag reaches the capture and validation waits
+// without threading a parameter through every call. Passing null restores environment/default
+// resolution, which is what a test that pinned a budget uses to put it back.
+export function setCaptureTimeoutMs(timeoutMs) {
+    captureTimeoutMs = timeoutMs;
+}
+function parseCaptureTimeoutMs(value) {
+    if (value === undefined)
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+let captureTimeoutMs = null;
+// Unchanged from the constant this replaced, so a run that sets neither flag nor environment behaves
+// exactly as before.
+const DEFAULT_CAPTURE_TIMEOUT_MS = 15_000;
+//# sourceMappingURL=captureTimeout.js.map

package/dist/captureTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureTimeout.js","sourceRoot":"","sources":["../src/captureTimeout.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,sGAAsG;AACtG,qGAAqG;AACrG,8FAA8F;AAC9F,EAAE;AACF,oGAAoG;AACpG,sGAAsG;AACtG,uGAAuG;AACvG,oGAAoG;AACpG,qCAAqC;AACrC,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,IAAI,uBAAuB,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,CAAC;AAC1G,CAAC;AAED,wFAAwF;AACxF,gFAAgF;AAChF,EAAE;AACF,kGAAkG;AAClG,qGAAqG;AACrG,8DAA8D;AAC9D,MAAM,UAAU,uBAAuB,CACrC,WAA+B,EAC/B,mBAAuC;IAEvC,OAAO,qBAAqB,CAAC,WAAW,CAAC,IAAI,qBAAqB,CAAC,mBAAmB,CAAC,IAAI,0BAA0B,CAAC;AACxH,CAAC;AAED,sGAAsG;AACtG,8FAA8F;AAC9F,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,SAAwB;IAC1D,gBAAgB,GAAG,SAAS,CAAC;AAC/B,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAyB;IACtD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC;AAED,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAE3C,qGAAqG;AACrG,qBAAqB;AACrB,MAAM,0BAA0B,GAAG,MAAM,CAAC"}

package/dist/captureValidation.d.ts

@@ -22,6 +22,18 @@ export interface CaptureValidationOptions {
     workerCount?: number;
     fingerprintSkip?: Readonly<string[]>;
     paritySkip?: Readonly<Record<string, 'all' | Readonly<string[]>>>;
+    /**
+     * Suppress the human-facing progress and summary output. The returned `CaptureValidationResult`
+     * carries every fact those lines report, so a programmatic caller loses nothing by silencing them.
+     *
+     * This exists because a caller that is *asserting how a failure is classified* still renders a real
+     * failure summary — a `✗ FAILED … 1 regression failed` block printed by a test that passes. In a CI
+     * log those lines are indistinguishable from an actual failure, which is worse than merely untidy:
+     * it trains a reader to scroll past the exact string they should stop at. Printing is a side effect
+     * the caller should ask for rather than one it has to work around, which is why this is an explicit
+     * option and not a check of the ambient environment.
+     */
+    quiet?: boolean;
     /** Explicit visual comparison groups. Unlike legacy parity, these may include DOM and arbitrary targets. */
     parityGroups?: Readonly<Record<string, Readonly<CaptureParityGroup>>>;
     /** Assertion-passed fingerprints from a preceding capture pass. Avoids reloading those pages. */
@@ -36,7 +48,9 @@ export interface CaptureValidationResult {
     loadFailures: number;
     parityFailures: number;
     parityPasses: number;
+    parityUncovered: number;
     regressionFailures: number;
+    regressionUncovered: number;
     regressionPasses: number;
     shouldFail: boolean;
     skipped: number;
@@ -45,6 +59,19 @@ export interface CaptureValidationResult {
     reportPath: string | null;
     checks: CaptureValidationCheck[];
 }
+export interface CaptureParityCoverage {
+    gateParity: boolean;
+    interrupted: boolean;
+    parityComparisons: number;
+    parityUncovered: number;
+    rendererFilterCount: number;
+}
+export interface CaptureRegressionCoverage {
+    gateRegression: boolean;
+    interrupted: boolean;
+    regressionComparisons: number;
+    regressionUncovered: number;
+}
 export interface CaptureValidationCheck {
     entry: string;
     renderers: string[];
@@ -53,6 +80,18 @@ export interface CaptureValidationCheck {
     message: string;
     distance?: number;
     threshold?: number;
+    /** Classification present only on a fingerprint mismatch that the regression leg already failed. */
+    sourceHashStatus?: 'changed' | 'unchanged' | 'unavailable';
+    recordedSourceHash?: string | null;
+    currentSourceHash?: string | null;
 }
+export declare function explainCaptureParityUncovered(eligibleCount: number, hasGroups: boolean): string;
+export declare function explainCaptureVerificationStall(verification: Readonly<{
+    fingerprint?: string | null;
+    state?: string;
+}> | null, waitedMs: number): string;
+export declare function isCaptureParityCoverageFailure(run: Readonly<CaptureParityCoverage>): boolean;
+export declare function isCaptureRegressionCoverageFailure(run: Readonly<CaptureRegressionCoverage>): boolean;
+export declare function isUniformCaptureFingerprint(fingerprint: string): boolean;
 export declare function runCaptureValidation(input: Readonly<CaptureValidationOptions>): Promise<CaptureValidationResult>;
 //# sourceMappingURL=captureValidation.d.ts.map

package/dist/captureValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"captureValidation.d.ts","sourceRoot":"","sources":["../src/captureValidation.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAKjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAClE,4GAA4G;IAC5G,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACtE,iGAAiG;IACjG,YAAY,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAC/C,kFAAkF;IAClF,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAC;IAClE,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAofD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GACxC,OAAO,CAAC,uBAAuB,CAAC,CA6LlC"}
+{"version":3,"file":"captureValidation.d.ts","sourceRoot":"","sources":["../src/captureValidation.ts"],"names":[],"mappings":"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"}

package/dist/captureValidation.js

@@ -28,6 +28,8 @@ import { formatDetailLine, formatStatusLine, formatSummaryCount, formatSummaryLi
 import { installAbortHandler, isBrowserClosedError } from './captureInterrupt.js';
 import { CAPTURE_PROTOCOL_VERSION } from './captureProtocol.js';
 import { writeCaptureReport } from './captureReport.js';
+import { getCaptureSceneSourceHash } from './captureSourceHash.js';
+import { getCaptureTimeoutMs } from './captureTimeout.js';
 function fingerprintKey(entry, renderer) {
     return `${entry}\0${renderer}`;
 }
@@ -48,8 +50,19 @@ function addPair(pairs, fingerprints, a, b, group, tolerance) {
     if (dist !== null)
         pairs.push({ a, b, label: `${group === '' ? '' : `${group}:`}${a}·${b}`, dist, tolerance });
 }
-// Loads a single test/renderer page and returns its render fingerprint, or null with a reason and a
-// flag marking whether the cause is a genuinely-unavailable backend (skippable) versus a real error.
+// Why an entry produced no parity pair. Each case has a different remedy, and a bare "0 comparisons"
+// sends a reader to the wrong one: an ineligible backend needs a parity group or a committed baseline,
+// while a single eligible backend has nothing to disagree with and needs a second one in scope.
+export function explainCaptureParityUncovered(eligibleCount, hasGroups) {
+    if (eligibleCount === 0) {
+        return hasGroups
+            ? 'no renderer in any parity group is eligible'
+            : 'no renderer is parity-eligible — declare a parity group, or commit a fingerprint baseline';
+    }
+    if (eligibleCount === 1)
+        return 'only one parity-eligible renderer — nothing to compare it against';
+    return 'every eligible pair is excluded by a parity skip';
+}
 async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
     // The real failure reason can arrive three ways, and Playwright's pageerror only catches the first:
     // a synchronous uncaught exception (pageerror), an unhandled promise rejection (the verifier is an
@@ -71,7 +84,7 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         const route = getCaptureEntryRoute(entry, renderer, subject);
         await page.goto(`${baseUrl}/${route}`, {
             waitUntil: 'domcontentloaded',
-            timeout: 15_000,
+            timeout: getCaptureTimeoutMs(),
         });
         // Wait for a TERMINAL state, not merely for __ftVerification to exist. runRenderVerification sets
         // that object up front with fingerprint:null, then fills the fingerprint only AFTER an async step —
@@ -79,12 +92,14 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         // null mid-readback and misreport every webgpu test as "verifier did not run" (canvas/WebGL win the
         // race because their readback is synchronous). So wait until the fingerprint is populated OR an error
         // overlay appears, then read the result. Poll on a timer (the capture harness halts rAF).
+        const waitStartedAt = performance.now();
         await page
             .waitForFunction(() => {
             const v = window.__ftVerification;
             return v?.state === 'passed' || v?.state === 'failed' || document.getElementById('ft-error') !== null;
-        }, null, { timeout: 15_000, polling: 100 })
+        }, null, { timeout: getCaptureTimeoutMs(), polling: 100 })
             .catch(() => { });
+        const waitedMs = Math.round(performance.now() - waitStartedAt);
         const verification = await page
             .evaluate(() => window.__ftVerification ?? null)
             .catch(() => null);
@@ -110,7 +125,12 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         const detail = verification?.error || pageError || overlay;
         if (BACKEND_UNAVAILABLE.test(detail))
             return { fingerprint: null, reason: `backend unavailable (${detail})`, unavailable: true, aborted: false };
-        return { fingerprint: null, reason: detail || 'verifier did not run', unavailable: false, aborted: false };
+        return {
+            fingerprint: null,
+            reason: detail || explainCaptureVerificationStall(verification, waitedMs),
+            unavailable: false,
+            aborted: false,
+        };
     }
     catch (err) {
         // A closed browser/page is the interrupt tearing things down — report it as an abort, not a failure.
@@ -187,10 +207,85 @@ async function captureDomFingerprint(page) {
         await handle?.dispose();
     }
 }
+// Why a verification wait ended without a fingerprint, as a reason a reader can act on. The bare
+// "verifier did not run" it replaces named a symptom shared by causes with opposite remedies, and left
+// the one number that decides between them — how long it actually waited — unrecorded.
+//
+// This exists because a gate that silently fails to run is the same inert-gate class as a check that
+// silently passes: the leg reports a failure nobody can diagnose, so it gets re-run rather than fixed.
+// Measured for context: the heaviest example scene verifies in ~4.1-6.2s across 6 to 16 workers, even
+// with a full monorepo check and test suite running alongside — about 42% of the budget at worst. So a
+// stall at or near the full budget is NOT the scene being slow, and the reason says so rather than
+// leaving the next reader to assume it and raise the timeout.
+//
+// The budget is read from the same seam the wait reads, not passed in, so the two can never disagree
+// about what it was. Passing it would let a caller name a budget the wait did not use, which is the
+// one thing this message must never do — it exists to be trusted about how long the wait actually had.
+export function explainCaptureVerificationStall(verification, waitedMs) {
+    const budget = `waited ${waitedMs}ms of ${getCaptureTimeoutMs()}ms`;
+    if (verification === null || verification === undefined) {
+        return `verifier never registered — no __ftVerification on the page (${budget}); the page's module likely failed to run`;
+    }
+    if (verification.state === undefined) {
+        return `verifier object present but carries no state (${budget}); suspect a capture-protocol mismatch`;
+    }
+    if (verification.state === 'passed') {
+        return `verifier passed but produced no fingerprint (${budget}); the readback completed empty`;
+    }
+    // Registered and still non-terminal: it started and never finished, which is a stall rather than a
+    // scene that is merely expensive. The STAGE is the actionable half — 'awaitingFrame' means a presented
+    // frame never arrived (page/scheduler), 'readingBack' means the GPU readback never resolved (driver).
+    const stage = verification.stage;
+    const where = stage === undefined ? '' : ` at stage "${stage}"`;
+    return `verifier registered but stalled${where} in state "${verification.state}" (${budget}); it started and never reached a terminal state`;
+}
+export function isCaptureParityCoverageFailure(run) {
+    if (!run.gateParity || run.interrupted)
+        return false;
+    if (run.rendererFilterCount === 1)
+        return false;
+    return run.parityComparisons === 0 && run.parityUncovered > 0;
+}
+// A tier either has what it needs and gates hard, or it says so loudly — there is no silent
+// degrade-to-success. A gated parity run that compared NOTHING is UNCONFIGURED, not clean, and the
+// green tick it used to print is worse than an absent leg, because an absent leg is visibly absent.
+//
+// Two runs genuinely cannot compare, and are exempt rather than excused: one narrowed to a single
+// renderer (the operator disabled parity themselves, so reporting it back at them is noise), and an
+// interrupted run, whose remaining entries never ran at all. A run with nothing uncovered — every
+// entry skipped by policy before parity was reached — is not this failure either.
+export function isCaptureRegressionCoverageFailure(run) {
+    if (!run.gateRegression || run.interrupted)
+        return false;
+    return run.regressionComparisons === 0 && run.regressionUncovered > 0;
+}
+// Loads a single test/renderer page and returns its render fingerprint, or null with a reason and a
+// flag marking whether the cause is a genuinely-unavailable backend (skippable) versus a real error.
+// True when every cell of a coarse fingerprint carries the same value — a blank or flat-filled frame.
+//
+// This is a WRITE-SIDE gate, not a render check: a uniform frame may be a legitimate render (a solid
+// background scene), but it is never worth BLESSING as a regression baseline, because it cannot
+// distinguish a working scene from a broken one. Refusing it costs a real flat scene its regression
+// coverage and costs a broken one nothing — the asymmetry is the point.
+//
+// Format: "<cellSize>:<hex cells>", so the payload after the colon is split into fixed-width cells.
+export function isUniformCaptureFingerprint(fingerprint) {
+    const payload = fingerprint.slice(fingerprint.indexOf(':') + 1);
+    if (payload.length <= CAPTURE_FINGERPRINT_CELL_CHARS)
+        return true;
+    const first = payload.slice(0, CAPTURE_FINGERPRINT_CELL_CHARS);
+    for (let i = CAPTURE_FINGERPRINT_CELL_CHARS; i < payload.length; i += CAPTURE_FINGERPRINT_CELL_CHARS) {
+        if (payload.slice(i, i + CAPTURE_FINGERPRINT_CELL_CHARS) !== first)
+            return false;
+    }
+    return true;
+}
 async function processEntry(entry, entryIndex, totalEntries, isAborted, options, samples) {
     const result = {
         regressionFailures: 0,
+        regressionUncovered: 0,
         parityFailures: 0,
+        parityUncovered: 0,
         regressionPasses: 0,
         parityPasses: 0,
         loadFailures: 0,
@@ -201,6 +296,19 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
     };
     result.output.push(`${pc.dim(`[${entryIndex + 1}/${totalEntries}]`)} ${pc.bold(entry.name)}`);
     const renderers = validationRenderers(entry, options.rendererFilter, options.parityGroups);
+    // An entry whose renderers are all filtered out otherwise emits NOTHING — no skip line, no parity line,
+    // no failure — so a reader cannot tell "covered and silent" from "never ran". Say it out loud.
+    if (renderers.length === 0) {
+        result.output.push(`  ${pc.dim('·')} ${pc.dim(`no renderer in scope for this leg (entry declares: ${entry.renderers.join(', ') || 'none'})`)}`);
+        result.checks.push({
+            entry: entry.name,
+            renderers: [],
+            kind: 'load',
+            status: 'skipped',
+            message: `no renderer in scope; entry declares ${entry.renderers.join(', ') || 'none'}`,
+        });
+        return result;
+    }
     const labelWidth = Math.max(6, ...renderers.map((r) => r.length));
     const statusLine = (tone, label, message) => formatStatusLine(tone, label, labelWidth, message);
     const detailLine = (glyph, label, message, paint) => formatDetailLine(glyph, label, labelWidth, message, paint);
@@ -278,7 +386,30 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                 });
                 continue;
             }
+            // A uniform fingerprint is every cell identical — a blank or flat-filled frame. The stability check
+            // above CANNOT catch it: a frame that renders blank every time has a self-distance of zero, the most
+            // stable result possible, so it sails through and gets blessed as ground truth. That has already
+            // happened once in this repo (a WebGPU capture on a software adapter that cannot present to the
+            // swapchain), and a blank baseline is worse than no baseline, because every later run then compares
+            // against the blank and passes.
+            if (isUniformCaptureFingerprint(fingerprint)) {
+                const note = 'not baselined — uniform frame (every cell identical); a blank capture must not become ground truth';
+                result.output.push(statusLine('skip', renderer, note));
+                result.skipped++;
+                result.checks.push({
+                    entry: entry.name,
+                    renderers: [renderer],
+                    kind: 'baseline',
+                    status: 'skipped',
+                    message: note,
+                });
+                continue;
+            }
             setBaselineField(options.root, options.subject, entry.name, renderer, 'fingerprint', fingerprint);
+            const sourceHash = getCaptureSceneSourceHash(options.root, options.subject, entry, renderer);
+            if (sourceHash !== null) {
+                setBaselineField(options.root, options.subject, entry.name, renderer, 'sourceHash', sourceHash);
+            }
             result.output.push(statusLine('pass', renderer, 'baseline written'));
             result.updated++;
             result.checks.push({
@@ -293,6 +424,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
         }
         const committed = getBaselineField(options.root, options.subject, entry.name, renderer, 'fingerprint');
         if (committed === null) {
+            result.regressionUncovered++;
             result.output.push(statusLine('muted', renderer, 'no fingerprint baseline — skipped'));
             result.skipped++;
             result.checks.push({
@@ -332,16 +464,23 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
         else if (options.gateRegression) {
             const check = evaluateCaptureRegression(fingerprint, committed, options.regressionTolerance);
             if (!check.pass) {
-                result.output.push(statusLine('fail', renderer, `regression ${dist.toFixed(2)} > ${options.regressionTolerance}`));
+                const recordedSourceHash = getBaselineField(options.root, options.subject, entry.name, renderer, 'sourceHash');
+                const currentSourceHash = getCaptureSceneSourceHash(options.root, options.subject, entry, renderer);
+                const freshness = classifyCaptureBaselineFreshness(recordedSourceHash, currentSourceHash);
+                const message = `regression ${dist.toFixed(2)} > ${options.regressionTolerance} — ${freshness.message}`;
+                result.output.push(statusLine('fail', renderer, message));
                 result.regressionFailures++;
                 result.checks.push({
                     entry: entry.name,
                     renderers: [renderer],
                     kind: 'regression',
                     status: 'failed',
-                    message: `regression ${dist.toFixed(2)} > ${options.regressionTolerance}`,
+                    message,
                     distance: dist,
                     threshold: options.regressionTolerance,
+                    sourceHashStatus: freshness.status,
+                    recordedSourceHash,
+                    currentSourceHash,
                 });
             }
             else {
@@ -394,6 +533,20 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
             }
         }
     }
+    // A gated parity run that compared NOTHING is the failure mode this whole tier was silently missing:
+    // with no eligible renderers there are no pairs, so every branch below is skipped and the entry reports
+    // success having checked nothing. Record it as uncovered so the run-level verdict can say so out loud.
+    // Report and baseline-write modes are excluded because neither claims to gate anything.
+    if (pairs.length === 0 && options.gateParity && !options.report && !options.updateFingerprints) {
+        result.parityUncovered++;
+        result.checks.push({
+            entry: entry.name,
+            renderers: [...eligible.keys()],
+            kind: 'parity',
+            status: 'skipped',
+            message: explainCaptureParityUncovered(eligible.size, groups.length > 0),
+        });
+    }
     if (pairs.length > 0) {
         if (options.report) {
             const segments = pairs.map((p) => `${p.label} ${p.dist.toFixed(2)}`).join('  ');
@@ -462,6 +615,7 @@ export async function runCaptureValidation(input) {
         rendererFilter: input.rendererFilter ?? [],
         captureFrames: Math.max(1, input.captureFrames ?? 1),
         report: input.report ?? false,
+        quiet: input.quiet ?? false,
         updateFingerprints: input.updateFingerprints ?? false,
         gateRegression: input.gateRegression ?? true,
         gateParity: input.gateParity ?? true,
@@ -483,6 +637,8 @@ export async function runCaptureValidation(input) {
     const isAborted = installAbortHandler();
     let regressionFailures = 0;
     let parityFailures = 0;
+    let parityUncovered = 0;
+    let regressionUncovered = 0;
     let regressionPasses = 0;
     let parityPasses = 0;
     let loadFailures = 0;
@@ -532,14 +688,17 @@ export async function runCaptureValidation(input) {
                     const result = await processEntry(job.entry, job.index, entries.length, isAborted, options, samples);
                     regressionFailures += result.regressionFailures;
                     parityFailures += result.parityFailures;
+                    parityUncovered += result.parityUncovered;
+                    regressionUncovered += result.regressionUncovered;
                     regressionPasses += result.regressionPasses;
                     parityPasses += result.parityPasses;
                     loadFailures += result.loadFailures;
                     updated += result.updated;
                     skipped += result.skipped;
                     checks.push(...result.checks);
-                    for (const line of result.output)
-                        console.log(line);
+                    if (!options.quiet)
+                        for (const line of result.output)
+                            console.log(line);
                 }
             });
             await Promise.all(workers);
@@ -551,14 +710,17 @@ export async function runCaptureValidation(input) {
                 const result = await processEntry(entries[entryIndex], entryIndex, entries.length, isAborted, options, samples);
                 regressionFailures += result.regressionFailures;
                 parityFailures += result.parityFailures;
+                parityUncovered += result.parityUncovered;
+                regressionUncovered += result.regressionUncovered;
                 regressionPasses += result.regressionPasses;
                 parityPasses += result.parityPasses;
                 loadFailures += result.loadFailures;
                 updated += result.updated;
                 skipped += result.skipped;
                 checks.push(...result.checks);
-                for (const line of result.output)
-                    console.log(line);
+                if (!options.quiet)
+                    for (const line of result.output)
+                        console.log(line);
             }
         }
     }
@@ -570,13 +732,14 @@ export async function runCaptureValidation(input) {
     const interrupted = isAborted();
     const note = interrupted ? pc.yellow('   — interrupted (partial run)') : '';
     if (options.updateFingerprints) {
-        console.log('\n' +
-            formatSummaryLine(loadFailures > 0, [
-                formatSummaryCount(updated, 'baselines written', 'pass'),
-                formatSummaryCount(skipped, 'skipped', 'warn'),
-                formatSummaryCount(loadFailures, 'load failures', 'fail'),
-            ]) +
-            note);
+        if (!options.quiet)
+            console.log('\n' +
+                formatSummaryLine(loadFailures > 0, [
+                    formatSummaryCount(updated, 'baselines written', 'pass'),
+                    formatSummaryCount(skipped, 'skipped', 'warn'),
+                    formatSummaryCount(loadFailures, 'load failures', 'fail'),
+                ]) +
+                note);
         if (loadFailures > 0) {
             console.error(pc.red(`${loadFailures} test(s) failed to load/verify — not a clean baseline run.`));
             return createResult(true);
@@ -584,26 +747,77 @@ export async function runCaptureValidation(input) {
         return createResult(loadFailures > 0);
     }
     if (options.report) {
+        if (!options.quiet)
+            console.log('\n' +
+                formatSummaryLine(loadFailures > 0, [
+                    formatSummaryCount(skipped, 'skipped', 'warn'),
+                    formatSummaryCount(loadFailures, 'load failures', 'fail'),
+                ]) +
+                pc.dim('   (report only — nothing gated)') +
+                note);
+        return createResult(loadFailures > 0);
+    }
+    // Same doctrine, other tier: a gated regression leg that compared NOTHING is unconfigured, not clean.
+    // Without this the tier reads as a green pass with zero coverage the moment nothing else is red.
+    const regressionCoverageFailed = isCaptureRegressionCoverageFailure({
+        gateRegression: options.gateRegression,
+        interrupted,
+        regressionComparisons: regressionPasses + regressionFailures,
+        regressionUncovered,
+    });
+    const parityCoverageFailed = isCaptureParityCoverageFailure({
+        gateParity: options.gateParity,
+        interrupted,
+        parityComparisons: parityPasses + parityFailures,
+        parityUncovered,
+        rendererFilterCount: options.rendererFilter.length,
+    });
+    const failed = regressionFailures > 0 ||
+        parityFailures > 0 ||
+        loadFailures > 0 ||
+        parityCoverageFailed ||
+        regressionCoverageFailed;
+    if (!options.quiet)
         console.log('\n' +
-            formatSummaryLine(loadFailures > 0, [
+            formatSummaryLine(failed, [
+                formatSummaryCount(regressionPasses, 'regression passed', 'pass'),
+                formatSummaryCount(regressionFailures, 'regression failed', 'fail'),
+                formatSummaryCount(parityPasses, 'parity passed', 'pass'),
+                formatSummaryCount(parityFailures, 'parity failed', 'fail'),
+                formatSummaryCount(parityUncovered, 'parity uncovered', parityCoverageFailed ? 'fail' : 'warn'),
+                formatSummaryCount(regressionUncovered, 'regression uncovered', regressionCoverageFailed ? 'fail' : 'warn'),
                 formatSummaryCount(skipped, 'skipped', 'warn'),
                 formatSummaryCount(loadFailures, 'load failures', 'fail'),
             ]) +
-            pc.dim('   (report only — nothing gated)') +
             note);
-        return createResult(loadFailures > 0);
+    // Name the entries behind an "N uncovered" count: a bare number tells a reader something is missing but
+    // not what to go look at, and the entries differ in why.
+    for (const [label, uncovered, failedTier] of [
+        ['parity', parityUncovered, parityCoverageFailed],
+        ['regression', regressionUncovered, regressionCoverageFailed],
+    ]) {
+        if (uncovered === 0)
+            continue;
+        const names = [
+            ...new Set(checks
+                .filter((check) => check.kind === (label === 'parity' ? 'parity' : 'baseline') && check.status === 'skipped')
+                .map((check) => check.entry)),
+        ];
+        if (names.length > 0) {
+            const line = `  ${label} uncovered: ${names.join(', ')}`;
+            if (!options.quiet)
+                console.log(failedTier ? pc.red(line) : pc.yellow(line));
+        }
+    }
+    if (regressionCoverageFailed) {
+        console.error(pc.red(`\nRegression compared NOTHING across ${regressionUncovered} entr${regressionUncovered === 1 ? 'y' : 'ies'} — this tier is unconfigured, not clean. Re-capture with --update-fingerprints on a leg where the tier is valid, or remove the stale baselines so the gap is honest.`));
+    }
+    if (parityCoverageFailed) {
+        console.error(pc.red(`\nParity compared NOTHING across all ${parityUncovered} entr${parityUncovered === 1 ? 'y' : 'ies'} — this leg is unconfigured, not clean.`));
+        for (const reason of new Set(checks.filter((check) => check.kind === 'parity' && check.status === 'skipped').map((check) => check.message))) {
+            console.error(pc.red(`  · ${reason}`));
+        }
     }
-    const failed = regressionFailures > 0 || parityFailures > 0 || loadFailures > 0;
-    console.log('\n' +
-        formatSummaryLine(failed, [
-            formatSummaryCount(regressionPasses, 'regression passed', 'pass'),
-            formatSummaryCount(regressionFailures, 'regression failed', 'fail'),
-            formatSummaryCount(parityPasses, 'parity passed', 'pass'),
-            formatSummaryCount(parityFailures, 'parity failed', 'fail'),
-            formatSummaryCount(skipped, 'skipped', 'warn'),
-            formatSummaryCount(loadFailures, 'load failures', 'fail'),
-        ]) +
-        note);
     return createResult(failed);
     function createResult(shouldFail) {
         const reportPath = input.reportPath === false
@@ -614,7 +828,9 @@ export async function runCaptureValidation(input) {
             loadFailures,
             parityFailures,
             parityPasses,
+            parityUncovered,
             regressionFailures,
+            regressionUncovered,
             regressionPasses,
             shouldFail,
             skipped,
@@ -628,4 +844,30 @@ export async function runCaptureValidation(input) {
         return result;
     }
 }
+function classifyCaptureBaselineFreshness(recordedSourceHash, currentSourceHash) {
+    if (recordedSourceHash === null) {
+        return {
+            message: 'scene-source freshness unavailable (baseline has no recorded source hash)',
+            status: 'unavailable',
+        };
+    }
+    if (currentSourceHash === null) {
+        return {
+            message: 'scene-source freshness unavailable (current scene source could not be read)',
+            status: 'unavailable',
+        };
+    }
+    if (recordedSourceHash !== currentSourceHash) {
+        return {
+            message: 'scene source changed since baseline — recapture owed by the scene owner',
+            status: 'changed',
+        };
+    }
+    return {
+        message: 'scene source unchanged since baseline — environment drift; never rebaseline',
+        status: 'unchanged',
+    };
+}
+// Hex characters per fingerprint cell (one RGB triplet).
+const CAPTURE_FINGERPRINT_CELL_CHARS = 6;
 //# sourceMappingURL=captureValidation.js.map