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

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

@@ -1,90 +1,146 @@
-// Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
-/** Every public REST endpoint's method, path (under `/_api`) and query keys, from the contract. */
+// Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client`.
+/** Every public REST endpoint's method, path (under `/_api`), query keys and offline mode (`'replay'` when it may be queued offline), from the contract. */
 export const ROUTES = {
-  ensureGuestSession: { method: 'POST', path: '/auth/guest', query: [] },
-  signUpWithPassword: { method: 'POST', path: '/auth/signup', query: [] },
-  logInWithPassword: { method: 'POST', path: '/auth/login', query: [] },
-  logOut: { method: 'POST', path: '/auth/logout', query: [] },
-  getCurrentUser: { method: 'GET', path: '/me', query: [] },
-  claimGuestAccount: { method: 'POST', path: '/auth/claim', query: [] },
-  listGames: { method: 'GET', path: '/games', query: [] },
-  listWhatsNewNotes: { method: 'GET', path: '/changes', query: ['game', 'since'] },
-  listFavoriteGames: { method: 'GET', path: '/favorites', query: [] },
-  setGameFavorite: { method: 'PUT', path: '/favorites/:slug', query: [] },
-  markWhatsNewSeen: { method: 'POST', path: '/changes/seen', query: [] },
-  getGameStats: { method: 'GET', path: '/games/:slug/stats', query: ['user'] },
-  getGameProfile: { method: 'GET', path: '/games/:slug/profile', query: [] },
-  setGameProfile: { method: 'PUT', path: '/games/:slug/profile', query: [] },
-  listSaves: { method: 'GET', path: '/games/:slug/saves', query: [] },
-  getSave: { method: 'GET', path: '/games/:slug/saves/:slot', query: [] },
-  writeSave: { method: 'PUT', path: '/games/:slug/saves/:slot', query: [] },
-  deleteSave: { method: 'DELETE', path: '/games/:slug/saves/:slot', query: [] },
-  updateGameStat: { method: 'POST', path: '/games/:slug/stats', query: [] },
-  resetMyGameProgress: { method: 'POST', path: '/games/:slug/reset', query: [] },
-  listMyLeaderboardRecords: { method: 'GET', path: '/me/records', query: ['game'] },
-  getMyOfflineSnapshot: { method: 'GET', path: '/me/snapshot', query: ['top'] },
-  listTopOfEveryLeaderboard: { method: 'GET', path: '/leaderboards', query: ['top'] },
-  listGameLeaderboards: { method: 'GET', path: '/games/:slug/leaderboards', query: [] },
-  getLeaderboard: { method: 'GET', path: '/games/:slug/leaderboards/:key', query: ['limit'] },
-  submitScore: { method: 'POST', path: '/games/:slug/leaderboards/:key/scores', query: [] },
-  listDailyChallengesForAllGames: { method: 'GET', path: '/daily', query: [] },
-  getGameDailyChallenges: { method: 'GET', path: '/games/:slug/daily', query: [] },
-  startDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/start', query: [] },
-  completeDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/complete', query: [] },
-  getMyInventory: { method: 'GET', path: '/games/:slug/inventory', query: [] },
-  grantInventoryItems: { method: 'POST', path: '/games/:slug/inventory/grant', query: [] },
-  exchangeInventoryItems: { method: 'POST', path: '/games/:slug/inventory/exchange', query: [] },
-  getPlayerInventory: { method: 'GET', path: '/games/:slug/players/:userId/inventory', query: [] },
-  listTradePartners: { method: 'GET', path: '/games/:slug/trades/players', query: [] },
-  listMyTrades: { method: 'GET', path: '/games/:slug/trades', query: ['box', 'status'] },
-  declineTrade: { method: 'POST', path: '/games/:slug/trades/:id/decline', query: [] },
-  cancelTrade: { method: 'POST', path: '/games/:slug/trades/:id/cancel', query: [] },
-  createTrade: { method: 'POST', path: '/games/:slug/trades', query: [] },
-  acceptTrade: { method: 'POST', path: '/games/:slug/trades/:id/accept', query: [] },
-  counterTradeOffer: { method: 'POST', path: '/games/:slug/trades/:id/counter', query: [] },
-  getSiteAnalytics: { method: 'GET', path: '/analytics', query: [] },
-  reportClientError: { method: 'POST', path: '/client-log', query: [] },
-  recordGameEvent: { method: 'POST', path: '/games/:slug/events', query: [] },
-  getGameAnalytics: { method: 'GET', path: '/games/:slug/analytics', query: [] },
-  getSocialConfig: { method: 'GET', path: '/social/config', query: [] },
-  getOnlineCounts: { method: 'GET', path: '/social/counts', query: [] },
-  getMySocialProfile: { method: 'GET', path: '/social/me', query: [] },
-  listFriendsAndRequests: { method: 'GET', path: '/social/friends', query: [] },
-  findPlayerByName: { method: 'GET', path: '/social/players/by-name/:name', query: [] },
-  getPlayerCard: { method: 'GET', path: '/social/players/:id', query: [] },
-  updateMySocialProfile: { method: 'PUT', path: '/social/me', query: [] },
-  setParentChatLock: { method: 'POST', path: '/social/chat-lock', query: [] },
-  sendFriendRequest: { method: 'POST', path: '/social/friends', query: [] },
-  acceptFriendRequest: { method: 'POST', path: '/social/friends/:id/accept', query: [] },
-  declineFriendRequest: { method: 'POST', path: '/social/friends/:id/decline', query: [] },
-  removeFriend: { method: 'DELETE', path: '/social/friends/:id', query: [] },
-  setFriendNotifications: { method: 'PUT', path: '/social/friends/:id/notify', query: [] },
-  blockPlayer: { method: 'POST', path: '/social/blocks', query: [] },
-  unblockPlayer: { method: 'DELETE', path: '/social/blocks/:id', query: [] },
-  listRecentPlayers: { method: 'GET', path: '/social/recent', query: [] },
-  listConversations: { method: 'GET', path: '/social/conversations', query: [] },
-  listDirectMessages: { method: 'GET', path: '/social/messages/:userId', query: ['before'] },
-  sendDirectMessage: { method: 'POST', path: '/social/messages/:userId', query: [] },
-  markDirectMessagesRead: { method: 'POST', path: '/social/messages/:userId/read', query: [] },
-  getNotificationPreferences: { method: 'GET', path: '/social/notify', query: [] },
-  unsubscribeFromPush: { method: 'DELETE', path: '/social/push', query: [] },
-  setNotificationPreferences: { method: 'PUT', path: '/social/notify', query: [] },
-  subscribeToPush: { method: 'POST', path: '/social/push', query: [] },
-  fileReport: { method: 'POST', path: '/social/reports', query: [] },
-  listPublicSuggestions: { method: 'GET', path: '/suggestions', query: ['sort'] },
-  submitSuggestion: { method: 'POST', path: '/suggestions', query: [] },
-  voteForSuggestion: { method: 'POST', path: '/suggestions/:id/vote', query: [] },
-  removeSuggestionVote: { method: 'DELETE', path: '/suggestions/:id/vote', query: [] },
-  withdrawSuggestion: { method: 'DELETE', path: '/suggestions/:id', query: [] },
-  sendGameInvite: { method: 'POST', path: '/mp/invites', query: [] },
-  acceptGameInvite: { method: 'POST', path: '/mp/invites/:id/accept', query: [] },
-  declineGameInvite: { method: 'POST', path: '/mp/invites/:id/decline', query: [] },
-  cancelGameInvite: { method: 'DELETE', path: '/mp/invites/:id', query: [] },
-  redeemLaunchToken: { method: 'GET', path: '/mp/launch/:token', query: [] },
-  setPartyJoinInfo: { method: 'POST', path: '/mp/parties/:id/join-info', query: [] },
-  leaveParty: { method: 'POST', path: '/mp/parties/:id/leave', query: [] },
-  launchIntoFriendsRoom: { method: 'POST', path: '/mp/join', query: [] },
-  getGameServerTicket: { method: 'POST', path: '/mp/ticket', query: [] },
-  listMyRaceHistory: { method: 'GET', path: '/race/history', query: ['game', 'with', 'before', 'limit'] },
-  getHubVersion: { method: 'GET', path: '/version', query: [] },
+  ensureGuestSession: { method: 'POST', path: '/auth/guest', query: [], offline: null },
+  signUpWithPassword: { method: 'POST', path: '/auth/signup', query: [], offline: null },
+  logInWithPassword: { method: 'POST', path: '/auth/login', query: [], offline: null },
+  logOut: { method: 'POST', path: '/auth/logout', query: [], offline: null },
+  getCurrentUser: { method: 'GET', path: '/me', query: [], offline: null },
+  claimGuestAccount: { method: 'POST', path: '/auth/claim', query: [], offline: null },
+  getGamePlayerCounts: { method: 'GET', path: '/catalog/players', query: [], offline: null },
+  getMyGameActivity: { method: 'GET', path: '/games/:slug/me/activity', query: [], offline: null },
+  listGames: { method: 'GET', path: '/games', query: [], offline: null },
+  listWhatsNewNotes: { method: 'GET', path: '/changes', query: ['game', 'since'], offline: null },
+  listFavoriteGames: { method: 'GET', path: '/favorites', query: [], offline: null },
+  setGameFavorite: { method: 'PUT', path: '/favorites/:slug', query: [], offline: 'replay' },
+  markWhatsNewSeen: { method: 'POST', path: '/changes/seen', query: [], offline: null },
+  getGameStats: { method: 'GET', path: '/games/:slug/stats', query: ['user'], offline: null },
+  getGameProfile: { method: 'GET', path: '/games/:slug/profile', query: [], offline: null },
+  setGameProfile: { method: 'PUT', path: '/games/:slug/profile', query: [], offline: 'replay' },
+  listSaves: { method: 'GET', path: '/games/:slug/saves', query: [], offline: null },
+  getSave: { method: 'GET', path: '/games/:slug/saves/:slot', query: [], offline: null },
+  writeSave: { method: 'PUT', path: '/games/:slug/saves/:slot', query: [], offline: 'replay' },
+  deleteSave: { method: 'DELETE', path: '/games/:slug/saves/:slot', query: [], offline: 'replay' },
+  updateGameStat: { method: 'POST', path: '/games/:slug/stats', query: [], offline: 'replay' },
+  resetMyGameProgress: { method: 'POST', path: '/games/:slug/reset', query: [], offline: null },
+  listMyLeaderboardRecords: { method: 'GET', path: '/me/records', query: ['game'], offline: null },
+  getMyOfflineSnapshot: { method: 'GET', path: '/me/snapshot', query: ['top'], offline: null },
+  listTopOfEveryLeaderboard: { method: 'GET', path: '/leaderboards', query: ['top'], offline: null },
+  listGameLeaderboards: { method: 'GET', path: '/games/:slug/leaderboards', query: [], offline: null },
+  getLeaderboard: { method: 'GET', path: '/games/:slug/leaderboards/:key', query: ['limit'], offline: null },
+  submitScore: { method: 'POST', path: '/games/:slug/leaderboards/:key/scores', query: [], offline: 'replay' },
+  listDailyChallengesForAllGames: { method: 'GET', path: '/daily', query: [], offline: null },
+  getGameDailyChallenges: { method: 'GET', path: '/games/:slug/daily', query: [], offline: null },
+  resumeDailyChallenge: { method: 'POST', path: '/daily/instances/:id/resume', query: [], offline: null },
+  startDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/start', query: [], offline: null },
+  completeDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/complete', query: [], offline: 'replay' },
+  getMyInventory: { method: 'GET', path: '/games/:slug/inventory', query: [], offline: null },
+  grantInventoryItems: { method: 'POST', path: '/games/:slug/inventory/grant', query: [], offline: 'replay' },
+  exchangeInventoryItems: { method: 'POST', path: '/games/:slug/inventory/exchange', query: [], offline: 'replay' },
+  getPlayerInventory: { method: 'GET', path: '/games/:slug/players/:userId/inventory', query: [], offline: null },
+  listTradePartners: { method: 'GET', path: '/games/:slug/trades/players', query: [], offline: null },
+  listMyTrades: { method: 'GET', path: '/games/:slug/trades', query: ['box', 'status'], offline: null },
+  declineTrade: { method: 'POST', path: '/games/:slug/trades/:id/decline', query: [], offline: null },
+  cancelTrade: { method: 'POST', path: '/games/:slug/trades/:id/cancel', query: [], offline: null },
+  createTrade: { method: 'POST', path: '/games/:slug/trades', query: [], offline: null },
+  acceptTrade: { method: 'POST', path: '/games/:slug/trades/:id/accept', query: [], offline: null },
+  counterTradeOffer: { method: 'POST', path: '/games/:slug/trades/:id/counter', query: [], offline: null },
+  getSiteAnalytics: { method: 'GET', path: '/analytics', query: [], offline: null },
+  reportClientError: { method: 'POST', path: '/client-log', query: [], offline: null },
+  recordGameEvent: { method: 'POST', path: '/games/:slug/events', query: [], offline: null },
+  getGameAnalytics: { method: 'GET', path: '/games/:slug/analytics', query: [], offline: null },
+  getSocialConfig: { method: 'GET', path: '/social/config', query: [], offline: null },
+  getOnlineCounts: { method: 'GET', path: '/social/counts', query: [], offline: null },
+  getMySocialProfile: { method: 'GET', path: '/social/me', query: [], offline: null },
+  listFriendsAndRequests: { method: 'GET', path: '/social/friends', query: [], offline: null },
+  findPlayerByName: { method: 'GET', path: '/social/players/by-name/:name', query: [], offline: null },
+  getPlayerCard: { method: 'GET', path: '/social/players/:id', query: [], offline: null },
+  updateMySocialProfile: { method: 'PUT', path: '/social/me', query: [], offline: null },
+  setParentChatLock: { method: 'POST', path: '/social/chat-lock', query: [], offline: null },
+  sendFriendRequest: { method: 'POST', path: '/social/friends', query: [], offline: null },
+  acceptFriendRequest: { method: 'POST', path: '/social/friends/:id/accept', query: [], offline: null },
+  declineFriendRequest: { method: 'POST', path: '/social/friends/:id/decline', query: [], offline: null },
+  removeFriend: { method: 'DELETE', path: '/social/friends/:id', query: [], offline: null },
+  setFriendNotifications: { method: 'PUT', path: '/social/friends/:id/notify', query: [], offline: null },
+  blockPlayer: { method: 'POST', path: '/social/blocks', query: [], offline: null },
+  unblockPlayer: { method: 'DELETE', path: '/social/blocks/:id', query: [], offline: null },
+  listRecentPlayers: { method: 'GET', path: '/social/recent', query: [], offline: null },
+  listConversations: { method: 'GET', path: '/social/conversations', query: [], offline: null },
+  listDirectMessages: { method: 'GET', path: '/social/messages/:userId', query: ['before'], offline: null },
+  sendDirectMessage: { method: 'POST', path: '/social/messages/:userId', query: [], offline: null },
+  markDirectMessagesRead: { method: 'POST', path: '/social/messages/:userId/read', query: [], offline: null },
+  getNotificationPreferences: { method: 'GET', path: '/social/notify', query: [], offline: null },
+  unsubscribeFromPush: { method: 'DELETE', path: '/social/push', query: [], offline: null },
+  setNotificationPreferences: { method: 'PUT', path: '/social/notify', query: [], offline: null },
+  setQuietHours: { method: 'PUT', path: '/social/notify/quiet', query: [], offline: null },
+  subscribeToPush: { method: 'POST', path: '/social/push', query: [], offline: null },
+  fileReport: { method: 'POST', path: '/social/reports', query: [], offline: null },
+  listPublicSuggestions: { method: 'GET', path: '/suggestions', query: ['sort'], offline: null },
+  submitSuggestion: { method: 'POST', path: '/suggestions', query: [], offline: null },
+  voteForSuggestion: { method: 'POST', path: '/suggestions/:id/vote', query: [], offline: null },
+  removeSuggestionVote: { method: 'DELETE', path: '/suggestions/:id/vote', query: [], offline: null },
+  withdrawSuggestion: { method: 'DELETE', path: '/suggestions/:id', query: [], offline: null },
+  sendGameInvite: { method: 'POST', path: '/mp/invites', query: [], offline: null },
+  acceptGameInvite: { method: 'POST', path: '/mp/invites/:id/accept', query: [], offline: null },
+  declineGameInvite: { method: 'POST', path: '/mp/invites/:id/decline', query: [], offline: null },
+  createInviteLink: { method: 'POST', path: '/mp/links', query: [], offline: null },
+  listInviteLinks: { method: 'GET', path: '/mp/links', query: ['game'], offline: null },
+  revokeInviteLink: { method: 'DELETE', path: '/mp/links/:token', query: [], offline: null },
+  cancelGameInvite: { method: 'DELETE', path: '/mp/invites/:id', query: [], offline: null },
+  redeemLaunchToken: { method: 'GET', path: '/mp/launch/:token', query: [], offline: null },
+  openInviteLink: { method: 'POST', path: '/mp/links/:token/open', query: [], offline: null },
+  setPartyJoinInfo: { method: 'POST', path: '/mp/parties/:id/join-info', query: [], offline: null },
+  leaveParty: { method: 'POST', path: '/mp/parties/:id/leave', query: [], offline: null },
+  launchIntoFriendsRoom: { method: 'POST', path: '/mp/join', query: [], offline: null },
+  getGameServerTicket: { method: 'POST', path: '/mp/ticket', query: [], offline: null },
+  listMyRaceHistory: { method: 'GET', path: '/race/history', query: ['game', 'with', 'before', 'limit'], offline: null },
+  listTournaments: { method: 'GET', path: '/tournaments', query: ['game'], offline: null },
+  getTournament: { method: 'GET', path: '/tournaments/:id', query: ['key'], offline: null },
+  createTournament: { method: 'POST', path: '/tournaments', query: [], offline: null },
+  inviteToTournament: { method: 'POST', path: '/tournaments/:id/invites', query: [], offline: null },
+  followTournament: { method: 'PUT', path: '/tournaments/:id/follow', query: [], offline: null },
+  unfollowTournament: { method: 'DELETE', path: '/tournaments/:id/follow', query: [], offline: null },
+  startTournament: { method: 'POST', path: '/tournaments/:id/start', query: [], offline: null },
+  cancelTournament: { method: 'DELETE', path: '/tournaments/:id', query: [], offline: null },
+  joinTournament: { method: 'POST', path: '/tournaments/:id/join', query: [], offline: null },
+  leaveTournament: { method: 'POST', path: '/tournaments/:id/leave', query: [], offline: null },
+  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 },
+  getMyAvatar: { method: 'GET', path: '/avatar/me', query: [], offline: null },
+  recordAvatarNudge: { method: 'POST', path: '/avatar/me/nudge', query: [], offline: null },
+  saveMyAvatar: { method: 'PUT', path: '/avatar/me', query: [], offline: null },
+  resetMyAvatar: { method: 'DELETE', path: '/avatar/me', query: [], offline: null },
+  getAvatar: { method: 'GET', path: '/avatar/of/:id', query: [], offline: null },
+  getAvatars: { method: 'POST', path: '/avatar/batch', query: [], offline: null },
+  listMySavedGames: { method: 'GET', path: '/saved', query: ['game', 'kinds'], offline: null },
+  getSavedGame: { method: 'GET', path: '/saved/:id', query: [], offline: null },
+  saveSavedGameState: { method: 'PUT', path: '/saved/:id/state', query: [], offline: 'replay' },
+  discardSavedGame: { method: 'POST', path: '/saved/:id/discard', query: [], offline: 'replay' },
+  discardGameSavedGames: { method: 'POST', path: '/games/:slug/saved/discard', query: [], offline: null },
+  createTurnGame: { method: 'POST', path: '/turns', query: [], offline: null },
+  joinTurnGame: { method: 'POST', path: '/turns/:id/join', query: [], offline: null },
+  joinTurnGameByLink: { method: 'POST', path: '/turns/join', query: [], offline: null },
+  startTurnGame: { method: 'POST', path: '/turns/:id/start', query: [], offline: null },
+  moveTurnGame: { method: 'POST', path: '/turns/:id/moves', query: [], offline: null },
+  leaveTurnGame: { method: 'POST', path: '/turns/:id/leave', query: [], offline: null },
+  nudgeTurnGame: { method: 'POST', path: '/turns/:id/nudge', query: [], offline: null },
+  setTurnGameNotify: { method: 'PUT', path: '/turns/:id/notify', query: [], offline: null },
+  rematchTurnGame: { method: 'POST', path: '/turns/:id/rematch', query: [], offline: null },
+  inviteToTurnGame: { method: 'POST', path: '/turns/:id/invite', query: [], offline: null },
+  shareTurnGame: { method: 'POST', path: '/turns/:id/share', query: [], offline: null },
+  autoPlayTurn: { method: 'POST', path: '/turns/:id/auto', query: [], offline: null },
+  chatInTurnGame: { method: 'POST', path: '/turns/:id/chat', query: [], offline: null },
+  getTurnGame: { method: 'GET', path: '/turns/:id', query: [], offline: null },
+  getTurnGameHistory: { method: 'GET', path: '/turns/:id/history', query: ['since'], offline: null },
+  listOpenTurnGames: { method: 'GET', path: '/open-turns', query: ['game'], offline: null },
+  listMyTurnGames: { method: 'GET', path: '/turns', query: ['game'], offline: null },
+  getWorldMap: { method: 'GET', path: '/world/maps/:key', query: ['rev'], offline: null },
 } as const;
+
+/** The request header that carries an offline operation key (the contract's `OFFLINE_OP_HEADER`). */
+export const OFFLINE_OP_HEADER = 'x-hub-op';

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

@@ -0,0 +1,286 @@
+/**
+ * `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 or an online room: those
+ * runs are never resumed. During a daily challenge they go to the day's own
+ * saved game (`hub.daily.save`), so the day can be picked up again.
+ */
+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.',
+  turns: 'an online game is open: the hub keeps its state, so nothing is saved on the page.',
+};
+
+/** 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;
+  /** The page's daily challenge while one is being played (saves go to the day instead of the run), else `null`. */
+  daily?(): DailyRoute | 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>;
+  /** The run changed here (saved or cleared): `hub.saved` listeners hear it. */
+  onChange?(): void;
+}
+
+/** Where a save goes during a daily challenge (`hub.daily`). */
+export interface DailyRoute {
+  save(input: ResumeSaveInput<GamePayload>): boolean;
+}
+
+/** The label a daily goes back to when the game clears its run mid-daily (the day restarts from its seed). */
+const DAILY_RESTART_LABEL = 'Started';
+
+/** 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 or an online room; during
+   * a daily challenge the save goes to the day (`hub.daily.save`). 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 daily = this.host.daily?.() ?? null;
+    if (daily !== null) {
+      // During a daily challenge the run IS the day: it is saved to the day's saved game, not the game's run.
+      return daily.save(run);
+    }
+    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.host.onChange?.();
+    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();
+    const daily = this.host.daily?.() ?? null;
+    if (daily !== null) {
+      // The day's run ended without a win: the day stays in progress, starting over from its seed.
+      daily.save({ state: null, progress: { label: DAILY_RESTART_LABEL } });
+      return;
+    }
+    await this.clearRun(slug);
+  }
+
+  /** Delete the game's saved run (never the day being played). */
+  private async clearRun(slug: string): Promise<void> {
+    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 });
+    this.host.onChange?.();
+    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) {
+      // A stale saved run is dropped; a daily being played is left alone.
+      await this.clearRun(slug);
+    }
+    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();
+        }
+      });
+    }
+  }
+}