@diffenderfer-games/hub 2.0.0-next.4 → 2.0.0-next.6

package/src/core/hub.ts

@@ -10,16 +10,23 @@ import { getInput, getUiStack, type InputSystem } from '../input';
 import { mp } from '../mp';
 import { race } from '../race';
 import { rooms } from '../rooms';
+import { pageBridge } from '../realtime/bridge';
 import { isInHubRoom } from '../realtime/rooms-forwarder';
 import { linkRealtimeToHub, notify, presence, social } from '../social';
+import { HubAvatar } from './avatar/hub-avatar';
 import { HubError, OfflineError, toHubError } from './errors';
 import { HubEconomy } from './hub-economy';
-import { DAILY_KIND, RESUME_KIND } from './offline/hub-kinds';
+import { AVATAR_KIND, DAILY_KIND, RESUME_KIND, SAVED_KIND } from './offline/hub-kinds';
 import { readDailyCompletion } from './offline/hub-kinds/daily-kind';
 import { hubMenu, type HubMenuControl } from './menu-control';
 import { detectGameTitle, emitWindowEvent } from './page';
 import { HubResume, type ResumeHost } from './resume/hub-resume';
 import { isResumeRequested } from './resume/resume-request';
+import { DailySaves } from './saved/daily-saves';
+import { HubSaved, type SavedHost } from './saved/hub-saved';
+import { HubTurns, type TurnsHost } from './turns/hub-turns';
+import { savedOpenedOnPage } from './saved/saved-open';
+import type { SavedEntry } from './saved/saved-types';
 import { fetchGameServerTicket } from './ticket';
 import { clientSupport, readHubVersion, type ClientSupport } from './version/hub-version';
 import { HUB_CLIENT_VERSION } from './version/client-version.gen';
@@ -31,6 +38,12 @@ export class Hub extends HubEconomy {
   readonly clientVersion: string = HUB_CLIENT_VERSION;
 
   private resumeApi: HubResume | undefined;
+  private avatarApi: HubAvatar | undefined;
+  private savedApi: HubSaved | undefined;
+  private dailySavesApi: DailySaves | undefined;
+  private turnsApi: HubTurns | undefined;
+  /** The online games open on this page (a run isn't saved while one is). */
+  private readonly openTurnGames = new Set<object>();
 
   /**
    * The hub's version and the client versions it supports (`GET /_api/version`),
@@ -118,6 +131,110 @@ export class Hub extends HubEconomy {
     return this.resumeApi;
   }
 
+  /**
+   * Players' avatars: `hub.avatar.mine()`, `of(userId)`, `from(seat)`,
+   * `bot(seed)`, `on('change')`, `openDesigner()` and `load()` for the renderer
+   * (docs: "Avatars"). No art or renderer until `load()`.
+   */
+  get avatar(): HubAvatar {
+    this.avatarApi ??= new HubAvatar({
+      currentUserId: () => this.userId(),
+      onAccount: (listener) => this.account.on(listener),
+      fetchMine: () => this.rest.call('getMyAvatar'),
+      fetchCodes: async (ids) => (await this.rest.call('getAvatars', { ids: [...ids] })).codes,
+      queueSave: async (code, savedAt) => {
+        await this.mutateOffline(AVATAR_KIND, { code, savedAt }, () => undefined);
+      },
+    });
+    return this.avatarApi;
+  }
+
+  /**
+   * Every game the player has in progress, of every kind: `hub.saved.list()`
+   * for this game's "Continue" list, `opened` and `onOpen` to open the one
+   * the player picked (docs: "Saved games").
+   */
+  get saved(): HubSaved {
+    this.savedApi ??= new HubSaved(this.savedHost());
+    return this.savedApi;
+  }
+
+  /**
+   * Online games played over minutes or days, run by the hub from the
+   * game's rules module (`game.turns`): `hub.turns.create`, `join`, `open`
+   * (docs/multiplayer.md "Turn games").
+   */
+  get turns(): HubTurns {
+    this.turnsApi ??= new HubTurns(this.turnsHost());
+    return this.turnsApi;
+  }
+
+  /** What `hub.turns` needs from this client: its REST calls. */
+  private turnsHost(): TurnsHost {
+    const { rest } = this;
+    return {
+      slug: this.slug,
+      create: (body) => rest.call('createTurnGame', body),
+      join: (id) => rest.call('joinTurnGame', { id }),
+      joinByLink: (key) => rest.call('joinTurnGameByLink', { key }),
+      get: (id) => rest.call('getTurnGame', { id }),
+      start: (id) => rest.call('startTurnGame', { id }),
+      move: (id, seq, move) => rest.call('moveTurnGame', { id, seq, move }),
+      history: async (id, since) => (await rest.call('getTurnGameHistory', { id, since })).moves,
+      leave: async (id) => { await rest.call('leaveTurnGame', { id }); },
+      nudge: async (id) => { await rest.call('nudgeTurnGame', { id }); },
+      setNotify: async (id, mode) => { await rest.call('setTurnGameNotify', { id, mode }); },
+      rematch: (id) => rest.call('rematchTurnGame', { id }),
+      invite: (id, userIds) => rest.call('inviteToTurnGame', { id, userIds: [...userIds] }),
+      share: (id, share) => rest.call('shareTurnGame', { id, ...share }),
+      autoPlay: (id) => rest.call('autoPlayTurn', { id }),
+      chat: (id, send) => rest.call('chatInTurnGame', { id, ...send }),
+      listOpen: async (game) => (await rest.call('listOpenTurnGames', game === null ? {} : { game })).games,
+      list: () => this.saved.list({ kinds: ['turns'] }),
+      opened: (game) => { this.openTurnGames.add(game); },
+      closed: (game) => { this.openTurnGames.delete(game); },
+      isLive: () => pageBridge.current() !== null,
+    };
+  }
+
+  /** What `hub.saved` needs from this client. */
+  private savedHost(): SavedHost {
+    return {
+      slug: this.slug,
+      fetchList: (game) => this.withFallback<readonly SavedEntry[] | undefined>(
+        async () => (await this.rest.call('listMySavedGames', game === null ? {} : { game })).games,
+        () => undefined,
+      ),
+      deviceCopies: () => {
+        const userId = this.store.getUser()?.id ?? null;
+        return {
+          runs: new Map([...this.resumeStore.all()].filter(([, copy]) => copy.userId === userId)),
+          dailies: this.dailyStore.all(userId),
+        };
+      },
+      discard: (entry) => this.discardSaved(entry),
+      navigate: (url) => {
+        location.assign(url);
+      },
+    };
+  }
+
+  /** Discard a daily or run: this game's run through `hub.resume` (works offline), others on the hub. */
+  private async discardSaved(entry: SavedEntry): Promise<void> {
+    if (entry.kind === 'run' && entry.game === this.slug) {
+      await this.resume.clear();
+      return;
+    }
+    if (!entry.id.startsWith('local:')) {
+      await this.rest.call('discardSavedGame', { id: entry.id });
+    }
+    if (entry.kind === 'run') {
+      this.resumeStore.remove(entry.game);
+    } else if (entry.daily !== undefined) {
+      this.dailyStore.remove(entry.game, entry.daily.day);
+    }
+  }
+
   /** What `hub.resume` needs from this client. */
   private resumeHost(): ResumeHost {
     return {
@@ -129,7 +246,14 @@ export class Hub extends HubEconomy {
         if (race.current() !== null) {
           return 'race';
         }
-        return this.daily.active === null ? (isInHubRoom() ? 'room' : null) : 'daily';
+        if (this.openTurnGames.size > 0) {
+          return 'turns';
+        }
+        return isInHubRoom() ? 'room' : null;
+      },
+      daily: () => {
+        const daily = this.daily;
+        return daily.active === null ? null : daily;
       },
       send: async (payload) => {
         await this.mutateOffline(RESUME_KIND, payload, () => undefined);
@@ -148,17 +272,59 @@ export class Hub extends HubEconomy {
       clearOther: async (slug) => {
         await this.rest.call('clearResumeSlot', { slug });
       },
+      onChange: () => {
+        this.savedApi?.changed();
+      },
     };
   }
 
-  /** What the daily system needs from this client: its REST calls and window events. */
+  /** This game's daily saves (device copies and their sends). */
+  private dailySaves(): DailySaves {
+    const slug = this.slug;
+    if (slug === null) {
+      throw new HubError('hub.daily: could not determine the game slug.');
+    }
+    this.dailySavesApi ??= new DailySaves({
+      slug,
+      local: this.dailyStore,
+      currentUserId: () => this.store.getUser()?.id ?? null,
+      gameTitle: () => detectGameTitle(slug),
+      send: async (payload) => {
+        await this.mutateOffline(SAVED_KIND, payload, () => undefined);
+        this.savedApi?.changed();
+      },
+    });
+    return this.dailySavesApi;
+  }
+
+  /** What the daily system needs from this client: its REST calls, the device copies and window events. */
   private dailyHost(): DailyHost {
     return {
       slug: this.slug,
       status: () => this.rest.call('getGameDailyChallenges', this.gameFields()),
       all: () => this.rest.call('listDailyChallengesForAllGames'),
-      start: (day) => this.rest.call('startDailyChallenge', { ...this.gameFields(), day }),
-      complete: (day, token, meta) => this.mutateOffline<DailyCompleteResponse | null>(DAILY_KIND, { day, token, meta }, () => null, (result) => readDailyCompletion(result)),
+      start: (day) => this.withFallback(
+        async () => this.dailySaves().remember(await this.rest.call('startDailyChallenge', { ...this.gameFields(), day })),
+        () => this.dailySaves().startLocally(day),
+      ),
+      resume: async (instanceId) => this.dailySaves().remember(await this.rest.call('resumeDailyChallenge', { id: instanceId })),
+      complete: async (day, token, meta) => {
+        this.dailySaves().finished(day);
+        const completed = await this.mutateOffline<DailyCompleteResponse | null>(DAILY_KIND, { day, token, meta }, () => null, (result) => readDailyCompletion(result));
+        if (completed !== null) {
+          this.dailySaves().completed(day);
+        }
+        this.savedApi?.changed();
+        return completed;
+      },
+      save: (challenge, input) => {
+        const isSaved = this.dailySaves().save(challenge, input);
+        this.savedApi?.changed();
+        return isSaved;
+      },
+      flush: () => this.dailySaves().flush(),
+      discard: (challenge) => this.dailySaves().discard(challenge),
+      inProgress: () => this.saved.list({ kinds: ['daily'] }),
       emit: (eventName, detail) => {
         emitWindowEvent(eventName, detail);
       },
@@ -175,8 +341,10 @@ linkRealtimeToHub({
 /** A ready-to-use client, with the slug and API base detected from the page. */
 export const hub: Hub = new Hub();
 
-// Take `?hub_resume` out of the address bar before the game's router sees it (the answer stays on `hub.resume.requested`).
+// Take `?hub_resume`, `?hub_open` and `?hub_kind` out of the address bar before the game's router sees them
+// (the answers stay on `hub.resume.requested` and `hub.saved.opened`).
 isResumeRequested();
+savedOpenedOnPage();
 
 /** Create a client for another slug or API base, or with other offline behaviour. */
 export function createHub(options: HubOptions = {}): Hub {

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/avatar-kind.ts

@@ -0,0 +1,42 @@
+/**
+ * The hub's avatar kind (`hub.avatar`, avatars.md §5.6): save your look.
+ * Latest wins: a newer save replaces a waiting one, and the hub keeps the
+ * newer of the replayed save and one another device made since (`savedAt`).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { decodeLook } from '@diffenderfer-games/hub-contract/avatar';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+
+/** The kind name. */
+export const AVATAR_KIND = 'hub.avatar';
+
+/** Save this look (its code) as of `savedAt`. */
+export type AvatarPayload = { readonly code: string; readonly savedAt: number };
+
+function readAvatar(stored: Json): AvatarPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const code = optionalString(stored.code);
+  const savedAt = optionalNumber(stored.savedAt);
+  return code === undefined || savedAt === undefined ? undefined : { code, savedAt };
+}
+
+/** The avatar kind, by name. */
+export function avatarKinds(): Record<string, RegisteredKind> {
+  return {
+    [AVATAR_KIND]: checkedKind(readAvatar, {
+      mergeKey: () => 'avatar',
+      replaces: true,
+      run: async (op, context) => {
+        const look = decodeLook(op.code)?.look;
+        if (look !== undefined) {
+          await context.call('saveMyAvatar', { look: { ...look, accessories: [...look.accessories] }, savedAt: op.savedAt });
+        }
+        return undefined;
+      },
+    }),
+  };
+}

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

@@ -3,19 +3,24 @@
  * client's outbox. The docs' "Offline and replay" table lists them.
  */
 import type { LocalResumeStore } from '../../resume/local-resume';
+import type { LocalDailyStore } from '../../saved/local-saved';
 import { writeLocalFavorites } from '../favorites';
 import type { Outbox } from '../outbox';
+import { avatarKinds } from './avatar-kind';
 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';
+import { savedKinds } from './saved-kind';
 
+export { AVATAR_KIND, type AvatarPayload } from './avatar-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 { RESUME_KIND, type ResumePayload } from './resume-kind';
-export { PROGRESS_KINDS, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
+export { SAVED_KIND, type SavedPayload } from './saved-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 {
@@ -25,15 +30,21 @@ export interface HubKindHooks {
   readonly onDailyComplete: (payload: DailyPayload, completion: DailyCompletion) => void;
   /** The device copies of each game's resume slot (`hub.resume`). */
   readonly resume: LocalResumeStore;
+  /** The device copies of daily challenges in progress (`hub.saved`). */
+  readonly dailies: LocalDailyStore;
+  /** 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),
+    ...avatarKinds(),
+    ...savedKinds(hooks.dailies),
   };
   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/saved-kind.ts

@@ -0,0 +1,93 @@
+/**
+ * The hub's saved-games kind (`hub.saved`): send a daily challenge's state,
+ * or discard the day, from the device copy (`LocalDailyStore`). One op per
+ * (game, day): a newer one replaces a waiting one, so a discard after a
+ * save drops the save. The op carries only which day and when; when it runs
+ * it sends the newest state the device holds, so the outbox stays small.
+ *
+ * A day started offline has a device-only id (`local:<slug>:<day>`): the op
+ * first starts the day on the hub, which finds or makes its saved game (one
+ * per player, game and day), then saves to that. A save or discard that
+ * finds the day already finished or discarded elsewhere (409, 404) is done:
+ * the device copy is dropped.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalDaily, LocalDailyStore } from '../../saved/local-saved';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+
+/** The kind name. */
+export const SAVED_KIND = 'hub.saved';
+
+/** Send (`save`) or discard a day's saved game; `at` is when the device copy changed. */
+export type SavedPayload = { readonly action: 'save' | 'discard'; readonly game: string; readonly day: string; readonly at: number };
+
+function readSaved(stored: Json): SavedPayload | undefined {
+  if (!isRecord(stored) || (stored.action !== 'save' && stored.action !== 'discard')) {
+    return undefined;
+  }
+  const game = optionalString(stored.game);
+  const day = optionalString(stored.day);
+  const at = optionalNumber(stored.at);
+  return game === undefined || day === undefined || at === undefined ? undefined : { action: stored.action, game, day, at };
+}
+
+/** Whether a failure means the instance is gone or closed on the hub (the change is moot). */
+function isGoneOrClosed(failure: Error): boolean {
+  return failure instanceof HubError && (failure.status === 404 || failure.status === 409);
+}
+
+/** The hub's id for the copy's day: its own, or the one the hub gives the day when it was started offline (`null`: already completed). */
+async function resolveId(copy: LocalDaily, context: ReplayContext): Promise<string | null> {
+  if (!copy.id.startsWith('local:')) {
+    return copy.id;
+  }
+  const started = await context.call('startDailyChallenge', { slug: copy.game, day: copy.day });
+  return started.instanceId;
+}
+
+/** Run one op against the copy it names. */
+async function runSaved(op: SavedPayload, local: LocalDailyStore, context: ReplayContext): Promise<undefined> {
+  const copy = local.read(op.game, op.day);
+  if (copy === null) {
+    return undefined;
+  }
+  try {
+    const id = await resolveId(copy, context);
+    if (id === null) {
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    if (op.action === 'discard') {
+      await context.call('discardSavedGame', { id });
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    // A null state is sent too: it is hub.resume.clear() during the day (start over from the seed).
+    if (copy.status === 'active') {
+      await context.call('saveSavedGameState', {
+        id, state: copy.state, progress: { label: copy.label, fraction: copy.fraction }, title: copy.title, version: copy.version, savedAt: copy.at,
+      });
+    }
+    local.markSynced(op.game, op.day, copy.at, id);
+  } catch (failure) {
+    if (!(failure instanceof Error) || !isGoneOrClosed(failure)) {
+      throw failure;
+    }
+    local.remove(op.game, op.day);
+  }
+  return undefined;
+}
+
+/** The saved-games kind, by name, over the device copies in `local`. */
+export function savedKinds(local: LocalDailyStore): Record<string, RegisteredKind> {
+  return {
+    [SAVED_KIND]: checkedKind(readSaved, {
+      mergeKey: (op) => `daily:${op.game}#${op.day}`,
+      replaces: true,
+      run: (op, context) => runSaved(op, local, context),
+    }),
+  };
+}

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);
     }