@diffenderfer-games/hub 2.0.0-next.3 → 2.0.0-next.5

package/src/core/offline/cloud-saves.ts

@@ -0,0 +1,62 @@
+/**
+ * What this device last saw of a game's save slots on the hub, per player:
+ * each slot's `updatedAt` there, or `null` for a slot known to be empty. It
+ * decides two things offline. `getSave` answers from the cache only when
+ * the device knows the hub's copy of that slot (so a fresh device or cleared
+ * browser never reports "no save" for a slot it simply hasn't seen), and a
+ * queued save write sends the hub's `updatedAt` it was built on, so the hub
+ * refuses it when the slot has changed since.
+ *
+ * A snapshot gives the full list (`complete`: any other slot is empty); a
+ * single read or write adds that slot to a partial list.
+ */
+import { isRecord, optionalNumber } from '../storage/json-guards';
+
+/** The hub's save slots for one game, as this device last saw them. */
+export interface CloudSaveIndex {
+  /** Whose slots these are. */
+  readonly userId: number;
+  /** `true` when every slot the hub had is listed (from a snapshot). */
+  readonly complete: boolean;
+  /** Each slot's `updatedAt` on the hub, or `null` when it was empty. */
+  readonly saves: Readonly<Record<string, number | null>>;
+}
+
+/** A stored index, or `null` when missing or malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an index read back from localStorage
+export function readCloudSaveIndex(stored: unknown): CloudSaveIndex | null {
+  if (!isRecord(stored) || typeof stored.complete !== 'boolean' || !isRecord(stored.saves)) {
+    return null;
+  }
+  const userId = optionalNumber(stored.userId);
+  if (userId === undefined) {
+    return null;
+  }
+  const saves: Record<string, number | null> = {};
+  for (const [slot, updatedAt] of Object.entries(stored.saves)) {
+    const known = updatedAt === null ? null : optionalNumber(updatedAt);
+    if (known === undefined) {
+      return null;
+    }
+    saves[slot] = known;
+  }
+  return { userId, complete: stored.complete, saves };
+}
+
+/**
+ * The hub's `updatedAt` for `slot` as `userId` last saw it: a number, `null`
+ * when the slot was empty, or `undefined` when this device doesn't know.
+ */
+export function cloudSaveOf(index: CloudSaveIndex | null, userId: number, slot: string): number | null | undefined {
+  if (index?.userId !== userId) {
+    return undefined;
+  }
+  const updatedAt = index.saves[slot];
+  return updatedAt === undefined && index.complete ? null : updatedAt;
+}
+
+/** `index` with `slot` seen at `updatedAt` (`null`: empty) by `userId`; another player's index starts over. */
+export function withCloudSave(index: CloudSaveIndex | null, userId: number, slot: string, updatedAt: number | null): CloudSaveIndex {
+  const base = index?.userId === userId ? index : { userId, complete: false, saves: {} };
+  return { ...base, saves: { ...base.saves, [slot]: updatedAt } };
+}

package/src/core/offline/hub-kinds/index.ts

@@ -2,17 +2,20 @@
  * Every kind the hub itself queues offline (`hub.*`), registered on a
  * client's outbox. The docs' "Offline and replay" table lists them.
  */
+import type { LocalResumeStore } from '../../resume/local-resume';
 import { writeLocalFavorites } from '../favorites';
 import type { Outbox } from '../outbox';
 import { dailyKinds, type DailyCompletion, type DailyPayload } from './daily-kind';
 import { economyKinds } from './economy-kinds';
 import type { GameFieldsSource } from './game-fields';
-import { progressKinds } from './progress-kinds';
+import { progressKinds, type CloudSaveTracker } from './progress-kinds';
+import { resumeKinds } from './resume-kind';
 
 export { DAILY_KIND, type DailyPayload } from './daily-kind';
 export { ECONOMY_KINDS, type ExchangePayload, type FavoritePayload } from './economy-kinds';
 export { legacyOperation } from './legacy-ops';
-export { PROGRESS_KINDS, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
+export { RESUME_KIND, type ResumePayload } from './resume-kind';
+export { PROGRESS_KINDS, type CloudSaveTracker, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
 
 /** What the hub kinds report back to their client. */
 export interface HubKindHooks {
@@ -20,14 +23,19 @@ export interface HubKindHooks {
   readonly game: GameFieldsSource;
   /** A daily completion landed (the menu's calendar listens for `hub:daily-complete`). */
   readonly onDailyComplete: (payload: DailyPayload, completion: DailyCompletion) => void;
+  /** The device copies of each game's resume slot (`hub.resume`). */
+  readonly resume: LocalResumeStore;
+  /** What this device last saw of the game's save slots on the hub. */
+  readonly cloudSaves: CloudSaveTracker;
 }
 
 /** Register every hub kind on `outbox`. */
 export function registerHubKinds(outbox: Outbox, hooks: HubKindHooks): void {
   const kinds = {
-    ...progressKinds(hooks.game),
+    ...progressKinds(hooks.game, hooks.cloudSaves),
     ...dailyKinds(hooks.game, hooks.onDailyComplete),
     ...economyKinds(hooks.game, writeLocalFavorites),
+    ...resumeKinds(hooks.game, hooks.resume),
   };
   for (const [kind, definition] of Object.entries(kinds)) {
     outbox.define(kind, definition);

package/src/core/offline/hub-kinds/progress-kinds.ts

@@ -12,6 +12,14 @@ import type { RegisteredKind } from '../outbox-kinds';
 import { betterScore } from '../queue';
 import type { GameFieldsSource } from './game-fields';
 
+/** What the save kind reads and records about the hub's copy of a slot (`LocalStore`). */
+export interface CloudSaveTracker {
+  /** The hub's `updatedAt` for `slot` as this device last saw it (`null`: empty), or `undefined` when it doesn't know. */
+  cloudSave(slot: string): number | null | undefined;
+  /** Note the hub's copy of `slot` after a write landed: its `updatedAt`, or `null` once deleted. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void;
+}
+
 /** A save slot write: new contents, or a delete. */
 export type SavePayload =
   | { readonly slot: string; readonly data: Json; readonly label: string | null }
@@ -109,8 +117,14 @@ export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPay
   }
 }
 
-/** The progress kinds, by name. */
-export function progressKinds(game: GameFieldsSource): Record<string, RegisteredKind> {
+/**
+ * The progress kinds, by name. A save write replayed from the queue sends
+ * the hub's `updatedAt` this device last saw for the slot (`null` when it
+ * saw it empty or never saw it), so the hub refuses it (409 `save_conflict`,
+ * dropped and reported as a conflict) when another device saved since. A
+ * write sent at once, online, always lands, as before.
+ */
+export function progressKinds(game: GameFieldsSource, cloudSaves: CloudSaveTracker): Record<string, RegisteredKind> {
   return {
     [PROGRESS_KINDS.save]: checkedKind(readSave, {
       mergeKey: (save) => save.slot,
@@ -118,9 +132,12 @@ export function progressKinds(game: GameFieldsSource): Record<string, Registered
       run: async (save, context) => {
         if ('deleted' in save) {
           await context.call('deleteSave', { ...game(), slot: save.slot });
-        } else {
-          await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label });
+          cloudSaves.rememberCloudSave(save.slot, null);
+          return;
         }
+        const base = context.isReplay ? { base: cloudSaves.cloudSave(save.slot) ?? null } : {};
+        const written = await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label, ...base });
+        cloudSaves.rememberCloudSave(save.slot, written.updatedAt);
       },
     }),
     [PROGRESS_KINDS.stat]: checkedKind(readStat, {

package/src/core/offline/hub-kinds/resume-kind.ts

@@ -0,0 +1,108 @@
+/**
+ * The hub's resume kind (`hub.resume`): send a game's saved run, or clear it.
+ * One slot per game, so a new op replaces any waiting one (a clear after a
+ * save drops the save, and the other way round).
+ *
+ * A save op carries only the run's facts and time: when it runs it sends
+ * the newest run in the device copy (`LocalResumeStore`), which keeps the
+ * outbox small. When the device copy couldn't be stored, the op carries the
+ * state itself. A session that lapsed (401) gets a guest session and tries
+ * once more, so a player's very first save can't be lost to it.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalResumeStore } from '../../resume/local-resume';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** The kind name. */
+export const RESUME_KIND = 'hub.resume';
+
+/** Send the run saved at `savedAt`; `state` only when the device copy couldn't hold it. */
+export type ResumeSavePayload = {
+  readonly action: 'save';
+  readonly savedAt: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  readonly state?: Json;
+};
+
+/** Clear the run, unless one was saved after `before`. */
+export type ResumeClearPayload = { readonly action: 'clear'; readonly before: number };
+
+/** One resume op. */
+export type ResumePayload = ResumeSavePayload | ResumeClearPayload;
+
+function readResume(stored: Json): ResumePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  if (stored.action === 'clear') {
+    const before = optionalNumber(stored.before);
+    return before === undefined ? undefined : { action: 'clear', before };
+  }
+  const savedAt = optionalNumber(stored.savedAt);
+  const label = optionalString(stored.label);
+  const version = optionalNumber(stored.version);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  if (stored.action !== 'save' || savedAt === undefined || label === undefined || version === undefined || fraction === undefined
+    || !isNullableString(stored.title) || (stored.state !== undefined && !isJson(stored.state))) {
+    return undefined;
+  }
+  const base = { action: 'save', savedAt, label, fraction, title: stored.title, version } as const;
+  return stored.state === undefined ? base : { ...base, state: stored.state };
+}
+
+/** The run to send: the device copy when it is at least as new as the op, else the op's own state; `undefined` when there is none. */
+function runToSend(save: ResumeSavePayload, local: LocalResumeStore, slug: string): ResumeSavePayload | undefined {
+  const copy = local.read(slug);
+  if (copy?.status === 'saved' && copy.at >= save.savedAt) {
+    return { action: 'save', savedAt: copy.at, label: copy.label, fraction: copy.fraction, title: copy.title, version: copy.version, state: copy.state };
+  }
+  return save.state === undefined ? undefined : save;
+}
+
+/** Run `call`; on a lapsed session (401) start a guest session and run it once more. */
+async function withSession<Reply>(context: ReplayContext, call: () => Promise<Reply>): Promise<Reply> {
+  try {
+    return await call();
+  } catch (failure) {
+    if (!(failure instanceof HubError) || failure.status !== 401) {
+      throw failure;
+    }
+    await context.call('ensureGuestSession');
+    return call();
+  }
+}
+
+/** The resume kind, by name, over the device copies in `local`. */
+export function resumeKinds(game: GameFieldsSource, local: LocalResumeStore): Record<string, RegisteredKind> {
+  return {
+    [RESUME_KIND]: checkedKind(readResume, {
+      mergeKey: () => 'resume',
+      replaces: true,
+      run: async (op, context) => {
+        const { slug } = game();
+        if (op.action === 'clear') {
+          await withSession(context, () => context.call('clearResumeSlot', { slug, before: op.before }));
+          local.markSynced(slug, op.before);
+          return undefined;
+        }
+        const run = runToSend(op, local, slug);
+        if (run?.state === undefined) {
+          return undefined;
+        }
+        const { state } = run;
+        await withSession(context, () => context.call('saveResumeSlot', {
+          slug, state, progress: { label: run.label, fraction: run.fraction }, title: run.title, version: run.version, savedAt: run.savedAt,
+        }));
+        local.markSynced(slug, run.savedAt);
+        return undefined;
+      },
+    }),
+  };
+}

package/src/core/offline/local-store.ts

@@ -10,6 +10,7 @@ import type { Board, Inventory, Json, SortDir, Stats } from '@diffenderfer-games
 import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
 import { createPageStore, type KeyValueStore } from '../storage/key-value';
 import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
+import { cloudSaveOf, readCloudSaveIndex, withCloudSave, type CloudSaveIndex } from './cloud-saves';
 import { appendEvent, readEvents, type BufferedEvent } from './events';
 import { EMPTY_INVENTORY, readInventory } from './local-inventory';
 import { betterScore, readQueue, type QueueOp, type QueuedScoreOptions } from './queue';
@@ -159,6 +160,37 @@ export class LocalStore {
     this.store.remove(`${this.prefix}save:${slot}`);
   }
 
+  /**
+   * The hub's `updatedAt` for `slot` as the current user last saw it (`null`:
+   * the slot was empty), or `undefined` when this device doesn't know.
+   */
+  cloudSave(slot: string): number | null | undefined {
+    const user = this.getUser();
+    return user === null ? undefined : cloudSaveOf(this.readCloudSaves(this.prefix), user.id, slot);
+  }
+
+  /** Note the hub's copy of `slot` (just read or written) for the current user: its `updatedAt`, or `null` when empty. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void {
+    const user = this.getUser();
+    if (user !== null) {
+      this.writeStored(`${this.prefix}cloud-saves`, withCloudSave(this.readCloudSaves(this.prefix), user.id, slot, updatedAt));
+    }
+  }
+
+  /** Cache a slot as read from the hub (forgetting it when the hub has none), and note the hub's copy. */
+  cacheCloudSave(slot: string, save: Save | null): void {
+    if (save === null) {
+      this.deleteSave(slot);
+    } else {
+      this.writeStored(`${this.prefix}save:${slot}`, save);
+    }
+    this.rememberCloudSave(slot, save?.updatedAt ?? null);
+  }
+
+  private readCloudSaves(gamePrefix: string): CloudSaveIndex | null {
+    return readCloudSaveIndex(this.readStored(`${gamePrefix}cloud-saves`));
+  }
+
   /** This game's cached stats. */
   getStats(): Stats {
     const stored = this.readStored(`${this.prefix}stats`);
@@ -232,11 +264,20 @@ export class LocalStore {
     this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
   }
 
-  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  /**
+   * Fan a `/me/snapshot` reply out across every game's cache keys. It lists
+   * every save slot of every game the player has played, so each game's
+   * slots on the hub become known (and this game's are all empty when it
+   * isn't listed).
+   */
   hydrate(snapshot: SnapshotResponse): void {
     if (snapshot.user !== null) {
       this.writeStored(USER_KEY, snapshot.user);
     }
+    const userId = snapshot.user?.id;
+    if (userId !== undefined && !Object.keys(snapshot.games).some((slug) => `hub:${slug}:` === this.prefix)) {
+      this.writeStored(`${this.prefix}cloud-saves`, { userId, complete: true, saves: {} } satisfies CloudSaveIndex);
+    }
     for (const [slug, game] of Object.entries(snapshot.games)) {
       const gamePrefix = `hub:${slug}:`;
       if (game.profile !== null) {
@@ -245,6 +286,10 @@ export class LocalStore {
       for (const save of game.saves) {
         this.writeStored(`${gamePrefix}save:${save.slot}`, save);
       }
+      if (userId !== undefined) {
+        const saves = Object.fromEntries(game.saves.map((save) => [save.slot, save.updatedAt]));
+        this.writeStored(`${gamePrefix}cloud-saves`, { userId, complete: true, saves } satisfies CloudSaveIndex);
+      }
       this.writeStored(`${gamePrefix}stats`, game.stats);
       this.writeStored(`${gamePrefix}inventory`, game.inventory);
     }

package/src/core/page.ts

@@ -37,6 +37,16 @@ export function injectedConfig(): InjectedConfig {
   return { ...(slug === undefined ? {} : { slug }), ...(apiBase === undefined ? {} : { apiBase }) };
 }
 
+/** The game's display title: the host's injected one, else the page's `<title>`, else `fallback`. */
+export function detectGameTitle(fallback: string): string {
+  const injected = isBrowserPage() && isRecord(window.__HUB__) ? optionalString(window.__HUB__.title) : undefined;
+  if (injected !== undefined && injected !== '') {
+    return injected;
+  }
+  const pageTitle = typeof document === 'undefined' ? '' : document.title.trim();
+  return pageTitle === '' ? fallback : pageTitle;
+}
+
 /** The game's slug: the injected one, else the first URL path segment, else `null`. */
 export function detectSlug(): string | null {
   const injectedSlug = injectedConfig().slug;

package/src/core/rest/routes.gen.ts

@@ -105,6 +105,10 @@ export const ROUTES = {
   launchTournamentMatch: { method: 'POST', path: '/tournaments/:id/matches/:match/launch', query: [], offline: null },
   getPlayOnline: { method: 'GET', path: '/play-online', query: [], offline: null },
   getHubVersion: { method: 'GET', path: '/version', query: [], offline: null },
+  getResumeSlot: { method: 'GET', path: '/games/:slug/resume', query: [], offline: null },
+  saveResumeSlot: { method: 'PUT', path: '/games/:slug/resume', query: [], offline: 'replay' },
+  clearResumeSlot: { method: 'DELETE', path: '/games/:slug/resume', query: ['before'], offline: 'replay' },
+  listMyResumeSlots: { method: 'GET', path: '/me/resume', query: [], offline: null },
 } as const;
 
 /** The request header that carries an offline operation key (the contract's `OFFLINE_OP_HEADER`). */

package/src/core/resume/hub-resume.ts

@@ -0,0 +1,252 @@
+/**
+ * `hub.resume`: auto-save a long single-player run so the player can pick it
+ * up again from the home page's Resume card, on any device. One slot per
+ * player per game; the latest save wins.
+ *
+ * - `save(run)` stores the run on the device at once and sends it to the hub
+ *   after a short quiet spell (debounced), straight away when the page is
+ *   hidden or closed, and through the offline outbox (`hub.resume`), so it
+ *   works offline and lands once.
+ * - `clear()` when the run ends (won, lost or quit).
+ * - `load()` / `get()` read it back; `requested` says the page was opened to
+ *   resume, so the game restores without asking.
+ *
+ * Saves are ignored while the page is in a race, a daily challenge or an
+ * online room: those runs are never resumed.
+ */
+import type { ResumeSlot, ResumeSummary } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../errors';
+import { toGameData, toStoredJson, type GamePayload } from '../game-data';
+import type { ResumePayload } from '../offline/hub-kinds';
+import { isBrowserPage } from '../page';
+import type { LocalResumeStore, LocalRun } from './local-resume';
+import { mergeResumeLists } from './resume-list';
+import { isResumeRequested } from './resume-request';
+import type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeRun, ResumeSaveInput } from './resume-types';
+
+/** How long saves must be quiet before the latest is sent, ms. */
+export const RESUME_DEBOUNCE_MS = 3000;
+
+/** Largest state, bytes of JSON (the contract's `RESUME_MAX_STATE_BYTES`). */
+export const RESUME_MAX_STATE_BYTES = 512 * 1024;
+
+/** What a game should do when a save is ignored, by blocker (logged once per page). */
+const BLOCKED_HINTS: Readonly<Record<ResumeBlocker, string>> = {
+  daily: 'a daily challenge is active. When the player leaves a daily without finishing it, call hub.daily.cancel().',
+  race: 'a race is on: races are never resumed.',
+  room: 'the page is in a hub room: online games are never resumed.',
+};
+
+/** Longest label or title kept (the contract's `RESUME_TEXT_MAX`). */
+const TEXT_MAX = 60;
+
+/** What `hub.resume` needs from its client. */
+export interface ResumeHost {
+  /** This game's slug; `null` on the home page. */
+  readonly slug: string | null;
+  readonly local: LocalResumeStore;
+  /** The signed-in player's id as the device knows it, or `null`. */
+  currentUserId(): number | null;
+  /** The game's display title. */
+  gameTitle(): string;
+  /** Why saving is off right now, or `null`. */
+  blocker(): ResumeBlocker | null;
+  /** Perform a resume op: at once when online with nothing waiting, else queued. */
+  send(payload: ResumePayload): Promise<void>;
+  /** This game's run on the hub, or `undefined` when the hub can't be reached. */
+  fetchSlot(): Promise<ResumeSlot | null | undefined>;
+  /** The player's runs on the hub, or `undefined` when it can't be reached. */
+  fetchList(): Promise<ResumeSummary[] | undefined>;
+  /** Clear another game's run on the hub (the home page's discard); throws offline. */
+  clearOther(slug: string): Promise<void>;
+}
+
+/** A label or title trimmed and clipped, or `null` when blank. */
+function shortText(text: string | null | undefined): string | null {
+  const trimmed = (text ?? '').trim();
+  return trimmed === '' ? null : trimmed.slice(0, TEXT_MAX);
+}
+
+/** The UTF-8 size of `text`. */
+function byteSize(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+/** The device copy as a run read back. */
+function runFromCopy<TState>(copy: LocalRun): ResumeRun<TState> {
+  return { state: toGameData<TState>(copy.state), progress: { label: copy.label, fraction: copy.fraction }, title: copy.title, version: copy.version, savedAt: copy.at };
+}
+
+/** The hub's slot as a run read back. */
+function runFromSlot<TState>(slot: ResumeSlot): ResumeRun<TState> {
+  return { state: toGameData<TState>(slot.state), progress: slot.progress, title: slot.title, version: slot.version, savedAt: slot.updatedAt };
+}
+
+/** `hub.resume`. */
+export class HubResume {
+  private readonly host: ResumeHost;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private waiting: ResumePayload | null = null;
+  private isListening = false;
+  private readonly warnedBlockers = new Set<ResumeBlocker>();
+
+  constructor(host: ResumeHost) {
+    this.host = host;
+  }
+
+  /**
+   * `true` when the page was opened from the Resume card (`?hub_resume=1`,
+   * taken out of the address bar). Synchronous, so a game can restore before
+   * it routes or draws its title screen.
+   */
+  get requested(): boolean {
+    return isResumeRequested();
+  }
+
+  /** Why a save would be ignored right now (`race`, `daily`, `room`), or `null`. */
+  get blockedBy(): ResumeBlocker | null {
+    return this.host.blocker();
+  }
+
+  /**
+   * Save the run (the latest save wins). Stored on the device at once; sent
+   * after {@link RESUME_DEBOUNCE_MS} of quiet, or when the page is hidden.
+   * Returns `false` (and saves nothing) in a race, a daily challenge or an
+   * online room. Throws a `HubError` 413 over 512 KB, 400 without a label.
+   */
+  save<TState extends GamePayload>(run: ResumeSaveInput<TState>): boolean {
+    const blocker = this.host.blocker();
+    if (blocker !== null) {
+      this.warnBlocked(blocker);
+      return false;
+    }
+    const slug = this.requireSlug();
+    const label = shortText(run.progress.label);
+    if (label === null) {
+      throw new HubError('hub.resume.save: progress.label is required.', 400);
+    }
+    const state = toStoredJson(run.state);
+    if (byteSize(JSON.stringify(state)) > RESUME_MAX_STATE_BYTES) {
+      throw new HubError(`hub.resume.save: state exceeds ${String(RESUME_MAX_STATE_BYTES)} bytes.`, 413);
+    }
+    const fraction = typeof run.progress.fraction === 'number' && Number.isFinite(run.progress.fraction) ? Math.min(1, Math.max(0, run.progress.fraction)) : null;
+    const copy: LocalRun = {
+      status: 'saved', userId: this.host.currentUserId(), at: Date.now(), label, fraction, title: shortText(run.title),
+      version: Math.max(0, Math.floor(run.version ?? 0)), gameTitle: this.host.gameTitle(), state, isSynced: false,
+    };
+    const isStored = this.host.local.write(slug, copy);
+    this.schedule({
+      action: 'save', savedAt: copy.at, label, fraction, title: copy.title, version: copy.version,
+      ...(isStored ? {} : { state }),
+    });
+    return true;
+  }
+
+  /** Send a waiting save now (the page does this itself when hidden or closed). */
+  async flush(): Promise<void> {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const payload = this.waiting;
+    this.waiting = null;
+    if (payload !== null) {
+      await this.host.send(payload);
+    }
+  }
+
+  /** Clear the run: call it when the run ends (won, lost or quit). Works offline. */
+  async clear(): Promise<void> {
+    const slug = this.requireSlug();
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.waiting = null;
+    const at = Date.now();
+    this.host.local.write(slug, { status: 'cleared', userId: this.host.currentUserId(), at, isSynced: false });
+    await this.host.send({ action: 'clear', before: at });
+  }
+
+  /** The saved run with its progress and time, or `null`. The newer of the device's copy and the hub's wins. */
+  async get<TState = GamePayload>(options: ResumeLoadOptions = {}): Promise<ResumeRun<TState> | null> {
+    const slug = this.requireSlug();
+    const copy = this.host.local.read(slug);
+    const mine = copy !== null && copy.userId === this.host.currentUserId() ? copy : null;
+    const slot = await this.host.fetchSlot();
+    let run: ResumeRun<TState> | null;
+    if (slot !== undefined && slot !== null && (mine === null || slot.updatedAt >= mine.at)) {
+      run = runFromSlot<TState>(slot);
+    } else {
+      // The device's run, unless the hub was asked, has none, and already had this one (it was cleared elsewhere).
+      const isClearedElsewhere = slot === null && mine?.isSynced === true;
+      run = mine?.status === 'saved' && !isClearedElsewhere ? runFromCopy<TState>(mine) : null;
+    }
+    if (run === null || options.version === undefined || run.version === options.version) {
+      return run;
+    }
+    if (run.version < options.version) {
+      await this.clear();
+    }
+    return null;
+  }
+
+  /** The saved state, or `null` (see {@link get} for the version rule). */
+  async load<TState = GamePayload>(options: ResumeLoadOptions = {}): Promise<TState | null> {
+    return (await this.get<TState>(options))?.state ?? null;
+  }
+
+  /** The player's saved runs in every resumable game, newest first (the home page's Resume card). */
+  async list(): Promise<ResumeEntry[]> {
+    return mergeResumeLists(await this.host.fetchList(), this.host.local.all(), this.host.currentUserId());
+  }
+
+  /** Discard another game's run from the home page (online only: throws a `HubError` offline). */
+  async discard(slug: string): Promise<void> {
+    await this.host.clearOther(slug);
+    this.host.local.remove(slug);
+  }
+
+  /** Say once per blocker why saves are ignored, so a game that forgot `hub.daily.cancel()` finds out. */
+  private warnBlocked(blocker: ResumeBlocker): void {
+    if (this.warnedBlockers.has(blocker)) {
+      return;
+    }
+    this.warnedBlockers.add(blocker);
+    // eslint-disable-next-line no-console -- a one-time hint to the game developer, with the fix
+    console.warn(`[hub] hub.resume.save ignored: ${BLOCKED_HINTS[blocker]}`);
+  }
+
+  private requireSlug(): string {
+    if (this.host.slug === null) {
+      throw new HubError('hub.resume: could not determine the game slug.');
+    }
+    return this.host.slug;
+  }
+
+  private schedule(payload: ResumePayload): void {
+    this.waiting = payload;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => { void this.flush().catch(() => undefined); }, RESUME_DEBOUNCE_MS);
+    this.listenToPage();
+  }
+
+  /** Send a waiting save as soon as the page is hidden or closed. */
+  private listenToPage(): void {
+    if (this.isListening || !isBrowserPage()) {
+      return;
+    }
+    this.isListening = true;
+    const flushNow = (): void => { void this.flush().catch(() => undefined); };
+    window.addEventListener('pagehide', flushNow);
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          flushNow();
+        }
+      });
+    }
+  }
+}