@driftengine/core 3.61.0

package/dist/core/preferences.d.ts

@@ -0,0 +1,47 @@
+import type { KeyValueStore } from './storage.ts';
+/**
+ * Persisted player preferences: a validated record in a `KeyValueStore`.
+ *
+ * Generic on purpose. A game declares *which* preferences exist and what their
+ * legal values are; everything below — reading, validating field by field,
+ * clamping, writing and announcing changes — is the same work in any game.
+ *
+ * Where the bytes actually live is the store's problem, not this module's, so a
+ * game can persist to the browser, a server or nothing at all without any of
+ * this changing. See `storage.ts` for why that seam is synchronous.
+ */
+export interface PreferenceSchema<T extends object> {
+    /** Storage key. Namespace it — the store is shared with everything else. */
+    readonly key: string;
+    /** The complete set of fields, and the value each falls back to. */
+    readonly defaults: T;
+    /** Inclusive `[min, max]` for numeric fields. Values outside are clamped. */
+    readonly ranges?: Partial<Record<keyof T, readonly [number, number]>>;
+    /** Legal values for string fields. Anything else falls back to the default. */
+    readonly options?: Partial<Record<keyof T, readonly string[]>>;
+}
+export declare function loadPreferences<T extends object>(schema: PreferenceSchema<T>, store?: KeyValueStore): T;
+export declare function savePreferences<T extends object>(schema: PreferenceSchema<T>, value: T, store?: KeyValueStore): void;
+/**
+ * A live preference record: the loaded value, validated updates, persistence
+ * and change notification for whatever applies them to running systems.
+ */
+export declare class PreferenceStore<T extends object> {
+    private readonly schema;
+    private readonly store;
+    private current;
+    private readonly listeners;
+    constructor(schema: PreferenceSchema<T>, store?: KeyValueStore);
+    get value(): Readonly<T>;
+    /**
+     * Apply a partial change. Every field goes through the same validation as a
+     * stored one — a control that can produce an illegal value would otherwise
+     * write it, leaving the read path as the only thing catching it, one boot too
+     * late.
+     */
+    update(patch: Partial<T>): void;
+    /** Returns an unsubscribe function. */
+    subscribe(listener: (value: Readonly<T>) => void): () => void;
+    /** Back to the declared defaults, persisted and announced like any change. */
+    reset(): void;
+}

package/dist/core/preferences.js

@@ -0,0 +1,140 @@
+import { defaultStore } from './storage.js';
+/**
+ * The field types a preference record can hold. A default of any other shape is refused.
+ *
+ * **Refused loudly, and that is the whole point of this function.** `validate` below answers
+ * `undefined` for anything that is not one of these, and `undefined` means "the stored value was
+ * unusable, keep the default" — which is exactly right for *data* and exactly wrong for a
+ * *schema*. A field the schema declares as an array took that path and cost a consumer a
+ * afternoon: `loadPreferences` handed back the default every time, and `update` skipped the field
+ * without ever setting `changed`, so writing one was a no-op that persisted nothing, notified
+ * nobody and reported no error. It was found by a failing test rather than by anything here.
+ *
+ * **The two paths are deliberately not symmetrical.** A stored record always lags the code that
+ * reads it, so one field of the wrong shape is the normal case and is tolerated field by field.
+ * A schema is written by a developer and is wrong at compile time or never, so it fails at init,
+ * where the engine's rule says a fault belongs.
+ */
+const SUPPORTED = ['number', 'boolean', 'string'];
+function assertSupportedSchema(schema) {
+    for (const key of Object.keys(schema.defaults)) {
+        const fallback = schema.defaults[key];
+        if (SUPPORTED.includes(typeof fallback))
+            continue;
+        const shape = Array.isArray(fallback) ? 'an array' : `a ${typeof fallback}`;
+        throw new Error(`preferences: "${schema.key}.${String(key)}" defaults to ${shape}, and a preference field ` +
+            `may only be a number, a boolean or a string. Anything else is written to the store and ` +
+            `silently dropped on the way back, so it is refused here rather than at the next boot.`);
+    }
+}
+/** Coerce one field, returning undefined when the candidate is unusable. */
+function validate(schema, key, value) {
+    const fallback = schema.defaults[key];
+    if (typeof fallback === 'number') {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            return undefined;
+        const range = schema.ranges?.[key];
+        if (range === undefined)
+            return value;
+        return Math.min(Math.max(value, range[0]), range[1]);
+    }
+    if (typeof fallback === 'boolean') {
+        return typeof value === 'boolean' ? value : undefined;
+    }
+    if (typeof fallback === 'string') {
+        if (typeof value !== 'string')
+            return undefined;
+        const allowed = schema.options?.[key];
+        if (allowed !== undefined && !allowed.includes(value))
+            return undefined;
+        return value;
+    }
+    return undefined;
+}
+export function loadPreferences(schema, store = defaultStore()) {
+    assertSupportedSchema(schema);
+    const result = { ...schema.defaults };
+    const raw = store.read(schema.key);
+    if (raw === null)
+        return result;
+    let stored;
+    try {
+        stored = JSON.parse(raw);
+    }
+    catch {
+        return result;
+    }
+    if (typeof stored !== 'object' || stored === null)
+        return result;
+    /*
+     * Field by field rather than all or nothing. A stored record always lags the
+     * code that reads it, so one field of the wrong shape is the normal case —
+     * and discarding the record over it would wipe every other preference the
+     * player had ever set.
+     */
+    const source = stored;
+    for (const key of Object.keys(schema.defaults)) {
+        const value = validate(schema, key, source[key]);
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+export function savePreferences(schema, value, store = defaultStore()) {
+    /* Checked here too: a caller that only ever saves would otherwise write a record that
+       nothing can read back, and find out one boot later in somebody else's session. */
+    assertSupportedSchema(schema);
+    store.write(schema.key, JSON.stringify(value));
+}
+/**
+ * A live preference record: the loaded value, validated updates, persistence
+ * and change notification for whatever applies them to running systems.
+ */
+export class PreferenceStore {
+    schema;
+    store;
+    current;
+    listeners = new Set();
+    constructor(schema, store = defaultStore()) {
+        this.schema = schema;
+        this.store = store;
+        this.current = loadPreferences(schema, store);
+    }
+    get value() {
+        return this.current;
+    }
+    /**
+     * Apply a partial change. Every field goes through the same validation as a
+     * stored one — a control that can produce an illegal value would otherwise
+     * write it, leaving the read path as the only thing catching it, one boot too
+     * late.
+     */
+    update(patch) {
+        let changed = false;
+        for (const key of Object.keys(patch)) {
+            if (!(key in this.schema.defaults))
+                continue;
+            const next = validate(this.schema, key, patch[key]);
+            if (next === undefined || next === this.current[key])
+                continue;
+            this.current[key] = next;
+            changed = true;
+        }
+        // Silent when nothing moved: subscribers apply settings to live systems and
+        // some of those write back, which without this is a loop.
+        if (!changed)
+            return;
+        savePreferences(this.schema, this.current, this.store);
+        for (const listener of this.listeners)
+            listener(this.current);
+    }
+    /** Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Back to the declared defaults, persisted and announced like any change. */
+    reset() {
+        this.update({ ...this.schema.defaults });
+    }
+}

package/dist/core/remoteSave.d.ts

@@ -0,0 +1,154 @@
+import type { KeyValueStore } from './storage.ts';
+/**
+ * A save that lives somewhere the engine cannot read synchronously — a server, a native shell, a
+ * sandbox — behind the synchronous seam every consumer already speaks.
+ *
+ * **A write-behind queue rather than a second interface, and that is the decision this module
+ * exists to record.** `KeyValueStore` is synchronous because preferences are read during *boot*,
+ * before the first frame: an await there means a frame drawn with the wrong settings and then
+ * corrected, which is a visible flicker on every load. So the choice was between widening the seam
+ * to an asynchronous twin, which every consumer and every store integration would then have to
+ * learn, or hydrating a cache once and draining writes behind it. Both shipped implementations of
+ * the seam that are already asynchronous underneath — a file the shell owns, and a cloud store —
+ * chose the second, independently, and neither needed the interface widened. This is that
+ * arrangement written once, with the three things a hand-rolled version leaves out.
+ *
+ * **The three:**
+ *
+ * 1. **Coalescing.** A settings slider writes on every drag frame. One request per write is sixty
+ *    requests for one decision, and it is the reason a naive fire-and-forget backend gets rate
+ *    limited. Writes accumulate into a batch, one entry per key, sent after a quiet period.
+ * 2. **Retry.** A save that cannot reach the server is a normal condition — a player on a train.
+ *    The batch is retried with a growing delay, and giving up on the *attempt* is never giving up
+ *    on the *data*: the changes stay queued and go out with the next batch.
+ * 3. **A status.** Failure surfaces as something the caller can read, never a throw. A game
+ *    showing "saved" over a queue that has been failing for ten minutes is worse than either a
+ *    crash or an honest indicator, and it is what fire-and-forget produces by construction.
+ *
+ * **What it costs.** A write is durable *later*, not now, and a player who closes the tab inside
+ * the flush delay loses it. `flush()` is the answer, called from whatever the consumer's platform
+ * gives it — `visibilitychange`, a shell's close hook, a menu's exit — and the engine does not
+ * register that listener itself, because a DOM listener is a decision about the page rather than
+ * about saving. **What would make this wrong** is a consumer needing a write acknowledged before
+ * it acts on it, and the honest answer then is `await flush()` at that one site rather than an
+ * asynchronous surface everywhere.
+ */
+/**
+ * The asynchronous side, which the consumer implements.
+ *
+ * **`save` takes a batch rather than one key**, because a network backend wants one round trip for
+ * a screen's worth of changes and a per-key interface makes that impossible to build on top. A
+ * consumer whose API is per-key loops inside `save`; a consumer whose API is a document writes one
+ * request. The reverse adaptation cannot be done at all.
+ */
+export interface SaveBackend {
+    /** Everything this backend holds, read once before the first frame. */
+    load(): Promise<Iterable<readonly [string, string]>>;
+    /**
+     * Apply a batch. A `null` value is a removal, so one call carries both kinds of change.
+     *
+     * Reject to have the batch retried. Resolving is a promise that it landed: a backend that
+     * resolves optimistically turns this store's status into a decoration.
+     */
+    save(changes: ReadonlyMap<string, string | null>): Promise<void>;
+}
+/**
+ * The delay, taken as a capability rather than reached for.
+ *
+ * The same rule `KeyValueStore` itself follows: nothing here may assume a browser origin, and a
+ * native shell or a test supplies its own. A platform with no timer at all still works — nothing
+ * is ever armed, and the consumer drives `flush()`.
+ */
+export interface SaveTimer {
+    schedule(callback: () => void, delayMs: number): number;
+    cancel(handle: number): void;
+}
+/** What the queue is doing, for an indicator a player can read. */
+export type SaveStatus = 'idle' | 'pending' | 'saving' | 'failed';
+export interface RemoteSaveOptions {
+    /** The quiet period a burst of writes is collected over, in milliseconds. Default 250. */
+    readonly flushDelayMs?: number;
+    /** How many times one batch is attempted before the status goes to `failed`. Default 3. */
+    readonly maxAttempts?: number;
+    /** The first retry delay, doubled at each further attempt. Default 500. */
+    readonly retryDelayMs?: number;
+}
+/** The global timer where there is one, and a timer that never fires where there is not. */
+export declare function defaultSaveTimer(): SaveTimer;
+export declare class RemoteSaveStore implements KeyValueStore {
+    private readonly backend;
+    private readonly timer;
+    /** Everything the backend held at boot, plus everything this session has written. */
+    private readonly cache;
+    /** Changes waiting to go out. Claimed once and swapped with `inFlight`, never rebuilt. */
+    private queued;
+    /** The batch currently being sent. Swapped rather than copied, so a flush allocates nothing. */
+    private inFlight;
+    private readonly listeners;
+    private loadedValue;
+    private warnedUnloaded;
+    private statusValue;
+    private lastErrorValue;
+    private handle;
+    private attempt;
+    private current;
+    private readonly flushDelayMs;
+    private readonly maxAttempts;
+    private readonly retryDelayMs;
+    constructor(backend: SaveBackend, timer?: SaveTimer, options?: RemoteSaveOptions);
+    /**
+     * Fill the cache from the backend. Await this **before the first frame**.
+     *
+     * Answers whether it worked rather than rejecting, because a rejected promise nobody caught is
+     * an unhandled rejection during boot and a store that cannot load is a store that still has to
+     * serve defaults. A failure also says so on the console once: a consumer that ignores both the
+     * answer and the status boots on defaults and overwrites the player's real settings with them on
+     * the first write, which is the one outcome worse than not loading.
+     */
+    load(): Promise<boolean>;
+    /** Whether `load` has completed, either way. */
+    get loaded(): boolean;
+    get status(): SaveStatus;
+    /** How many keys are waiting to be sent, counting a batch that failed and came back. */
+    get pending(): number;
+    /** The last failure's message, cleared by the next batch that lands. */
+    get lastError(): string | null;
+    /** Told when the status changes, and only when it changes. Returns the unsubscribe. */
+    onStatusChange(listener: (status: SaveStatus) => void): () => void;
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+    /**
+     * Send everything queued now, and resolve when that attempt has settled.
+     *
+     * For a consumer leaving the page. It never rejects: read `status` afterwards to find out
+     * whether it landed. A batch already in flight is awaited first, so two flushes cannot overlap.
+     */
+    flush(): Promise<void>;
+    /**
+     * Throw away everything waiting to be sent.
+     *
+     * The escape hatch that makes "a failed batch is kept forever" acceptable: a consumer that has
+     * decided the queue is stale — a player signing out, a save slot deleted — says so, rather than
+     * this store guessing after some number of failures. The cache is untouched, so reads still
+     * answer what the session wrote.
+     */
+    discardPending(): void;
+    /**
+     * One attempt at the queued batch. **Never rejects**, because it is reachable from a timer and
+     * from a frame, and the house rule is that neither throws.
+     */
+    private send;
+    private attemptSave;
+    /**
+     * Put a failed batch back **under** whatever arrived while it was away.
+     *
+     * The direction is the whole of it. A player dragging a slider writes 0.1, the batch leaves, they
+     * drag to 0.9, the batch fails — and a merge that overwrote would send 0.1 and silently undo the
+     * drag. Newer always wins, which is why this checks before it sets.
+     */
+    private returnToQueue;
+    private arm;
+    private disarm;
+    private setStatus;
+}

package/dist/core/remoteSave.js

@@ -0,0 +1,249 @@
+/** The global timer where there is one, and a timer that never fires where there is not. */
+export function defaultSaveTimer() {
+    const host = globalThis;
+    if (typeof host.setTimeout !== 'function') {
+        /* Not a silent no-op: `flush()` still sends, so a platform with no timer saves on demand and
+           never in the background. The alternative — throwing at construction — would refuse a store
+           that works, on a platform this engine has no business assuming anything about. */
+        return { schedule: () => 0, cancel: () => { } };
+    }
+    const set = host.setTimeout.bind(host);
+    const clear = host.clearTimeout?.bind(host);
+    let next = 1;
+    const handles = new Map();
+    return {
+        schedule(callback, delayMs) {
+            const id = next++;
+            handles.set(id, set(callback, delayMs));
+            return id;
+        },
+        cancel(handle) {
+            const native = handles.get(handle);
+            handles.delete(handle);
+            if (native !== undefined)
+                clear?.(native);
+        },
+    };
+}
+export class RemoteSaveStore {
+    backend;
+    timer;
+    /** Everything the backend held at boot, plus everything this session has written. */
+    cache = new Map();
+    /** Changes waiting to go out. Claimed once and swapped with `inFlight`, never rebuilt. */
+    queued = new Map();
+    /** The batch currently being sent. Swapped rather than copied, so a flush allocates nothing. */
+    inFlight = new Map();
+    listeners = [];
+    loadedValue = false;
+    warnedUnloaded = false;
+    statusValue = 'idle';
+    lastErrorValue = null;
+    handle = 0;
+    attempt = 0;
+    current = null;
+    flushDelayMs;
+    maxAttempts;
+    retryDelayMs;
+    constructor(backend, timer = defaultSaveTimer(), options = {}) {
+        this.backend = backend;
+        this.timer = timer;
+        this.flushDelayMs = options.flushDelayMs ?? 250;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.retryDelayMs = options.retryDelayMs ?? 500;
+    }
+    /**
+     * Fill the cache from the backend. Await this **before the first frame**.
+     *
+     * Answers whether it worked rather than rejecting, because a rejected promise nobody caught is
+     * an unhandled rejection during boot and a store that cannot load is a store that still has to
+     * serve defaults. A failure also says so on the console once: a consumer that ignores both the
+     * answer and the status boots on defaults and overwrites the player's real settings with them on
+     * the first write, which is the one outcome worse than not loading.
+     */
+    async load() {
+        try {
+            const entries = await this.backend.load();
+            for (const [key, value] of entries)
+                this.cache.set(key, value);
+            this.loadedValue = true;
+            return true;
+        }
+        catch (error) {
+            this.loadedValue = true;
+            this.lastErrorValue = messageOf(error);
+            this.setStatus('failed');
+            console.warn(`[driftengine] the save backend could not be read: ${this.lastErrorValue}. ` +
+                'The game will boot on defaults, and the first write will overwrite what is stored. ' +
+                'Read `status` before writing if that matters.');
+            return false;
+        }
+    }
+    /** Whether `load` has completed, either way. */
+    get loaded() {
+        return this.loadedValue;
+    }
+    get status() {
+        return this.statusValue;
+    }
+    /** How many keys are waiting to be sent, counting a batch that failed and came back. */
+    get pending() {
+        return this.queued.size + this.inFlight.size;
+    }
+    /** The last failure's message, cleared by the next batch that lands. */
+    get lastError() {
+        return this.lastErrorValue;
+    }
+    /** Told when the status changes, and only when it changes. Returns the unsubscribe. */
+    onStatusChange(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const at = this.listeners.indexOf(listener);
+            if (at >= 0)
+                this.listeners.splice(at, 1);
+        };
+    }
+    read(key) {
+        if (!this.loadedValue && !this.warnedUnloaded) {
+            this.warnedUnloaded = true;
+            console.warn('[driftengine] a remote save store was read before `load()` resolved, so it answered null. ' +
+                'Await `load()` before the first frame, or the game boots on defaults it will then save.');
+        }
+        return this.cache.get(key) ?? null;
+    }
+    write(key, value) {
+        this.cache.set(key, value);
+        this.queued.set(key, value);
+        this.arm(this.flushDelayMs);
+    }
+    remove(key) {
+        this.cache.delete(key);
+        this.queued.set(key, null);
+        this.arm(this.flushDelayMs);
+    }
+    /**
+     * Send everything queued now, and resolve when that attempt has settled.
+     *
+     * For a consumer leaving the page. It never rejects: read `status` afterwards to find out
+     * whether it landed. A batch already in flight is awaited first, so two flushes cannot overlap.
+     */
+    async flush() {
+        this.disarm();
+        if (this.current !== null)
+            await this.current;
+        if (this.queued.size === 0)
+            return;
+        /* A deliberate flush starts the attempt count over: the caller is asking now, and a previous
+           exhaustion should not make this call a no-op. */
+        this.attempt = 0;
+        await this.send();
+    }
+    /**
+     * Throw away everything waiting to be sent.
+     *
+     * The escape hatch that makes "a failed batch is kept forever" acceptable: a consumer that has
+     * decided the queue is stale — a player signing out, a save slot deleted — says so, rather than
+     * this store guessing after some number of failures. The cache is untouched, so reads still
+     * answer what the session wrote.
+     */
+    discardPending() {
+        this.disarm();
+        this.queued.clear();
+        this.inFlight.clear();
+        this.setStatus(this.statusValue === 'saving' ? 'saving' : 'idle');
+    }
+    /**
+     * One attempt at the queued batch. **Never rejects**, because it is reachable from a timer and
+     * from a frame, and the house rule is that neither throws.
+     */
+    async send() {
+        if (this.current !== null)
+            return this.current;
+        /* Swap rather than copy: the queue that was accumulating becomes the batch, and the empty one
+           that just went out becomes the queue. A write landing during the send goes into the new
+           queue and belongs to the next batch. */
+        const outgoing = this.queued;
+        this.queued = this.inFlight;
+        this.inFlight = outgoing;
+        this.attempt += 1;
+        this.setStatus('saving');
+        const run = this.attemptSave();
+        this.current = run;
+        try {
+            await run;
+        }
+        finally {
+            this.current = null;
+        }
+    }
+    async attemptSave() {
+        try {
+            /* Awaited inside the `try` so a backend that throws synchronously reads the same as one that
+               rejects — they are the same condition to a caller, and only one of them is catchable by a
+               plain `.catch`. */
+            await this.backend.save(this.inFlight);
+            this.inFlight.clear();
+            this.attempt = 0;
+            this.lastErrorValue = null;
+            if (this.queued.size > 0) {
+                this.setStatus('pending');
+                this.arm(this.flushDelayMs);
+                return;
+            }
+            this.setStatus('idle');
+        }
+        catch (error) {
+            this.lastErrorValue = messageOf(error);
+            this.returnToQueue();
+            if (this.attempt >= this.maxAttempts) {
+                /* Reset, so a later write or an explicit flush starts a fresh run of attempts rather than
+                   being refused by a counter left at the ceiling. */
+                this.attempt = 0;
+                this.setStatus('failed');
+                return;
+            }
+            this.setStatus('pending');
+            // determinism: build-time — a network retry backoff, which is wall-clock and not simulation
+            this.arm(this.retryDelayMs * 2 ** (this.attempt - 1));
+        }
+    }
+    /**
+     * Put a failed batch back **under** whatever arrived while it was away.
+     *
+     * The direction is the whole of it. A player dragging a slider writes 0.1, the batch leaves, they
+     * drag to 0.9, the batch fails — and a merge that overwrote would send 0.1 and silently undo the
+     * drag. Newer always wins, which is why this checks before it sets.
+     */
+    returnToQueue() {
+        for (const [key, value] of this.inFlight) {
+            if (!this.queued.has(key))
+                this.queued.set(key, value);
+        }
+        this.inFlight.clear();
+    }
+    arm(delayMs) {
+        if (this.statusValue !== 'saving')
+            this.setStatus('pending');
+        this.disarm();
+        this.handle = this.timer.schedule(() => {
+            this.handle = 0;
+            void this.send();
+        }, delayMs);
+    }
+    disarm() {
+        if (this.handle === 0)
+            return;
+        this.timer.cancel(this.handle);
+        this.handle = 0;
+    }
+    setStatus(status) {
+        if (status === this.statusValue)
+            return;
+        this.statusValue = status;
+        for (let i = 0; i < this.listeners.length; i++)
+            this.listeners[i]?.(status);
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/rng.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Seeded PRNG (mulberry32). The only randomness source allowed in simulation
+ * and world generation — `Math.random()` is banned there (see AGENTS.md).
+ * Same seed ⇒ same sequence on every platform.
+ */
+/**
+ * Deterministically choose one item from a list.
+ *
+ * The seed is hashed before the modulo rather than used raw. `seed % length`
+ * walks the list in order, so consecutive seeds — day numbers, level indices —
+ * produce a visible cycle; multiplying by the golden-ratio constant first
+ * scatters them, which is the difference between "today's track" feeling picked
+ * and feeling like a rota.
+ */
+export declare function pickBySeed<T>(seed: number, items: readonly T[]): T | null;
+/**
+ * A single well-mixed value in `[0, 1)` from one integer seed.
+ *
+ * `mulberry32`'s mixer without the stream: the same avalanche, applied once, for the
+ * very common case of "one deterministic value per index" — a per-particle jitter, a
+ * per-node displacement — where allocating a generator per lookup is absurd.
+ *
+ * It exists because the obvious alternative is wrong in a way that is hard to see.
+ * `fract(sin(x) * 43758.5453)` is the reflex GPU hash and it degrades badly on the CPU
+ * for large `x`: `sin` of a number in the millions has lost most of its precision to
+ * argument reduction, so nearby seeds correlate and *whole families of values collapse
+ * onto each other*. That is what an effect seeded from a tick count hands it. Measured
+ * as lightning whose every bolt came out the same shape however much variation the
+ * caller thought it was asking for: still visibly deterministic where the caller
+ * expected a fresh shape on every strike.
+ *
+ * Integer mixing has no such failure: every bit of the input reaches every bit of the
+ * output, at any magnitude, and it is bit-identical on every platform, which the
+ * replay contract requires.
+ */
+export declare function hashToUnit(seed: number): number;
+export declare function mulberry32(seed: number): () => number;
+/**
+ * A generator whose position can be read and written.
+ *
+ * **The closure above cannot be rewound, and a resimulation has to be.** A rollback loop restores
+ * a past tick and steps forward again; anything the replayed ticks draw from a generator must draw
+ * the same numbers they drew the first time, or the replay produces a different world from the run
+ * it is replaying. `mulberry32` keeps its position in a closed-over variable, which is the right
+ * shape for every other caller and unreachable for this one.
+ *
+ * **The whole position is one int32**, which is why this is an interface over a number and not a
+ * buffer: mulberry32 mixes a counter and holds nothing else. A `save()` is a number a caller can
+ * put in a snapshot beside the rest of a tick's state, and comparing two of them is `===`.
+ *
+ * The sequence is `mulberry32`'s, unchanged and asserted against it. **That is the promise, not an
+ * implementation note**: `AGENTS.md` makes the seeded sequence a contract about stored replays and
+ * ghosts, so a second generator that drifted from the first by an increment would invalidate every
+ * one of them while passing every test that only read this file.
+ */
+export interface SavableRandom {
+    /** The next value in `[0, 1)`. */
+    next(): number;
+    /** The position, as one integer. */
+    save(): number;
+    /** Resume from a position `save` returned. */
+    restore(state: number): void;
+}
+export declare function savableMulberry32(seed: number): SavableRandom;