import { type HelperTimeoutState } from './browser/launch';
/** The query parameter that boots a world for baking. `=1` and nothing else. */
export declare const BAKE_PARAM = "helixBake";
/** The artifact the bake writes, next to the visual contract it is pointed at from. */
export declare const BAKE_ARTIFACT_FILE = "helix.visuals.bake.json";
/** K sun keys, the driver's own default. Below 2 the planner cannot place both horizon keys. */
export declare const DEFAULT_BAKE_KEYS = 9;
/** Boot budget. SwiftShader boots a world minutes slower than a real GPU, so this is seconds-times-hundreds. */
export declare const DEFAULT_BAKE_BOOT_TIMEOUT_S = 300;
export type BakePhase = 'idle' | 'warm-up' | 'audit' | 'key' | 'practicals' | 'geometry' | 'done' | 'failed';
export type BakeProgress = {
    phase: BakePhase;
    done: number;
    total: number;
};
export type BakeKeyTiming = {
    hours: number;
    elevationDeg: number;
    azimuthDeg: number;
    ms: number;
    bakeMs: number;
};
export type BakeAuditSummary = {
    probes: number;
    flagged: number;
    counts: Record<string, number>;
    blockedEdges: number;
    leakingEdges: number;
    ms: number;
};
export type BakeRepairSummary = {
    damaged: number;
    substituted: number;
    leftDark: number;
    donorPool: number;
    occludedCandidates: number;
    maxDonorGridDistance: number;
    /** THE TRIPWIRE: a donated probe whose donor it cannot see is a cross-zone light teleport. MUST read 0. */
    donorsOccluded: number;
    ms: number;
};
/** Whether the probe volume fits the space the world is played in — a PLACEMENT verdict, not a bake defect. */
export type BakeVolumeFitSummary = {
    layers: number;
    /** Probe layers carrying at least `litShare` of the strongest layer's energy. */
    litLayers: number;
    litShare: number;
    /** Total DC irradiance per Y layer, bottom first. */
    layerEnergy: number[];
    /** False = most of the box baked darkness or open sky. */
    fits: boolean;
};
export type BakeSummary = {
    keys: number;
    probes: number;
    totalMs: number;
    warmUpMs: number;
    perKey: BakeKeyTiming[];
    practicalsMs: number;
    geometryMs: number;
    auditKey: number;
    audit: BakeAuditSummary;
    repair: BakeRepairSummary;
    /** OPTIONAL against the ENGINE, not against the contract: a world bundles its own @helix/visual, so a build
     *  made before the volume-fit verdict existed reports no `volumeFit` at all and simply gets no warning. */
    volumeFit?: BakeVolumeFitSummary;
    repairs: number;
    volume: {
        probes: [number, number, number];
        size: [number, number, number];
        center: [number, number, number];
    };
    /** False when the tier ran without DDGI visibility — the artifact then ships SH only. */
    geometry: boolean;
    fieldBytes: number;
    geometryBytes: number;
};
/** Where the bake serves from and which roots take the artifact + the pointer. */
export type BakeTargets = {
    /** The built bundle the browser loads. */
    servedDir: string;
    /** The world roots written to: the source `public/` (when it exists) and the built bundle root. */
    roots: string[];
};
export type BakeWrite = {
    path: string;
    kind: 'artifact' | 'contract';
    bytes: number;
    /** True when the file did not exist and this run created it. */
    created: boolean;
};
export type BakeLightingOptions = {
    directory: string;
    keys?: number | undefined;
    /** Boot budget in ms — the wait for `window.__helixBake`, NOT a cap on the bake itself. */
    timeoutMs?: number | undefined;
    onProgress?: ((message: string) => void) | undefined;
};
export type BakeLightingResult = {
    summary: BakeSummary;
    written: BakeWrite[];
    servedDir: string;
};
/**
 * Which bundle is served and which roots are written. Mirrors the convention `helix validate` reads the visual
 * contract under: the built bundle serves it from the ROOT, a source tree keeps it in `public/` — so both copies
 * are patched, leaving the just-baked build publishable and the next build carrying the same pointer.
 */
export declare function resolveBakeTargets(directory: string): BakeTargets;
/**
 * The contract patch: `mode: "baked"` plus the artifact pointer, every other key carried verbatim and in place.
 * `null` text creates the minimal v1 document — a world may declare no visual contract at all until it is baked.
 */
export declare function patchVisualsConfigText(text: string | null, artifact?: string): string;
/**
 * THE GATE. A donated probe whose donor it cannot see is light teleported across a wall, so the artifact is
 * refused rather than written: the run is sound only while this reads 0. Null when the field is clean.
 */
export declare function bakeGateFailure(summary: BakeSummary): string | null;
export declare function formatDuration(ms: number): string;
export declare function formatBakeProgress(progress: BakeProgress, elapsedMs: number): string;
/** The compact end-of-run report: what was baked, what it cost, what the audit found, and what landed on disk. */
export declare function formatBakeSummary(summary: BakeSummary, written: readonly BakeWrite[]): string[];
/** Page errors FIRST — a VisualInvariantError name is the diagnosis, and the reason below it is the consequence. */
export declare function composeBakeFailure(reason: string, errors: readonly string[]): string;
export declare function composeBakeTimeoutDiagnosis(state: HelperTimeoutState, errors: string[]): string;
/**
 * Serve, boot, bake, gate, write. The bake itself is MINUTES of blocking GPU work inside one `page.evaluate`,
 * which Playwright does not time out; `--timeout` bounds only the wait for the handle.
 */
export declare function bakeLighting(opts: BakeLightingOptions): Promise<BakeLightingResult>;