export declare const DEFAULT_MAP_DIR = ".styleproof/maps";
export declare const DEFAULT_MAP_LABEL = "current";
export declare const DEFAULT_MAP_STORE_BRANCH = "styleproof-maps";
export declare const DEFAULT_REMOTE = "origin";
export declare const MAP_MANIFEST = "styleproof-manifest.json";
/** Per-surface capture failures recorded when baseline-only tolerate mode is on. */
export declare const SURFACE_CAPTURE_FAILURES_DIR = "styleproof-surface-capture-failures";
/** Run-level marker proving that capture hit a fatal determinism/self-check failure. */
export declare const FATAL_CAPTURE_MARKER = "styleproof-fatal-capture.flag";
export type SurfaceCaptureFailure = {
    /** Capture key (`<surface>@<width>` or crawl label). */
    key: string;
    reason: string;
    /** `self-check` failures are never tolerated and should not appear here. */
    kind?: 'capture';
};
/** Sidecar written during a capture run (where a browser handle is in scope) recording
 *  the real browser build (`browser().version()`). `writeMapManifest` runs after Playwright
 *  has exited — no browser — so it reads the build back from here. Not a surface map. */
export declare const BROWSER_BUILD_SIDECAR = "styleproof-browser.json";
/** Sidecar recording where a run's BASELINE maps came from — restored from the
 *  exact base SHA, restored from a nearest ancestor (with the no-relevant-changes
 *  proof), or captured fresh (#367: reuse must never be silent). Written locally
 *  by the CI driver into its base dir; never a surface map. */
export declare const BASELINE_PROVENANCE_FILE = "styleproof-baseline-provenance.json";
/** The confidence ledger (#399) — per-surface trust statuses bundled with the
 *  maps. Defined here (not in confidence-ledger.ts, its owning module, which
 *  re-exports it) so {@link RESERVED_BUNDLE_FILES} needs no import cycle. */
export declare const CONFIDENCE_LEDGER = "styleproof-confidence.json";
/** Bundle files that sit alongside the maps but are NOT surfaces (manifest, coverage
 *  ledger, and any future sidecar). Every place that enumerates surface maps must skip
 *  these, or a sidecar reads as a phantom "new surface". */
export declare const RESERVED_BUNDLE_FILES: ReadonlySet<string>;
/** True for a captured surface map (`<key>@<width>.json[.gz]`), false for metadata. */
export declare function isMapFile(name: string): boolean;
/** True when a top-level entry is owned by StyleProof capture generation. */
export declare function isOwnedCaptureArtifact(name: string): boolean;
/** True when a flat failure receipt name could have been emitted by StyleProof. */
export declare function isSurfaceCaptureFailureArtifact(name: string): boolean;
/** Clear only artifacts that a crawl owns when refreshing a reused output directory.
 * Generated sidecars and the `<surface>@<width>` namespace are reserved StyleProof output;
 * unrelated names are preserved. Preflight before removal so malformed state cannot
 * leave a half-cleared bundle. */
export declare function clearCaptureOutput(dir: string): void;
export declare class MapStoreError extends Error {
}
/** A restore that failed because the requested bundle is genuinely absent — the map
 *  store branch does not exist yet, or it holds no bundle for this SHA/compatibility.
 *  This is an EXPECTED cache miss (the cold path should recapture), NOT an infrastructure
 *  fault. Kept distinct from a plain {@link MapStoreError} (network, clone, timeout, auth)
 *  so a caller can recapture on a true miss but fail loudly on a transient fault instead
 *  of silently paying a full cold recapture every flaky run. Extends MapStoreError, so
 *  existing `instanceof MapStoreError` handlers still catch it. */
export declare class MapStoreNotFoundError extends MapStoreError {
}
/** An upload refused because of the CONSUMER's own state (a dirty working tree,
 *  a missing manifest) — a precondition the user must fix, never a transient
 *  store/network fault. Kept distinct so the CLI can exit with the usage code
 *  (2, "fix your invocation/tree") instead of the retryable fault code (5,
 *  "re-run the job"): retrying a dirty tree can never succeed. */
export declare class MapStorePreconditionError extends MapStoreError {
}
export interface MapManifest {
    version: 1;
    packageVersion: string;
    sha: string;
    dirty: boolean;
    /** Repo-relative files/directories excluded from dirty provenance for this capture. */
    dirtyAllow?: string[];
    spec: string;
    specHash: string;
    lockfile?: string;
    lockfileHash?: string;
    playwrightVersion?: string;
    /** Real browser build (`browser().version()`), recorded at capture time. The npm
     *  `@playwright/test` version can hold constant while this changes (re-download, a
     *  different browser store, a CI image bump), so this is what actually gates a compare. */
    browserVersion?: string;
    platform: string;
    arch: string;
    nodeMajor: string;
    baseUrl?: string;
    screenshots: boolean;
    har: boolean;
    compatibilityKey: string;
    createdAt: string;
    /** Surfaces that failed during a tolerated baseline capture (partial bundle). */
    surfaceCaptureFailures?: SurfaceCaptureFailure[];
}
export interface CachedCaptureDirs {
    beforeDir: string;
    afterDir: string;
    baseRef: string;
    baseSha: string;
    headSha: string;
    compatibilityKey: string;
    tmpRoot: string;
}
export declare function workflowTokenCredentialArguments(): string[];
/** Record the real browser build into the capture dir. Called from a capture run, where a
 *  Playwright browser handle is in scope. Write-or-CLEAR semantics: an undefined version
 *  REMOVES any existing sidecar rather than leaving it, so a reused capture dir (e.g. the
 *  default `.styleproof/maps/current`) can never carry a PRIOR run's build into this run's
 *  manifest — that would stamp a false browser-build fingerprint the compatibility guard
 *  then trusts. Best-effort: the delete is forced and ignores a missing file. */
export declare function writeBrowserBuildSidecar(dir: string, browserVersion: string | undefined): void;
export declare function expectedCompatibilityKey(options?: {
    cwd?: string;
    spec?: string;
    baseUrl?: string;
}): string;
export declare function currentGitSha(cwd?: string, env?: NodeJS.ProcessEnv): string;
export declare function refSha(ref: string, cwd?: string): string;
/**
 * True if any tracked file is modified/added/deleted. `ignore` (repo-relative files or
 * directories) are excluded — pass the map OUTPUT dir when re-sampling AFTER a capture,
 * so the maps the capture just wrote don't read as tree dirt and mask a real source
 * edit, and pass `--dirty-allow` paths for files a dev tool rewrites on every run
 * (the ambient equivalent of the built-in next-env.d.ts allowance).
 */
export declare function workingTreeDirty(cwd?: string, ignore?: string | readonly string[]): boolean;
export declare function remoteExists(remote?: string, cwd?: string): boolean;
/** Record one tolerated surface failure (safe under parallel Playwright workers). */
export declare function recordSurfaceCaptureFailure(dir: string, failure: SurfaceCaptureFailure): void;
/** Read tolerated failures written during capture (sorted by key). */
export declare function readSurfaceCaptureFailures(dir: string): SurfaceCaptureFailure[];
/** Record a run-level capture failure that must never be tolerated or published. */
export declare function markFatalCaptureFailure(dir: string, reason: string): void;
/** Read the fatal marker written by a capture worker, if one exists. */
export declare function readFatalCaptureFailure(dir: string): string | undefined;
/** Split a capture key at the last `@` (`home@1280` → `home` + `1280`). */
export declare function captureKeyParts(key: string): {
    surface: string;
    width: string;
};
/**
 * Whether a baseline failure ledger entry accounts for a missing capture key on head.
 * `surface@auto` (viewport detection failed before width sweep) matches any width for
 * that exact surface key. Width-specific failures match only the same key.
 */
export declare function baselineFailureMatchesSurface(failureKey: string, surfaceKey: string): boolean;
/** True when any ledger entry explains why `surfaceKey` is absent from the base bundle. */
export declare function surfaceMissingMatchesBaselineFailure(surfaceKey: string, failures: readonly SurfaceCaptureFailure[]): boolean;
/** Head capture keys missing on base that the baseline failure ledger explains (sorted). */
export declare function explainedMissingBaselineSurfaces(surfaces: readonly {
    surface: string;
    missing?: 'before' | 'after';
}[], failures: readonly SurfaceCaptureFailure[]): string[];
export declare function writeMapManifest(options: {
    dir: string;
    spec: string;
    sha?: string;
    screenshots: boolean;
    dirty?: boolean;
    dirtyAllow?: readonly string[];
    cwd?: string;
    env?: NodeJS.ProcessEnv;
}): MapManifest;
/**
 * Write a `styleproof-manifest.json` for a one-shot `styleproof-capture` output dir,
 * so a two-directory `styleproof-diff design <build>` has the same-environment guard
 * on both sides (v4 refuses to compare a manifest-less side). Unlike
 * {@link writeMapManifest}, this may run OUTSIDE a git repo (a design mockup, a static
 * export), so the git-derived fields degrade gracefully: `sha` falls back to
 * `'uncommitted'` and `dirty` to `true` rather than throwing. The parts the guard
 * actually consumes — `compatibilityKey`, `platform`/`arch`/`nodeMajor`,
 * `playwrightVersion`, `browserVersion`, `baseUrl` — are recorded the same way as a
 * spec capture. Overwrites any existing manifest in `dir`.
 */
export declare function writeCaptureManifest(options: {
    dir: string;
    screenshots: boolean;
    cwd?: string;
    env?: NodeJS.ProcessEnv;
}): MapManifest;
export declare function readMapManifest(dir: string): MapManifest | null;
/** Where a run's baseline maps came from (#367). `ancestor-reuse` carries the
 *  no-relevant-changes proof: how many paths changed between the restored
 *  ancestor and the requested base commit (all of them capture-irrelevant),
 *  and the declared app source roots the relevance gate ran against. The
 *  restored bundle itself stays byte-identical to what was verified at capture
 *  time — this sidecar only records the reuse decision, it never rewrites the
 *  bundle's own manifest or SHA. */
export type BaselineProvenance = {
    version: 1;
    baseline: 'exact-restore' | 'ancestor-reuse' | 'captured';
    /** The base commit this run needed a baseline for. */
    requestedSha: string;
    /** The commit whose stored bundle was restored (absent for `captured`). */
    restoredSha?: string;
    /** 1 = the base commit's direct first-parent parent. */
    ancestorDepth?: number;
    /** `git diff --name-only <restoredSha> <requestedSha>` path count — the proof. */
    changedPathCount?: number;
    /** The app source roots the relevance gate was declared with. */
    sourceRoots?: string[];
};
/** Record the baseline-provenance sidecar into a base map dir (#367: no silent reuse). */
export declare function writeBaselineProvenance(dir: string, provenance: BaselineProvenance): void;
/** Read the baseline-provenance sidecar; `null` when absent or unreadable. */
export declare function readBaselineProvenance(dir: string): BaselineProvenance | null;
/** Which side(s) of a two-directory compare hold captured maps but NO
 *  `styleproof-manifest.json` — a legacy committed-map bundle. Since v4 that is
 *  unsupported: without a manifest the same-environment guard can't be enforced, so the
 *  CLI refuses (exit 2). `null` means every side WITH maps also has a manifest (nothing to
 *  refuse). A side with zero maps is NOT flagged — an empty/bare dir is "no baseline yet",
 *  handled by the base/head-missing guards, not this one. Pure: presence reads only, so the
 *  CLI layer owns the exit code and the library stays side-effect-free. */
export declare function manifestlessSide(beforeDir: string, afterDir: string): 'before' | 'after' | 'both' | null;
/** Fail-loud message for a manifest-less compare. Since v4 a side without a
 *  `styleproof-manifest.json` is unsupported: the same-environment guard can't be
 *  enforced, so captures from different browser builds or platforms would diff as
 *  false changes. The CLI raises this and exits 2 (usage/capture error) — the
 *  legacy "compare anyway" tolerance is gone. */
export declare function manifestlessError(side: 'before' | 'after' | 'both'): string;
export declare function assertCompatibleMapDirs(beforeDir: string, afterDir: string): void;
export declare function publishMapBundle(options: {
    dir: string;
    branch?: string;
    remote?: string;
    cwd?: string;
    includeHar?: boolean;
}): {
    sha: string;
    compatibilityKey: string;
    branch: string;
};
export declare function restoreMapBundle(options: {
    sha: string;
    outDir: string;
    branch?: string;
    remote?: string;
    cwd?: string;
    compatibilityKey?: string;
}): MapManifest;
/**
 * The commit SHAs that currently have at least one stored bundle on the map
 * store branch — the top-level directory names at the branch tip. One bounded
 * network operation: a `tree:0` no-checkout clone plus one root `ls-tree`, so
 * no map blob (and no subtree) is downloaded. A missing branch is an EMPTY set
 * (nothing stored yet, not a fault); any network/clone failure throws a plain
 * {@link MapStoreError} so the caller can fall back rather than trust a
 * partial listing. Used by the nearest-ancestor baseline reuse (#367).
 */
export declare function listMapStoreBundleShas(options?: {
    branch?: string;
    remote?: string;
    cwd?: string;
}): Set<string>;
export declare function resolveCachedCaptureDirs(options: {
    command: string;
    args: string[];
    spec: string;
    branch?: string;
    remote?: string;
    cwd?: string;
    baseUrl?: string;
    usage: string;
}): CachedCaptureDirs;
export declare function cleanupCachedCaptureDirs(captureDirs: CachedCaptureDirs | null): void;