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

package/src/core/hub-progress.ts

@@ -6,8 +6,11 @@
  */
 import type { Board, Json, Stats } from '@diffenderfer-games/hub-contract';
 import { HubConnection } from './connection';
+import { HubError, SAVE_UNKNOWN_CODE } from './errors';
 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 { pageAccount, toPageUser } from './page-account';
+import { isRecord } from './storage/json-guards';
 import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
 
 /** A signed-in user, as the auth calls answer. */
@@ -44,9 +47,30 @@ function typedSave<TData>(save: Save | null): Save<TData> | null {
 
 /** Accounts, profile, saves, stats and leaderboards. */
 export class HubProgress extends HubConnection {
+  /** Who the page is signed in as, as the hub's events and this client's sign-ins tell it. */
+  protected readonly account = pageAccount();
+
+  /**
+   * Your user id, or `null` when nobody is signed in (also before an offline
+   * first visit has an account). Synchronous, and it follows the account as
+   * the hub changes it (a new guest's account made by the menu, sign-in,
+   * sign-out) with no `hub.me()` needed. Compare it with a seat's `userId`
+   * to find yours.
+   */
+  userId(): number | null {
+    const heard = this.account.user;
+    const id = heard === undefined ? this.store.getUser()?.id ?? null : heard?.id ?? null;
+    // 0 is an offline local guest: no account on the hub yet.
+    return id === 0 ? null : id;
+  }
+
   /** The current user (or `null`) and the games they have a profile in. */
   me(): Promise<MeResponse> {
-    return this.withFallback(() => this.rest.call('getCurrentUser'), () => {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('getCurrentUser');
+      this.account.note(reply.user === null ? null : toPageUser(reply.user));
+      return reply;
+    }, () => {
       const profile = this.store.getProfile();
       return { user: this.store.getUser(), profiles: profile === null ? [] : [{ game: profile.game, displayName: profile.displayName }] };
     });
@@ -58,14 +82,12 @@ export class HubProgress extends HubConnection {
    * sign-in. Idempotent. Offline, a local guest is used.
    */
   ensureGuest(): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('ensureGuestSession'), () => {
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('ensureGuestSession')), () => {
       const known = this.store.getUser();
       if (known !== null) {
         return { user: known };
       }
-      const guest: User = { id: 0, username: 'Guest-local', guest: true };
-      this.store.setUser(guest);
-      return { user: guest };
+      return this.signInLocally({ id: 0, username: 'Guest-local', guest: true });
     });
   }
 
@@ -75,32 +97,53 @@ export class HubProgress extends HubConnection {
    * the name is taken; the player should `login` instead.
    */
   claim(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('claimGuestAccount', { username, password }), () => this.signInLocally({ id: 0, username, guest: false }));
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('claimGuestAccount', { username, password })), () => this.signInLocally({ id: 0, username, guest: false }));
   }
 
   /** Create an account and sign in. (Offline: a local user is stored.) */
   signup(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('signUpWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('signUpWithPassword', { username, password })), () => this.signInLocally({ id: 0, username }));
   }
 
   /** Sign in. (Offline: a local user is stored so signed-in flows work.) */
   login(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('logInWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('logInWithPassword', { username, password })), () => this.signInLocally({ id: 0, username }));
   }
 
   /** Sign out (ends the session shared by every game). */
   logout(): Promise<{ ok: true }> {
-    return this.withFallback(() => this.rest.call('logOut'), () => {
-      this.store.clearUser();
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('logOut');
+      this.signedOut();
+      return reply;
+    }, () => {
+      this.signedOut();
       return { ok: true } as const;
     });
   }
 
   private signInLocally(user: User): AuthResponse {
-    this.store.setUser(user);
+    this.remember(user);
     return { user };
   }
 
+  /** Remember who the hub signed in, so the cache's notes about the hub's copies are read for the right player. */
+  private signedIn(reply: AuthResponse): AuthResponse {
+    this.remember(reply.user);
+    return reply;
+  }
+
+  /** The cache and the page (`hub.userId()`, `hub.avatar`) learn who is signed in. */
+  private remember(user: User): void {
+    this.store.setUser(user);
+    this.account.note(toPageUser(user));
+  }
+
+  private signedOut(): void {
+    this.store.clearUser();
+    this.account.note(null);
+  }
+
   /** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
   getProfile<TData = Json>(): Promise<{ profile: Profile<TData> | null }> {
     return this.withFallback(
@@ -111,14 +154,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) } };
     });
@@ -129,24 +169,48 @@ export class HubProgress extends HubConnection {
     return this.withFallback(() => this.rest.call('listSaves', this.gameFields()), () => ({ saves: this.store.listSaves() }));
   }
 
-  /** One slot's contents, or `save: null` when the slot is empty. `TData` is the game's own save type. */
+  /**
+   * One slot's contents, or `save: null` when the slot is empty. `TData` is
+   * the game's own save type. Offline it answers from the device's copy, but
+   * only when the device knows the hub's copy of the slot; otherwise (a fresh
+   * device or cleared browser) it rejects with a {@link HubError} whose
+   * `code` is `save_unknown` (`isOffline` is `true`), never a false "empty".
+   */
   getSave<TData = Json>(slot: string): Promise<{ save: Save<TData> | null }> {
     return this.withFallback(
-      async () => ({ save: typedSave<TData>((await this.rest.call('getSave', { ...this.gameFields(), slot })).save) }),
-      () => ({ save: typedSave<TData>(this.store.getSave(slot)) }),
+      async () => {
+        const { save } = await this.rest.call('getSave', { ...this.gameFields(), slot });
+        if (this.outbox.count() === 0) {
+          this.store.cacheCloudSave(slot, save);
+        }
+        return { save: typedSave<TData>(save) };
+      },
+      () => ({ save: typedSave<TData>(this.offlineSave(slot)) }),
     );
   }
 
+  /** The device's copy of `slot`, when it can be trusted offline (see {@link getSave}). */
+  private offlineSave(slot: string): Save | null {
+    // Trusted: a slot whose hub copy the device has seen, a slot it wrote itself and hasn't sent
+    // yet, or any slot of a player signed in only on this device (offline, never reached the hub).
+    const isLocalOnly = this.store.getUser()?.id === 0;
+    const hasQueuedWrite = this.outbox.pending().some((op) => op.kind === PROGRESS_KINDS.save && isRecord(op.payload) && op.payload.slot === slot);
+    if (!isLocalOnly && !hasQueuedWrite && this.store.cloudSave(slot) === undefined) {
+      throw new HubError(`Hub: offline, and this device hasn't seen save "${slot}" yet.`, undefined, { code: SAVE_UNKNOWN_CODE });
+    }
+    return this.store.getSave(slot);
+  }
+
   /** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
   // 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 +226,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

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

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

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

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

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