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

package/dist/shared/rooms.js.map

@@ -1 +1 @@
-{"version":3,"file":"rooms.js","names":[],"sources":["../../src/realtime/rooms-forwarder.ts"],"mappings":";;;;AAUA,IAAM,gBAAN,MAAuC;CAGrC,YAAY,MAAe;EAFV,gBAAA,MAAA,QAAA,KAAA,CAAA;EAGf,KAAK,OAAO;CACd;CAEA,IAAI,OAAiB;EACnB,OAAO,KAAK,KAAK;CACnB;CAEA,IAAI,QAAmB;EACrB,OAAO,KAAK,KAAK;CACnB;CAEA,IAAI,KAAe;EACjB,OAAO,KAAK,KAAK;CACnB;CAEA,QAAoB;EAClB,OAAO,KAAK,KAAK,KAAK;CACxB;CAEA,GAAkC,OAAa,UAA2D;EACxG,OAAO,KAAK,KAAK,GAAG,OAAO,QAAQ;CACrC;CAEA,MAAM,SAAiC;EACrC,OAAO,kBAAkB,KAAK,KAAK,MAAM,OAAO,CAAC;CACnD;CAEA,KAAK,UAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,QAAQ,CAAC;CACnD;CAEA,QAAuB;EACrB,OAAO,kBAAkB,KAAK,KAAK,MAAM,CAAC;CAC5C;CAEA,KAAK,SAAe,SAA0C;EAC5D,OAAO,kBAAkB,KAAK,KAAK,KAAK,SAAS,OAAO,CAAC;CAC3D;CAEA,SAAS,OAAkB,SAA2C;EACpE,OAAO,kBAAkB,KAAK,KAAK,SAAS,OAAO,OAAO,CAAC;CAC7D;CAEA,KAAK,MAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,IAAI,CAAC;CAC/C;CAEA,MAAM,UAAiC;EACrC,OAAO,kBAAkB,KAAK,KAAK,MAAM,QAAQ,CAAC;CACpD;CAEA,KAAK,QAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,MAAM,CAAC;CACjD;CAEA,QAAuB;EACrB,OAAO,kBAAkB,KAAK,KAAK,MAAM,CAAC;CAC5C;CAEA,IAAI,SAA+B;EACjC,OAAO,kBAAkB,KAAK,KAAK,IAAI,OAAO,CAAC;CACjD;AACF;;AAGA,MAAa,iBAA8B;CACzC,SAAS,YAAY,WAAW,KAAK,OAAO,aAAa,IAAI,cAAc,MAAM,SAAS,MAAM,OAAO,OAAO,CAAC,CAAC;CAChH,OAAO,UAAU,YAAY,WAAW,KAAK,OAAO,aAAa,IAAI,cAAc,MAAM,SAAS,MAAM,KAAK,UAAU,OAAO,CAAC,CAAC;CAChI,OAAO,YAAY,WAAW,MAAM,aAAa,SAAS,MAAM,KAAK,OAAO,CAAC;CAC7E,eAAe,WAAW,KAAK,OAAO,aAAa;EACjD,IAAI,SAAS,MAAM,YAAY,KAAA,GAC7B,MAAM,gBAAgB,oBAAoB;EAE5C,MAAM,OAAO,MAAM,SAAS,MAAM,QAAQ;EAC1C,OAAO,SAAS,OAAO,OAAO,IAAI,cAAc,IAAI;CACtD,CAAC;AACH"}
+{"version":3,"file":"rooms.js","names":[],"sources":["../../src/realtime/rooms-forwarder.ts"],"mappings":";;;;AAYA,MAAM,4BAAY,IAAI,IAAa;;AAGnC,SAAgB,cAAuB;CACrC,OAAO,UAAU,OAAO;AAC1B;;AAGA,IAAM,gBAAN,MAAuC;CAGrC,YAAY,MAAe;EAFV,gBAAA,MAAA,QAAA,KAAA,CAAA;EAGf,KAAK,OAAO;EACZ,UAAU,IAAI,IAAI;EAClB,KAAK,GAAG,gBAAgB;GAAE,UAAU,OAAO,IAAI;EAAG,CAAC;CACrD;CAEA,IAAI,OAAiB;EACnB,OAAO,KAAK,KAAK;CACnB;CAEA,IAAI,QAAmB;EACrB,OAAO,KAAK,KAAK;CACnB;CAEA,IAAI,KAAe;EACjB,OAAO,KAAK,KAAK;CACnB;CAEA,QAAoB;EAClB,OAAO,KAAK,KAAK,KAAK;CACxB;CAEA,GAAkC,OAAa,UAA2D;EACxG,OAAO,KAAK,KAAK,GAAG,OAAO,QAAQ;CACrC;CAEA,MAAM,SAAiC;EACrC,OAAO,kBAAkB,KAAK,KAAK,MAAM,OAAO,CAAC;CACnD;CAEA,KAAK,UAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,QAAQ,CAAC;CACnD;CAEA,QAAuB;EACrB,OAAO,kBAAkB,KAAK,KAAK,MAAM,CAAC;CAC5C;CAEA,KAAK,SAAe,SAA0C;EAC5D,OAAO,kBAAkB,KAAK,KAAK,KAAK,SAAS,OAAO,CAAC;CAC3D;CAEA,SAAS,OAAkB,SAA2C;EACpE,OAAO,kBAAkB,KAAK,KAAK,SAAS,OAAO,OAAO,CAAC;CAC7D;CAEA,KAAK,MAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,IAAI,CAAC;CAC/C;CAEA,MAAM,UAAiC;EACrC,OAAO,kBAAkB,KAAK,KAAK,MAAM,QAAQ,CAAC;CACpD;CAEA,KAAK,QAA+B;EAClC,OAAO,kBAAkB,KAAK,KAAK,KAAK,MAAM,CAAC;CACjD;CAEA,QAAuB;EACrB,UAAU,OAAO,KAAK,IAAI;EAC1B,OAAO,kBAAkB,KAAK,KAAK,MAAM,CAAC;CAC5C;CAEA,IAAI,SAA+B;EACjC,OAAO,kBAAkB,KAAK,KAAK,IAAI,OAAO,CAAC;CACjD;AACF;;AAGA,MAAa,iBAA8B;CACzC,SAAS,YAAY,WAAW,KAAK,OAAO,aAAa,IAAI,cAAc,MAAM,SAAS,MAAM,OAAO,OAAO,CAAC,CAAC;CAChH,OAAO,UAAU,YAAY,WAAW,KAAK,OAAO,aAAa,IAAI,cAAc,MAAM,SAAS,MAAM,KAAK,UAAU,OAAO,CAAC,CAAC;CAChI,OAAO,YAAY,WAAW,MAAM,aAAa,SAAS,MAAM,KAAK,OAAO,CAAC;CAC7E,eAAe,WAAW,KAAK,OAAO,aAAa;EACjD,IAAI,SAAS,MAAM,YAAY,KAAA,GAC7B,MAAM,gBAAgB,oBAAoB;EAE5C,MAAM,OAAO,MAAM,SAAS,MAAM,QAAQ;EAC1C,OAAO,SAAS,OAAO,OAAO,IAAI,cAAc,IAAI;CACtD,CAAC;AACH"}

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. */
@@ -618,6 +618,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,16 +771,13 @@ 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),
 		...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);
 }
@@ -1576,6 +1661,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 +1755,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 +2417,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 +2564,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 +2586,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 +2611,8 @@ var HubConnection = class {
 					rank: completion.rank,
 					meta: payload.meta
 				});
-			}
+			},
+			resume: this.resumeStore
 		});
 		this.importLegacyQueue();
 		if (typeof navigator !== "undefined" && "onLine" in navigator) this.isReachable = navigator.onLine;
@@ -3120,6 +3318,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 +3745,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 +3811,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 +3876,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 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