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

package/src/core/resume/hub-resume.ts

@@ -0,0 +1,252 @@
+/**
+ * `hub.resume`: auto-save a long single-player run so the player can pick it
+ * up again from the home page's Resume card, on any device. One slot per
+ * player per game; the latest save wins.
+ *
+ * - `save(run)` stores the run on the device at once and sends it to the hub
+ *   after a short quiet spell (debounced), straight away when the page is
+ *   hidden or closed, and through the offline outbox (`hub.resume`), so it
+ *   works offline and lands once.
+ * - `clear()` when the run ends (won, lost or quit).
+ * - `load()` / `get()` read it back; `requested` says the page was opened to
+ *   resume, so the game restores without asking.
+ *
+ * Saves are ignored while the page is in a race, a daily challenge or an
+ * online room: those runs are never resumed.
+ */
+import type { ResumeSlot, ResumeSummary } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../errors';
+import { toGameData, toStoredJson, type GamePayload } from '../game-data';
+import type { ResumePayload } from '../offline/hub-kinds';
+import { isBrowserPage } from '../page';
+import type { LocalResumeStore, LocalRun } from './local-resume';
+import { mergeResumeLists } from './resume-list';
+import { isResumeRequested } from './resume-request';
+import type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeRun, ResumeSaveInput } from './resume-types';
+
+/** How long saves must be quiet before the latest is sent, ms. */
+export const RESUME_DEBOUNCE_MS = 3000;
+
+/** Largest state, bytes of JSON (the contract's `RESUME_MAX_STATE_BYTES`). */
+export const RESUME_MAX_STATE_BYTES = 512 * 1024;
+
+/** What a game should do when a save is ignored, by blocker (logged once per page). */
+const BLOCKED_HINTS: Readonly<Record<ResumeBlocker, string>> = {
+  daily: 'a daily challenge is active. When the player leaves a daily without finishing it, call hub.daily.cancel().',
+  race: 'a race is on: races are never resumed.',
+  room: 'the page is in a hub room: online games are never resumed.',
+};
+
+/** Longest label or title kept (the contract's `RESUME_TEXT_MAX`). */
+const TEXT_MAX = 60;
+
+/** What `hub.resume` needs from its client. */
+export interface ResumeHost {
+  /** This game's slug; `null` on the home page. */
+  readonly slug: string | null;
+  readonly local: LocalResumeStore;
+  /** The signed-in player's id as the device knows it, or `null`. */
+  currentUserId(): number | null;
+  /** The game's display title. */
+  gameTitle(): string;
+  /** Why saving is off right now, or `null`. */
+  blocker(): ResumeBlocker | null;
+  /** Perform a resume op: at once when online with nothing waiting, else queued. */
+  send(payload: ResumePayload): Promise<void>;
+  /** This game's run on the hub, or `undefined` when the hub can't be reached. */
+  fetchSlot(): Promise<ResumeSlot | null | undefined>;
+  /** The player's runs on the hub, or `undefined` when it can't be reached. */
+  fetchList(): Promise<ResumeSummary[] | undefined>;
+  /** Clear another game's run on the hub (the home page's discard); throws offline. */
+  clearOther(slug: string): Promise<void>;
+}
+
+/** A label or title trimmed and clipped, or `null` when blank. */
+function shortText(text: string | null | undefined): string | null {
+  const trimmed = (text ?? '').trim();
+  return trimmed === '' ? null : trimmed.slice(0, TEXT_MAX);
+}
+
+/** The UTF-8 size of `text`. */
+function byteSize(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+/** The device copy as a run read back. */
+function runFromCopy<TState>(copy: LocalRun): ResumeRun<TState> {
+  return { state: toGameData<TState>(copy.state), progress: { label: copy.label, fraction: copy.fraction }, title: copy.title, version: copy.version, savedAt: copy.at };
+}
+
+/** The hub's slot as a run read back. */
+function runFromSlot<TState>(slot: ResumeSlot): ResumeRun<TState> {
+  return { state: toGameData<TState>(slot.state), progress: slot.progress, title: slot.title, version: slot.version, savedAt: slot.updatedAt };
+}
+
+/** `hub.resume`. */
+export class HubResume {
+  private readonly host: ResumeHost;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private waiting: ResumePayload | null = null;
+  private isListening = false;
+  private readonly warnedBlockers = new Set<ResumeBlocker>();
+
+  constructor(host: ResumeHost) {
+    this.host = host;
+  }
+
+  /**
+   * `true` when the page was opened from the Resume card (`?hub_resume=1`,
+   * taken out of the address bar). Synchronous, so a game can restore before
+   * it routes or draws its title screen.
+   */
+  get requested(): boolean {
+    return isResumeRequested();
+  }
+
+  /** Why a save would be ignored right now (`race`, `daily`, `room`), or `null`. */
+  get blockedBy(): ResumeBlocker | null {
+    return this.host.blocker();
+  }
+
+  /**
+   * Save the run (the latest save wins). Stored on the device at once; sent
+   * after {@link RESUME_DEBOUNCE_MS} of quiet, or when the page is hidden.
+   * Returns `false` (and saves nothing) in a race, a daily challenge or an
+   * online room. Throws a `HubError` 413 over 512 KB, 400 without a label.
+   */
+  save<TState extends GamePayload>(run: ResumeSaveInput<TState>): boolean {
+    const blocker = this.host.blocker();
+    if (blocker !== null) {
+      this.warnBlocked(blocker);
+      return false;
+    }
+    const slug = this.requireSlug();
+    const label = shortText(run.progress.label);
+    if (label === null) {
+      throw new HubError('hub.resume.save: progress.label is required.', 400);
+    }
+    const state = toStoredJson(run.state);
+    if (byteSize(JSON.stringify(state)) > RESUME_MAX_STATE_BYTES) {
+      throw new HubError(`hub.resume.save: state exceeds ${String(RESUME_MAX_STATE_BYTES)} bytes.`, 413);
+    }
+    const fraction = typeof run.progress.fraction === 'number' && Number.isFinite(run.progress.fraction) ? Math.min(1, Math.max(0, run.progress.fraction)) : null;
+    const copy: LocalRun = {
+      status: 'saved', userId: this.host.currentUserId(), at: Date.now(), label, fraction, title: shortText(run.title),
+      version: Math.max(0, Math.floor(run.version ?? 0)), gameTitle: this.host.gameTitle(), state, isSynced: false,
+    };
+    const isStored = this.host.local.write(slug, copy);
+    this.schedule({
+      action: 'save', savedAt: copy.at, label, fraction, title: copy.title, version: copy.version,
+      ...(isStored ? {} : { state }),
+    });
+    return true;
+  }
+
+  /** Send a waiting save now (the page does this itself when hidden or closed). */
+  async flush(): Promise<void> {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    const payload = this.waiting;
+    this.waiting = null;
+    if (payload !== null) {
+      await this.host.send(payload);
+    }
+  }
+
+  /** Clear the run: call it when the run ends (won, lost or quit). Works offline. */
+  async clear(): Promise<void> {
+    const slug = this.requireSlug();
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.waiting = null;
+    const at = Date.now();
+    this.host.local.write(slug, { status: 'cleared', userId: this.host.currentUserId(), at, isSynced: false });
+    await this.host.send({ action: 'clear', before: at });
+  }
+
+  /** The saved run with its progress and time, or `null`. The newer of the device's copy and the hub's wins. */
+  async get<TState = GamePayload>(options: ResumeLoadOptions = {}): Promise<ResumeRun<TState> | null> {
+    const slug = this.requireSlug();
+    const copy = this.host.local.read(slug);
+    const mine = copy !== null && copy.userId === this.host.currentUserId() ? copy : null;
+    const slot = await this.host.fetchSlot();
+    let run: ResumeRun<TState> | null;
+    if (slot !== undefined && slot !== null && (mine === null || slot.updatedAt >= mine.at)) {
+      run = runFromSlot<TState>(slot);
+    } else {
+      // The device's run, unless the hub was asked, has none, and already had this one (it was cleared elsewhere).
+      const isClearedElsewhere = slot === null && mine?.isSynced === true;
+      run = mine?.status === 'saved' && !isClearedElsewhere ? runFromCopy<TState>(mine) : null;
+    }
+    if (run === null || options.version === undefined || run.version === options.version) {
+      return run;
+    }
+    if (run.version < options.version) {
+      await this.clear();
+    }
+    return null;
+  }
+
+  /** The saved state, or `null` (see {@link get} for the version rule). */
+  async load<TState = GamePayload>(options: ResumeLoadOptions = {}): Promise<TState | null> {
+    return (await this.get<TState>(options))?.state ?? null;
+  }
+
+  /** The player's saved runs in every resumable game, newest first (the home page's Resume card). */
+  async list(): Promise<ResumeEntry[]> {
+    return mergeResumeLists(await this.host.fetchList(), this.host.local.all(), this.host.currentUserId());
+  }
+
+  /** Discard another game's run from the home page (online only: throws a `HubError` offline). */
+  async discard(slug: string): Promise<void> {
+    await this.host.clearOther(slug);
+    this.host.local.remove(slug);
+  }
+
+  /** Say once per blocker why saves are ignored, so a game that forgot `hub.daily.cancel()` finds out. */
+  private warnBlocked(blocker: ResumeBlocker): void {
+    if (this.warnedBlockers.has(blocker)) {
+      return;
+    }
+    this.warnedBlockers.add(blocker);
+    // eslint-disable-next-line no-console -- a one-time hint to the game developer, with the fix
+    console.warn(`[hub] hub.resume.save ignored: ${BLOCKED_HINTS[blocker]}`);
+  }
+
+  private requireSlug(): string {
+    if (this.host.slug === null) {
+      throw new HubError('hub.resume: could not determine the game slug.');
+    }
+    return this.host.slug;
+  }
+
+  private schedule(payload: ResumePayload): void {
+    this.waiting = payload;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => { void this.flush().catch(() => undefined); }, RESUME_DEBOUNCE_MS);
+    this.listenToPage();
+  }
+
+  /** Send a waiting save as soon as the page is hidden or closed. */
+  private listenToPage(): void {
+    if (this.isListening || !isBrowserPage()) {
+      return;
+    }
+    this.isListening = true;
+    const flushNow = (): void => { void this.flush().catch(() => undefined); };
+    window.addEventListener('pagehide', flushNow);
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          flushNow();
+        }
+      });
+    }
+  }
+}

package/src/core/resume/local-resume.ts

@@ -0,0 +1,130 @@
+/**
+ * The device's copy of each game's resume slot (`hub:<slug>:resume`), in the
+ * browser storage every game on the site shares. It is written the moment a
+ * game saves, before the debounced send, so:
+ * - `hub.resume.load()` works offline and right after a reload;
+ * - the queued send reads the newest state from here, so the outbox entry
+ *   stays small (it carries the state itself only when this copy couldn't
+ *   be stored);
+ * - the home page's Resume card can show a run the hub hasn't heard of yet
+ *   (saved offline, or the tab closed before the send), and hide one cleared
+ *   offline.
+ *
+ * A record belongs to the player who saved it (`userId`), so another account
+ * on the same device never sees it. `isSynced` turns true once the hub has it.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import type { KeyValueStore } from '../storage/key-value';
+
+/** A run as this device saved it. */
+export interface LocalRun {
+  readonly status: 'saved';
+  readonly userId: number | null;
+  /** When the game saved it, epoch ms. */
+  readonly at: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  /** The game's title, for the Resume card before the hub knows the run. */
+  readonly gameTitle: string;
+  readonly state: Json;
+  readonly isSynced: boolean;
+}
+
+/** A run this device cleared (kept until the hub has the clear). */
+export interface LocalClear {
+  readonly status: 'cleared';
+  readonly userId: number | null;
+  readonly at: number;
+  readonly isSynced: boolean;
+}
+
+/** A device copy of one game's slot. */
+export type LocalResume = LocalRun | LocalClear;
+
+const KEY_PATTERN = /^hub:(.+):resume$/;
+
+function keyFor(slug: string): string {
+  return `hub:${slug}:resume`;
+}
+
+/** A stored record read back, or `null` when missing or malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a record read back from localStorage
+function readRecord(stored: unknown): LocalResume | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const at = optionalNumber(stored.at);
+  const userId = stored.userId === null ? null : optionalNumber(stored.userId);
+  const isSynced = stored.isSynced === true;
+  if (at === undefined || userId === undefined) {
+    return null;
+  }
+  if (stored.status === 'cleared') {
+    return { status: 'cleared', userId, at, isSynced };
+  }
+  const label = optionalString(stored.label);
+  const gameTitle = optionalString(stored.gameTitle);
+  const version = optionalNumber(stored.version);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  if (stored.status !== 'saved' || label === undefined || gameTitle === undefined || version === undefined
+    || fraction === undefined || !isNullableString(stored.title) || !isJson(stored.state)) {
+    return null;
+  }
+  return { status: 'saved', userId, at, label, fraction, title: stored.title, version, gameTitle, state: stored.state, isSynced };
+}
+
+/** The device copies of every game's slot. */
+export class LocalResumeStore {
+  private readonly store: KeyValueStore;
+
+  constructor(store: KeyValueStore) {
+    this.store = store;
+  }
+
+  /** `slug`'s copy, or `null`. */
+  read(slug: string): LocalResume | null {
+    const text = this.store.read(keyFor(slug));
+    return text === null ? null : readRecord(parseJsonText(text));
+  }
+
+  /** Store `slug`'s copy; answers whether it stuck (a full storage refuses a large state). */
+  write(slug: string, record: LocalResume): boolean {
+    const text = JSON.stringify(record);
+    this.store.write(keyFor(slug), text);
+    return this.store.read(keyFor(slug)) === text;
+  }
+
+  /** Forget `slug`'s copy. */
+  remove(slug: string): void {
+    this.store.remove(keyFor(slug));
+  }
+
+  /** The hub now has `slug`'s save or clear made at `at`: mark it synced (a clear is simply forgotten). */
+  markSynced(slug: string, at: number): void {
+    const record = this.read(slug);
+    if (record === null || record.at !== at) {
+      return;
+    }
+    if (record.status === 'cleared') {
+      this.remove(slug);
+    } else {
+      this.write(slug, { ...record, isSynced: true });
+    }
+  }
+
+  /** Every game's copy, by slug. */
+  all(): Map<string, LocalResume> {
+    const records = new Map<string, LocalResume>();
+    for (const key of this.store.keys()) {
+      const slug = KEY_PATTERN.exec(key)?.[1];
+      const record = slug === undefined ? null : this.read(slug);
+      if (slug !== undefined && record !== null) {
+        records.set(slug, record);
+      }
+    }
+    return records;
+  }
+}

package/src/core/resume/resume-list.ts

@@ -0,0 +1,65 @@
+/**
+ * The player's saved runs: the hub's list merged with this device's copies,
+ * so a run saved offline (or just before the tab closed) shows at once and a
+ * run cleared offline disappears at once. Pure.
+ */
+import type { ResumeSummary } from '@diffenderfer-games/hub-contract';
+import type { LocalResume, LocalRun } from './local-resume';
+import type { ResumeEntry } from './resume-types';
+
+function fromHub(summary: ResumeSummary): ResumeEntry {
+  return {
+    slug: summary.game,
+    gameTitle: summary.gameTitle,
+    path: summary.path,
+    hasImage: summary.hasImage,
+    progress: summary.progress,
+    title: summary.title,
+    savedAt: summary.updatedAt,
+    isLocalOnly: false,
+  };
+}
+
+function fromDevice(slug: string, run: LocalRun, known: ResumeSummary | undefined): ResumeEntry {
+  return {
+    slug,
+    gameTitle: known?.gameTitle ?? run.gameTitle,
+    path: known?.path ?? `/${slug}`,
+    hasImage: known?.hasImage ?? false,
+    progress: { label: run.label, fraction: run.fraction },
+    title: run.title,
+    savedAt: run.at,
+    isLocalOnly: !run.isSynced,
+  };
+}
+
+/** One game's entry, from the hub's summary (if any) and the device copy (if the player's). */
+function mergeOne(slug: string, hub: ResumeSummary | undefined, copy: LocalResume | undefined, isHubKnown: boolean): ResumeEntry | null {
+  if (copy === undefined) {
+    return hub === undefined ? null : fromHub(hub);
+  }
+  if (copy.status === 'cleared') {
+    return hub !== undefined && hub.updatedAt > copy.at ? fromHub(hub) : null;
+  }
+  if (hub !== undefined && hub.updatedAt >= copy.at) {
+    return fromHub(hub);
+  }
+  // The hub hasn't got this run: show it while it waits to be sent, or when the hub can't be asked.
+  // A synced copy the hub no longer lists was cleared or pruned elsewhere.
+  return !copy.isSynced || !isHubKnown || hub !== undefined ? fromDevice(slug, copy, hub) : null;
+}
+
+/**
+ * The runs to show, newest first. `hub` is the hub's list, or `undefined`
+ * when it couldn't be reached; `copies` are the device's, by slug; only
+ * those saved by `userId` count.
+ */
+export function mergeResumeLists(hub: readonly ResumeSummary[] | undefined, copies: ReadonlyMap<string, LocalResume>, userId: number | null): ResumeEntry[] {
+  const hubBySlug = new Map((hub ?? []).map((summary) => [summary.game, summary] as const));
+  const mine = new Map([...copies].filter(([, copy]) => copy.userId === userId));
+  const slugs = new Set([...hubBySlug.keys(), ...mine.keys()]);
+  return [...slugs]
+    .map((slug) => mergeOne(slug, hubBySlug.get(slug), mine.get(slug), hub !== undefined))
+    .filter((entry): entry is ResumeEntry => entry !== null)
+    .sort((a, b) => b.savedAt - a.savedAt);
+}

package/src/core/resume/resume-request.ts

@@ -0,0 +1,52 @@
+/**
+ * Whether this page was opened from the home page's Resume card
+ * (`/<slug>/?hub_resume=1`). The first client copy on the page to look takes
+ * the parameter out of the address bar (so a reload or a shared link doesn't
+ * resume again) and records the answer on `window`, so every other copy on
+ * the page (a game's bundled client and the host's `/_hub/hub.js`) answers
+ * the same, however late it asks.
+ */
+import { isBrowserPage } from '../page';
+
+/** The query parameter (the contract's `RESUME_REQUEST_PARAM`; the browser client carries no contract code). */
+export const RESUME_REQUEST_PARAM = 'hub_resume';
+
+/** Where the answer is kept for the page. */
+const PAGE_FLAG = '__HUB_RESUME_REQUESTED__';
+
+/** Take `hub_resume` out of the address bar, keeping the rest of the URL and the history state. */
+function stripParam(url: URL): void {
+  url.searchParams.delete(RESUME_REQUEST_PARAM);
+  try {
+    history.replaceState(history.state, '', `${url.pathname}${url.search}${url.hash}`);
+  } catch {
+    // A sandboxed page that refuses replaceState keeps the parameter; the answer is still recorded.
+  }
+}
+
+/** Whether the address has `hub_resume`; it is taken out when it does. */
+function takeParam(): boolean {
+  try {
+    const url = new URL(location.href);
+    if (!url.searchParams.has(RESUME_REQUEST_PARAM)) {
+      return false;
+    }
+    stripParam(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `true` when the page was opened to resume (synchronous, so a game can decide before it routes or draws). */
+export function isResumeRequested(): boolean {
+  if (!isBrowserPage()) {
+    return false;
+  }
+  if (Reflect.has(window, PAGE_FLAG)) {
+    return Reflect.get(window, PAGE_FLAG) === true;
+  }
+  const isRequested = takeParam();
+  Reflect.set(window, PAGE_FLAG, isRequested);
+  return isRequested;
+}

package/src/core/resume/resume-types.ts

@@ -0,0 +1,64 @@
+/**
+ * `hub.resume`'s public types: what a game saves, what it loads back, and
+ * the player's list of saved runs the home page shows.
+ */
+import type { GamePayload } from '../game-data';
+
+/** How far along a run is. */
+export interface ResumeProgress {
+  /** A short line the game writes, such as "Level 12" or "Round 3 of 5" (up to 60 characters). */
+  readonly label: string;
+  /** 0 to 1, drawn as a progress bar; leave it out when the game can't say. */
+  readonly fraction?: number | null;
+}
+
+/** A run to save. `TState` is the game's own JSON-safe state type. */
+export interface ResumeSaveInput<TState extends GamePayload> {
+  /** Everything the game needs to pick the run up again (up to 512 KB as JSON). */
+  readonly state: TState;
+  readonly progress: ResumeProgress;
+  /** An optional name for the run ("Klondike, draw 3"), shown under the game's name. */
+  readonly title?: string | null;
+  /** The game's state version (default 0). Bump it when `state` changes shape; see `load({ version })`. */
+  readonly version?: number;
+}
+
+/** A saved run, read back. */
+export interface ResumeRun<TState> {
+  readonly state: TState;
+  readonly progress: { readonly label: string; readonly fraction: number | null };
+  readonly title: string | null;
+  readonly version: number;
+  /** When the game saved it, epoch ms. */
+  readonly savedAt: number;
+}
+
+/** Options for reading the run back. */
+export interface ResumeLoadOptions {
+  /**
+   * The state version this code reads. A run saved with an older version is
+   * dropped (cleared) and reads as `null`; a newer one (from a newer copy of
+   * the game in another tab) reads as `null` but is kept.
+   */
+  readonly version?: number;
+}
+
+/** One saved run in the player's list (the home page's Resume card). */
+export interface ResumeEntry {
+  /** The game's slug. */
+  readonly slug: string;
+  readonly gameTitle: string;
+  /** The game's URL path, like `/solitaire`. */
+  readonly path: string;
+  /** The game has a tile image (`/_tiles/<slug>`). */
+  readonly hasImage: boolean;
+  readonly progress: { readonly label: string; readonly fraction: number | null };
+  readonly title: string | null;
+  /** When it was saved, epoch ms. */
+  readonly savedAt: number;
+  /** Saved on this device and not yet sent to the hub (offline, or the tab closed first). */
+  readonly isLocalOnly: boolean;
+}
+
+/** Why a save was ignored: the page is in a race, a daily challenge or an online room. */
+export type ResumeBlocker = 'race' | 'daily' | 'room';

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

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

package/src/daily/daily-system.ts

@@ -42,8 +42,12 @@ function messageOf(error: unknown): string {
 /** Daily challenges (`hub.daily`). */
 export class DailySystem {
   /**
-   * The challenge in progress (set when a day starts, cleared on complete).
-   * A game's win handler checks it: `if (hub.daily.active) hub.daily.complete(…)`.
+   * The challenge in progress: set when a day starts; cleared the moment the
+   * game calls `complete` (whatever the hub answers, and before it answers)
+   * or `cancel`. A game's win handler checks it:
+   * `if (hub.daily.active) hub.daily.complete(…)`. While it is set the page
+   * is in a daily run, so `hub.resume.save` saves nothing: a game whose
+   * player leaves a daily unfinished must call `cancel()`.
    */
   active: DailyChallenge | null = null;
   private readonly host: DailyHost;
@@ -115,16 +119,17 @@ export class DailySystem {
    * Resolves with the new completion count and rank, or `null` when no
    * challenge is active, the hub refused, or the hub can't be reached: then
    * the completion is queued (`hub:daily-queued`) and replays when it is
-   * back (`hub:daily-complete` follows).
+   * back (`hub:daily-complete` follows). The daily run ends at the call,
+   * so `active` is `null` at once, even if the hub then refuses it.
    */
   async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
     const challenge = this.active;
     if (challenge === null) {
       return null;
     }
+    this.active = null;
     try {
       const completed = await this.host.complete(challenge.day, challenge.token, meta);
-      this.active = null;
       if (completed === null) {
         // Queued offline: `hub:daily-complete` follows when it replays.
         this.host.emit('hub:daily-queued', { day: challenge.day, queued: true, meta });
@@ -151,7 +156,11 @@ export class DailySystem {
     }
   }
 
-  /** Abandon the active challenge without recording it (e.g. the player quit). */
+  /**
+   * Abandon the active challenge without recording it: the player quit, or
+   * left the daily for normal play (another level, a new game). Until then
+   * the page counts as in a daily run and `hub.resume.save` saves nothing.
+   */
   cancel(): void {
     this.active = null;
   }

package/src/index.ts

@@ -17,7 +17,7 @@
  * queue their own operations with `hub.offline` (docs: "Offline and replay").
  *
  * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * `hub.daily`, `hub.resume`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
  * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
  * only that part.
  *
@@ -36,6 +36,8 @@ export type { SyncConflict, SyncResult } from './core/connection';
 export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
 export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
 export type { HubMenuControl } from './core/menu-control';
+export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
+export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
 export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
 export { OfflineApi } from './core/offline/offline-api';
 export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';

package/src/realtime/rooms-forwarder.ts

@@ -1,18 +1,30 @@
 /**
  * `hub.rooms`: hub relay rooms, forwarded to the social runtime. Each room is
- * wrapped so its rejections use the core client's error classes.
+ * wrapped so its rejections use the core client's error classes, and the
+ * page's open rooms are tracked (`isInHubRoom`), so `hub.resume` can refuse
+ * to save an online run.
  */
 import type { Json, RoomInfo } from '@diffenderfer-games/hub-contract';
 import { outdatedRuntime, pageBridge, rethrowAsHubError } from './bridge';
 import type { HubRoom, HubRoomsApi, RoomEvents, RoomSelf, RoomSendOptions, RoomState, RoomStateOptions } from './room-types';
 import type { RoomSeat } from './wire-types';
 
+/** The rooms this page is in (created, joined or reclaimed, and not yet left or closed). */
+const openRooms = new Set<HubRoom>();
+
+/** Whether this page is in a hub room right now. */
+export function isInHubRoom(): boolean {
+  return openRooms.size > 0;
+}
+
 /** A runtime room whose rejections are re-created as the core client's errors. */
 class ForwardedRoom implements HubRoom {
   private readonly room: HubRoom;
 
   constructor(room: HubRoom) {
     this.room = room;
+    openRooms.add(room);
+    room.on('closed', () => { openRooms.delete(room); });
   }
 
   get info(): RoomInfo {
@@ -68,6 +80,7 @@ class ForwardedRoom implements HubRoom {
   }
 
   leave(): Promise<void> {
+    openRooms.delete(this.room);
     return rethrowAsHubError(this.room.leave());
   }