@jgengine/core 0.9.0 → 0.11.0

package/dist/game/race.js

@@ -316,6 +316,175 @@ export class RaceState {
         return events;
     }
 }
+/**
+ * A checkpoint race state machine — laps, forks, live standings, splits, and pluggable win conditions.
+ *
+ * @capability race-track a checkpoint race with laps, standings, splits, and win conditions
+ */
 export function createRaceState(config) {
     return new RaceState(config);
 }
+/**
+ * Create a {@link LapTimer} starting at lap 0 with no splits, best, or last time recorded.
+ *
+ * @capability lap-timer wall-clock current/last/best lap timing with splits
+ */
+export function createLapTimer() {
+    let currentLap = 0;
+    let lastLap = null;
+    let bestLap = null;
+    let total = 0;
+    const splits = [];
+    return {
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            currentLap += dt;
+            total += dt;
+        },
+        completeLap() {
+            const lapTime = currentLap;
+            lastLap = lapTime;
+            bestLap = bestLap === null || lapTime < bestLap ? lapTime : bestLap;
+            splits.push(lapTime);
+            currentLap = 0;
+            return lapTime;
+        },
+        penalize(seconds) {
+            if (seconds <= 0)
+                return;
+            currentLap += seconds;
+            total += seconds;
+        },
+        reset() {
+            currentLap = 0;
+            lastLap = null;
+            bestLap = null;
+            total = 0;
+            splits.length = 0;
+        },
+        snapshot() {
+            return { currentLap, lastLap, bestLap, total, lapCount: splits.length, splits: [...splits] };
+        },
+    };
+}
+const DEFAULT_COUNTDOWN_SECONDS = 3;
+/**
+ * The pre-race session on the grid: `idle`, both clocks at zero. Call {@link startRaceCountdown} to
+ * light the lights, or hold here until the field is ready.
+ *
+ * @capability race-session pure idle→countdown→racing→finished clock every racer wraps around its state
+ */
+export function idleRaceSession() {
+    return { phase: "idle", countdown: 0, elapsed: 0 };
+}
+/**
+ * Drop the lights: return a fresh `countdown` session of `seconds` (default 3). A non-positive length
+ * skips straight to `racing` for a standing start with no countdown.
+ */
+export function startRaceCountdown(options) {
+    const seconds = Math.max(0, options?.seconds ?? DEFAULT_COUNTDOWN_SECONDS);
+    return seconds === 0 ? { phase: "racing", countdown: 0, elapsed: 0 } : { phase: "countdown", countdown: seconds, elapsed: 0 };
+}
+/**
+ * Advance the session by `dt` seconds: bleed the countdown down and flip to `racing` when it reaches
+ * zero, or accumulate `elapsed` while `racing`. `idle` and `finished` are inert. Overshoot past the
+ * countdown is dropped rather than banked into `elapsed`, so the race clock always starts from zero.
+ */
+export function tickRaceSession(session, dt) {
+    if (dt <= 0)
+        return session;
+    if (session.phase === "countdown") {
+        const countdown = session.countdown - dt;
+        return countdown <= 0 ? { phase: "racing", countdown: 0, elapsed: 0 } : { phase: "countdown", countdown, elapsed: session.elapsed };
+    }
+    if (session.phase === "racing")
+        return { phase: "racing", countdown: 0, elapsed: session.elapsed + dt };
+    return session;
+}
+/** Cross the flag: move a `racing` session to `finished`, freezing its `elapsed`. A no-op in any other phase. */
+export function finishRaceSession(session) {
+    return session.phase === "racing" ? { phase: "finished", countdown: 0, elapsed: session.elapsed } : session;
+}
+function outcomeForPlace(place, winningPlaces) {
+    return place <= winningPlaces ? "win" : "lose";
+}
+/**
+ * Turn a finish-order ranking (index 0 = winner, e.g. the `ranking` of a `race.finished` event) into
+ * per-racer {@link RacePlacement}s — the `1st/2nd/3rd` + win/lose every results screen shows.
+ *
+ * @capability race-placements finish order into per-racer place + win/lose for a results screen
+ */
+export function racePlacements(finishOrder, options) {
+    const winningPlaces = Math.max(0, Math.floor(options?.winningPlaces ?? 1));
+    return finishOrder.map((racerId, index) => ({ racerId, place: index + 1, outcome: outcomeForPlace(index + 1, winningPlaces) }));
+}
+/**
+ * One racer's {@link RacePlacement} within a finish order, or `null` if they never crossed the line.
+ *
+ * @capability race-placements look up one racer's place + win/lose within a finish order
+ */
+export function placementOf(finishOrder, racerId, options) {
+    const index = finishOrder.indexOf(racerId);
+    if (index < 0)
+        return null;
+    const winningPlaces = Math.max(0, Math.floor(options?.winningPlaces ?? 1));
+    return { racerId, place: index + 1, outcome: outcomeForPlace(index + 1, winningPlaces) };
+}
+/**
+ * The win/lose verdict for one racer in a finish order — `ranking[0] === player ? "win" : "lose"`, the
+ * check every racing game hand-rolls, generalized to a `winningPlaces` cutoff. A racer absent from the
+ * order counts as a `lose`.
+ */
+export function raceOutcomeOf(finishOrder, racerId, options) {
+    return placementOf(finishOrder, racerId, options)?.outcome ?? "lose";
+}
+/**
+ * Per-segment durations from a cumulative split book (`splits[i]` = elapsed time at checkpoint `i`):
+ * `segments[i] = splits[i] − splits[i−1]`, the first measured from `start` (default 0). Turns the
+ * cumulative splits {@link RacerProgress} records into the individual leg times a results screen shows.
+ *
+ * @capability lap-splits turn cumulative split times into per-segment leg times
+ */
+export function splitSegments(splits, start = 0) {
+    const segments = [];
+    let previous = start;
+    for (const split of splits) {
+        segments.push(split - previous);
+        previous = split;
+    }
+    return segments;
+}
+/**
+ * Per-lap durations from a cumulative split book with `gatesPerLap` checkpoints per lap — each lap's time
+ * is its finish-gate split minus the previous lap's finish. Only complete laps are returned.
+ *
+ * @capability lap-splits per-lap durations from a cumulative split book
+ */
+export function lapDurations(splits, gatesPerLap) {
+    if (gatesPerLap <= 0)
+        return [];
+    const laps = [];
+    for (let lap = 0;; lap += 1) {
+        const finish = lap * gatesPerLap + (gatesPerLap - 1);
+        if (finish >= splits.length)
+            break;
+        const previousFinish = lap === 0 ? 0 : (splits[lap * gatesPerLap - 1] ?? 0);
+        laps.push(splits[finish] - previousFinish);
+    }
+    return laps;
+}
+/**
+ * Elementwise delta of a cumulative split book against a `reference` book (a personal best or par lap):
+ * positive means behind the reference at that checkpoint. Compared up to the shorter length — the
+ * `+0.3s` / `−1.2s` gap every racing HUD shows against its ghost.
+ *
+ * @capability lap-splits delta of splits against a personal-best or par reference
+ */
+export function parDelta(splits, reference) {
+    const count = Math.min(splits.length, reference.length);
+    const deltas = [];
+    for (let i = 0; i < count; i += 1)
+        deltas.push(splits[i] - reference[i]);
+    return deltas;
+}

package/dist/game/recordBook.d.ts

@@ -1,8 +1,6 @@
-export interface RecordStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
+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;
@@ -25,5 +23,7 @@ export interface RecordBook<K extends string> {
  * 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>;

package/dist/game/recordBook.js

@@ -1,3 +1,4 @@
+import { defaultKeyValueStorage } from "./keyValueStore.js";
 function loadStored(config, storage) {
     if (storage === null)
         return {};
@@ -33,9 +34,11 @@ function loadStored(config, storage) {
  * 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 function createRecordBook(config) {
-    const storage = config.storage ?? null;
+    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
     let best = loadStored(config, storage);
     function persist() {
         if (storage === null)

package/dist/game/ruleSelection.d.ts

@@ -0,0 +1,75 @@
+import { type ParamLayer, type LayerSelection } from "./paramLayers.js";
+/**
+ * A selectable rule over a tagged pool. `tags` classify it for include/exclude filtering and for
+ * `requires`/`conflicts` matching (which match either another rule's id or one of its tags). `layers`
+ * are the parameter layers this rule contributes when active; `payload` is opaque caller data.
+ */
+export interface RuleDef<TPayload = unknown> {
+    readonly id: string;
+    readonly tags?: readonly string[];
+    /** Relative pick weight; non-positive or omitted is treated as `1`. */
+    readonly weight?: number;
+    /** Ids/tags that must already be selected for this rule to become eligible. */
+    readonly requires?: readonly string[];
+    /** Ids/tags that, if already selected (either direction), make this rule ineligible. */
+    readonly conflicts?: readonly string[];
+    /** Parameter layers contributed when this rule is active, read back via {@link RuleRegistry.layersFor}. */
+    readonly layers?: readonly ParamLayer[];
+    readonly payload?: TPayload;
+}
+/** Deterministic selection inputs — plain serializable data a host can persist and replay. */
+export interface RuleSelectionConfig {
+    readonly count: number;
+    readonly seed: string | number;
+    /** If set, only rules carrying at least one of these tags are eligible. */
+    readonly includeTags?: readonly string[];
+    /** Rules carrying any of these tags are excluded outright. */
+    readonly excludeTags?: readonly string[];
+    /** Rule ids force-selected first, in order; counts toward `count`. Unknown ids are ignored. */
+    readonly locked?: readonly string[];
+}
+/** The result of a selection — the chosen rules and their ids (a serializable {@link LayerSelection}-style list). */
+export interface RuleSelection<TPayload = unknown> {
+    readonly rules: readonly RuleDef<TPayload>[];
+    readonly ids: readonly string[];
+}
+/**
+ * Select up to `count` rules from `pool` deterministically from `config.seed`. Locked ids are placed
+ * first (in order), then remaining slots are filled by weighted draw from tag-filtered, still-eligible
+ * candidates, honoring `requires`/`conflicts` after each pick. Each slot draws from an independent
+ * seed stream keyed by slot index, so a later slot's outcome never shifts an earlier one. Selection
+ * stops early when no compatible candidate remains. Pure given `pool` + `config`.
+ *
+ * @capability rule-selection deterministically select rules from a tagged pool under compatibility/exclusion constraints
+ */
+export declare function selectRules<TPayload = unknown>(pool: readonly RuleDef<TPayload>[], config: RuleSelectionConfig): RuleSelection<TPayload>;
+/**
+ * Reroll a prior selection: keep `keepIds` (the locked slots) and re-draw the rest under a fresh,
+ * still-deterministic stream derived from `config.seed` and `salt`. The same seed + salt + keep set
+ * reproduce the same reroll, so reroll history stays replayable.
+ *
+ * @capability rule-selection reroll unlocked slots of a selection deterministically from seed and salt
+ */
+export declare function rerollRules<TPayload = unknown>(pool: readonly RuleDef<TPayload>[], config: RuleSelectionConfig, keepIds: readonly string[], salt?: string | number): RuleSelection<TPayload>;
+/** Registered pool of {@link RuleDef}s — the install seam games register mutators/modes/events into. */
+export interface RuleRegistry<TPayload = unknown> {
+    register(rule: RuleDef<TPayload>): void;
+    has(id: string): boolean;
+    get(id: string): RuleDef<TPayload> | undefined;
+    all(): readonly RuleDef<TPayload>[];
+    /** Run {@link selectRules} over the registered pool. */
+    select(config: RuleSelectionConfig): RuleSelection<TPayload>;
+    /**
+     * Collect the parameter layers contributed by the given selected rule ids, in id order. Unknown ids
+     * are skipped so stale/migrated selections resolve without throwing. This is the bridge from a
+     * rule selection to a {@link ParamLayer} stack — core reads `.layers`, never a rule's name.
+     */
+    layersFor(ids: LayerSelection): readonly ParamLayer[];
+}
+/**
+ * Create a {@link RuleRegistry}. Rules install through `register` (duplicate ids throw); selection and
+ * `layersFor` are data-driven, so the core never branches on which mutators exist.
+ *
+ * @capability rule-selection register rules and bridge a selection to its contributed parameter layers
+ */
+export declare function createRuleRegistry<TPayload = unknown>(initial?: readonly RuleDef<TPayload>[]): RuleRegistry<TPayload>;

package/dist/game/ruleSelection.js

@@ -0,0 +1,127 @@
+/**
+ * Seeded rule selection over a tagged pool.
+ *
+ * A {@link RuleDef} is a caller-owned selectable — a mutator, game mode, event, or challenge modifier
+ * — carrying tags, an optional weight, compatibility (`requires`) and exclusion (`conflicts`)
+ * constraints, and any {@link ParamLayer}s it contributes when active. {@link selectRules} draws a
+ * requested count from the eligible pool using injected, deterministic randomness: the same seed and
+ * pool always yield the same rules, so a host can reproduce a session from `{ seed, count }` alone and
+ * every peer agrees without replicating the roll.
+ *
+ * Core never branches on known rule names — selection is driven entirely by tags and the caller's
+ * constraint data, and a selected rule's behavior is read back through its `layers`/`payload`. That
+ * keeps the seam genre-agnostic and lets games install rules through {@link createRuleRegistry}
+ * without the primitive knowing what any mutator "means".
+ */
+import { pickWeighted } from "../random/pick.js";
+import { seededStreams } from "../random/rng.js";
+import {} from "./paramLayers.js";
+function tokensOf(rule) {
+    return [rule.id, ...(rule.tags ?? [])];
+}
+function passesTagFilter(rule, config) {
+    const tags = rule.tags ?? [];
+    if (config.excludeTags?.some((tag) => tags.includes(tag)))
+        return false;
+    if (config.includeTags && config.includeTags.length > 0) {
+        return config.includeTags.some((tag) => tags.includes(tag));
+    }
+    return true;
+}
+function isCompatible(rule, selected) {
+    const selectedTokens = new Set(selected.flatMap(tokensOf));
+    if (rule.requires && !rule.requires.every((token) => selectedTokens.has(token)))
+        return false;
+    if (rule.conflicts?.some((token) => selectedTokens.has(token)))
+        return false;
+    const ruleTokens = new Set(tokensOf(rule));
+    for (const other of selected) {
+        if (other.conflicts?.some((token) => ruleTokens.has(token)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Select up to `count` rules from `pool` deterministically from `config.seed`. Locked ids are placed
+ * first (in order), then remaining slots are filled by weighted draw from tag-filtered, still-eligible
+ * candidates, honoring `requires`/`conflicts` after each pick. Each slot draws from an independent
+ * seed stream keyed by slot index, so a later slot's outcome never shifts an earlier one. Selection
+ * stops early when no compatible candidate remains. Pure given `pool` + `config`.
+ *
+ * @capability rule-selection deterministically select rules from a tagged pool under compatibility/exclusion constraints
+ */
+export function selectRules(pool, config) {
+    const byId = new Map(pool.map((rule) => [rule.id, rule]));
+    const chosen = [];
+    const chosenIds = new Set();
+    for (const id of config.locked ?? []) {
+        const rule = byId.get(id);
+        if (rule && !chosenIds.has(id)) {
+            chosen.push(rule);
+            chosenIds.add(id);
+        }
+        if (chosen.length >= config.count)
+            return { rules: chosen, ids: chosen.map((r) => r.id) };
+    }
+    const streams = seededStreams(config.seed);
+    let slot = chosen.length;
+    while (chosen.length < config.count) {
+        const candidates = pool.filter((rule) => !chosenIds.has(rule.id) && passesTagFilter(rule, config) && isCompatible(rule, chosen));
+        if (candidates.length === 0)
+            break;
+        const picked = pickWeighted(streams(`slot:${slot}`), candidates, (rule) => rule.weight !== undefined && rule.weight > 0 ? rule.weight : 1);
+        if (!picked)
+            break;
+        chosen.push(picked);
+        chosenIds.add(picked.id);
+        slot += 1;
+    }
+    return { rules: chosen, ids: chosen.map((r) => r.id) };
+}
+/**
+ * Reroll a prior selection: keep `keepIds` (the locked slots) and re-draw the rest under a fresh,
+ * still-deterministic stream derived from `config.seed` and `salt`. The same seed + salt + keep set
+ * reproduce the same reroll, so reroll history stays replayable.
+ *
+ * @capability rule-selection reroll unlocked slots of a selection deterministically from seed and salt
+ */
+export function rerollRules(pool, config, keepIds, salt = 0) {
+    return selectRules(pool, {
+        ...config,
+        locked: keepIds,
+        seed: `${config.seed}:reroll:${salt}`,
+    });
+}
+/**
+ * Create a {@link RuleRegistry}. Rules install through `register` (duplicate ids throw); selection and
+ * `layersFor` are data-driven, so the core never branches on which mutators exist.
+ *
+ * @capability rule-selection register rules and bridge a selection to its contributed parameter layers
+ */
+export function createRuleRegistry(initial) {
+    const rules = new Map();
+    const register = (rule) => {
+        if (rules.has(rule.id))
+            throw new Error(`rule "${rule.id}" is already registered`);
+        rules.set(rule.id, rule);
+    };
+    if (initial)
+        for (const rule of initial)
+            register(rule);
+    return {
+        register,
+        has: (id) => rules.has(id),
+        get: (id) => rules.get(id),
+        all: () => [...rules.values()],
+        select: (config) => selectRules([...rules.values()], config),
+        layersFor(ids) {
+            const layers = [];
+            for (const id of ids) {
+                const rule = rules.get(id);
+                if (rule?.layers)
+                    layers.push(...rule.layers);
+            }
+            return layers;
+        },
+    };
+}

package/dist/game/runDraft.d.ts

@@ -31,4 +31,9 @@ export interface RunDraft<TStat extends string = string, TData = unknown> {
     choose(offerId: string): boolean;
     stack(): RunModifierStack<TStat, TData>;
 }
+/**
+ * A roguelike run built from stacking drafted modifier picks that reshape the run.
+ *
+ * @capability run-modifiers a roguelike run built from stacking drafted modifier picks
+ */
 export declare function createRunDraft<TStat extends string = string, TData = unknown>(config: RunDraftConfig<TStat, TData>): RunDraft<TStat, TData>;

package/dist/game/runDraft.js

@@ -68,6 +68,11 @@ export function createRunModifierStack(offers) {
         },
     };
 }
+/**
+ * A roguelike run built from stacking drafted modifier picks that reshape the run.
+ *
+ * @capability run-modifiers a roguelike run built from stacking drafted modifier picks
+ */
 export function createRunDraft(config) {
     const stack = createRunModifierStack(config.offers);
     const defaultRng = config.rng ?? Math.random;

package/dist/game/saveStore.d.ts

@@ -0,0 +1,111 @@
+import { type KeyValueStorage } from "./keyValueStore.js";
+/**
+ * The one async storage seam a save store persists through. Every backend
+ * satisfies this same three-method shape — the browser's `localStorage`
+ * (offline), an in-memory map (tests/SSR), or a database/Convex/HTTP endpoint
+ * (cloud) — so a game switches offline saves for cloud saves by swapping the
+ * backend and changing nothing else. Keys are opaque namespaced strings; values
+ * are already-serialized strings, so a backend never needs to know the save
+ * shape.
+ */
+export interface SaveBackend {
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/**
+ * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
+ * browser's `localStorage` by default (offline, on-device saves), a test stub,
+ * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
+ * DOM) degrade to no-ops, so a save never throws into a game tick.
+ *
+ * @capability local-save persist a game to on-device localStorage (offline)
+ */
+export declare function localSaveBackend(storage?: KeyValueStorage | null): SaveBackend;
+/** A memory-only {@link SaveBackend} — saves survive a reload only within the same session. For tests, SSR, or a "no persistence" mode that still exercises the same save code path. */
+export declare function memorySaveBackend(): SaveBackend;
+/** Adopt any async `read`/`write`/`remove` trio as a {@link SaveBackend} — the seam for cloud saves backed by a database, an HTTP endpoint, or Convex (see `@jgengine/convex/convexSaveBackend`). Reads/writes may reject; the save store surfaces the failure as `"error"` status instead of throwing. */
+export declare function remoteSaveBackend(backend: SaveBackend): SaveBackend;
+/** Lifecycle of the last save/load — drive a "Saving…"/"Saved" indicator or a loading gate off it. `"error"` means the backend rejected a read or write. */
+export type SaveStatus = "idle" | "loading" | "saving" | "saved" | "error";
+/** Autosave cadence: debounce writes `debounceMs` after the last edit, but never wait longer than `maxWaitMs` while edits keep coming (`0` removes the ceiling). `autosave: true` uses `{ debounceMs: 1000, maxWaitMs: 15000 }`. */
+export interface SaveAutoConfig {
+    debounceMs?: number;
+    maxWaitMs?: number;
+}
+/** The timer seam autosave schedules through — defaults to the ambient `setTimeout`/`clearTimeout`; inject fakes in tests. */
+export interface SaveTimers {
+    set(handler: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** The versioned envelope written to the backend — `version` lets a later game build detect and {@link SaveStoreConfig.migrate | migrate} an older payload. */
+export interface SaveEnvelope<T> {
+    version: number;
+    savedAt: number;
+    value: T;
+}
+/** How a {@link createSaveStore} is wired — the backend it persists through, the initial value, and optional slot/versioning/autosave/serialization knobs. */
+export interface SaveStoreConfig<T> {
+    /** Where saves live — {@link localSaveBackend}, {@link memorySaveBackend}, or a {@link remoteSaveBackend}. */
+    backend: SaveBackend;
+    /** The value a fresh save starts from (nothing stored yet, or after `clear`). */
+    initial: T;
+    /** Storage namespace, joined with the slot into the backend key. Default `"save"`. */
+    key?: string;
+    /** Active save slot — pass distinct slots for multiple parallel saves. Default `"default"`. */
+    slot?: string;
+    /** Current save-format version. Default `1`. Bump it on a breaking shape change and pass {@link migrate}. */
+    version?: number;
+    /** Upgrade an older payload to the current shape. Receives the stored value and the version it was written at (`0` for a pre-versioned/raw payload). */
+    migrate?: (data: unknown, fromVersion: number) => T;
+    /** Autosave on every `set`/`patch`. `false` (default) saves only on an explicit `save()`. */
+    autosave?: boolean | SaveAutoConfig;
+    serialize?: (envelope: SaveEnvelope<T>) => string;
+    deserialize?: (raw: string) => unknown;
+    /** Injectable clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Injectable timers for autosave. Default ambient `setTimeout`/`clearTimeout`. */
+    timers?: SaveTimers;
+    /** Notified on any backend read/write failure — status is already `"error"` when it runs. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * A pluggable-backend game save with autosave, named slots, and versioned
+ * migration. `value()`/`patch()` hold the live state; `load()` hydrates it from
+ * the backend; `save()` (or autosave) writes it back. Backend failures surface
+ * as `"error"` status and through `onError` — a save never throws into a tick.
+ */
+export interface SaveStore<T> {
+    value(): T;
+    status(): SaveStatus;
+    slot(): string;
+    /** Monotonic change counter — bumps on any value or status change; drive `useSyncExternalStore` off it. */
+    revision(): number;
+    /** Hydrate the active slot from the backend into `value()`; corrupt payloads fall back to `initial`. */
+    load(): Promise<T>;
+    /** Replace the value and mark it dirty (schedules autosave). */
+    set(value: T): void;
+    /** Read-modify-write the value and mark it dirty; returns the next value. */
+    patch(mutate: (previous: T) => T): T;
+    /** Flush the current value to the backend now (serialized against in-flight saves). */
+    save(): Promise<void>;
+    /** Delete the active slot and reset `value()` to `initial`. */
+    clear(): Promise<void>;
+    /** Flush any dirty state, switch to `slot`, and load it. */
+    switchSlot(slot: string): Promise<T>;
+    /** The slots this store has written (for a load/save menu). */
+    slots(): Promise<string[]>;
+    subscribe(listener: () => void): () => void;
+    /** Stop autosave timers and drop listeners. */
+    dispose(): void;
+}
+/**
+ * Create a {@link SaveStore}. Same call for offline and cloud — only the
+ * `backend` differs (localStorage, memory, or an async DB/Convex endpoint). Turn
+ * on `autosave` and every `set`/`patch` persists on a debounce; leave it off and
+ * call `save()` at checkpoints. Bump `version` + pass `migrate` when the save
+ * shape changes so old players keep their progress.
+ *
+ * @capability game-save save/load game state with a pluggable backend, autosave, slots, and migration
+ */
+export declare function createSaveStore<T>(config: SaveStoreConfig<T>): SaveStore<T>;