@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/connection.ts

@@ -1,299 +1,408 @@
-/**
- * The machinery under every `Hub` call: reaching the REST API, falling back
- * to the offline cache, queueing writes made offline and replaying them,
- * buffering analytics, warming the cache for every game, and reporting
- * online/offline/sync status (to `onStatus` listeners and as `hub:*` window
- * events, which the injected menu listens for).
- */
-import { HubError } from './errors';
-import { LocalStore } from './offline/local-store';
-import type { QueueOp, QueueOpInput } from './offline/queue';
-import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
-import { createRestClient, type RestClient } from './rest/rest-client';
-import type { HubOptions, HubStatus, SnapshotResponse } from './types';
-
-/** How long `prefetchAll()` waits between snapshots unless forced. */
-const PREFETCH_INTERVAL_MS = 30_000;
-
-/** A queued write the hub refused during a sync: dropped, with the hub's message. */
-export interface SyncConflict {
-  /** The refused op. */
-  readonly op: QueueOp;
-  /** The hub's message. */
-  readonly error?: string;
-}
-
-/** What one `sync()` did. */
-export interface SyncResult {
-  /** Queued writes the hub accepted. */
-  readonly flushed: number;
-  /** Queued writes the hub refused (and that were dropped). */
-  readonly conflicts: SyncConflict[];
-}
-
-/** Whether a failure means "the hub can't be reached" (rather than a refusal). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a call threw
-function isTransportFailure(failure: unknown): boolean {
-  return failure instanceof HubError && failure.isOffline;
-}
-
-/** The game slug's path field, or a {@link HubError} when the slug is unknown. */
-export interface GameFields {
-  /** The game's slug. */
-  readonly slug: string;
-}
-
-/** The connection, offline cache and sync machinery shared by every `Hub` method. */
-export class HubConnection {
-  /** This client's game slug (`null` when it could not be determined). */
-  readonly slug: string | null;
-  /** The absolute API base, e.g. `https://diffenderfer.games/_api`. */
-  readonly apiBase: string;
-  /** Typed REST calls to {@link apiBase}. */
-  protected readonly rest: RestClient;
-  /** This game's offline cache, queue and event buffer. */
-  protected readonly store: LocalStore;
-  private readonly offlineMode: NonNullable<HubOptions['offline']>;
-  private isReachable = true;
-  private isSyncing = false;
-  private lastPrefetchAt = 0;
-  private readonly statusListeners = new Set<(status: HubStatus) => void>();
-
-  /** A connection for `options` (slug and API base default to the page's). */
-  constructor(options: HubOptions = {}) {
-    this.slug = options.slug ?? detectSlug();
-    this.apiBase = options.apiBase === undefined ? detectApiBase() : absoluteApiBase(options.apiBase);
-    this.offlineMode = options.offline ?? 'auto';
-    this.rest = createRestClient({
-      apiBase: this.apiBase,
-      fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
-      onReachable: () => {
-        this.setReachable(true);
-      },
-    });
-    this.store = new LocalStore(this.slug ?? 'app');
-    if (typeof navigator !== 'undefined' && 'onLine' in navigator) {
-      this.isReachable = navigator.onLine;
-    }
-    if (isBrowserPage()) {
-      window.addEventListener('online', () => {
-        this.setReachable(true);
-      });
-      window.addEventListener('offline', () => {
-        this.setReachable(false);
-      });
-    }
-  }
-
-  /** `true` when calls are being served from the offline cache rather than the hub. */
-  get isOffline(): boolean {
-    return this.offlineMode === 'always' || (this.offlineMode === 'auto' && !this.isReachable);
-  }
-
-  /** `true` while the hub is reachable. */
-  get isOnline(): boolean {
-    return this.isReachable;
-  }
-
-  /** Queued writes plus buffered analytics events waiting to sync. */
-  pending(): number {
-    return this.store.queueLength() + this.store.getEvents().length;
-  }
-
-  /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
-  onStatus(listener: (status: HubStatus) => void): () => void {
-    this.statusListeners.add(listener);
-    return () => {
-      this.statusListeners.delete(listener);
-    };
-  }
-
-  /** Tell `onStatus` listeners and the page (`hub:status`) the current status. */
-  protected notifyStatus(): void {
-    const status: HubStatus = { online: this.isReachable, offline: this.isOffline, pending: this.pending() };
-    for (const listener of this.statusListeners) {
-      try {
-        listener(status);
-      } catch {
-        // A listener's failure must not stop the others.
-      }
-    }
-    emitWindowEvent('hub:status', status);
-  }
-
-  /** Record reachability; coming back online syncs the queue and re-warms the cache. */
-  protected setReachable(isReachableNow: boolean): void {
-    if (isReachableNow === this.isReachable) {
-      return;
-    }
-    this.isReachable = isReachableNow;
-    emitWindowEvent(isReachableNow ? 'hub:online' : 'hub:offline', { pending: this.pending() });
-    this.notifyStatus();
-    if (isReachableNow) {
-      void this.sync();
-      void this.prefetchAll().catch(() => undefined);
-    }
-  }
-
-  /** `{ slug }` for this game's endpoints; throws when the slug is unknown. */
-  protected gameFields(): GameFields {
-    if (this.slug === null) {
-      throw new HubError('Hub: could not determine the game slug.');
-    }
-    return { slug: this.slug };
-  }
-
-  /**
-   * Run the network call, falling back to the offline answer when the hub
-   * can't be reached (per the offline mode). Real API errors (with an HTTP
-   * status) always reach the caller.
-   */
-  protected async withFallback<Reply>(networkCall: () => Promise<Reply>, offlineAnswer: () => Reply): Promise<Reply> {
-    if (this.isOffline) {
-      return offlineAnswer();
-    }
-    try {
-      return await networkCall();
-    } catch (failure) {
-      if (!isTransportFailure(failure) || this.offlineMode === 'never') {
-        throw failure;
-      }
-      this.setReachable(false);
-      return offlineAnswer();
-    }
-  }
-
-  /** Send one queued write. */
-  private async sendOp(op: QueueOpInput): Promise<void> {
-    const game = this.gameFields();
-    switch (op.kind) {
-      case 'putSave':
-        await this.rest.call('writeSave', { ...game, slot: op.slot, data: op.data, label: op.label });
-        return;
-      case 'deleteSave':
-        await this.rest.call('deleteSave', { ...game, slot: op.slot });
-        return;
-      case 'setStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'set' });
-        return;
-      case 'maxStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.value, mode: 'max' });
-        return;
-      case 'incrStat':
-        await this.rest.call('updateGameStat', { ...game, key: op.key, value: op.amount, mode: 'incr' });
-        return;
-      case 'submitScore':
-        await this.rest.call('submitScore', { ...game, key: op.key, score: op.score, ...op.opts });
-        return;
-      case 'setProfile':
-        await this.rest.call('setGameProfile', { ...game, ...op.patch });
-        return;
-    }
-  }
-
-  /**
-   * Apply a write to the offline cache at once, then send it now (online
-   * with an empty queue) or queue it behind the others. Resolves with the
-   * local answer; a real API error on the direct path reaches the caller and
-   * is not queued.
-   */
-  protected async mutateQueued<Reply>(input: QueueOpInput, localAnswer: () => Reply): Promise<Reply> {
-    const answer = localAnswer();
-    if (this.isOffline || this.store.queueLength() > 0) {
-      this.store.enqueue(input);
-      this.notifyStatus();
-      if (!this.isOffline) {
-        void this.sync();
-      }
-      return answer;
-    }
-    try {
-      await this.sendOp(input);
-      return answer;
-    } catch (failure) {
-      if (!isTransportFailure(failure)) {
-        throw failure;
-      }
-      this.setReachable(false);
-      this.store.enqueue(input);
-      this.notifyStatus();
-      return answer;
-    }
-  }
-
-  /**
-   * Replay the queue, then the buffered events, in order. Stops at the first
-   * transport failure (offline again: the rest stays queued); a write the hub
-   * refuses is dropped and reported as a conflict.
-   */
-  async sync(): Promise<SyncResult> {
-    if (this.isSyncing || this.isOffline || this.slug === null) {
-      return { flushed: 0, conflicts: [] };
-    }
-    this.isSyncing = true;
-    let flushed = 0;
-    const conflicts: SyncConflict[] = [];
-    try {
-      let queue = this.store.getQueue();
-      for (let op = queue[0]; op !== undefined; op = queue[0]) {
-        try {
-          await this.sendOp(op);
-          flushed += 1;
-        } catch (failure) {
-          if (isTransportFailure(failure)) {
-            break;
-          }
-          conflicts.push({ op, error: failure instanceof Error ? failure.message : String(failure) });
-        }
-        queue = queue.slice(1);
-        this.store.setQueue(queue);
-      }
-      await this.flushEvents();
-    } finally {
-      this.isSyncing = false;
-    }
-    emitWindowEvent('hub:sync', { pending: this.pending(), flushed, conflicts });
-    this.notifyStatus();
-    return { flushed, conflicts };
-  }
-
-  /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
-  private async flushEvents(): Promise<void> {
-    let events = this.store.getEvents();
-    for (let event = events[0]; event !== undefined; event = events[0]) {
-      try {
-        await this.rest.call('recordGameEvent', { ...this.gameFields(), type: event.type });
-      } catch (failure) {
-        if (isTransportFailure(failure)) {
-          return;
-        }
-      }
-      events = events.slice(1);
-      this.store.setEvents(events);
-    }
-  }
-
-  /**
-   * Warm the offline cache for every game the player has touched, in one
-   * request, so going offline later still shows complete progress.
-   * Throttled to once per 30 s unless `isForced`; `null` when offline or throttled.
-   */
-  async prefetchAll(isForced = false): Promise<SnapshotResponse | null> {
-    if (this.isOffline || (!isForced && Date.now() - this.lastPrefetchAt < PREFETCH_INTERVAL_MS)) {
-      return null;
-    }
-    let snapshot: SnapshotResponse;
-    try {
-      snapshot = await this.rest.call('getMyOfflineSnapshot');
-    } catch (failure) {
-      if (isTransportFailure(failure)) {
-        return null;
-      }
-      throw failure;
-    }
-    this.lastPrefetchAt = Date.now();
-    this.store.hydrate(snapshot);
-    emitWindowEvent('hub:prefetch', { games: Object.keys(snapshot.games).length });
-    return snapshot;
-  }
-}
+/**
+ * The machinery under every `Hub` call: reaching the REST API, falling back
+ * to the offline cache, queueing writes made offline in the outbox and
+ * replaying them, buffering analytics, warming the cache for every game, and
+ * reporting online/offline/sync status (to `onStatus` listeners and as
+ * `hub:*` window events, which the injected menu listens for).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from './errors';
+import { registerHubKinds, legacyOperation } from './offline/hub-kinds';
+import { LocalStore } from './offline/local-store';
+import { OfflineApi } from './offline/offline-api';
+import { Outbox, type OfflineOp } from './offline/outbox';
+import { LocalResumeStore } from './resume/local-resume';
+import { LocalDailyStore } from './saved/local-saved';
+import { absoluteApiBase, detectApiBase, detectSlug, emitWindowEvent, isBrowserPage } from './page';
+import { createRestClient, type RestClient } from './rest/rest-client';
+import { createPageStore } from './storage/key-value';
+import type { HubOptions, HubStatus, SnapshotResponse } from './types';
+
+/** How long `prefetchAll()` waits between snapshots unless forced. */
+const PREFETCH_INTERVAL_MS = 30_000;
+
+/** A queued op the hub refused during a sync (or that kept failing): dropped, with the reason. */
+export interface SyncConflict {
+  /** The dropped op. */
+  readonly op: OfflineOp;
+  /** The hub's (or the handler's) message. */
+  readonly error?: string;
+}
+
+/** What one `sync()` did. */
+export interface SyncResult {
+  /** Queued ops that landed. */
+  readonly flushed: number;
+  /** Queued ops that were dropped. */
+  readonly conflicts: SyncConflict[];
+}
+
+/** A sync that did nothing. */
+const NOTHING_SYNCED: SyncResult = { flushed: 0, conflicts: [] };
+
+/** Whether a failure means "the hub can't be reached" (rather than a refusal). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a call threw
+function isTransportFailure(failure: unknown): boolean {
+  return failure instanceof HubError && failure.isOffline;
+}
+
+/** The game slug's path field, or a {@link HubError} when the slug is unknown. */
+export interface GameFields {
+  /** The game's slug. */
+  readonly slug: string;
+}
+
+/** The connection, offline cache and sync machinery shared by every `Hub` method. */
+export class HubConnection {
+  /** This client's game slug (`null` when it could not be determined). */
+  readonly slug: string | null;
+  /** The absolute API base, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** Typed REST calls to {@link apiBase}. */
+  protected readonly rest: RestClient;
+  /** This game's offline cache and event buffer. */
+  protected readonly store: LocalStore;
+  /** This game's queued operations. */
+  protected readonly outbox: Outbox;
+  /** The device copies of every game's resume slot (`hub.resume`). */
+  protected readonly resumeStore: LocalResumeStore;
+  /** The device copies of daily challenges in progress (every game's). */
+  protected readonly dailyStore: LocalDailyStore;
+  private readonly offlineMode: NonNullable<HubOptions['offline']>;
+  private isReachable = true;
+  private runningSync: Promise<SyncResult> | null = null;
+  private followingSync: Promise<SyncResult> | null = null;
+  private isFollowingEager = false;
+  private directSend: Promise<Json | undefined> | null = null;
+  private lastPrefetchAt = 0;
+  private offlineApi: OfflineApi | undefined;
+  private readonly statusListeners = new Set<(status: HubStatus) => void>();
+
+  /** A connection for `options` (slug and API base default to the page's). */
+  constructor(options: HubOptions = {}) {
+    this.slug = options.slug ?? detectSlug();
+    this.apiBase = options.apiBase === undefined ? detectApiBase() : absoluteApiBase(options.apiBase);
+    this.offlineMode = options.offline ?? 'auto';
+    this.rest = createRestClient({
+      apiBase: this.apiBase,
+      fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+      onReachable: () => {
+        this.setReachable(true);
+      },
+    });
+    const pageStore = createPageStore();
+    this.store = new LocalStore(this.slug ?? 'app', pageStore);
+    this.resumeStore = new LocalResumeStore(pageStore);
+    this.dailyStore = new LocalDailyStore(pageStore);
+    this.outbox = new Outbox({
+      slug: this.slug ?? 'app',
+      store: pageStore,
+      rest: this.rest,
+      emit: emitWindowEvent,
+      onUnreachable: () => {
+        this.setReachable(false);
+      },
+      onChange: () => {
+        this.notifyStatus();
+      },
+      onRetryDue: () => {
+        void this.retrySync();
+      },
+    });
+    registerHubKinds(this.outbox, {
+      game: () => this.gameFields(),
+      onDailyComplete: (payload, completion) => {
+        if (this.slug !== null) {
+          this.dailyStore.remove(this.slug, payload.day);
+        }
+        emitWindowEvent('hub:daily-complete', { day: payload.day, count: completion.count, rank: completion.rank, meta: payload.meta });
+      },
+      resume: this.resumeStore,
+      dailies: this.dailyStore,
+      cloudSaves: this.store,
+    });
+    this.importLegacyQueue();
+    if (typeof navigator !== 'undefined' && 'onLine' in navigator) {
+      this.isReachable = navigator.onLine;
+    }
+    if (isBrowserPage()) {
+      this.listenToPage();
+    }
+  }
+
+  /** `true` when calls are being served from the offline cache rather than the hub. */
+  get isOffline(): boolean {
+    return this.offlineMode === 'always' || (this.offlineMode === 'auto' && !this.isReachable);
+  }
+
+  /** `true` while the hub is reachable. */
+  get isOnline(): boolean {
+    return this.isReachable;
+  }
+
+  /**
+   * The offline outbox: define your own kinds of operation, queue them, and
+   * hear how they replay (`hub.offline.define`, `enqueue`, `pending`, `on`).
+   */
+  get offline(): OfflineApi {
+    this.offlineApi ??= new OfflineApi({
+      outbox: this.outbox,
+      requestSync: () => {
+        if (!this.isOffline) {
+          void this.sync();
+        }
+      },
+    });
+    return this.offlineApi;
+  }
+
+  /** Queued operations plus buffered analytics events waiting to sync. */
+  pending(): number {
+    return this.outbox.count() + this.store.getEvents().length;
+  }
+
+  /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
+  onStatus(listener: (status: HubStatus) => void): () => void {
+    this.statusListeners.add(listener);
+    return () => {
+      this.statusListeners.delete(listener);
+    };
+  }
+
+  /** Tell `onStatus` listeners and the page (`hub:status`) the current status. */
+  protected notifyStatus(): void {
+    const status: HubStatus = { online: this.isReachable, offline: this.isOffline, pending: this.pending() };
+    for (const listener of this.statusListeners) {
+      try {
+        listener(status);
+      } catch {
+        // A listener's failure must not stop the others.
+      }
+    }
+    emitWindowEvent('hub:status', status);
+  }
+
+  /** Record reachability; coming back online replays the outbox and re-warms the cache. */
+  protected setReachable(isReachableNow: boolean): void {
+    if (isReachableNow === this.isReachable) {
+      return;
+    }
+    this.isReachable = isReachableNow;
+    emitWindowEvent(isReachableNow ? 'hub:online' : 'hub:offline', { pending: this.pending() });
+    this.notifyStatus();
+    if (isReachableNow) {
+      // Replay first, so the snapshot that re-warms the cache already has the queued changes.
+      void this.replayAll(true).then(() => this.prefetchAll()).catch(() => undefined);
+    }
+  }
+
+  /** `{ slug }` for this game's endpoints; throws when the slug is unknown. */
+  protected gameFields(): GameFields {
+    if (this.slug === null) {
+      throw new HubError('Hub: could not determine the game slug.');
+    }
+    return { slug: this.slug };
+  }
+
+  /**
+   * Run the network call, falling back to the offline answer when the hub
+   * can't be reached (per the offline mode). Real API errors (with an HTTP
+   * status) always reach the caller.
+   */
+  protected async withFallback<Reply>(networkCall: () => Promise<Reply>, offlineAnswer: () => Reply): Promise<Reply> {
+    if (this.isOffline) {
+      return offlineAnswer();
+    }
+    try {
+      return await networkCall();
+    } catch (failure) {
+      if (!isTransportFailure(failure) || this.offlineMode === 'never') {
+        throw failure;
+      }
+      this.setReachable(false);
+      return offlineAnswer();
+    }
+  }
+
+  /**
+   * Apply a write to the offline cache at once, then perform it as an op of
+   * `kind`: sent now when online with nothing waiting, else queued behind
+   * the others. Resolves with the local answer (or, sent now, with
+   * `replyAnswer`'s reading of the hub's reply). A real API error on the
+   * direct path reaches the caller and is not queued; a transport failure
+   * queues the op under the same id, so if the request did land, its replay
+   * is recognised by the hub and not applied twice.
+   */
+  protected async mutateOffline<Reply>(kind: string, payload: Json, localAnswer: () => Reply, replyAnswer?: (result: Json | undefined) => Reply | undefined): Promise<Reply> {
+    const answer = localAnswer();
+    const op = this.outbox.stamp(kind, payload);
+    if (this.isOffline || this.outbox.count() > 0 || this.runningSync !== null || this.directSend !== null) {
+      this.outbox.add(op);
+      if (!this.isOffline) {
+        void this.sync();
+      }
+      return answer;
+    }
+    const sending = this.outbox.runNow(op);
+    this.directSend = sending;
+    try {
+      const result = await sending;
+      return replyAnswer?.(result) ?? answer;
+    } catch (failure) {
+      if (!isTransportFailure(failure)) {
+        throw failure;
+      }
+      this.setReachable(false);
+      this.outbox.add({ ...op, attempts: 1 });
+      return answer;
+    } finally {
+      if (this.directSend === sending) {
+        this.directSend = null;
+      }
+    }
+  }
+
+  /**
+   * Replay the outbox, then the buffered events, in order. Stops at the
+   * first transport failure (offline again: the rest stays queued); an op
+   * the hub refuses is dropped and reported as a conflict.
+   */
+  sync(): Promise<SyncResult> {
+    return this.isOffline ? Promise.resolve(NOTHING_SYNCED) : this.replayAll(false);
+  }
+
+  /** A retry came due: try again even when the hub was last unreachable (the try is the probe), unless the browser itself is offline. */
+  private retrySync(): Promise<SyncResult> {
+    const isBrowserOffline = typeof navigator !== 'undefined' && 'onLine' in navigator && !navigator.onLine;
+    return this.offlineMode === 'always' || isBrowserOffline ? Promise.resolve(NOTHING_SYNCED) : this.replayAll(false);
+  }
+
+  /**
+   * One replay at a time per client. A call during one queues a single
+   * follow-up replay (eager if any caller asked for that), so an op queued
+   * or a reconnect that happens mid-replay is never missed.
+   */
+  private replayAll(isEager: boolean): Promise<SyncResult> {
+    if (this.slug === null || this.offlineMode === 'always') {
+      return Promise.resolve(NOTHING_SYNCED);
+    }
+    const running = this.runningSync;
+    if (running === null) {
+      return this.startReplay(isEager);
+    }
+    this.isFollowingEager ||= isEager;
+    this.followingSync ??= running.catch(() => NOTHING_SYNCED).then(() => {
+      const isFollowUpEager = this.isFollowingEager;
+      this.isFollowingEager = false;
+      this.followingSync = null;
+      return this.startReplay(isFollowUpEager);
+    });
+    return this.followingSync;
+  }
+
+  private startReplay(isEager: boolean): Promise<SyncResult> {
+    const run = this.runReplay(isEager).finally(() => {
+      if (this.runningSync === run) {
+        this.runningSync = null;
+      }
+    });
+    this.runningSync = run;
+    return run;
+  }
+
+  private async runReplay(isEager: boolean): Promise<SyncResult> {
+    if (this.directSend !== null) {
+      await this.directSend.catch(() => undefined);
+    }
+    const report = await this.outbox.replay(isEager);
+    const conflicts = report.failed.map((failure) => ({ op: failure.entry, error: failure.error }));
+    if (report.stoppedBy !== 'connection') {
+      await this.flushEvents();
+    }
+    const result: SyncResult = { flushed: report.replayed.length, conflicts };
+    emitWindowEvent('hub:sync', { pending: this.pending(), ...result });
+    this.notifyStatus();
+    return result;
+  }
+
+  /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
+  private async flushEvents(): Promise<void> {
+    let events = this.store.getEvents();
+    for (let event = events[0]; event !== undefined; event = events[0]) {
+      try {
+        await this.rest.call('recordGameEvent', { ...this.gameFields(), type: event.type });
+      } catch (failure) {
+        if (isTransportFailure(failure)) {
+          return;
+        }
+      }
+      events = events.slice(1);
+      this.store.setEvents(events);
+    }
+  }
+
+  /** Move a v1 copy's queued writes into the outbox, in their order. */
+  private importLegacyQueue(): void {
+    if (this.slug === null) {
+      return;
+    }
+    try {
+      for (const legacy of this.store.takeLegacyQueue()) {
+        const operation = legacyOperation(legacy);
+        if (operation !== undefined) {
+          this.outbox.add(this.outbox.stamp(operation.kind, operation.payload));
+        }
+      }
+    } catch {
+      // A full outbox keeps what fitted; the client must still start.
+    }
+  }
+
+  /** Follow the browser's connection, other tabs' outbox changes, and replay what an earlier page left queued. */
+  private listenToPage(): void {
+    window.addEventListener('online', () => {
+      this.setReachable(true);
+    });
+    window.addEventListener('offline', () => {
+      this.setReachable(false);
+    });
+    window.addEventListener('storage', (event) => {
+      if (event instanceof StorageEvent && this.outbox.entries.owns(event.key)) {
+        this.notifyStatus();
+      }
+    });
+    if (this.outbox.count() > 0) {
+      setTimeout(() => {
+        void this.sync();
+      }, 0);
+    }
+  }
+
+  /**
+   * Warm the offline cache for every game the player has touched, in one
+   * request, so going offline later still shows complete progress.
+   * Throttled to once per 30 s unless `isForced`; `null` when offline or throttled.
+   */
+  async prefetchAll(isForced = false): Promise<SnapshotResponse | null> {
+    if (this.isOffline || (!isForced && Date.now() - this.lastPrefetchAt < PREFETCH_INTERVAL_MS)) {
+      return null;
+    }
+    let snapshot: SnapshotResponse;
+    try {
+      snapshot = await this.rest.call('getMyOfflineSnapshot');
+    } catch (failure) {
+      if (isTransportFailure(failure)) {
+        return null;
+      }
+      throw failure;
+    }
+    this.lastPrefetchAt = Date.now();
+    if (this.outbox.count() > 0) {
+      // Changes are still waiting to sync: the cache already holds them, and the snapshot doesn't yet.
+      return snapshot;
+    }
+    this.store.hydrate(snapshot);
+    emitWindowEvent('hub:prefetch', { games: Object.keys(snapshot.games).length });
+    return snapshot;
+  }
+}