import { type KeyValueStorage } from "./keyValueStore.js";
/** The structural storage backend a record book persists through — an alias of the shared {@link KeyValueStorage} seam (browser `localStorage`, a test stub, or `null`). */
export type RecordStorage = KeyValueStorage;
export type RecordDirection = "lower" | "higher";
export interface RecordBookConfig<K extends string> {
    readonly key: string;
    readonly fields: Readonly<Record<K, RecordDirection>>;
    readonly storage?: RecordStorage | null;
}
export interface RecordSubmission<K extends string> {
    readonly improved: readonly K[];
    readonly best: Readonly<Partial<Record<K, number>>>;
}
export interface RecordBook<K extends string> {
    best(): Readonly<Partial<Record<K, number>>>;
    bestOf(field: K): number | null;
    submit(run: Readonly<Partial<Record<K, number>>>): RecordSubmission<K>;
    clear(): void;
}
/**
 * A personal-best record book: named numeric fields each racing toward "lower"
 * (times) or "higher" (scores, streaks), persisted through a structural
 * key-value storage (pass `localStorage` in a browser, a stub in tests, or
 * `null` for in-memory only). Corrupt or unavailable storage degrades to an
 * empty book — a record write never throws into a game tick.
 *
 * @capability best-record persist personal-best times/scores with safe storage fallback
 */
export declare function createRecordBook<K extends string>(config: RecordBookConfig<K>): RecordBook<K>;