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

package/dist/shared/src.js

@@ -6,7 +6,7 @@ import { t as getUiStack } from "./page-stack.js";
 import { f as linkRealtimeToHub } from "./bridge.js";
 import { t as multiplayerForwarder } from "./mp.js";
 import { t as raceForwarder } from "./race.js";
-import { t as roomsForwarder } from "./rooms.js";
+import { n as roomsForwarder, t as isInHubRoom } from "./rooms.js";
 import { n as presenceForwarder, r as socialForwarder, t as notifyForwarder } from "./social.js";
 //#region src/core/storage/json-guards.ts
 /** Whether `candidate` is a non-null, non-array object. */
@@ -60,6 +60,12 @@ function isJsonObject(candidate) {
 */
 const UNSUPPORTED_BY_HUB = "unsupported_by_hub";
 /**
+* The code `getSave` rejects with when the hub can't be reached and this
+* device has no copy of the slot it can trust (a fresh device or cleared
+* browser): the slot may well hold a save, so it is not reported empty.
+*/
+const SAVE_UNKNOWN_CODE = "save_unknown";
+/**
 * Thrown by every hub call that fails. `status` is the HTTP status when the
 * hub answered (401 = not signed in, 404 = unknown game or board, 413 = too
 * large), or `undefined` for a transport failure (offline, no host). Social
@@ -555,23 +561,36 @@ function mergeStats(waiting, incoming) {
 		case "set": return incoming;
 	}
 }
-/** The progress kinds, by name. */
-function progressKinds(game) {
+/**
+* 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.
+*/
+function progressKinds(game, cloudSaves) {
 	return {
 		[PROGRESS_KINDS.save]: checkedKind(readSave$1, {
 			mergeKey: (save) => save.slot,
 			replaces: true,
 			run: async (save, context) => {
-				if ("deleted" in save) await context.call("deleteSave", {
-					...game(),
-					slot: save.slot
-				});
-				else await context.call("writeSave", {
+				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
+					label: save.label,
+					...base
 				});
+				cloudSaves.rememberCloudSave(save.slot, written.updatedAt);
 			}
 		}),
 		[PROGRESS_KINDS.stat]: checkedKind(readStat, {
@@ -618,6 +637,94 @@ function progressKinds(game) {
 	};
 }
 //#endregion
+//#region src/core/offline/hub-kinds/resume-kind.ts
+/** The kind name. */
+const RESUME_KIND = "hub.resume";
+function readResume(stored) {
+	if (!isRecord(stored)) return;
+	if (stored.action === "clear") {
+		const before = optionalNumber(stored.before);
+		return before === void 0 ? void 0 : {
+			action: "clear",
+			before
+		};
+	}
+	const savedAt = optionalNumber(stored.savedAt);
+	const label = optionalString(stored.label);
+	const version = optionalNumber(stored.version);
+	const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+	if (stored.action !== "save" || savedAt === void 0 || label === void 0 || version === void 0 || fraction === void 0 || !isNullableString(stored.title) || stored.state !== void 0 && !isJson(stored.state)) return;
+	const base = {
+		action: "save",
+		savedAt,
+		label,
+		fraction,
+		title: stored.title,
+		version
+	};
+	return stored.state === void 0 ? base : {
+		...base,
+		state: stored.state
+	};
+}
+/** The run to send: the device copy when it is at least as new as the op, else the op's own state; `undefined` when there is none. */
+function runToSend(save, local, slug) {
+	const copy = local.read(slug);
+	if (copy?.status === "saved" && copy.at >= save.savedAt) return {
+		action: "save",
+		savedAt: copy.at,
+		label: copy.label,
+		fraction: copy.fraction,
+		title: copy.title,
+		version: copy.version,
+		state: copy.state
+	};
+	return save.state === void 0 ? void 0 : save;
+}
+/** Run `call`; on a lapsed session (401) start a guest session and run it once more. */
+async function withSession(context, call) {
+	try {
+		return await call();
+	} catch (failure) {
+		if (!(failure instanceof HubError) || failure.status !== 401) throw failure;
+		await context.call("ensureGuestSession");
+		return call();
+	}
+}
+/** The resume kind, by name, over the device copies in `local`. */
+function resumeKinds(game, local) {
+	return { [RESUME_KIND]: checkedKind(readResume, {
+		mergeKey: () => "resume",
+		replaces: true,
+		run: async (op, context) => {
+			const { slug } = game();
+			if (op.action === "clear") {
+				await withSession(context, () => context.call("clearResumeSlot", {
+					slug,
+					before: op.before
+				}));
+				local.markSynced(slug, op.before);
+				return;
+			}
+			const run = runToSend(op, local, slug);
+			if (run?.state === void 0) return;
+			const { state } = run;
+			await withSession(context, () => context.call("saveResumeSlot", {
+				slug,
+				state,
+				progress: {
+					label: run.label,
+					fraction: run.fraction
+				},
+				title: run.title,
+				version: run.version,
+				savedAt: run.savedAt
+			}));
+			local.markSynced(slug, run.savedAt);
+		}
+	}) };
+}
+//#endregion
 //#region src/core/offline/hub-kinds/legacy-ops.ts
 /** The outbox operation for a v1 queued write, or `undefined` when it no longer reads as one. */
 function legacyOperation(op) {
@@ -683,19 +790,71 @@ function legacyOperation(op) {
 }
 //#endregion
 //#region src/core/offline/hub-kinds/index.ts
-/**
-* Every kind the hub itself queues offline (`hub.*`), registered on a
-* client's outbox. The docs' "Offline and replay" table lists them.
-*/
 /** Register every hub kind on `outbox`. */
 function registerHubKinds(outbox, hooks) {
 	const kinds = {
-		...progressKinds(hooks.game),
+		...progressKinds(hooks.game, hooks.cloudSaves),
 		...dailyKinds(hooks.game, hooks.onDailyComplete),
-		...economyKinds(hooks.game, writeLocalFavorites)
+		...economyKinds(hooks.game, writeLocalFavorites),
+		...resumeKinds(hooks.game, hooks.resume)
 	};
 	for (const [kind, definition] of Object.entries(kinds)) outbox.define(kind, definition);
 }
+//#endregion
+//#region src/core/offline/cloud-saves.ts
+/**
+* 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.
+*/
+/** A stored index, or `null` when missing or malformed. */
+function readCloudSaveIndex(stored) {
+	if (!isRecord(stored) || typeof stored.complete !== "boolean" || !isRecord(stored.saves)) return null;
+	const userId = optionalNumber(stored.userId);
+	if (userId === void 0) return null;
+	const saves = {};
+	for (const [slot, updatedAt] of Object.entries(stored.saves)) {
+		const known = updatedAt === null ? null : optionalNumber(updatedAt);
+		if (known === void 0) 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.
+*/
+function cloudSaveOf(index, userId, slot) {
+	if (index?.userId !== userId) return;
+	const updatedAt = index.saves[slot];
+	return updatedAt === void 0 && index.complete ? null : updatedAt;
+}
+/** `index` with `slot` seen at `updatedAt` (`null`: empty) by `userId`; another player's index starts over. */
+function withCloudSave(index, userId, slot, updatedAt) {
+	const base = index?.userId === userId ? index : {
+		userId,
+		complete: false,
+		saves: {}
+	};
+	return {
+		...base,
+		saves: {
+			...base.saves,
+			[slot]: updatedAt
+		}
+	};
+}
 /** The well-formed events of a stored buffer. */
 function readEvents(stored) {
 	if (!Array.isArray(stored)) return [];
@@ -909,6 +1068,28 @@ var LocalStore = class {
 	deleteSave(slot) {
 		this.store.remove(`${this.prefix}save:${slot}`);
 	}
+	/**
+	* The hub's `updatedAt` for `slot` as the current user last saw it (`null`:
+	* the slot was empty), or `undefined` when this device doesn't know.
+	*/
+	cloudSave(slot) {
+		const user = this.getUser();
+		return user === null ? void 0 : cloudSaveOf(this.readCloudSaves(this.prefix), user.id, slot);
+	}
+	/** Note the hub's copy of `slot` (just read or written) for the current user: its `updatedAt`, or `null` when empty. */
+	rememberCloudSave(slot, updatedAt) {
+		const user = this.getUser();
+		if (user !== null) this.writeStored(`${this.prefix}cloud-saves`, withCloudSave(this.readCloudSaves(this.prefix), user.id, slot, updatedAt));
+	}
+	/** Cache a slot as read from the hub (forgetting it when the hub has none), and note the hub's copy. */
+	cacheCloudSave(slot, save) {
+		if (save === null) this.deleteSave(slot);
+		else this.writeStored(`${this.prefix}save:${slot}`, save);
+		this.rememberCloudSave(slot, save?.updatedAt ?? null);
+	}
+	readCloudSaves(gamePrefix) {
+		return readCloudSaveIndex(this.readStored(`${gamePrefix}cloud-saves`));
+	}
 	/** This game's cached stats. */
 	getStats() {
 		const stored = this.readStored(`${this.prefix}stats`);
@@ -985,13 +1166,32 @@ var LocalStore = class {
 			ts: Date.now()
 		}));
 	}
-	/** Fan a `/me/snapshot` reply out across every game's cache keys. */
+	/**
+	* Fan a `/me/snapshot` reply out across every game's cache keys. It lists
+	* every save slot of every game the player has played, so each game's
+	* slots on the hub become known (and this game's are all empty when it
+	* isn't listed).
+	*/
 	hydrate(snapshot) {
 		if (snapshot.user !== null) this.writeStored(USER_KEY, snapshot.user);
+		const userId = snapshot.user?.id;
+		if (userId !== void 0 && !Object.keys(snapshot.games).some((slug) => `hub:${slug}:` === this.prefix)) this.writeStored(`${this.prefix}cloud-saves`, {
+			userId,
+			complete: true,
+			saves: {}
+		});
 		for (const [slug, game] of Object.entries(snapshot.games)) {
 			const gamePrefix = `hub:${slug}:`;
 			if (game.profile !== null) this.writeStored(`${gamePrefix}profile`, game.profile);
 			for (const save of game.saves) this.writeStored(`${gamePrefix}save:${save.slot}`, save);
+			if (userId !== void 0) {
+				const saves = Object.fromEntries(game.saves.map((save) => [save.slot, save.updatedAt]));
+				this.writeStored(`${gamePrefix}cloud-saves`, {
+					userId,
+					complete: true,
+					saves
+				});
+			}
 			this.writeStored(`${gamePrefix}stats`, game.stats);
 			this.writeStored(`${gamePrefix}inventory`, game.inventory);
 		}
@@ -1576,6 +1776,85 @@ function outboxFull() {
 	return new HubError("Too many changes are waiting to sync. Reconnect to save more.", 507, { code: OUTBOX_FULL_CODE });
 }
 //#endregion
+//#region src/core/resume/local-resume.ts
+const KEY_PATTERN = /^hub:(.+):resume$/;
+function keyFor(slug) {
+	return `hub:${slug}:resume`;
+}
+/** A stored record read back, or `null` when missing or malformed. */
+function readRecord(stored) {
+	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 === void 0 || userId === void 0) 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 === void 0 || gameTitle === void 0 || version === void 0 || fraction === void 0 || !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. */
+var LocalResumeStore = class {
+	constructor(store) {
+		_defineProperty(this, "store", void 0);
+		this.store = store;
+	}
+	/** `slug`'s copy, or `null`. */
+	read(slug) {
+		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, record) {
+		const text = JSON.stringify(record);
+		this.store.write(keyFor(slug), text);
+		return this.store.read(keyFor(slug)) === text;
+	}
+	/** Forget `slug`'s copy. */
+	remove(slug) {
+		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, at) {
+		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() {
+		const records = /* @__PURE__ */ new Map();
+		for (const key of this.store.keys()) {
+			const slug = KEY_PATTERN.exec(key)?.[1];
+			const record = slug === void 0 ? null : this.read(slug);
+			if (slug !== void 0 && record !== null) records.set(slug, record);
+		}
+		return records;
+	}
+};
+//#endregion
 //#region src/core/page.ts
 /** Whether this code runs in a browser page. */
 function isBrowserPage() {
@@ -1591,6 +1870,13 @@ function injectedConfig() {
 		...apiBase === void 0 ? {} : { apiBase }
 	};
 }
+/** The game's display title: the host's injected one, else the page's `<title>`, else `fallback`. */
+function detectGameTitle(fallback) {
+	const injected = isBrowserPage() && isRecord(window.__HUB__) ? optionalString(window.__HUB__.title) : void 0;
+	if (injected !== void 0 && injected !== "") return injected;
+	const pageTitle = typeof document === "undefined" ? "" : document.title.trim();
+	return pageTitle === "" ? fallback : pageTitle;
+}
 /** The game's slug: the injected one, else the first URL path segment, else `null`. */
 function detectSlug() {
 	const injectedSlug = injectedConfig().slug;
@@ -2246,6 +2532,30 @@ const ROUTES = {
 		path: "/version",
 		query: [],
 		offline: null
+	},
+	getResumeSlot: {
+		method: "GET",
+		path: "/games/:slug/resume",
+		query: [],
+		offline: null
+	},
+	saveResumeSlot: {
+		method: "PUT",
+		path: "/games/:slug/resume",
+		query: [],
+		offline: "replay"
+	},
+	clearResumeSlot: {
+		method: "DELETE",
+		path: "/games/:slug/resume",
+		query: ["before"],
+		offline: "replay"
+	},
+	listMyResumeSlots: {
+		method: "GET",
+		path: "/me/resume",
+		query: [],
+		offline: null
 	}
 };
 /** The request header that carries an offline operation key (the contract's `OFFLINE_OP_HEADER`). */
@@ -2369,6 +2679,7 @@ var HubConnection = class {
 		_defineProperty(this, "rest", void 0);
 		_defineProperty(this, "store", void 0);
 		_defineProperty(this, "outbox", void 0);
+		_defineProperty(this, "resumeStore", void 0);
 		_defineProperty(this, "offlineMode", void 0);
 		_defineProperty(this, "isReachable", true);
 		_defineProperty(this, "runningSync", null);
@@ -2390,6 +2701,7 @@ var HubConnection = class {
 		});
 		const pageStore = createPageStore();
 		this.store = new LocalStore(this.slug ?? "app", pageStore);
+		this.resumeStore = new LocalResumeStore(pageStore);
 		this.outbox = new Outbox({
 			slug: this.slug ?? "app",
 			store: pageStore,
@@ -2414,7 +2726,9 @@ var HubConnection = class {
 					rank: completion.rank,
 					meta: payload.meta
 				});
-			}
+			},
+			resume: this.resumeStore,
+			cloudSaves: this.store
 		});
 		this.importLegacyQueue();
 		if (typeof navigator !== "undefined" && "onLine" in navigator) this.isReachable = navigator.onLine;
@@ -2682,7 +2996,7 @@ var HubProgress = class extends HubConnection {
 	* sign-in. Idempotent. Offline, a local guest is used.
 	*/
 	ensureGuest() {
-		return this.withFallback(() => this.rest.call("ensureGuestSession"), () => {
+		return this.withFallback(async () => this.signedIn(await this.rest.call("ensureGuestSession")), () => {
 			const known = this.store.getUser();
 			if (known !== null) return { user: known };
 			const guest = {
@@ -2700,10 +3014,10 @@ var HubProgress = class extends HubConnection {
 	* the name is taken; the player should `login` instead.
 	*/
 	claim(username, password) {
-		return this.withFallback(() => this.rest.call("claimGuestAccount", {
+		return this.withFallback(async () => this.signedIn(await this.rest.call("claimGuestAccount", {
 			username,
 			password
-		}), () => this.signInLocally({
+		})), () => this.signInLocally({
 			id: 0,
 			username,
 			guest: false
@@ -2711,27 +3025,31 @@ var HubProgress = class extends HubConnection {
 	}
 	/** Create an account and sign in. (Offline: a local user is stored.) */
 	signup(username, password) {
-		return this.withFallback(() => this.rest.call("signUpWithPassword", {
+		return this.withFallback(async () => this.signedIn(await this.rest.call("signUpWithPassword", {
 			username,
 			password
-		}), () => this.signInLocally({
+		})), () => this.signInLocally({
 			id: 0,
 			username
 		}));
 	}
 	/** Sign in. (Offline: a local user is stored so signed-in flows work.) */
 	login(username, password) {
-		return this.withFallback(() => this.rest.call("logInWithPassword", {
+		return this.withFallback(async () => this.signedIn(await this.rest.call("logInWithPassword", {
 			username,
 			password
-		}), () => this.signInLocally({
+		})), () => this.signInLocally({
 			id: 0,
 			username
 		}));
 	}
 	/** Sign out (ends the session shared by every game). */
 	logout() {
-		return this.withFallback(() => this.rest.call("logOut"), () => {
+		return this.withFallback(async () => {
+			const reply = await this.rest.call("logOut");
+			this.store.clearUser();
+			return reply;
+		}, () => {
 			this.store.clearUser();
 			return { ok: true };
 		});
@@ -2740,6 +3058,11 @@ var HubProgress = class extends HubConnection {
 		this.store.setUser(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. */
+	signedIn(reply) {
+		this.store.setUser(reply.user);
+		return reply;
+	}
 	/** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
 	getProfile() {
 		return this.withFallback(async () => ({ profile: typedProfile((await this.rest.call("getGameProfile", this.gameFields())).profile) }), () => ({ profile: typedProfile(this.store.getProfile()) }));
@@ -2762,12 +3085,29 @@ var HubProgress = class extends HubConnection {
 	listSaves() {
 		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(slot) {
-		return this.withFallback(async () => ({ save: typedSave((await this.rest.call("getSave", {
-			...this.gameFields(),
-			slot
-		})).save) }), () => ({ save: typedSave(this.store.getSave(slot)) }));
+		return this.withFallback(async () => {
+			const { save } = await this.rest.call("getSave", {
+				...this.gameFields(),
+				slot
+			});
+			if (this.outbox.count() === 0) this.store.cacheCloudSave(slot, save);
+			return { save: typedSave(save) };
+		}, () => ({ save: typedSave(this.offlineSave(slot)) }));
+	}
+	/** The device's copy of `slot`, when it can be trusted offline (see {@link getSave}). */
+	offlineSave(slot) {
+		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) === void 0) throw new HubError(`Hub: offline, and this device hasn't seen save "${slot}" yet.`, void 0, { code: SAVE_UNKNOWN_CODE });
+		return this.store.getSave(slot);
 	}
 	/** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
 	putSave(slot, saveData, label) {
@@ -3120,6 +3460,292 @@ const hubMenu = {
 	}
 };
 //#endregion
+//#region src/core/resume/resume-list.ts
+function fromHub(summary) {
+	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, run, known) {
+	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, hub, copy, isHubKnown) {
+	if (copy === void 0) return hub === void 0 ? null : fromHub(hub);
+	if (copy.status === "cleared") return hub !== void 0 && hub.updatedAt > copy.at ? fromHub(hub) : null;
+	if (hub !== void 0 && hub.updatedAt >= copy.at) return fromHub(hub);
+	return !copy.isSynced || !isHubKnown || hub !== void 0 ? 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.
+*/
+function mergeResumeLists(hub, copies, userId) {
+	const hubBySlug = new Map((hub ?? []).map((summary) => [summary.game, summary]));
+	const mine = new Map([...copies].filter(([, copy]) => copy.userId === userId));
+	return [.../* @__PURE__ */ new Set([...hubBySlug.keys(), ...mine.keys()])].map((slug) => mergeOne(slug, hubBySlug.get(slug), mine.get(slug), hub !== void 0)).filter((entry) => entry !== null).sort((a, b) => b.savedAt - a.savedAt);
+}
+//#endregion
+//#region src/core/resume/resume-request.ts
+/**
+* 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.
+*/
+/** The query parameter (the contract's `RESUME_REQUEST_PARAM`; the browser client carries no contract code). */
+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.searchParams.delete(RESUME_REQUEST_PARAM);
+	try {
+		history.replaceState(history.state, "", `${url.pathname}${url.search}${url.hash}`);
+	} catch {}
+}
+/** Whether the address has `hub_resume`; it is taken out when it does. */
+function takeParam() {
+	try {
+		const url = new URL(location.href);
+		if (!url.searchParams.has("hub_resume")) 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). */
+function isResumeRequested() {
+	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;
+}
+//#endregion
+//#region src/core/resume/hub-resume.ts
+/** How long saves must be quiet before the latest is sent, ms. */
+const RESUME_DEBOUNCE_MS = 3e3;
+/** Largest state, bytes of JSON (the contract's `RESUME_MAX_STATE_BYTES`). */
+const RESUME_MAX_STATE_BYTES = 524288;
+/** What a game should do when a save is ignored, by blocker (logged once per page). */
+const BLOCKED_HINTS = {
+	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;
+/** A label or title trimmed and clipped, or `null` when blank. */
+function shortText(text) {
+	const trimmed = (text ?? "").trim();
+	return trimmed === "" ? null : trimmed.slice(0, TEXT_MAX);
+}
+/** The UTF-8 size of `text`. */
+function byteSize(text) {
+	return new TextEncoder().encode(text).length;
+}
+/** The device copy as a run read back. */
+function runFromCopy(copy) {
+	return {
+		state: toGameData(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(slot) {
+	return {
+		state: toGameData(slot.state),
+		progress: slot.progress,
+		title: slot.title,
+		version: slot.version,
+		savedAt: slot.updatedAt
+	};
+}
+/** `hub.resume`. */
+var HubResume = class {
+	constructor(host) {
+		_defineProperty(this, "host", void 0);
+		_defineProperty(this, "timer", null);
+		_defineProperty(this, "waiting", null);
+		_defineProperty(this, "isListening", false);
+		_defineProperty(this, "warnedBlockers", /* @__PURE__ */ new Set());
+		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() {
+		return isResumeRequested();
+	}
+	/** Why a save would be ignored right now (`race`, `daily`, `room`), or `null`. */
+	get blockedBy() {
+		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(run) {
+		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)) > 524288) 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 = {
+			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() {
+		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() {
+		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(options = {}) {
+		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;
+		if (slot !== void 0 && slot !== null && (mine === null || slot.updatedAt >= mine.at)) run = runFromSlot(slot);
+		else {
+			const isClearedElsewhere = slot === null && mine?.isSynced === true;
+			run = mine?.status === "saved" && !isClearedElsewhere ? runFromCopy(mine) : null;
+		}
+		if (run === null || options.version === void 0 || 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(options = {}) {
+		return (await this.get(options))?.state ?? null;
+	}
+	/** The player's saved runs in every resumable game, newest first (the home page's Resume card). */
+	async list() {
+		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) {
+		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. */
+	warnBlocked(blocker) {
+		if (this.warnedBlockers.has(blocker)) return;
+		this.warnedBlockers.add(blocker);
+		console.warn(`[hub] hub.resume.save ignored: ${BLOCKED_HINTS[blocker]}`);
+	}
+	requireSlug() {
+		if (this.host.slug === null) throw new HubError("hub.resume: could not determine the game slug.");
+		return this.host.slug;
+	}
+	schedule(payload) {
+		this.waiting = payload;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.flush().catch(() => void 0);
+		}, RESUME_DEBOUNCE_MS);
+		this.listenToPage();
+	}
+	/** Send a waiting save as soon as the page is hidden or closed. */
+	listenToPage() {
+		if (this.isListening || !isBrowserPage()) return;
+		this.isListening = true;
+		const flushNow = () => {
+			this.flush().catch(() => void 0);
+		};
+		window.addEventListener("pagehide", flushNow);
+		if (typeof document !== "undefined") document.addEventListener("visibilitychange", () => {
+			if (document.visibilityState === "hidden") flushNow();
+		});
+	}
+};
+//#endregion
 //#region src/core/ticket.ts
 /**
 * The own-server ticket request (`hub.mp.ticket()`): a 60-second identity
@@ -3261,6 +3887,7 @@ var Hub = class extends HubEconomy {
 	constructor(..._args) {
 		super(..._args);
 		_defineProperty(this, "clientVersion", HUB_CLIENT_VERSION);
+		_defineProperty(this, "resumeApi", void 0);
 	}
 	/**
 	* The hub's version and the client versions it supports (`GET /_api/version`),
@@ -3326,6 +3953,43 @@ var Hub = class extends HubEconomy {
 	get race() {
 		return raceForwarder;
 	}
+	/**
+	* 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() {
+		this.resumeApi ?? (this.resumeApi = new HubResume(this.resumeHost()));
+		return this.resumeApi;
+	}
+	/** What `hub.resume` needs from this client. */
+	resumeHost() {
+		return {
+			slug: this.slug,
+			local: this.resumeStore,
+			currentUserId: () => this.store.getUser()?.id ?? null,
+			gameTitle: () => detectGameTitle(this.slug ?? ""),
+			blocker: () => {
+				if (raceForwarder.current() !== null) return "race";
+				return this.daily.active === null ? isInHubRoom() ? "room" : null : "daily";
+			},
+			send: async (payload) => {
+				await this.mutateOffline(RESUME_KIND, payload, () => void 0);
+			},
+			fetchSlot: () => this.withFallback(async () => {
+				try {
+					return (await this.rest.call("getResumeSlot", this.gameFields())).resume;
+				} catch (failure) {
+					if (failure instanceof HubError && failure.status === 401) return null;
+					throw failure;
+				}
+			}, () => void 0),
+			fetchList: () => this.withFallback(async () => (await this.rest.call("listMyResumeSlots")).games, () => void 0),
+			clearOther: async (slug) => {
+				await this.rest.call("clearResumeSlot", { slug });
+			}
+		};
+	}
 	/** What the daily system needs from this client: its REST calls and window events. */
 	dailyHost() {
 		return {
@@ -3354,11 +4018,12 @@ linkRealtimeToHub({
 });
 /** A ready-to-use client, with the slug and API base detected from the page. */
 const hub = new Hub();
+isResumeRequested();
 /** Create a client for another slug or API base, or with other offline behaviour. */
 function createHub(options = {}) {
 	return new Hub(options);
 }
 //#endregion
-export { OUTBOX_FULL_CODE as a, OfflineApi as c, OfflineError as d, UNSUPPORTED_BY_HUB as f, CLIENT_VERSION_HEADER as i, ContentRejectedError as l, createHub as n, OUTBOX_MAX_CHARS as o, hub as r, OUTBOX_MAX_ENTRIES as s, Hub as t, HubError as u };
+export { RESUME_DEBOUNCE_MS as a, OUTBOX_FULL_CODE as c, OfflineApi as d, ContentRejectedError as f, UNSUPPORTED_BY_HUB as g, SAVE_UNKNOWN_CODE as h, HubResume as i, OUTBOX_MAX_CHARS as l, OfflineError as m, createHub as n, RESUME_MAX_STATE_BYTES as o, HubError as p, hub as r, CLIENT_VERSION_HEADER as s, Hub as t, OUTBOX_MAX_ENTRIES as u };
 
 //# sourceMappingURL=src.js.map