import type { DeterministicFinding, ShotRecord } from "../types.js";
export declare const PROVENANCE_VERSION = 1;
export interface ProvenanceElement {
    tag: string;
    id: string | null;
    testid: string | null;
    /** Explicit role attribute only. */
    role: string | null;
    /** First 5 class names, each capped. */
    classes: string[];
    /** innerText, whitespace collapsed, first 80 chars. */
    text: string | null;
    cssPath: string;
    landmark: boolean;
    /** Document-relative CSS px. */
    box: {
        x: number;
        y: number;
        w: number;
        h: number;
    };
    /** Framework component-name chain, innermost first, up to 5. */
    components: string[];
    /** Best-effort source hint from dev tooling; absent in production builds. */
    source?: {
        file: string;
        line?: number;
    };
}
export interface RawProvenance {
    devicePixelRatio: number;
    viewport: {
        width: number;
        height: number;
    };
    scroll: {
        x: number;
        y: number;
    };
    document: {
        width: number;
        height: number;
    };
    /** Document-relative box of the crop root for element shots, else the document box. */
    originBox: {
        x: number;
        y: number;
        w: number;
        h: number;
    };
    elements: ProvenanceElement[];
    /** Index into `elements` per resolve selector that matched. */
    resolved: Record<string, number>;
    truncated: boolean;
}
export interface ProvenanceSidecar extends RawProvenance {
    version: number;
    note: string;
    shotId: string;
    runId: string;
    capturedAt: string;
    /** sha256 of the PNG this sidecar describes, for drift detection. */
    shotHash: string;
    origin: "document" | "element";
    /** Actual PNG dimensions, the mapping's authority (Chromium clamps tall pages). */
    image: {
        width: number;
        height: number;
    };
}
/**
 * A shot's sidecar, by the convention store.ts writes; null when absent or
 * foreign.
 *
 * Here rather than beside the placement brief that used to own it, because
 * the judge reads sidecars now too and `src/judge/` may not import
 * `src/design/`: one oracle reaching into another's module is exactly the
 * dependency this codebase keeps out.
 */
export declare function loadSidecarBeside(evDir: string, pngRelPath: string): ProvenanceSidecar | null;
/** Read a shot's sidecar back; null when absent or from another version. */
export declare function parseSidecar(text: string): ProvenanceSidecar | null;
/** An element's box in PNG pixels, per the sidecar's own mapping note. */
export declare function pngBoxOf(sidecar: Pick<ProvenanceSidecar, "image" | "originBox">, box: {
    x: number;
    y: number;
    w: number;
    h: number;
}): {
    x: number;
    y: number;
    w: number;
    h: number;
};
/**
 * Rank and cap what the walk collected, then wrap it as the sidecar. Source
 * hints outrank bare identity, identity outranks landmarks, landmarks outrank
 * size: when the cap bites, the records that can name code survive.
 */
export declare function buildSidecar(raw: RawProvenance, shot: Pick<ShotRecord, "id" | "runId" | "capturedAt" | "hash"> & {
    origin: "document" | "element";
    image: {
        width: number;
        height: number;
    };
}, opts?: {
    maxElements?: number;
}): ProvenanceSidecar;
/** One deterministic finding's element, joined at capture time. */
export interface ProvenanceRef {
    selector: string;
    cssPath: string;
    component: string | null;
    file: string | null;
    line: number | null;
}
/** The selectors a finding offers the join: axe target paths, overflow offender. */
export declare function selectorsOf(f: DeterministicFinding): string[];
/**
 * Attach each finding's resolved elements as `meta.provenance`. The join
 * happened in the page (querySelector against the live DOM, nearest collected
 * ancestor by node identity); this maps the surviving indices back through
 * the sidecar. A selector that resolved to nothing writes nothing: an exact
 * join stays exact or stays silent.
 */
export declare function attachProvenance(findings: DeterministicFinding[], sidecar: Pick<ProvenanceSidecar, "resolved" | "elements">): void;