@driftengine/core 3.61.0

package/src/core/remoteSave.ts

@@ -0,0 +1,347 @@
+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 function defaultSaveTimer(): SaveTimer {
+  const host = globalThis as {
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+  };
+  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<number, unknown>();
+  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 implements KeyValueStore {
+  /** Everything the backend held at boot, plus everything this session has written. */
+  private readonly cache = new Map<string, string>();
+  /** Changes waiting to go out. Claimed once and swapped with `inFlight`, never rebuilt. */
+  private queued = new Map<string, string | null>();
+  /** The batch currently being sent. Swapped rather than copied, so a flush allocates nothing. */
+  private inFlight = new Map<string, string | null>();
+  private readonly listeners: ((status: SaveStatus) => void)[] = [];
+
+  private loadedValue = false;
+  private warnedUnloaded = false;
+  private statusValue: SaveStatus = 'idle';
+  private lastErrorValue: string | null = null;
+  private handle = 0;
+  private attempt = 0;
+  private current: Promise<void> | null = null;
+
+  private readonly flushDelayMs: number;
+  private readonly maxAttempts: number;
+  private readonly retryDelayMs: number;
+
+  constructor(
+    private readonly backend: SaveBackend,
+    private readonly timer: SaveTimer = defaultSaveTimer(),
+    options: RemoteSaveOptions = {},
+  ) {
+    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(): Promise<boolean> {
+    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(): boolean {
+    return this.loadedValue;
+  }
+
+  get status(): SaveStatus {
+    return this.statusValue;
+  }
+
+  /** How many keys are waiting to be sent, counting a batch that failed and came back. */
+  get pending(): number {
+    return this.queued.size + this.inFlight.size;
+  }
+
+  /** The last failure's message, cleared by the next batch that lands. */
+  get lastError(): string | null {
+    return this.lastErrorValue;
+  }
+
+  /** Told when the status changes, and only when it changes. Returns the unsubscribe. */
+  onStatusChange(listener: (status: SaveStatus) => void): () => void {
+    this.listeners.push(listener);
+    return () => {
+      const at = this.listeners.indexOf(listener);
+      if (at >= 0) this.listeners.splice(at, 1);
+    };
+  }
+
+  read(key: string): string | null {
+    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: string, value: string): void {
+    this.cache.set(key, value);
+    this.queued.set(key, value);
+    this.arm(this.flushDelayMs);
+  }
+
+  remove(key: string): void {
+    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(): Promise<void> {
+    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(): void {
+    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.
+   */
+  private async send(): Promise<void> {
+    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;
+    }
+  }
+
+  private async attemptSave(): Promise<void> {
+    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.
+   */
+  private returnToQueue(): void {
+    for (const [key, value] of this.inFlight) {
+      if (!this.queued.has(key)) this.queued.set(key, value);
+    }
+    this.inFlight.clear();
+  }
+
+  private arm(delayMs: number): void {
+    if (this.statusValue !== 'saving') this.setStatus('pending');
+    this.disarm();
+    this.handle = this.timer.schedule(() => {
+      this.handle = 0;
+      void this.send();
+    }, delayMs);
+  }
+
+  private disarm(): void {
+    if (this.handle === 0) return;
+    this.timer.cancel(this.handle);
+    this.handle = 0;
+  }
+
+  private setStatus(status: SaveStatus): void {
+    if (status === this.statusValue) return;
+    this.statusValue = status;
+    for (let i = 0; i < this.listeners.length; i++) this.listeners[i]?.(status);
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/core/rng.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 function pickBySeed<T>(seed: number, items: readonly T[]): T | null {
+  if (items.length === 0) return null;
+  const scrambled = Math.abs(Math.imul(seed | 0, 0x9e3779b1)) % items.length;
+  return items[scrambled] ?? 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 function hashToUnit(seed: number): number {
+  let t = (seed | 0) + 0x6d2b79f5;
+  t = Math.imul(t ^ (t >>> 15), 1 | t);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+export function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * 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 function savableMulberry32(seed: number): SavableRandom {
+  let state = seed | 0;
+  return {
+    next(): number {
+      state = (state + 0x6d2b79f5) | 0;
+      let t = Math.imul(state ^ (state >>> 15), 1 | state);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    },
+    save(): number {
+      return state;
+    },
+    restore(next: number): void {
+      state = next | 0;
+    },
+  };
+}

package/src/core/stepBudget.ts

@@ -0,0 +1,136 @@
+/**
+ * Spending a slice of a frame on work that can stop, without spending more than the slice.
+ *
+ * A **budgeted step pump**: the caller has some job — building a square of world, uploading a
+ * mesh, decoding a model — that can be broken into indivisible units, and wants to advance it
+ * a little every frame without the frame noticing. This holds the clock and the arithmetic;
+ * the caller holds the work and decides what to do next.
+ *
+ * **What it guarantees, in the honest words:** a call costs the larger of the budget and one
+ * uninterrupted stop. Not the budget. A stop cannot be interrupted from outside, so the only
+ * way to bound a call by the budget alone would be to bound every stop, which is the caller's
+ * job and not this one's — see `worstIn`, which exists to say which of the caller's units is
+ * the one over the line.
+ *
+ * **Why this rather than a count of units.** A count bounds the cheap term and leaves the
+ * expensive one free. `assets/uploadBudget.ts` records the measurement that established it:
+ * the parts of a model cost between 6 and 254 ms each, so three per frame was three of
+ * whatever they happened to be. The clock is exact, needs no per-asset tuning, and is as
+ * right on a phone as on a workstation.
+ *
+ * Nothing here touches a renderer or a device, on purpose: the property worth testing is a
+ * whole number of stops, and a test that needed a GPU could not assert it.
+ */
+
+/** A per-call decay of the guard: a half-life of sixty-nine calls, a little over a second at 60 Hz. */
+const DEFAULT_FORGET = 0.99;
+
+export interface StepBudgetOptions {
+  /**
+   * The clock, in milliseconds.
+   *
+   * Injected so a test can move time by hand. Every property this class has is a whole number
+   * of milliseconds and a whole number of stops; measuring them against a real clock would be
+   * measuring the machine the suite ran on.
+   */
+  readonly now?: () => number;
+  /**
+   * How fast the worst-stop estimate forgets, as a factor applied once per call.
+   *
+   * One per cent by default, and the number is load-bearing. Five per cent was tried by a
+   * consumer and is wrong: the estimate falls below the real cost inside a single crossing of
+   * a town, the guard lets a second stop start with no room for it, and a call costs the
+   * budget *plus* a stop rather than the larger of the two — which is the whole thing the
+   * guard exists to prevent.
+   */
+  readonly forget?: number;
+}
+
+export class StepBudget<Label = string> {
+  private readonly clock: () => number;
+  private readonly forget: number;
+
+  /**
+   * What one more stop is assumed to cost, and therefore whether there is room for it.
+   *
+   * The largest stop seen so far, decayed a little each call. It starts at zero, which means
+   * the first call of a program's life overshoots by one stop and learns from it — the price
+   * of not asking a caller to declare a number it cannot know.
+   */
+  private guard = 0;
+
+  private worstEver = 0;
+  private worstEverIn: Label | null = null;
+
+  constructor(options: StepBudgetOptions = {}) {
+    this.clock = options.now ?? ((): number => performance.now());
+    this.forget = options.forget ?? DEFAULT_FORGET;
+  }
+
+  /** What one more stop is currently assumed to cost. Decays; see `StepBudgetOptions.forget`. */
+  get estimate(): number {
+    return this.guard;
+  }
+
+  /** The longest single stop ever taken. Does not decay: this is the report, not the guard. */
+  get worst(): number {
+    return this.worstEver;
+  }
+
+  /**
+   * The label the caller gave the longest stop.
+   *
+   * **A budget being blown is useless information without the name of the unit that blew it.**
+   * That is the whole reason `next` returns a label rather than a boolean: "the worst stop was
+   * 57 ms" sends a reader nowhere, and "the worst stop was 57 ms, in upload" sends them to one
+   * file.
+   */
+  get worstIn(): Label | null {
+    return this.worstEverIn;
+  }
+
+  /**
+   * Advance the caller's work for up to `budgetMs`, and say how many stops that took.
+   *
+   * `next` performs exactly one indivisible unit and returns a label naming what it did, or
+   * `null` when there is nothing left to do — which ends the call without counting a stop.
+   *
+   * **Return the label of the work just done, not of the work about to be done.** The two are
+   * easy to confuse where a job names its own next phase, and the report that results sends a
+   * reader to the wrong builder every time the phase changes.
+   *
+   * The two rules the loop is made of, both arrived at by getting them wrong first:
+   *
+   * - *Do not start what you cannot finish.* A driver that keeps going while any budget
+   *   remains overshoots by a whole stop. Measured by a consumer at 30 Hz: 8.3 ms of budget
+   *   plus an 8.6 ms stop against a frame of 16.7.
+   * - *But always do one.* Without the unconditional first stop, a unit costing more than the
+   *   whole budget means nothing ever advances at all, and a world that never loads is worse
+   *   than a frame that runs long.
+   */
+  spend(budgetMs: number, next: () => Label | null): number {
+    const started = this.clock();
+    let stops = 0;
+
+    for (;;) {
+      const elapsed = this.clock() - started;
+      if (stops > 0 && elapsed + this.guard > budgetMs) break;
+
+      const began = this.clock();
+      const did = next();
+      if (did === null) break;
+      const took = this.clock() - began;
+
+      if (took > this.guard) this.guard = took;
+      if (took > this.worstEver) {
+        this.worstEver = took;
+        this.worstEverIn = did;
+      }
+      stops += 1;
+    }
+
+    /* And the estimate forgets, or one bad stop holds the queue for ever. */
+    this.guard *= this.forget;
+    return stops;
+  }
+}

package/src/core/storage.ts

@@ -0,0 +1,114 @@
+/**
+ * Where persisted state goes.
+ *
+ * The engine must not assume a browser origin. A game may want its saves on a
+ * server, in a native shell's own store, in an embedder-provided sandbox, or
+ * nowhere at all — so every engine system that persists takes a
+ * `KeyValueStore` and the browser is merely the default implementation.
+ *
+ * **Synchronous by design.** Preferences, one-time flags and a chosen character
+ * are all read during boot, before the first frame, and an await there means a
+ * frame rendered with the wrong settings and then corrected — a visible flicker
+ * on every load. An asynchronous backend (a server, IndexedDB) fits by
+ * hydrating a cache first and implementing `write` as fire-and-forget; that is
+ * what `MemoryStore.hydrate` exists for.
+ *
+ * No implementation here throws. Storage failure is a normal condition — Safari
+ * private mode and several embedded webviews throw on plain access — and a
+ * preference is never worth failing a boot for.
+ */
+export interface KeyValueStore {
+  read(key: string): string | null;
+  write(key: string, value: string): void;
+  remove(key: string): void;
+}
+
+/** Volatile store: the test double, and the fallback when nothing persists. */
+export class MemoryStore implements KeyValueStore {
+  private readonly entries = new Map<string, string>();
+
+  read(key: string): string | null {
+    return this.entries.get(key) ?? null;
+  }
+
+  write(key: string, value: string): void {
+    this.entries.set(key, value);
+  }
+
+  remove(key: string): void {
+    this.entries.delete(key);
+  }
+
+  /** Seed from an asynchronous backend before anything reads. */
+  hydrate(entries: Iterable<readonly [string, string]>): void {
+    for (const [key, value] of entries) this.entries.set(key, value);
+  }
+}
+
+/**
+ * `localStorage`, with every access guarded.
+ *
+ * A blocked store degrades to memory rather than to nothing: settings then last
+ * the session instead of resetting between screens, and a first-run prompt
+ * fires once per visit instead of on every single load. Never showing it at all
+ * would be the worse failure — a player who arrived from a link would have no
+ * idea what the controls are.
+ */
+export class BrowserStore implements KeyValueStore {
+  private readonly fallback = new MemoryStore();
+  private readonly available: boolean;
+
+  constructor() {
+    this.available = probeLocalStorage();
+  }
+
+  read(key: string): string | null {
+    if (!this.available) return this.fallback.read(key);
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return this.fallback.read(key);
+    }
+  }
+
+  write(key: string, value: string): void {
+    this.fallback.write(key, value);
+    if (!this.available) return;
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      // Quota exceeded or blocked mid-session; the memory copy still stands.
+    }
+  }
+
+  remove(key: string): void {
+    this.fallback.remove(key);
+    if (!this.available) return;
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      // As above.
+    }
+  }
+}
+
+function probeLocalStorage(): boolean {
+  try {
+    // Reading is not enough of a probe: some browsers allow the read and throw
+    // only on write, which would strand a store that reports itself healthy.
+    const probe = '__driftengine_probe__';
+    localStorage.setItem(probe, '1');
+    localStorage.removeItem(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+let shared: KeyValueStore | null = null;
+
+/** The default store: the browser's when it works, memory when it does not. */
+export function defaultStore(): KeyValueStore {
+  shared ??= new BrowserStore();
+  return shared;
+}