/**
 * GPU Parity Diff — diagnostic helpers for detecting shape-dependent
 * hardware-GPU capture bugs by comparing frames captured via the two
 * capture paths (hardware-GPU vs software-GPU / screenshot bypass).
 *
 * Field pattern this exists to catch:
 *
 *   • ts=1784049136 · hardware-GPU capture emitted intermittent black
 *     rectangles in one scene; `--no-browser-gpu --low-memory-mode
 *     --workers 1` (software-GPU screenshot mode) resolved it.
 *   • ts=1784032286 · animated `clip-path` on a large image → intermittent
 *     black rectangles from Chrome capture; deterministic precomposited
 *     swipe states removed the artifact.
 *   • Baseline · JetBrains Mono glyph-drop on parallel/BeginFrame text
 *     capture.
 *
 * Common shape: hardware-GPU writes solid-black regions where content
 * should exist; software-GPU / screenshot fallback renders the same
 * region correctly. A raw per-pixel diff is a coarse signal for this —
 * on its own it fires on every animation frame's compositor jitter, so
 * this module also isolates the *asymmetric* black-in-A-only pattern
 * that is the diagnostic fingerprint of the bug.
 *
 * This module is the reduced-scope first pass: a pure helper + unit
 * tests. Wiring a `hyperframes verify-gpu-parity` CLI surface, capture
 * orchestration, and integration coverage is intentionally deferred to
 * a follow-up so the diagnostic primitive can land and be exercised
 * against real captured frames in isolation.
 */
/** A decoded RGBA frame. Matches the shape returned by `decodePng`. */
export interface RgbaFrame {
    width: number;
    height: number;
    data: Uint8Array;
}
export interface GpuParityDiffOptions {
    /**
     * Per-channel absolute difference at which a pixel is considered "differing".
     * A pixel counts as differing if any of R/G/B channels differ by more than
     * this value. Default 8 (tolerates minor compositor jitter / dithering).
     */
    pixelChannelTolerance?: number;
    /**
     * A pixel qualifies as "solid black" when R + G + B is ≤ this value.
     * Default 12 (covers hardware capture bugs that write pure #000 as well
     * as slightly off-black values from Chrome's compositor).
     */
    blackSumThreshold?: number;
    /**
     * A pixel qualifies as "has content" (non-black) when R + G + B is ≥ this
     * value. Default 32 — deliberately higher than `blackSumThreshold` so the
     * two categories cannot overlap on borderline near-black pixels.
     */
    contentSumThreshold?: number;
    /**
     * A frame is flagged as failing parity when the black-only-in-A fraction
     * of pixels exceeds this value. Default 0.001 (~0.1% of the frame).
     * Lowering trades sensitivity for false-positive risk on legitimate
     * animation frames that momentarily contain a small black shape only on
     * one capture path.
     */
    blackOnlyFractionThreshold?: number;
}
export interface BlackOnlyInARegion {
    /** Count of pixels that are black in A but have content in B. */
    pixels: number;
    /** `pixels / (width * height)`. */
    fraction: number;
    /**
     * Axis-aligned bounding box of all black-only-in-A pixels. `null` when
     * `pixels === 0`. This is intentionally coarse — a single bbox is
     * cheaper than connected-component labeling and is sufficient to
     * localize the "one large black rectangle" pattern the field bugs
     * produce. Callers wanting per-region detail can extend this later.
     */
    boundingBox: {
        x: number;
        y: number;
        width: number;
        height: number;
    } | null;
}
export interface GpuParityDiffResult {
    /** Frame dimensions (both inputs must match). */
    width: number;
    height: number;
    /** Total pixels compared. */
    totalPixels: number;
    /** Pixels differing beyond `pixelChannelTolerance`. */
    diffPixels: number;
    /** `diffPixels / totalPixels`. */
    diffFraction: number;
    /**
     * Pixels that are solid-black in A (the hardware-GPU frame by
     * convention) *and* have content in B (the software-GPU frame). This
     * is the diagnostic-grade signal for shape-dependent hardware-GPU
     * capture bugs.
     */
    blackOnlyInA: BlackOnlyInARegion;
    /**
     * Symmetric counterpart — black in B but content in A. Useful for
     * ruling out the inverse (extremely rare in the wild, but if it
     * shows up it means the software path is the buggy one).
     */
    blackOnlyInB: BlackOnlyInARegion;
}
export interface VerifyGpuParityResult {
    ok: boolean;
    /** Human-readable failure summary; empty when `ok === true`. */
    reason: string;
    diff: GpuParityDiffResult;
}
/**
 * Compare two RGBA frames captured via different GPU paths.
 *
 * The two inputs must have identical dimensions; on mismatch this throws
 * (with the mismatched sizes surfaced in the message) so callers cannot
 * silently compare misaligned frames.
 *
 * Alpha channel is *not* considered for the black-only detection — Chrome's
 * capture output is opaque along the code paths this diagnostic targets,
 * and considering alpha would false-positive on legitimately transparent
 * pixels. `pixelChannelTolerance` also compares only R/G/B for the same
 * reason.
 */
export declare function diffGpuParityFrames(a: RgbaFrame, b: RgbaFrame, options?: GpuParityDiffOptions): GpuParityDiffResult;
/**
 * PNG-buffer convenience wrapper around `diffGpuParityFrames`. Decodes
 * both inputs via `decodePng` and delegates. Errors from the decoder are
 * re-thrown with `cause` preserved so the failing side (A or B) is
 * obvious in the stack.
 */
export declare function diffGpuParityPngs(pngA: Buffer, pngB: Buffer, options?: GpuParityDiffOptions): GpuParityDiffResult;
/**
 * Verdict wrapper — returns `{ ok, reason }` suitable for a follow-up
 * CLI or gate to emit. `ok === false` when either black-only fraction
 * exceeds `blackOnlyFractionThreshold`. Raw diff numbers are always
 * included on both branches so callers can log or gate on their own
 * metrics without a second pass.
 */
export declare function verifyGpuParity(a: RgbaFrame, b: RgbaFrame, options?: GpuParityDiffOptions): VerifyGpuParityResult;
//# sourceMappingURL=gpuParityDiff.d.ts.map