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

package/src/core/offline/queue.ts

@@ -1,12 +1,8 @@
 /**
- * The offline mutation queue. Writes apply to the local cache at once and
- * queue a durable op; when the hub is reachable again the queue replays in
- * order. Ops collapse as they are queued (a save's last write wins, `incr`s
- * add up, `max`es keep the largest, a board keeps its best, profile patches
- * merge), so the backlog stays small.
- *
- * The op shapes are the v1 client's, unchanged: a page upgraded from a
- * vendored copy replays the queue that copy left in `localStorage`.
+ * The v1 client's offline queue (`hub:<slug>:queue`): its op shapes and the
+ * reader for what a vendored v1 copy left in `localStorage`. This client
+ * queues into the outbox instead (`outbox.ts`) and moves any v1 ops there on
+ * start (`hub-kinds/legacy-ops.ts`), so nothing a v1 copy queued is lost.
  */
 import type { Json } from '@diffenderfer-games/hub-contract';
 import type { SortDir } from '@diffenderfer-games/hub-contract';
@@ -128,44 +124,3 @@ export function readQueue(stored: unknown): QueueOp[] {
 export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
   return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
 }
-
-/** The op that `queued` becomes when `incoming` collapses into it, or `undefined` when they don't collapse. */
-function collapsedOp(queued: QueueOp, incoming: QueueOp): QueueOp | undefined {
-  if (queued.kind === 'incrStat' && incoming.kind === 'incrStat' && queued.key === incoming.key) {
-    return { ...queued, amount: queued.amount + incoming.amount };
-  }
-  if (queued.kind === 'maxStat' && incoming.kind === 'maxStat' && queued.key === incoming.key) {
-    return { ...queued, value: Math.max(queued.value, incoming.value) };
-  }
-  if (queued.kind === 'setStat' && incoming.kind === 'setStat' && queued.key === incoming.key) {
-    return { ...queued, value: incoming.value };
-  }
-  if (queued.kind === 'submitScore' && incoming.kind === 'submitScore' && queued.key === incoming.key) {
-    return { ...queued, score: betterScore(queued.score, incoming.score, incoming.opts.sort), opts: incoming.opts };
-  }
-  if (queued.kind === 'setProfile' && incoming.kind === 'setProfile') {
-    return { ...queued, patch: { ...queued.patch, ...incoming.patch } };
-  }
-  return undefined;
-}
-
-/** Whether an op writes save slot `slot`. */
-function writesSlot(op: QueueOp, slot: string): boolean {
-  return (op.kind === 'putSave' || op.kind === 'deleteSave') && op.slot === slot;
-}
-
-/**
- * The queue with `incoming` added: a save or delete replaces any queued
- * write to the same slot (and goes last); a compatible op merges into the
- * first queued one in place; anything else is appended.
- */
-export function enqueueOp(queue: readonly QueueOp[], incoming: QueueOp): QueueOp[] {
-  if (incoming.kind === 'putSave' || incoming.kind === 'deleteSave') {
-    return [...queue.filter((op) => !writesSlot(op, incoming.slot)), incoming];
-  }
-  const mergeAt = queue.findIndex((op) => collapsedOp(op, incoming) !== undefined);
-  if (mergeAt < 0) {
-    return [...queue, incoming];
-  }
-  return queue.map((op, i) => (i === mergeAt ? (collapsedOp(op, incoming) ?? op) : op));
-}

package/src/core/offline/replay-lease.ts

@@ -0,0 +1,87 @@
+/**
+ * One replayer at a time per game, across tabs and across the client copies
+ * on one page: a Web Lock where the browser has them, else a lease in
+ * `localStorage` that its holder renews while it works and that lapses if
+ * the tab dies. A replayer that can't get it simply doesn't run; the holder
+ * replays for everyone.
+ */
+import { isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** Runs work while holding the lease. */
+export interface ReplayLease {
+  /** Run `work` holding the lease; `false` (without running it) when another replayer holds it. */
+  hold(work: () => Promise<void>): Promise<boolean>;
+}
+
+/** How long a `localStorage` lease lasts without renewal. */
+export const STORAGE_LEASE_MS = 15_000;
+
+/** How often the holder renews it. */
+const RENEW_EVERY_MS = 5_000;
+
+/** A lease on the Web Locks API. */
+function webLockLease(locks: LockManager, name: string): ReplayLease {
+  return {
+    hold: (work) => locks.request(name, { ifAvailable: true }, async (lock) => {
+      if (lock === null) {
+        return false;
+      }
+      await work();
+      return true;
+    }),
+  };
+}
+
+/** The lease's holder and expiry, or `undefined` when there is none. */
+function readLease(text: string | null): { readonly owner: string; readonly until: number } | undefined {
+  const stored = text === null ? undefined : parseJsonText(text);
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const owner = optionalString(stored.owner);
+  const until = optionalNumber(stored.until);
+  return owner === undefined || until === undefined ? undefined : { owner, until };
+}
+
+/** A lease kept in `store` under `key`, for pages without Web Locks. */
+export function storageLease(store: KeyValueStore, key: string, now: () => number = Date.now): ReplayLease {
+  const owner = `${String(now())}-${Math.random().toString(36).slice(2)}`;
+  const claim = (): boolean => {
+    const current = readLease(store.read(key));
+    if (current !== undefined && current.owner !== owner && current.until > now()) {
+      return false;
+    }
+    store.write(key, JSON.stringify({ owner, until: now() + STORAGE_LEASE_MS }));
+    return readLease(store.read(key))?.owner === owner;
+  };
+  return {
+    async hold(work) {
+      if (!claim()) {
+        return false;
+      }
+      const renewal = setInterval(claim, RENEW_EVERY_MS);
+      try {
+        await work();
+      } finally {
+        clearInterval(renewal);
+        if (readLease(store.read(key))?.owner === owner) {
+          store.remove(key);
+        }
+      }
+      return true;
+    },
+  };
+}
+
+/** The page's Web Locks, when it has them. */
+function pageLocks(): LockManager | undefined {
+  return typeof navigator !== 'undefined' && 'locks' in navigator ? navigator.locks : undefined;
+}
+
+/** The lease for game `slug`'s outbox: a Web Lock when available, else one in `store`. */
+export function createReplayLease(slug: string, store: KeyValueStore): ReplayLease {
+  const name = `hub:${slug}:outbox-lease`;
+  const locks = pageLocks();
+  return locks === undefined ? storageLease(store, name) : webLockLease(locks, name);
+}

package/src/core/offline/replay-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * What a failed replay does next, and how long it waits:
+ *
+ * - `offline`: the hub (or the network) can't be reached. The op stays at
+ *   the head of the queue and replay waits for the connection.
+ * - `retry`: the hub answered with a passing problem (408, 429, 5xx) or a
+ *   game handler's fetch failed. The op stays at the head and is retried with
+ *   backoff, up to {@link MAX_RETRIES} times, then dropped.
+ * - `drop`: the hub refused it (any other status) or the handler threw
+ *   something else. The op is dropped and reported, and the queue moves on.
+ */
+import { HubError } from '../errors';
+
+/** What to do after a failed replay. */
+export type FailureVerdict = 'offline' | 'retry' | 'drop';
+
+/** The most tries for an op that keeps getting a passing failure. */
+export const MAX_RETRIES = 8;
+
+/** The first retry's delay. */
+const BASE_DELAY_MS = 1000;
+
+/** The longest delay between tries. */
+const MAX_DELAY_MS = 60_000;
+
+/** Statuses that mean "try again later". */
+const PASSING_STATUSES: ReadonlySet<number> = new Set([408, 425, 429]);
+
+/** The verdict for a failure. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function verdictFor(failure: unknown): FailureVerdict {
+  if (failure instanceof HubError) {
+    if (failure.status === undefined) {
+      return 'offline';
+    }
+    return failure.status >= 500 || PASSING_STATUSES.has(failure.status) ? 'retry' : 'drop';
+  }
+  // A game handler's own fetch rejects with a TypeError when the network is down.
+  return failure instanceof TypeError ? 'retry' : 'drop';
+}
+
+/** The delay before try `attempts + 1`: doubling from 1 s, capped at 60 s, with jitter so tabs and players spread out. */
+export function backoffMs(attempts: number, random: () => number = Math.random): number {
+  const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.max(0, attempts - 1));
+  return Math.round(ceiling / 2 + (ceiling / 2) * random());
+}
+
+/** A failure's message, for reports. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever a replay handler threw
+export function failureMessage(failure: unknown): string {
+  return failure instanceof Error ? failure.message : String(failure);
+}

package/src/core/rest/rest-client.ts

@@ -9,7 +9,7 @@ import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../erro
 import { isRecord } from '../storage/json-guards';
 import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
 import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
-import { ROUTES } from './routes.gen';
+import { OFFLINE_OP_HEADER, ROUTES } from './routes.gen';
 
 /** The header that tells the hub which client version is calling. */
 export const CLIENT_VERSION_HEADER = 'x-hub-client';
@@ -38,6 +38,12 @@ export interface RestClient {
   readonly apiBase: string;
   /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
   call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+  /**
+   * Call an endpoint as part of an offline operation: an endpoint marked for
+   * offline replay gets `opKey` in the operation header, so the hub runs it
+   * once however often it is sent; any other endpoint is called as usual.
+   */
+  callOnce<K extends EndpointName>(opKey: string, name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
 }
 
 /** One field value as URL text. */
@@ -126,14 +132,18 @@ async function failureOf(name: EndpointName, response: Response): Promise<HubErr
 /** A REST client for one API base. */
 export function createRestClient(options: RestClientOptions): RestClient {
   // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-  async function send<Reply>(name: EndpointName, fields: unknown): Promise<Reply> {
+  async function send<Reply>(name: EndpointName, fields: unknown, opKey?: string): Promise<Reply> {
     const planned = planRequest(name, fields);
     let response: Response;
     try {
       response = await options.fetch(options.apiBase + planned.pathAndQuery, {
         method: planned.method,
         credentials: 'same-origin',
-        headers: { 'content-type': 'application/json', [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION },
+        headers: {
+          'content-type': 'application/json',
+          [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION,
+          ...(opKey !== undefined && ROUTES[name].offline === 'replay' ? { [OFFLINE_OP_HEADER]: opKey } : {}),
+        },
         ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
       });
     } catch (failure) {
@@ -148,5 +158,6 @@ export function createRestClient(options: RestClientOptions): RestClient {
   return {
     apiBase: options.apiBase,
     call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
+    callOnce: (opKey, name, ...fieldsArgument) => send(name, fieldsArgument[0], opKey),
   };
 }

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

@@ -1,90 +1,111 @@
 // 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. */
+/** 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 },
+  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 },
+  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 },
 } 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/storage/json-guards.ts

@@ -72,3 +72,9 @@ export function parseJsonText(text: string): unknown {
     return undefined;
   }
 }
+
+/** Whether `candidate` is a JSON object (not an array or `null`). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isJsonObject(candidate: unknown): candidate is { readonly [key: string]: Json } {
+  return isRecord(candidate) && Object.values(candidate).every(isJson);
+}

package/src/core/version/client-version.gen.ts

@@ -1,3 +1,3 @@
 // Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
 /** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
-export const HUB_CLIENT_VERSION = '2.0.0-next.1';
+export const HUB_CLIENT_VERSION = '2.0.0-next.3';

package/src/daily/daily-system.ts

@@ -113,7 +113,9 @@ export class DailySystem {
   /**
    * Record completion of the active challenge with optional metadata.
    * Resolves with the new completion count and rank, or `null` when no
-   * challenge is active or the hub refused.
+   * challenge is active, the hub refused, or the hub can't be reached: then
+   * the completion is queued (`hub:daily-queued`) and replays when it is
+   * back (`hub:daily-complete` follows).
    */
   async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
     const challenge = this.active;
@@ -123,6 +125,11 @@ export class DailySystem {
     try {
       const completed = await this.host.complete(challenge.day, challenge.token, meta);
       this.active = null;
+      if (completed === null) {
+        // Queued offline: `hub:daily-complete` follows when it replays.
+        this.host.emit('hub:daily-queued', { day: challenge.day, queued: true, meta });
+        return null;
+      }
       this.host.emit('hub:daily-complete', { day: challenge.day, count: completed.count, rank: completed.rank, meta });
       return completed;
     } catch (error) {

package/src/daily/types.ts

@@ -54,8 +54,8 @@ export interface DailyHost {
   all(): Promise<DailyAll>;
   /** `POST /games/:slug/daily/:day/start`. */
   start(day: string): Promise<DailyStartResponse>;
-  /** `POST /games/:slug/daily/:day/complete`. */
-  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse>;
+  /** `POST /games/:slug/daily/:day/complete`; `null` when it was queued offline, to replay when the hub is back. */
+  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse | null>;
   /** Fire a `hub:*` window event (the menu listens). */
   emit(name: string, detail: DailyEventDetail): void;
 }
@@ -64,4 +64,5 @@ export interface DailyHost {
 export type DailyEventDetail =
   | { day: string; seed: number; alreadyCompleted: boolean }
   | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
+  | { day: string; queued: true; meta: DailyCompletionMeta }
   | { day: string; error: string };

package/src/doctor/checks.ts

@@ -4,7 +4,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { GamePackageJson, type HubVersion } from '@diffenderfer-games/hub-contract';
+import { GAME_LABELS, GamePackageJson, splitGameLabels, type HubVersion } from '@diffenderfer-games/hub-contract';
 import { clientSupport } from '../core/version/hub-version';
 import { isHubUnreachable, type HubUnreachable } from './hub-version-fetch';
 
@@ -68,7 +68,15 @@ export function checkVendoredCopies(gameDir: string): Finding[] {
 export function checkManifest(packageJson: unknown): Finding[] {
   const parsed = GamePackageJson.safeParse(packageJson);
   if (parsed.success) {
-    return [{ level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` }];
+    const unknownLabels = splitGameLabels(parsed.data.game.labels ?? []).unknown;
+    return [
+      { level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` },
+      ...unknownLabels.map((label): Finding => ({
+        level: 'warning',
+        check: 'manifest',
+        message: `game.labels: "${label}" is not a known label (the catalog ignores it); use any of ${GAME_LABELS.join(', ')}`,
+      })),
+    ];
   }
   return parsed.error.issues.map((issue) => ({
     level: 'error',

package/src/index.ts

@@ -13,7 +13,8 @@
  * {@link createHub} for others. Every call rejects with a {@link HubError}
  * when it fails, except the fire-and-forget analytics (`recordPlay`,
  * `heartbeat`, `event`). When the hub can't be reached, reads come from an
- * offline cache and writes are queued until it is back.
+ * offline cache and writes are queued in an outbox until it is back; games
+ * queue their own operations with `hub.offline` (docs: "Offline and replay").
  *
  * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
  * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
@@ -36,6 +37,10 @@ export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progres
 export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
 export type { HubMenuControl } from './core/menu-control';
 export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
+export { OfflineApi } from './core/offline/offline-api';
+export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';
+export type { OfflineHandler, OfflineKindDefinition, ReplayContext } from './core/offline/outbox-kinds';
+export { OUTBOX_MAX_CHARS, OUTBOX_MAX_ENTRIES } from './core/offline/outbox-store';
 export type { BufferedEvent } from './core/offline/events';
 export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
 export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';

package/src/input/focus-ring.ts

@@ -0,0 +1,13 @@
+/**
+ * The hub's focus ring: a two-tone box-shadow (a dark gap, then a light ring)
+ * that follows the element's own border-radius and shows on light and dark
+ * buttons alike. Pages tune it with CSS variables:
+ * `--hub-focus-color` (the ring), `--hub-focus-inner` (the gap),
+ * `--hub-focus-width` and `--hub-focus-gap`.
+ */
+
+const GAP = 'var(--hub-focus-gap, 2px)';
+const WIDTH = 'var(--hub-focus-width, 3px)';
+
+/** The ring as a `box-shadow` value. */
+export const FOCUS_RING_SHADOW = `0 0 0 ${GAP} var(--hub-focus-inner, rgba(13, 15, 20, 0.85)), 0 0 0 calc(${GAP} + ${WIDTH}) var(--hub-focus-color, #fff)`;

package/src/input/input-registry.ts

@@ -132,13 +132,20 @@ export class InputRegistry {
     return { value: raw, raw, isDown: this.wentDown(name), isUp: this.wentUp(name) };
   }
 
-  /** A named axis (or an ad-hoc negative/positive pair) as -1..1. */
+  /**
+   * A named axis (or an ad-hoc negative/positive pair) as -1..1: its `x`, or
+   * its `y` when it declares only `y` (a vertical one-axis control, like a
+   * paddle).
+   */
   axis(name: string, positive?: string): number {
     if (positive !== undefined) {
       return clampUnit(this.value(positive)) - clampUnit(this.value(name));
     }
     const axis = this.axes.get(name);
-    return axis === undefined ? this.value(name) : readAxisSide(axis.x, (input) => this.value(input));
+    if (axis === undefined) {
+      return this.value(name);
+    }
+    return readAxisSide(axis.x ?? axis.y, (input) => this.value(input));
   }
 
   /** A named axis pair as a vector clamped to the unit circle. */