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

package/src/core/hub.ts

@@ -1,131 +1,352 @@
-/**
- * The `Hub` client: every REST method (in `hub-progress.ts` and
- * `hub-economy.ts`), the hub's version, and the page-wide namespaces as lazy
- * 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 { getInput, getUiStack, type InputSystem } from '../input';
-import { mp } from '../mp';
-import { race } from '../race';
-import { rooms } from '../rooms';
-import { linkRealtimeToHub, notify, presence, social } from '../social';
-import { OfflineError, toHubError } from './errors';
-import { HubEconomy } from './hub-economy';
-import { hubMenu, type HubMenuControl } from './menu-control';
-import { emitWindowEvent } from './page';
-import { fetchGameServerTicket } from './ticket';
-import { clientSupport, readHubVersion, type ClientSupport } from './version/hub-version';
-import { HUB_CLIENT_VERSION } from './version/client-version.gen';
-import type { HubOptions } from './types';
-
-/** The hub client. Use the ready-made {@link hub}, or `createHub()` for another slug or API base. */
-export class Hub extends HubEconomy {
-  /** This client's package version (sent as `x-hub-client`). */
-  readonly clientVersion: string = HUB_CLIENT_VERSION;
-
-  /**
-   * The hub's version and the client versions it supports (`GET /_api/version`),
-   * read once per page. `null` for a hub from before versioning.
-   */
-  hubVersion(): Promise<HubVersion | null> {
-    return readHubVersion(this.rest);
-  }
-
-  /** How the hub regards this client: `supported`, `deprecated`, `unsupported`, or `unknown` (an older hub). */
-  async clientSupport(): Promise<ClientSupport> {
-    return clientSupport(await this.hubVersion());
-  }
-
-  /**
-   * The input system (keyboard, touch and gamepad): `hub.input.define({ ... })`,
-   * `hub.input.value('jump')`. Page-wide; remaps are saved locally and to the
-   * reserved `__controls` save slot.
-   */
-  get input(): InputSystem {
-    return getInput({
-      slug: this.slug,
-      saveToCloud: (overrides) => {
-        void this.putSave('__controls', overrides).catch(() => undefined);
-      },
-    });
-  }
-
-  /** Hub UI covering the game (menu, dialogs, chat): open/close events and `autoPause`. Page-wide. */
-  get overlay(): ReturnType<typeof getUiStack> {
-    return getUiStack();
-  }
-
-  /** Show or hide the injected hub menu button (page-wide). */
-  get menu(): HubMenuControl {
-    return hubMenu;
-  }
-
-  /**
-   * Daily challenges: call `hub.daily.define({ play })` once at load and
-   * `hub.daily.complete({ ... })` on finish. Page-wide, shared with the
-   * injected menu, which can start a clicked day on the same instance.
-   */
-  get daily(): DailySystem {
-    return getDaily(this.dailyHost());
-  }
-
-  /** Tell friends what the player is doing in this game. */
-  get presence(): typeof presence {
-    return presence;
-  }
-
-  /** Friends, players and the hub's social dialogs. */
-  get social(): typeof social {
-    return social;
-  }
-
-  /** Invites, launches, the leave guard and own-server tickets. */
-  get mp(): typeof mp {
-    return mp;
-  }
-
-  /** Hub relay rooms, for games without a server. */
-  get rooms(): typeof rooms {
-    return rooms;
-  }
-
-  /** Toast behaviour during intense play. */
-  get notify(): typeof notify {
-    return notify;
-  }
-
-  /** Races: a single-player game becomes multiplayer by racing. */
-  get race(): typeof race {
-    return race;
-  }
-
-  /** What the daily system needs from this client: its REST calls 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 }),
-      emit: (eventName, detail) => {
-        emitWindowEvent(eventName, detail);
-      },
-    };
-  }
-}
-
-linkRealtimeToHub({
-  toHubError,
-  createOfflineError: (message) => new OfflineError(message),
-  getGameServerTicket: fetchGameServerTicket,
-});
-
-/** A ready-to-use client, with the slug and API base detected from the page. */
-export const hub: Hub = new Hub();
-
-/** Create a client for another slug or API base, or with other offline behaviour. */
-export function createHub(options: HubOptions = {}): Hub {
-  return new Hub(options);
-}
+/**
+ * The `Hub` client: every REST method (in `hub-progress.ts` and
+ * `hub-economy.ts`), the hub's version, and the page-wide namespaces as lazy
+ * 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, 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 { 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 { 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';
+import type { HubOptions } from './types';
+
+/** The hub client. Use the ready-made {@link hub}, or `createHub()` for another slug or API base. */
+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.
+   */
+  hubVersion(): Promise<HubVersion | null> {
+    return readHubVersion(this.rest);
+  }
+
+  /** How the hub regards this client: `supported`, `deprecated`, `unsupported`, or `unknown` (an older hub). */
+  async clientSupport(): Promise<ClientSupport> {
+    return clientSupport(await this.hubVersion());
+  }
+
+  /**
+   * The input system (keyboard, touch and gamepad): `hub.input.define({ ... })`,
+   * `hub.input.value('jump')`. Page-wide; remaps are saved locally and to the
+   * reserved `__controls` save slot.
+   */
+  get input(): InputSystem {
+    return getInput({
+      slug: this.slug,
+      saveToCloud: (overrides) => {
+        void this.putSave('__controls', overrides).catch(() => undefined);
+      },
+    });
+  }
+
+  /** Hub UI covering the game (menu, dialogs, chat): open/close events and `autoPause`. Page-wide. */
+  get overlay(): ReturnType<typeof getUiStack> {
+    return getUiStack();
+  }
+
+  /** Show or hide the injected hub menu button (page-wide). */
+  get menu(): HubMenuControl {
+    return hubMenu;
+  }
+
+  /**
+   * Daily challenges: call `hub.daily.define({ play })` once at load and
+   * `hub.daily.complete({ ... })` on finish. Page-wide, shared with the
+   * injected menu, which can start a clicked day on the same instance.
+   */
+  get daily(): DailySystem {
+    return getDaily(this.dailyHost());
+  }
+
+  /** Tell friends what the player is doing in this game. */
+  get presence(): typeof presence {
+    return presence;
+  }
+
+  /** Friends, players and the hub's social dialogs. */
+  get social(): typeof social {
+    return social;
+  }
+
+  /** Invites, launches, the leave guard and own-server tickets. */
+  get mp(): typeof mp {
+    return mp;
+  }
+
+  /** Hub relay rooms, for games without a server. */
+  get rooms(): typeof rooms {
+    return rooms;
+  }
+
+  /** Toast behaviour during intense play. */
+  get notify(): typeof notify {
+    return notify;
+  }
+
+  /** Races: a single-player game becomes multiplayer by racing. */
+  get race(): typeof race {
+    return race;
+  }
+
+  /**
+   * 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.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);
+      },
+    };
+  }
+}
+
+linkRealtimeToHub({
+  toHubError,
+  createOfflineError: (message) => new OfflineError(message),
+  getGameServerTicket: fetchGameServerTicket,
+});
+
+/** 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/menu-control.ts

@@ -1,61 +1,61 @@
-/**
- * `hub.menu`: show or hide the injected hub menu button. The menu
- * (`/_hub/menu.js`) may load before or after the game, and the game may
- * bundle its own client copy, so the shared state is a window global and a
- * window event rather than an object:
- *
- * - `window.__HUB_MENU_VISIBLE__` (boolean; absent means visible);
- * - `hub:menu-visibility` (`CustomEvent`, detail `{ visible }`).
- *
- * The menu reads the global on boot and listens for the event.
- */
-import { emitWindowEvent, isBrowserPage } from './page';
-
-declare global {
-  interface Window {
-    /** The last requested menu-button visibility (absent: visible). */
-    __HUB_MENU_VISIBLE__?: boolean;
-  }
-}
-
-/** Control over the injected hub menu button. */
-export interface HubMenuControl {
-  /**
-   * Show (`true`) or hide (`false`) the menu button. Hidden means faded out,
-   * not focusable and `aria-hidden`; an open drawer stays open until closed,
-   * and the gamepad Select button still opens it. A small corner hotspot
-   * peeks it back for a few seconds on hover or tap, so players can always
-   * reach it.
-   */
-  setVisible(isVisible: boolean): void;
-  /** Show the menu button. */
-  show(): void;
-  /** Hide the menu button. */
-  hide(): void;
-  /** The last requested visibility (`true` unless a game hid it). */
-  readonly visible: boolean;
-}
-
-/** The page's menu control (one per page; every client copy shares the window state). */
-export const hubMenu: HubMenuControl = {
-  setVisible(isVisible: boolean): void {
-    if (!isBrowserPage()) {
-      return;
-    }
-    const wasVisible = window.__HUB_MENU_VISIBLE__;
-    if (wasVisible === isVisible || (wasVisible === undefined && isVisible)) {
-      return;
-    }
-    window.__HUB_MENU_VISIBLE__ = isVisible;
-    emitWindowEvent('hub:menu-visibility', { visible: isVisible });
-  },
-  show(): void {
-    hubMenu.setVisible(true);
-  },
-  hide(): void {
-    hubMenu.setVisible(false);
-  },
-  get visible(): boolean {
-    return !isBrowserPage() || window.__HUB_MENU_VISIBLE__ !== false;
-  },
-};
+/**
+ * `hub.menu`: show or hide the injected hub menu button. The menu
+ * (`/_hub/menu.js`) may load before or after the game, and the game may
+ * bundle its own client copy, so the shared state is a window global and a
+ * window event rather than an object:
+ *
+ * - `window.__HUB_MENU_VISIBLE__` (boolean; absent means visible);
+ * - `hub:menu-visibility` (`CustomEvent`, detail `{ visible }`).
+ *
+ * The menu reads the global on boot and listens for the event.
+ */
+import { emitWindowEvent, isBrowserPage } from './page';
+
+declare global {
+  interface Window {
+    /** The last requested menu-button visibility (absent: visible). */
+    __HUB_MENU_VISIBLE__?: boolean;
+  }
+}
+
+/** Control over the injected hub menu button. */
+export interface HubMenuControl {
+  /**
+   * Show (`true`) or hide (`false`) the menu button. Hidden means faded out,
+   * not focusable and `aria-hidden`; an open drawer stays open until closed,
+   * and the gamepad Select button still opens it. A small corner hotspot
+   * peeks it back for a few seconds on hover or tap, so players can always
+   * reach it.
+   */
+  setVisible(isVisible: boolean): void;
+  /** Show the menu button. */
+  show(): void;
+  /** Hide the menu button. */
+  hide(): void;
+  /** The last requested visibility (`true` unless a game hid it). */
+  readonly visible: boolean;
+}
+
+/** The page's menu control (one per page; every client copy shares the window state). */
+export const hubMenu: HubMenuControl = {
+  setVisible(isVisible: boolean): void {
+    if (!isBrowserPage()) {
+      return;
+    }
+    const wasVisible = window.__HUB_MENU_VISIBLE__;
+    if (wasVisible === isVisible || (wasVisible === undefined && isVisible)) {
+      return;
+    }
+    window.__HUB_MENU_VISIBLE__ = isVisible;
+    emitWindowEvent('hub:menu-visibility', { visible: isVisible });
+  },
+  show(): void {
+    hubMenu.setVisible(true);
+  },
+  hide(): void {
+    hubMenu.setVisible(false);
+  },
+  get visible(): boolean {
+    return !isBrowserPage() || window.__HUB_MENU_VISIBLE__ !== false;
+  },
+};