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

package/src/core/connection.ts

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

package/src/core/game-data.ts

@@ -6,26 +6,28 @@
  * v1 client. These two functions are the only places that hand-over happens.
  */
 import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, parseJsonText } from './storage/json-guards';
 
 /** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
 export type GamePayload = object | string | number | boolean | null;
 
-/** Always true: a game's payload is sent as JSON (`JSON.stringify` drops what JSON can't hold). */
-function isSentAsJson(_payload: GamePayload): _payload is GamePayload & Json {
-  return true;
-}
-
 /** Always true: JSON the game stored is read back as the game's type. */
 function isGameOwnData<TData>(_stored: Json): _stored is Json & TData {
   return true;
 }
 
-/** A game's payload as the JSON the hub stores. */
+/**
+ * A game's payload as the JSON the hub stores: a copy of exactly what
+ * `JSON.stringify` sends, so an optional field left `undefined` is simply
+ * absent (as on the wire) and the outbox's payload checks accept it, and a
+ * later change to the game's object can't alter a queued write.
+ */
 export function toStoredJson(payload: GamePayload): Json {
-  if (isSentAsJson(payload)) {
-    return payload;
+  const stored = parseJsonText(JSON.stringify(payload));
+  if (isJson(stored)) {
+    return stored;
   }
-  throw new TypeError('unreachable: every payload is sent as JSON');
+  throw new TypeError('This value cannot be stored as JSON.');
 }
 
 /** JSON the game stored, typed as the game's own type. */

package/src/core/hub-economy.ts

@@ -4,9 +4,13 @@
  * offline they are buffered and sent when the hub is back. Method names are
  * the v1 client's, unchanged.
  */
+import type { Json } from '@diffenderfer-games/hub-contract';
 import { HubProgress } from './hub-progress';
 import { readLocalFavorites, writeLocalFavorites } from './offline/favorites';
+import { ECONOMY_KINDS, type ExchangePayload } from './offline/hub-kinds';
+import { readInventory, withGoods, withoutGoods, type GoodsPayload } from './offline/local-inventory';
 import { HubError } from './errors';
+import { isRecord, stringsIn } from './storage/json-guards';
 import type { EndpointFields, EndpointReply } from './rest/endpoint-types';
 import type { GameAnalytics, GameInfo, GlobalAnalytics, InventorySnapshot } from './types';
 
@@ -25,6 +29,18 @@ export interface TradeNoteOptions {
   readonly note?: string;
 }
 
+/** Goods as queued: `null` parts left out. */
+function goodsOf(bundle: TradeBundle | GrantBundle | undefined): GoodsPayload {
+  const items = bundle?.items ?? undefined;
+  const coins = bundle?.coins ?? undefined;
+  return { ...(items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+/** The holdings in a grant or exchange reply, or `undefined` when it doesn't read as one. */
+function inventoryReply(result: Json | undefined): InventorySnapshot | undefined {
+  return readInventory(result) ?? undefined;
+}
+
 /** Which trades `listTrades` lists. */
 export type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
 
@@ -92,11 +108,14 @@ export class HubEconomy extends HubProgress {
     }, () => ({ games: readLocalFavorites() }));
   }
 
-  /** Star (`isOn = true`) or unstar a game. Needs a connection. */
-  async setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
-    const reply = await this.rest.call('setGameFavorite', { slug, on: isOn });
-    writeLocalFavorites(reply.games);
-    return reply;
+  /** Star (`isOn = true`) or unstar a game. Offline, the local list changes at once and the hub's when it is back. */
+  setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
+    return this.mutateOffline(ECONOMY_KINDS.favorite, { slug, on: isOn }, () => {
+      const others = readLocalFavorites().filter((starred) => starred !== slug);
+      const games = isOn ? [...others, slug] : others;
+      writeLocalFavorites(games);
+      return { games };
+    }, (result) => (isRecord(result) ? { games: stringsIn(result.games) } : undefined));
   }
 
   /** The player's leaderboard standings, grouped by game (every game, or one via `forSlug`). Empty offline or signed out. */
@@ -109,7 +128,7 @@ export class HubEconomy extends HubProgress {
 
   /** This game's inventory and coin balance for the current user. */
   getInventory(): Promise<InventorySnapshot> {
-    return this.withFallback(() => this.rest.call('getMyInventory', this.gameFields()), () => ({ items: [], coins: 0 }));
+    return this.withFallback(async () => this.store.setInventory(await this.rest.call('getMyInventory', this.gameFields())), () => this.store.getInventory());
   }
 
   /** Another player's available holdings (to compose a trade). */
@@ -117,14 +136,32 @@ export class HubEconomy extends HubProgress {
     return this.withFallback(() => this.rest.call('getPlayerInventory', { ...this.gameFields(), userId }), () => ({ items: [], coins: 0 }));
   }
 
-  /** Add goods to the player (gameplay rewards); answers the new holdings. */
+  /**
+   * Add goods to the player (gameplay rewards); answers the new holdings.
+   * Offline, the cached holdings change at once and the grant replays later.
+   */
   grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>> {
-    return this.rest.call('grantInventoryItems', { ...this.gameFields(), ...bundle });
+    const goods = goodsOf(bundle);
+    return this.mutateOffline(ECONOMY_KINDS.grant, goods, () => this.store.setInventory(withGoods(this.store.getInventory(), goods)), inventoryReply);
   }
 
-  /** An atomic swap with the house: remove `take`, add `give`. */
+  /**
+   * An atomic swap with the house: remove `take`, add `give`. Offline it is
+   * checked against the cached holdings (409 when they can't cover `take`),
+   * applied to them at once, and replayed later; the hub has the last word.
+   */
   exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>> {
-    return this.rest.call('exchangeInventoryItems', { ...this.gameFields(), ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) });
+    const payload: ExchangePayload = { ...(take === undefined ? {} : { take: goodsOf(take) }), ...(give === undefined ? {} : { give: goodsOf(give) }) };
+    return this.mutateOffline(ECONOMY_KINDS.exchange, payload, () => {
+      const remaining = withoutGoods(this.store.getInventory(), payload.take ?? {});
+      if (typeof remaining === 'string') {
+        if (this.isOffline) {
+          throw new HubError(remaining, 409);
+        }
+        return this.store.getInventory();
+      }
+      return this.store.setInventory(withGoods(remaining, payload.give ?? {}));
+    }, inventoryReply);
   }
 
   /** Sell items to the house for coins. */

package/src/core/hub-progress.ts

@@ -7,7 +7,7 @@
 import type { Board, Json, Stats } from '@diffenderfer-games/hub-contract';
 import { HubConnection } from './connection';
 import { toGameData, toStoredJson, type GamePayload } from './game-data';
-import type { ProfilePatch, QueuedScoreOptions } from './offline/queue';
+import { PROGRESS_KINDS, type ProfilePayload, type ScorePayload } from './offline/hub-kinds';
 import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
 
 /** A signed-in user, as the auth calls answer. */
@@ -111,14 +111,11 @@ export class HubProgress extends HubConnection {
 
   /** Create or update this game's profile for the current user. */
   setProfile<TData extends GamePayload = Json>(patch: ProfileUpdate<TData>): Promise<{ profile: Profile<TData> }> {
-    const queued: ProfilePatch = {};
-    if (patch.displayName !== undefined) {
-      queued.displayName = patch.displayName;
-    }
-    if (patch.data !== undefined) {
-      queued.data = toStoredJson(patch.data);
-    }
-    return this.mutateQueued({ kind: 'setProfile', patch: queued }, () => {
+    const queued: ProfilePayload = {
+      ...(patch.displayName === undefined ? {} : { displayName: patch.displayName }),
+      ...(patch.data === undefined ? {} : { data: toStoredJson(patch.data) }),
+    };
+    return this.mutateOffline(PROGRESS_KINDS.profile, queued, () => {
       const stored = this.store.setProfile(this.slug ?? 'app', patch.displayName ?? null, queued.data ?? {});
       return { profile: { ...stored, data: toGameData<TData>(stored.data) } };
     });
@@ -141,12 +138,12 @@ export class HubProgress extends HubConnection {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- kept so v1 calls such as putSave<MySave>(...) still compile
   putSave<TData extends GamePayload = Json>(slot: string, saveData: TData, label?: string): Promise<{ ok: true; updatedAt: number }> {
     const stored = toStoredJson(saveData);
-    return this.mutateQueued({ kind: 'putSave', slot, data: stored, label: label ?? null }, () => ({ ok: true as const, updatedAt: this.store.putSave(slot, stored, label ?? null) }));
+    return this.mutateOffline(PROGRESS_KINDS.save, { slot, data: stored, label: label ?? null }, () => ({ ok: true as const, updatedAt: this.store.putSave(slot, stored, label ?? null) }));
   }
 
   /** Delete a save slot. */
   deleteSave(slot: string): Promise<{ ok: true }> {
-    return this.mutateQueued({ kind: 'deleteSave', slot }, () => {
+    return this.mutateOffline(PROGRESS_KINDS.save, { slot, deleted: true }, () => {
       this.store.deleteSave(slot);
       return { ok: true as const };
     });
@@ -162,27 +159,27 @@ export class HubProgress extends HubConnection {
 
   /** Overwrite a stat. */
   setStat(key: string, value: number): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'setStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'set') }));
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'set', value }, () => ({ key, value: this.store.updateStat(key, value, 'set') }));
   }
 
   /** Add to a stat (creating it at `amount` when absent). */
   incrStat(key: string, amount = 1): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'incrStat', key, amount }, () => ({ key, value: this.store.updateStat(key, amount, 'incr') }));
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'incr', value: amount }, () => ({ key, value: this.store.updateStat(key, amount, 'incr') }));
   }
 
   /** Keep the larger of the stored and the given value. */
   maxStat(key: string, value: number): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'maxStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'max') }));
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'max', value }, () => ({ key, value: this.store.updateStat(key, value, 'max') }));
   }
 
   /** Submit a score. The board is created on first use; only a player's best score sticks. */
   submitScore<TMeta extends GamePayload = Json>(boardKey: string, score: number, opts: SubmitScoreOptions<TMeta> = {}): Promise<SubmitScoreResult> {
-    const queued: QueuedScoreOptions = {
+    const queued: ScorePayload['opts'] = {
       ...(opts.title === undefined ? {} : { title: opts.title }),
       ...(opts.sort === undefined ? {} : { sort: opts.sort }),
       ...(opts.meta === undefined ? {} : { meta: toStoredJson(opts.meta) }),
     };
-    return this.mutateQueued({ kind: 'submitScore', key: boardKey, score, opts: queued }, () => ({ ...this.store.submitScore(boardKey, score, queued), rank: 1 }));
+    return this.mutateOffline(PROGRESS_KINDS.score, { key: boardKey, score, opts: queued }, () => ({ ...this.store.submitScore(boardKey, score, queued), rank: 1 }));
   }
 
   /** One board's ranked entries (top `limit`, default 50). Offline: only the player's own best. */

package/src/core/hub.ts

@@ -5,7 +5,7 @@
  * `hub.race`, ...), so v1 code such as `hub.input.define(...)` works unchanged.
  */
 import type { HubVersion } from '@diffenderfer-games/hub-contract';
-import { getDaily, type DailyHost, type DailySystem } from '../daily';
+import { getDaily, type DailyCompleteResponse, type DailyHost, type DailySystem } from '../daily';
 import { getInput, getUiStack, type InputSystem } from '../input';
 import { mp } from '../mp';
 import { race } from '../race';
@@ -13,6 +13,8 @@ import { rooms } from '../rooms';
 import { linkRealtimeToHub, notify, presence, social } from '../social';
 import { OfflineError, toHubError } from './errors';
 import { HubEconomy } from './hub-economy';
+import { DAILY_KIND } from './offline/hub-kinds';
+import { readDailyCompletion } from './offline/hub-kinds/daily-kind';
 import { hubMenu, type HubMenuControl } from './menu-control';
 import { emitWindowEvent } from './page';
 import { fetchGameServerTicket } from './ticket';
@@ -108,7 +110,7 @@ export class Hub extends HubEconomy {
       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.rest.call('completeDailyChallenge', { ...this.gameFields(), day, token, meta }),
+      complete: (day, token, meta) => this.mutateOffline<DailyCompleteResponse | null>(DAILY_KIND, { day, token, meta }, () => null, (result) => readDailyCompletion(result)),
       emit: (eventName, detail) => {
         emitWindowEvent(eventName, detail);
       },