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

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

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

package/src/core/offline/events.ts

@@ -1,50 +1,50 @@
-/**
- * Analytics events recorded while offline (`play`, `heartbeat`, custom
- * events), kept under `hub:<slug>:events` and sent when the hub is back.
- * The buffer is capped; heartbeats are dropped first, then the oldest.
- */
-import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
-
-/** The most events kept while offline. */
-export const EVENT_BUFFER_CAP = 100;
-
-/** One buffered event. */
-export interface BufferedEvent {
-  /** The event type, as `recordGameEvent` sends it. */
-  readonly type: string;
-  /** When it happened (epoch ms). */
-  readonly ts: number;
-}
-
-/** The well-formed events of a stored buffer. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a buffer read back from localStorage (possibly written by a v1 client)
-export function readEvents(stored: unknown): BufferedEvent[] {
-  if (!Array.isArray(stored)) {
-    return [];
-  }
-  return stored.flatMap((entry): BufferedEvent[] => {
-    if (!isRecord(entry)) {
-      return [];
-    }
-    const type = optionalString(entry.type);
-    const ts = optionalNumber(entry.ts);
-    return type === undefined || ts === undefined ? [] : [{ type, ts }];
-  });
-}
-
-/** The buffer with one more event, trimmed to {@link EVENT_BUFFER_CAP}: oldest heartbeats go first, then the oldest events. */
-export function appendEvent(events: readonly BufferedEvent[], incoming: BufferedEvent): BufferedEvent[] {
-  let buffered = [...events, incoming];
-  let excess = buffered.length - EVENT_BUFFER_CAP;
-  if (excess <= 0) {
-    return buffered;
-  }
-  buffered = buffered.filter((event) => {
-    if (excess > 0 && event.type === 'heartbeat') {
-      excess -= 1;
-      return false;
-    }
-    return true;
-  });
-  return buffered.length > EVENT_BUFFER_CAP ? buffered.slice(buffered.length - EVENT_BUFFER_CAP) : buffered;
-}
+/**
+ * Analytics events recorded while offline (`play`, `heartbeat`, custom
+ * events), kept under `hub:<slug>:events` and sent when the hub is back.
+ * The buffer is capped; heartbeats are dropped first, then the oldest.
+ */
+import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
+
+/** The most events kept while offline. */
+export const EVENT_BUFFER_CAP = 100;
+
+/** One buffered event. */
+export interface BufferedEvent {
+  /** The event type, as `recordGameEvent` sends it. */
+  readonly type: string;
+  /** When it happened (epoch ms). */
+  readonly ts: number;
+}
+
+/** The well-formed events of a stored buffer. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a buffer read back from localStorage (possibly written by a v1 client)
+export function readEvents(stored: unknown): BufferedEvent[] {
+  if (!Array.isArray(stored)) {
+    return [];
+  }
+  return stored.flatMap((entry): BufferedEvent[] => {
+    if (!isRecord(entry)) {
+      return [];
+    }
+    const type = optionalString(entry.type);
+    const ts = optionalNumber(entry.ts);
+    return type === undefined || ts === undefined ? [] : [{ type, ts }];
+  });
+}
+
+/** The buffer with one more event, trimmed to {@link EVENT_BUFFER_CAP}: oldest heartbeats go first, then the oldest events. */
+export function appendEvent(events: readonly BufferedEvent[], incoming: BufferedEvent): BufferedEvent[] {
+  let buffered = [...events, incoming];
+  let excess = buffered.length - EVENT_BUFFER_CAP;
+  if (excess <= 0) {
+    return buffered;
+  }
+  buffered = buffered.filter((event) => {
+    if (excess > 0 && event.type === 'heartbeat') {
+      excess -= 1;
+      return false;
+    }
+    return true;
+  });
+  return buffered.length > EVENT_BUFFER_CAP ? buffered.slice(buffered.length - EVENT_BUFFER_CAP) : buffered;
+}

package/src/core/offline/favorites.ts

@@ -1,21 +1,21 @@
-/**
- * Starred games are site-wide, not per game, so they live under one global
- * key (`hub:favorites`, the v1 client's) rather than in a game's cache. The
- * list mirrors the hub's so the menu still shows it offline.
- */
-import { parseJsonText, stringsIn } from '../storage/json-guards';
-import { createPageStore } from '../storage/key-value';
-
-/** The key of the mirrored favorites list. */
-export const FAVORITES_KEY = 'hub:favorites';
-
-/** The mirrored favorite slugs (empty when none or unreadable). */
-export function readLocalFavorites(): string[] {
-  const text = createPageStore().read(FAVORITES_KEY);
-  return text === null ? [] : stringsIn(parseJsonText(text));
-}
-
-/** Mirror the hub's favorites list. */
-export function writeLocalFavorites(games: readonly string[]): void {
-  createPageStore().write(FAVORITES_KEY, JSON.stringify(games));
-}
+/**
+ * Starred games are site-wide, not per game, so they live under one global
+ * key (`hub:favorites`, the v1 client's) rather than in a game's cache. The
+ * list mirrors the hub's so the menu still shows it offline.
+ */
+import { parseJsonText, stringsIn } from '../storage/json-guards';
+import { createPageStore } from '../storage/key-value';
+
+/** The key of the mirrored favorites list. */
+export const FAVORITES_KEY = 'hub:favorites';
+
+/** The mirrored favorite slugs (empty when none or unreadable). */
+export function readLocalFavorites(): string[] {
+  const text = createPageStore().read(FAVORITES_KEY);
+  return text === null ? [] : stringsIn(parseJsonText(text));
+}
+
+/** Mirror the hub's favorites list. */
+export function writeLocalFavorites(games: readonly string[]): void {
+  createPageStore().write(FAVORITES_KEY, JSON.stringify(games));
+}

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

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

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

@@ -0,0 +1,68 @@
+/**
+ * The hub's daily kind, a composite op: complete a day with the token the
+ * game started it with; when that token has expired by the time the op
+ * replays (401), start the day again for a fresh token and complete with
+ * that. The completion is replayable, so a retry after a lost reply never
+ * records it twice. A completion sent at once (online) is reported by the
+ * daily system itself; one that replays later is reported here.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { EndpointReply } from '../../rest/endpoint-types';
+import { isJsonObject, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** One daily completion. */
+export type DailyPayload = { readonly day: string; readonly token: string; readonly meta: { readonly [key: string]: Json } };
+
+/** The kind name. */
+export const DAILY_KIND = 'hub.daily';
+
+/** What a completion answers. */
+export type DailyCompletion = EndpointReply<'completeDailyChallenge'>;
+
+function readDaily(stored: Json): DailyPayload | undefined {
+  if (!isRecord(stored) || !isJsonObject(stored.meta)) {
+    return undefined;
+  }
+  const day = optionalString(stored.day);
+  const token = optionalString(stored.token);
+  return day === undefined || token === undefined ? undefined : { day, token, meta: stored.meta };
+}
+
+/** A completion reply read back, or `undefined` when it doesn't read as one. */
+export function readDailyCompletion(result: Json | undefined): DailyCompletion | undefined {
+  if (!isRecord(result) || result.ok !== true) {
+    return undefined;
+  }
+  const day = optionalString(result.day);
+  const count = optionalNumber(result.count);
+  const rank = result.rank === null ? null : optionalNumber(result.rank);
+  return day === undefined || count === undefined || rank === undefined ? undefined : { ok: true, day, count, rank };
+}
+
+/** The daily kind, by name; `onCompleted` hears each completion that lands from the queue. */
+export function dailyKinds(game: GameFieldsSource, onCompleted: (payload: DailyPayload, completion: DailyCompletion) => void): Record<string, RegisteredKind> {
+  return {
+    [DAILY_KIND]: checkedKind(readDaily, {
+      run: async ({ day, token, meta }, context) => {
+        let completion: DailyCompletion;
+        try {
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token, meta });
+        } catch (failure) {
+          if (!(failure instanceof HubError) || failure.status !== 401) {
+            throw failure;
+          }
+          const started = await context.call('startDailyChallenge', { ...game(), day });
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token: started.token, meta });
+        }
+        if (context.isReplay) {
+          onCompleted({ day, token, meta }, completion);
+        }
+        return completion;
+      },
+    }),
+  };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The hub's economy and catalog kinds: inventory grants and house
+ * exchanges (each one replayable call, never folded: every grant counts),
+ * and starring a game (a game's last star or unstar wins).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { GoodsPayload } from '../local-inventory';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** A house exchange: what the player gives up and gets. */
+export type ExchangePayload = { readonly take?: GoodsPayload; readonly give?: GoodsPayload };
+
+/** A star or unstar. */
+export type FavoritePayload = { readonly slug: string; readonly on: boolean };
+
+/** The kind names. */
+export const ECONOMY_KINDS = { grant: 'hub.grant', exchange: 'hub.exchange', favorite: 'hub.favorite' } as const;
+
+/** Goods read back, or `undefined` when malformed. */
+export function readGoods(stored: Json | undefined): GoodsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const coins = stored.coins === undefined ? undefined : optionalNumber(stored.coins);
+  if (stored.coins !== undefined && coins === undefined) {
+    return undefined;
+  }
+  const items: Record<string, number> = {};
+  if (stored.items !== undefined) {
+    if (!isRecord(stored.items)) {
+      return undefined;
+    }
+    for (const [key, qty] of Object.entries(stored.items)) {
+      const count = optionalNumber(qty);
+      if (count === undefined) {
+        return undefined;
+      }
+      items[key] = count;
+    }
+  }
+  return { ...(stored.items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+function readExchange(stored: Json): ExchangePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const take = stored.take === undefined ? undefined : readGoods(stored.take);
+  const give = stored.give === undefined ? undefined : readGoods(stored.give);
+  if ((stored.take !== undefined && take === undefined) || (stored.give !== undefined && give === undefined)) {
+    return undefined;
+  }
+  return { ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) };
+}
+
+function readFavorite(stored: Json): FavoritePayload | undefined {
+  if (!isRecord(stored) || typeof stored.on !== 'boolean') {
+    return undefined;
+  }
+  const slug = optionalString(stored.slug);
+  return slug === undefined ? undefined : { slug, on: stored.on };
+}
+
+/** The economy kinds, by name; `onFavorites` hears the starred list each star answers with. */
+export function economyKinds(game: GameFieldsSource, onFavorites: (games: string[]) => void): Record<string, RegisteredKind> {
+  return {
+    [ECONOMY_KINDS.grant]: checkedKind(readGoods, {
+      run: (goods, context) => context.call('grantInventoryItems', { ...game(), ...goods }),
+    }),
+    [ECONOMY_KINDS.exchange]: checkedKind(readExchange, {
+      run: (exchange, context) => context.call('exchangeInventoryItems', { ...game(), ...exchange }),
+    }),
+    [ECONOMY_KINDS.favorite]: checkedKind(readFavorite, {
+      mergeKey: (favorite) => favorite.slug,
+      replaces: true,
+      run: async (favorite, context) => {
+        const reply = await context.call('setGameFavorite', { slug: favorite.slug, on: favorite.on });
+        onFavorites(reply.games);
+        return reply;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/game-fields.ts

@@ -0,0 +1,2 @@
+/** The `{ slug }` path field the hub kinds' calls need, read when they run (it throws when the slug is unknown). */
+export type GameFieldsSource = () => { readonly slug: string };

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

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

package/src/core/offline/hub-kinds/legacy-ops.ts

@@ -0,0 +1,37 @@
+/**
+ * The v1 client's queued writes (`hub:<slug>:queue`) as outbox operations,
+ * so a page upgraded from a vendored copy still replays what that copy queued.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { QueueOp } from '../queue';
+import { PROGRESS_KINDS, readProfile, readScoreOptions } from './progress-kinds';
+
+/** One outbox operation, before it is stamped. */
+export interface KindedPayload {
+  readonly kind: string;
+  readonly payload: Json;
+}
+
+/** The outbox operation for a v1 queued write, or `undefined` when it no longer reads as one. */
+export function legacyOperation(op: QueueOp): KindedPayload | undefined {
+  switch (op.kind) {
+    case 'putSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, data: op.data, label: op.label } };
+    case 'deleteSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, deleted: true } };
+    case 'setStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'set', value: op.value } };
+    case 'maxStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'max', value: op.value } };
+    case 'incrStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'incr', value: op.amount } };
+    case 'submitScore': {
+      const opts = readScoreOptions({ ...op.opts });
+      return opts === undefined ? undefined : { kind: PROGRESS_KINDS.score, payload: { key: op.key, score: op.score, opts } };
+    }
+    case 'setProfile': {
+      const patch = readProfile({ ...op.patch });
+      return patch === undefined ? undefined : { kind: PROGRESS_KINDS.profile, payload: patch };
+    }
+  }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * The hub's progress kinds: saves, stats, scores and the game profile. Each
+ * is one replayable call, and each folds new writes into waiting ones so the
+ * backlog stays small: a save slot's last write wins, `incr`s add up, `max`es
+ * keep the largest, `set`s keep the last, a board keeps its best, and profile
+ * patches merge.
+ */
+import type { Json, SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import { betterScore } from '../queue';
+import type { GameFieldsSource } from './game-fields';
+
+/** What the save kind reads and records about the hub's copy of a slot (`LocalStore`). */
+export interface CloudSaveTracker {
+  /** The hub's `updatedAt` for `slot` as this device last saw it (`null`: empty), or `undefined` when it doesn't know. */
+  cloudSave(slot: string): number | null | undefined;
+  /** Note the hub's copy of `slot` after a write landed: its `updatedAt`, or `null` once deleted. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void;
+}
+
+/** A save slot write: new contents, or a delete. */
+export type SavePayload =
+  | { readonly slot: string; readonly data: Json; readonly label: string | null }
+  | { readonly slot: string; readonly deleted: true };
+
+/** How a stat update combines with the stored value. */
+export type StatMode = 'set' | 'incr' | 'max';
+
+/** One stat update. */
+export type StatPayload = { readonly key: string; readonly mode: StatMode; readonly value: number };
+
+/** A score's board options, as queued. */
+export type ScoreOptionsPayload = { readonly title?: string; readonly sort?: SortDir; readonly meta?: Json };
+
+/** One score submission. */
+export type ScorePayload = { readonly key: string; readonly score: number; readonly opts: ScoreOptionsPayload };
+
+/** A profile change; either part may be left out. */
+export type ProfilePayload = { readonly displayName?: string | null; readonly data?: Json };
+
+/** The kind names. */
+export const PROGRESS_KINDS = { save: 'hub.save', stat: 'hub.stat', score: 'hub.score', profile: 'hub.profile' } as const;
+
+function readSave(stored: Json): SavePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const slot = optionalString(stored.slot);
+  if (slot === undefined) {
+    return undefined;
+  }
+  if (stored.deleted === true) {
+    return { slot, deleted: true };
+  }
+  return isJson(stored.data) && isNullableString(stored.label) ? { slot, data: stored.data, label: stored.label } : undefined;
+}
+
+function readStat(stored: Json): StatPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const value = optionalNumber(stored.value);
+  const mode = stored.mode === 'set' || stored.mode === 'incr' || stored.mode === 'max' ? stored.mode : undefined;
+  return key === undefined || value === undefined || mode === undefined ? undefined : { key, mode, value };
+}
+
+/** Score options read back, or `undefined` when malformed. */
+export function readScoreOptions(stored: Json): ScoreOptionsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+function readScore(stored: Json): ScorePayload | undefined {
+  if (!isRecord(stored) || !isJson(stored.opts)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const score = optionalNumber(stored.score);
+  const opts = readScoreOptions(stored.opts);
+  return key === undefined || score === undefined || opts === undefined ? undefined : { key, score, opts };
+}
+
+/** A profile patch read back, or `undefined` when malformed. */
+export function readProfile(stored: Json): ProfilePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const { displayName, data: profileData } = stored;
+  if ((displayName !== undefined && !isNullableString(displayName)) || (profileData !== undefined && !isJson(profileData))) {
+    return undefined;
+  }
+  return { ...(displayName === undefined ? {} : { displayName }), ...(profileData === undefined ? {} : { data: profileData }) };
+}
+
+/** Two waiting stat updates of one key folded together, or `undefined` when their modes differ. */
+export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPayload | undefined {
+  if (waiting.mode !== incoming.mode) {
+    return undefined;
+  }
+  switch (incoming.mode) {
+    case 'incr':
+      return { ...waiting, value: waiting.value + incoming.value };
+    case 'max':
+      return { ...waiting, value: Math.max(waiting.value, incoming.value) };
+    case 'set':
+      return incoming;
+  }
+}
+
+/**
+ * The progress kinds, by name. A save write replayed from the queue sends
+ * the hub's `updatedAt` this device last saw for the slot (`null` when it
+ * saw it empty or never saw it), so the hub refuses it (409 `save_conflict`,
+ * dropped and reported as a conflict) when another device saved since. A
+ * write sent at once, online, always lands, as before.
+ */
+export function progressKinds(game: GameFieldsSource, cloudSaves: CloudSaveTracker): Record<string, RegisteredKind> {
+  return {
+    [PROGRESS_KINDS.save]: checkedKind(readSave, {
+      mergeKey: (save) => save.slot,
+      replaces: true,
+      run: async (save, context) => {
+        if ('deleted' in save) {
+          await context.call('deleteSave', { ...game(), slot: save.slot });
+          cloudSaves.rememberCloudSave(save.slot, null);
+          return;
+        }
+        const base = context.isReplay ? { base: cloudSaves.cloudSave(save.slot) ?? null } : {};
+        const written = await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label, ...base });
+        cloudSaves.rememberCloudSave(save.slot, written.updatedAt);
+      },
+    }),
+    [PROGRESS_KINDS.stat]: checkedKind(readStat, {
+      mergeKey: (stat) => stat.key,
+      merge: mergeStats,
+      run: async (stat, context) => {
+        await context.call('updateGameStat', { ...game(), key: stat.key, value: stat.value, mode: stat.mode });
+      },
+    }),
+    [PROGRESS_KINDS.score]: checkedKind(readScore, {
+      mergeKey: (submission) => submission.key,
+      merge: (waiting, incoming) => ({ ...waiting, score: betterScore(waiting.score, incoming.score, incoming.opts.sort), opts: incoming.opts }),
+      run: async (submission, context) => {
+        await context.call('submitScore', { ...game(), key: submission.key, score: submission.score, ...submission.opts });
+      },
+    }),
+    [PROGRESS_KINDS.profile]: checkedKind(readProfile, {
+      mergeKey: () => 'profile',
+      merge: (waiting, incoming) => ({ ...waiting, ...incoming }),
+      run: async (patch, context) => {
+        await context.call('setGameProfile', { ...game(), ...patch });
+      },
+    }),
+  };
+}