@diffenderfer-games/hub-contract 0.0.0-stage → 2.0.0-next.0

package/dist/index.js

@@ -0,0 +1,4855 @@
+import { z } from "zod";
+import { ctx, middleware, spec, use } from "@ayepi/core";
+//#region src/common.ts
+/**
+* Primitives shared by every part of the contract. Each one is the single
+* definition of its rule: the server validates with it, the client's types
+* come from it, and the docs are generated from it.
+*/
+/** A user id: a positive integer. In paths it arrives as a string and is coerced. */
+const UserId = z.number().int().positive();
+/** A user id taken from a URL path segment (`/players/:userId`). */
+const UserIdParam = z.coerce.number().int().positive();
+/** A numeric row id taken from a URL path segment (`/trades/:id`, `/reports/:id`). */
+const IdParam = z.coerce.number().int().positive();
+/** Milliseconds since the Unix epoch. */
+const Millis = z.number().int().nonnegative();
+/** A game's slug: its folder name under `apps/`, as used in `/<slug>/` URLs. */
+const Slug = z.string().min(1).max(64);
+/**
+* An app-chosen identifier: a save slot, leaderboard key or stat name.
+* Letters, digits and `_ . : -`, 1 to 64 characters.
+*/
+const Key = z.string().regex(/^[A-Za-z0-9_.:-]{1,64}$/);
+/** Any JSON value (saves, metadata, room state). */
+const Json = z.json();
+/** The `{ ok: true }` body many write endpoints answer with. */
+const Ok = z.object({ ok: z.literal(true) });
+/** A UTC day key, `YYYY-MM-DD`. */
+const DayKey = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+/** A `#rrggbb` colour. */
+const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
+//#endregion
+//#region src/entities.ts
+/**
+* Entity shapes that several areas of the API share. Shapes used by only one
+* area live in that area's `api/` file.
+*/
+/** Account roles. An empty string is a normal player. */
+const Role = z.enum(["", "admin"]);
+/**
+* The signed-in user as the hub sees it (`GET /me`, socket `hello`).
+* `id`, `username` and `guest` are the long-standing fields; the rest drive
+* social permissions and are only ever sent to the user themself.
+*/
+const SessionUser = z.object({
+	id: UserId,
+	username: z.string(),
+	/** A temporary account with no password yet; it can be claimed. */
+	guest: z.boolean(),
+	role: Role,
+	/** Avatar token, `''` for the default. */
+	avatar: z.string(),
+	/** A parent locked chat for this account. */
+	chatLock: z.boolean(),
+	/** Muted until this time (epoch ms), `0` when not muted. */
+	mutedUntil: Millis,
+	/** Suspended until this time (epoch ms), `0` when not suspended. */
+	suspendedUntil: Millis
+});
+/** The short account shape the auth endpoints return for a new session. */
+const AuthUser = SessionUser.pick({
+	id: true,
+	username: true,
+	guest: true
+});
+/**
+* The effective chat mode of a conversation, room or the whole site: free
+* text (still filtered), quick-chat phrases only, or no messaging at all.
+* The strictest of the operator setting, the admin switch and every
+* participant (guests and parent-locked accounts are `quick`) applies.
+*/
+const ChatMode = z.enum([
+	"on",
+	"quick",
+	"off"
+]);
+/** Another player as lists and cards show them. */
+const PlayerLite = z.object({
+	id: UserId,
+	username: z.string(),
+	/** Avatar token; never empty (a default is derived from the id). */
+	avatar: z.string(),
+	guest: z.boolean()
+});
+//#endregion
+//#region src/errors/codes/core.ts
+/** Error codes any endpoint or socket op can return. */
+const CORE_CODES = [
+	"bad_request",
+	"signed_out",
+	"suspended",
+	"claim_required",
+	"rate_limited",
+	"content_rejected",
+	"too_large"
+];
+//#endregion
+//#region src/errors/codes/multiplayer.ts
+/** Error codes from invites, parties, hub rooms, races and the socket envelope. */
+const MULTIPLAYER_CODES = [
+	"unknown_op",
+	"hello_required",
+	"not_multiplayer",
+	"not_supported",
+	"bad_mode",
+	"bad_target",
+	"cannot_invite",
+	"already_member",
+	"party_full",
+	"invite_gone",
+	"party_gone",
+	"not_leader",
+	"bad_info",
+	"launch_invalid",
+	"not_joinable",
+	"bad_quick",
+	"room_not_found",
+	"not_in_room",
+	"not_host",
+	"too_many_rooms",
+	"banned",
+	"in_progress",
+	"room_full",
+	"not_ready",
+	"ended",
+	"bad_patch",
+	"race_room",
+	"not_race",
+	"not_in_race",
+	"not_started",
+	"race_over",
+	"too_fast",
+	"bad_stats",
+	"bad_param"
+];
+//#endregion
+//#region src/errors/codes/play.ts
+/** Error codes from accounts and the single-player API (saves, stats, boards, daily, economy, trades). */
+const PLAY_CODES = ["server_board"];
+//#endregion
+//#region src/errors/codes/social.ts
+/** Error codes from friends, messages, notifications, reports and suggestions. */
+const SOCIAL_CODES = [
+	"no_player",
+	"bad_avatar",
+	"bad_password",
+	"friend_requests_off",
+	"bad_target",
+	"guest_target",
+	"blocked",
+	"friends_limit",
+	"pending_limit",
+	"no_request",
+	"not_friends",
+	"blocks_limit",
+	"dms_closed",
+	"too_many_pending"
+];
+/** Every public error code. */
+const ErrorCode = z.enum([
+	...CORE_CODES,
+	...PLAY_CODES,
+	...SOCIAL_CODES,
+	...MULTIPLAYER_CODES
+]);
+/**
+* Why text was rejected or a chat action was refused. Coarse on purpose: a
+* reason names a category, never the word or list that matched.
+*/
+const RejectReason = z.enum([
+	"link",
+	"personal_info",
+	"contact",
+	"language",
+	"slur",
+	"sexual",
+	"grown_up",
+	"unkind",
+	"threat",
+	"drugs",
+	"spam",
+	"shouting",
+	"too_long",
+	"empty",
+	"chars",
+	"reserved",
+	"rate_limited",
+	"muted",
+	"check_unavailable",
+	"chat_off",
+	"not_friends",
+	"suspended",
+	"quick_only",
+	"dms_closed",
+	"other"
+]);
+const errorBody = z.object({
+	/** A sentence that is always safe to show the player. */
+	error: z.string(),
+	/** What went wrong, for code to branch on. */
+	code: ErrorCode.optional(),
+	/** Content rejects and suspensions: the category. */
+	reason: RejectReason.optional(),
+	/** A kid-friendly suggestion, e.g. "try saying it another way". */
+	hint: z.string().optional(),
+	/** Rate limits: how long to wait, in ms (0 when not limited). */
+	retryAfterMs: z.number().int().nonnegative().optional(),
+	/** Suspensions and mutes: when they end (epoch ms). */
+	until: Millis.optional()
+});
+/** The body of every error response and failed socket ack. */
+const ErrorBody = errorBody;
+/**
+* The 422 content-rejected body (multiplayer.md §4.6), shared by DMs, room
+* chat, suggestions, names and trade notes.
+*/
+const ContentRejected = errorBody.extend({
+	code: z.literal("content_rejected"),
+	reason: RejectReason,
+	hint: z.string()
+});
+//#endregion
+//#region src/middleware.ts
+/**
+* Middleware **defs** for the public API (plan §6.1). A def is a contract
+* only: a name, the context it provides and its dependencies. It holds no
+* code, so it is safe in a published package; the server binds the real
+* implementation. Each endpoint's guards are part of its declaration, which
+* lets tests check rules such as "every social endpoint requires an active
+* account" (plan §10.3).
+*/
+/**
+* Resolves the `hub_session` cookie (the user, or `null`) and the anonymous
+* `hub_cid` client id. Every endpoint has it.
+*/
+const session = middleware("session", {
+	provides: ctx(),
+	doc: { security: { cookieAuth: {
+		type: "apiKey",
+		in: "cookie",
+		name: "hub_session"
+	} } }
+});
+/** Signed in, as a guest or an account. Otherwise 401 `signed_out`. */
+const requireUser = middleware("requireUser", {
+	provides: ctx(),
+	requires: [session]
+});
+/**
+* Signed in and not suspended. Otherwise 401 `signed_out` or 403
+* `suspended`. Every social, multiplayer, race and trade endpoint has it.
+*/
+const requireActive = middleware("requireActive", {
+	provides: ctx(),
+	requires: [requireUser]
+});
+/** Active and a claimed account (not a guest). Otherwise 403 `claim_required`. */
+const requireClaimed = middleware("requireClaimed", {
+	provides: ctx(),
+	requires: [requireActive]
+});
+/**
+* Owns the `:slug` path segment and checks it names a known game.
+* Otherwise 404 "No such game".
+*/
+const game = middleware.loader("slug", Slug, { requires: [session] });
+//#endregion
+//#region src/coerce.ts
+/**
+* Request coercions the single-player handlers apply today. The old hub reads
+* many request fields loosely (`Number(x)`, `String(x)`, truthiness), and the
+* contract must accept every request the hub accepts, so these schemas
+* coerce the same way while keeping the input type clients should send.
+*/
+/**
+* A finite number, read like the hub's `Number(x)`: numeric strings (and
+* query-string values) pass. Clients should send a JSON number.
+*/
+const LooseNumber = z.coerce.number();
+/**
+* A flag read by truthiness, like the hub's `if (body.on)`: any value is
+* accepted and becomes `true` or `false`. Clients should send a boolean.
+*/
+const Truthy = z.coerce.boolean();
+/**
+* Free text read with `String(x)`; the hub trims or clips it to its own limit
+* rather than rejecting it. Clients should send a string.
+*/
+const LooseText = z.coerce.string();
+/**
+* A row count from the query string (`?limit=`, `?top=`). The hub clamps it to
+* its own range and falls back to a default for `0` or a missing value.
+*/
+const RowCount = LooseNumber.int();
+/**
+* Required text read like the hub's `String(x || '')`, with the old hub's
+* message for a missing or invalid value. Numbers are accepted and become
+* strings; anything else fails with `message`. Refine the result with
+* `.pipe(...)` (e.g. a pattern carrying the same message).
+*/
+function requiredText(message) {
+	return z.union([z.string(), z.number()], { error: message }).transform(String);
+}
+/**
+* A positive integer id read like the hub's `Number(x)` (numeric strings
+* pass), with the old hub's message for any bad value (`"id must be a user
+* id."`). Clients should send a JSON number.
+*/
+function requiredId(message) {
+	return z.coerce.number({ error: message }).int({ error: message }).positive({ error: message });
+}
+//#endregion
+//#region src/api/analytics.ts
+/**
+* Gameplay events and client error logs sent by games and the menu, and the
+* play counts built from them. Events need no account: they carry the user id
+* when signed in and always the anonymous `hub_cid` client id.
+*/
+/** Play counts for one game or the whole catalog. A player is an account, else a client id. */
+const Metrics = z.object({
+	/** `play` events recorded. */
+	totalPlays: z.number().int().nonnegative(),
+	/** Distinct players who sent any event. */
+	uniquePlayers: z.number().int().nonnegative(),
+	/** Distinct players with a `play` or `heartbeat` in the last 5 minutes (`HUB_ACTIVE_WINDOW_MS`). */
+	activeNow: z.number().int().nonnegative()
+});
+/** The analytics endpoints. */
+const analyticsEndpoints = {
+	...session.group({
+		getSiteAnalytics: {
+			method: "GET",
+			path: "/analytics",
+			response: z.object({
+				global: Metrics,
+				games: z.array(Metrics.extend({
+					slug: Slug,
+					title: z.string()
+				}))
+			}),
+			doc: {
+				summary: "Catalog-wide play counts with a per-game breakdown",
+				tags: ["analytics"]
+			}
+		},
+		/**
+		* Report a client-side failure (for example the social runtime failing
+		* to load) to the admin console. Open to signed-out visitors; limited to
+		* 20 an hour per IP, after which it answers `{ ok: false }` and drops the
+		* report. Fields are clipped, never rejected.
+		*/
+		reportClientError: {
+			method: "POST",
+			path: "/client-log",
+			body: z.object({
+				/** Which part failed, up to 40 characters (`unknown` when empty). */
+				where: LooseText.optional(),
+				/** Up to 300 characters. */
+				message: LooseText.optional(),
+				/** Up to 1200 characters. */
+				stack: LooseText.optional(),
+				/** The page, up to 200 characters. */
+				url: LooseText.optional()
+			}),
+			response: z.object({ 
+			/** `false` when the report was dropped by the rate limit. */
+ok: z.boolean() }),
+			doc: {
+				summary: "Report a client error to the admin console",
+				tags: ["analytics"]
+			}
+		}
+	}),
+	...use(session, game).path("/games/:slug").group({
+		/** Record one event. The menu sends `play` on load and periodic `heartbeat`s; games may add their own. */
+		recordGameEvent: {
+			method: "POST",
+			path: "/events",
+			body: z.object({ 
+			/** 1 to 32 of letters, digits and `_ . : -` (surrounding spaces are trimmed). */
+type: requiredText("Invalid event type.").pipe(z.string().trim().regex(/^[a-z0-9_.:-]{1,32}$/i, "Invalid event type.")) }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Record a gameplay event",
+				tags: ["analytics"]
+			}
+		},
+		getGameAnalytics: {
+			method: "GET",
+			path: "/analytics",
+			response: Metrics.extend({ slug: Slug }),
+			errors: { 404: ErrorBody },
+			doc: {
+				summary: "This game's play counts",
+				tags: ["analytics"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/auth.ts
+/**
+* Accounts and sessions: guests, claiming, sign-up, log-in, log-out, and the
+* current user (`/me`). Sessions ride the `hub_session` cookie.
+*/
+/**
+* A credential field, read like the hub's `String(x ?? '')`: a missing field
+* is empty text (the hub then answers with its own rule, or a failed log-in)
+* and a number becomes text. Clients should send a string.
+*/
+function credentialText(message) {
+	return z.union([z.string(), z.number()], { error: message }).nullish().transform((value) => String(value ?? ""));
+}
+/** Username + password, as the sign-up, claim and log-in forms send them. */
+const Credentials = z.object({
+	/** 2 to 24 characters: letters, digits, `_`, `-` and spaces. */
+	username: credentialText("Username can use letters, numbers, _, -, and spaces."),
+	/** At least 6 characters. */
+	password: credentialText("Password must be at least 6 characters.")
+});
+/** `{ user }`: the session's account after an auth call. */
+const AuthResult = z.object({ user: AuthUser });
+/** A 400 from sign-up or claim: a bad name or password, or a name the filter rejects. */
+const CredentialsError = z.union([ContentRejected, ErrorBody]);
+/** The auth endpoints. */
+const authEndpoints = {
+	...session.group({
+		/**
+		* Make sure a session exists. Idempotent: returns the current user if
+		* signed in (the full {@link SessionUser}), else creates a guest.
+		*/
+		ensureGuestSession: {
+			method: "POST",
+			path: "/auth/guest",
+			response: z.object({ user: z.union([SessionUser, AuthUser]) }),
+			doc: {
+				summary: "Ensure a session (creates a guest if needed)",
+				tags: ["auth"]
+			}
+		},
+		signUpWithPassword: {
+			method: "POST",
+			path: "/auth/signup",
+			body: Credentials,
+			response: AuthResult,
+			errors: {
+				400: CredentialsError,
+				409: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Create an account and sign in",
+				tags: ["auth"]
+			}
+		},
+		logInWithPassword: {
+			method: "POST",
+			path: "/auth/login",
+			body: Credentials,
+			response: AuthResult,
+			errors: {
+				401: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Sign in; a guest session on this device is merged into the account",
+				tags: ["auth"]
+			}
+		},
+		logOut: {
+			method: "POST",
+			path: "/auth/logout",
+			response: Ok,
+			doc: {
+				summary: "Sign out and clear the session cookie",
+				tags: ["auth"]
+			}
+		},
+		getCurrentUser: {
+			method: "GET",
+			path: "/me",
+			response: z.object({
+				user: SessionUser.nullable(),
+				/** Games the user has a profile in. */
+				profiles: z.array(z.object({
+					game: Slug,
+					displayName: z.string().nullable()
+				}))
+			}),
+			doc: {
+				summary: "The current user (or null) and their game profiles",
+				tags: ["auth"]
+			}
+		}
+	}),
+	...requireUser.group({ claimGuestAccount: {
+		method: "POST",
+		path: "/auth/claim",
+		body: Credentials,
+		response: AuthResult,
+		errors: {
+			400: CredentialsError,
+			401: ErrorBody,
+			409: ErrorBody,
+			429: ErrorBody
+		},
+		doc: {
+			summary: "Turn the current guest into an account, keeping its progress",
+			tags: ["auth"]
+		}
+	} })
+};
+//#endregion
+//#region src/limits.ts
+/**
+* Limits a UI has to know about: text lengths, name rules, seat counts and
+* the rules for a game's `package.json` `game.*` block. Each number is
+* defined once here; the schemas and the server import it.
+*
+* Rate thresholds, caps and timers are server-only and not part of this package.
+*/
+/** Account name and password rules (sign-up, claim, rename). */
+const ACCOUNT_LIMITS = {
+	/** Shortest username, after trimming. */
+	usernameMin: 2,
+	/** Longest username, after trimming. */
+	usernameMax: 24,
+	/** Shortest password. */
+	passwordMin: 6,
+	/** How many built-in avatars there are (`a0` … `a23`). */
+	avatarCount: 24
+};
+/** The characters a username may use: letters, digits, `_`, `-` and spaces. */
+const USERNAME_PATTERN = /^[A-Za-z0-9_\- ]+$/;
+/**
+* The text limits every social UI renders from. The hub sends the live values
+* in `GET /social/config` and the socket `hello` (`limits`); the server can
+* change them (`HUB_LIMITS_JSON`), so a UI should prefer the sent values.
+*/
+const UiLimits = z.object({
+	/** Longest direct message, in characters. */
+	dmMaxChars: z.number().int().positive(),
+	/** Longest room or party chat line, in characters. */
+	roomChatMaxChars: z.number().int().positive(),
+	/** Longest suggestion title, in characters. */
+	suggestionTitleMax: z.number().int().positive(),
+	/** Longest suggestion body, in characters. */
+	suggestionBodyMax: z.number().int().positive()
+});
+/** Today's default {@link UiLimits}, used until the hub sends its own. */
+const UI_LIMIT_DEFAULTS = {
+	dmMaxChars: 200,
+	roomChatMaxChars: 120,
+	suggestionTitleMax: 60,
+	suggestionBodyMax: 500
+};
+/** Seats in hub rooms and parties. */
+const SEAT_LIMITS = {
+	/** Most players in one hub room, and the top of any `players` range. */
+	maxSeats: 8,
+	/** Most members in one party. */
+	partyMax: 8
+};
+/** What a racer's live stats (`hub.race.status(stats)`) may hold. */
+const RACE_STATS_LIMITS = {
+	/** Most stat keys in one update. */
+	maxKeys: 12,
+	/** Largest update, in bytes of JSON. */
+	maxBytes: 600
+};
+/** Limits on the `package.json` `game.*` block (see the manifest schemas). */
+const MANIFEST_LIMITS = {
+	/** Most `game.changes` entries the hub reads. */
+	changesMax: 200,
+	/** Longest `game.changes` entry, in characters. */
+	changeTextMax: 280,
+	/** Longest leaderboard title, in characters. */
+	leaderboardTitleMax: 80,
+	/** Furthest the menu button may be pushed from its corner, in px. */
+	menuOffsetMax: 600,
+	/** Longest lobby URL suffix, in characters. */
+	lobbyMax: 200,
+	/** Most `game.multiplayer.modes`. */
+	modesMax: 16,
+	/** Longest mode title, in characters. */
+	modeTitleMax: 40,
+	/** Most `game.multiplayer.quickChat` phrases. */
+	quickChatMax: 24,
+	/** Longest quick-chat phrase, in characters. */
+	quickChatTextMax: 40,
+	/** Most `game.multiplayer.chatAllow` words. */
+	chatAllowMax: 20,
+	/** Most `game.race.params`. */
+	raceParamsMax: 6,
+	/** Most options in one race param. */
+	raceOptionsMax: 12,
+	/** Most `game.race.stats` (the live HUD shows the first 3). */
+	raceStatsMax: 8,
+	/** Longest race param, option or stat title, in characters. */
+	raceTitleMax: 24,
+	/** Largest `game.race.minMs`, in ms (10 minutes). */
+	raceMinMsMax: 6e5
+};
+//#endregion
+//#region src/api/mp/races.ts
+/**
+* Race shapes (docs/plans/race.md): params, live stats, racers and decided
+* results. Shared by the `race.*` socket ops and events, the race block of
+* a room, and `GET /race/history`. Each rule here is defined once.
+*/
+/** A race param or stat key: a letter, then up to 23 letters, digits or `_`. */
+const RaceKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,23}$/);
+/** A race param value, one of the game's declared options: a number, a boolean or a short token. */
+const RaceParamValue = z.union([
+	z.number(),
+	z.boolean(),
+	z.string().regex(/^[A-Za-z0-9_-]{1,24}$/)
+]);
+/**
+* The creator's choices, keyed by the manifest's `race.params[].key`. The
+* hub keeps only declared keys and option values (anything else becomes the
+* param's default), so everyone gets the same puzzle.
+*/
+const RaceParams = z.record(RaceKey, RaceParamValue);
+/** Live stat values are clamped to ±1e9. */
+const STAT_LIMIT = 1e9;
+/**
+* A live stat value: a finite number (clamped to ±1e9), a boolean or a
+* `#rrggbb` colour (lower-cased). Never text.
+*/
+const RaceStatValue = z.union([
+	z.number().transform((n) => Math.max(-1e9, Math.min(STAT_LIMIT, n))),
+	z.boolean(),
+	HexColor.transform((c) => c.toLowerCase())
+]);
+/**
+* A racer's live stats, keyed like the manifest's `race.stats[].key`: at
+* most 12 keys and 600 bytes of JSON once cleaned.
+*/
+const RaceStats = z.record(RaceKey, RaceStatValue).refine((s) => Object.keys(s).length <= RACE_STATS_LIMITS.maxKeys, `at most ${String(RACE_STATS_LIMITS.maxKeys)} stats`).refine((s) => JSON.stringify(s).length <= RACE_STATS_LIMITS.maxBytes, "stats too large");
+/** How far along a racer is, 0 to 1. The hub clamps values outside that range. */
+const RaceProgress = z.number().transform((n) => Math.max(0, Math.min(1, n)));
+/** A race room's phase: waiting for racers → countdown → racing → done (→ countdown on a rematch). */
+const RacePhase = z.enum([
+	"waiting",
+	"countdown",
+	"racing",
+	"done"
+]);
+/** A racer's state while the race runs. */
+const RacerState = z.enum([
+	"racing",
+	"finished",
+	"lost",
+	"forfeit",
+	"disconnected"
+]);
+/** How a race ended: the winner finished, everyone else lost / gave up / dropped, or time ran out. */
+const RaceOutcome = z.enum([
+	"finished",
+	"lost",
+	"forfeit",
+	"disconnected",
+	"timeout"
+]);
+/** One racer's result. `beaten`: still racing when someone else won. */
+const RacerResult = z.enum([
+	"won",
+	"beaten",
+	"lost",
+	"forfeit",
+	"disconnected",
+	"timeout"
+]);
+/** Fields every live racer line has (room roster and result card). */
+const RacerLine = z.object({
+	userId: UserId,
+	/** The racer's username when the race began. */
+	name: z.string(),
+	/** Avatar token; never empty. */
+	avatar: z.string(),
+	stats: RaceStats,
+	/** 0..1, when the game reports it. */
+	progress: RaceProgress.optional()
+});
+/** A racer in a race room's roster (RoomInfo.race.players). */
+const Racer = RacerLine.extend({
+	state: RacerState,
+	/** Server-measured ms from the go to finishing or dropping out. */
+	ms: z.number().int().nonnegative().optional()
+});
+/** One racer's line in a {@link RaceResult}. */
+const RaceResultPlayer = RacerLine.extend({
+	/** 1 for the winner. */
+	place: z.number().int().positive(),
+	result: RacerResult,
+	/** Server-measured ms from the go to finishing or dropping out (the race's end for those still in). */
+	ms: z.number().int().nonnegative()
+});
+/** Fields a decided race has both live and in the history. */
+const DecidedRace = z.object({
+	game: Slug,
+	params: RaceParams,
+	outcome: RaceOutcome,
+	/** Epoch ms of the go. */
+	startedAt: Millis,
+	/** Epoch ms. */
+	endedAt: Millis,
+	/** ms from the go to the decision. */
+	durationMs: z.number().int().nonnegative()
+});
+/** A decided race: the `race.result` event, the `race.finish` ack and RoomInfo.race.result. */
+const RaceResult = DecidedRace.extend({
+	/** The race's id in the history; `null` if recording it failed. */
+	id: z.number().int().positive().nullable(),
+	/** The room code. */
+	room: z.string(),
+	/** 1 for the room's first race, +1 per rematch. */
+	round: z.number().int().positive(),
+	seed: z.number().int().positive(),
+	/** `null` when nobody won (time ran out, or everyone dropped out). */
+	winnerId: UserId.nullable(),
+	/** In finishing order (place 1 first). */
+	players: z.array(RaceResultPlayer)
+});
+/** The referee's view of a race room (RoomInfo.race). */
+const RaceState = z.object({
+	phase: RacePhase,
+	/** 1 for the first race in the room, +1 per rematch; 0 while waiting for the first. */
+	round: z.number().int().nonnegative(),
+	params: RaceParams,
+	/** The countdown can start once this many racers are seated. */
+	minPlayers: z.number().int().positive(),
+	/** Everyone racing this round (empty while waiting for the first). */
+	players: z.array(Racer),
+	/** Who asked for a rematch since the last race. */
+	rematch: z.array(UserId),
+	/** Present once the countdown starts (never before, so nobody can pre-solve). */
+	seed: z.number().int().positive().optional(),
+	/** Epoch ms of the go (server clock); present with `seed`. */
+	startAt: Millis.optional(),
+	/** Present once the round is decided. */
+	result: RaceResult.optional()
+});
+/** The countdown began (`race.start`): build the puzzle from `seed` + `params`. */
+const RaceStart = z.object({
+	roomId: z.string(),
+	round: z.number().int().positive(),
+	seed: z.number().int().positive(),
+	params: RaceParams,
+	/** Epoch ms of the go (server clock). */
+	startAt: Millis,
+	/** ms until the go. */
+	startsIn: z.number().int().nonnegative(),
+	/** The racers' user ids. */
+	players: z.array(UserId)
+});
+/** A racer in a history record. Suspended opponents are `hidden`: id 0, name "A player", no avatar. */
+const RaceRecordPlayer = z.object({
+	/** 0 when hidden. */
+	userId: z.number().int().nonnegative(),
+	username: z.string(),
+	/** Avatar token; `''` when hidden. */
+	avatar: z.string(),
+	guest: z.boolean(),
+	place: z.number().int().positive(),
+	result: RacerResult,
+	/** Server-measured ms from the go to finishing or dropping out. */
+	ms: z.number().int().nonnegative().optional(),
+	progress: RaceProgress.optional(),
+	stats: RaceStats,
+	hidden: z.literal(true).optional()
+});
+/** One past race the player was in (`GET /race/history`). */
+const RaceRecord = DecidedRace.extend({
+	id: z.number().int().positive(),
+	gameTitle: z.string(),
+	/** `null` when nobody won; 0 when the winner is hidden (suspended). */
+	winnerId: z.number().int().nonnegative().nullable(),
+	/** The signed-in player's own line (`null` only if their row is missing). */
+	me: RaceRecordPlayer.nullable(),
+	/** In place order. */
+	players: z.array(RaceRecordPlayer)
+});
+//#endregion
+//#region src/manifest/fields.ts
+/**
+* Field rules shared by several parts of the `game.*` manifest. Each rule is
+* defined once here.
+*/
+/**
+* A non-empty string with no leading or trailing whitespace. Used for fields
+* the hub reads verbatim (commands, paths, titles), where stray spaces are a
+* mistake rather than something the hub would trim away.
+*/
+const Trimmed = z.string().regex(/^\S(?:[\s\S]*\S)?$/, "must be non-empty, with no leading or trailing spaces");
+/** A label the hub trims and shows to players, at most `max` characters. */
+function trimmedText(max) {
+	return z.string().trim().min(1).max(max);
+}
+/**
+* A URL suffix relative to `/<slug>/` that invites and Join open, such as
+* `?lobby=1` or `play/online`. Not absolute, no `..`, no `//`.
+*/
+const LobbySuffix = z.string().trim().regex(new RegExp(`^[A-Za-z0-9_./?=&#%-]{0,${MANIFEST_LIMITS.lobbyMax}}$`), "may only use letters, digits and _ . / ? = & # % -").refine((s) => !s.startsWith("/") && !s.includes("..") && !s.includes("//"), "must be a relative URL suffix (no leading /, no .., no //)");
+/**
+* A `[min, max]` player range: whole numbers, `lowest <= min <= max <= 8`.
+*
+* @param lowest - the smallest `min` allowed (1 for multiplayer, 2 for races)
+*/
+function playerRange(lowest) {
+	const seatCount = z.number().int().min(lowest).max(SEAT_LIMITS.maxSeats);
+	return z.tuple([seatCount, seatCount]).refine(([min, max]) => min <= max, `must be [min, max] with ${lowest} <= min <= max <= ${SEAT_LIMITS.maxSeats}`);
+}
+/**
+* An optional block that may also be written as `false` ("off"). `false`
+* parses to `undefined`, the same as leaving the field out.
+*
+* (A `z.union` with `z.literal(false)` would work too, but it hides the
+* block's own field errors behind a bare "Invalid input".)
+*/
+function orFalse(block) {
+	return z.preprocess((v) => v === false ? void 0 : v, block.optional()).optional();
+}
+/** True when no two items share a `key`. */
+function hasUniqueKeys(items) {
+	return new Set(items.map((i) => i.key)).size === items.length;
+}
+/** The placeholders a `build` or `start` command may use. */
+const COMMAND_PLACEHOLDERS = [
+	"PORT",
+	"GAME_PATH",
+	"GAME_SLUG"
+];
+const PLACEHOLDER = /\{\{(\w+)\}\}/g;
+const KNOWN_PLACEHOLDERS = new Set(COMMAND_PLACEHOLDERS);
+/**
+* A shell command the host runs in the app folder. It may use the
+* placeholders `{{PORT}}`, `{{GAME_PATH}}` and `{{GAME_SLUG}}`; any other
+* `{{NAME}}` fails the build.
+*/
+const Command = Trimmed.refine((cmd) => [...cmd.matchAll(PLACEHOLDER)].every((m) => KNOWN_PLACEHOLDERS.has(m[1] ?? "")), `may only use the placeholders ${COMMAND_PLACEHOLDERS.map((p) => `{{${p}}}`).join(", ")}`);
+/** True when a relative path names something strictly inside its folder. */
+function staysInside(path) {
+	let depth = 0;
+	for (const part of path.split(/[\\/]/)) if (part === "..") {
+		depth -= 1;
+		if (depth < 0) return false;
+	} else if (part !== "" && part !== ".") depth += 1;
+	return depth > 0;
+}
+/** A file path relative to the app folder that stays inside it, e.g. `cover.png`. */
+const AppFilePath = Trimmed.refine(staysInside, "must be a file inside the app folder");
+//#endregion
+//#region src/manifest/race.ts
+/**
+* `game.race`: the opt-in that turns a single-player game into a race target
+* (docs/multiplayer.md §14, docs/plans/race.md §5).
+*/
+const RaceTitle = trimmedText(MANIFEST_LIMITS.raceTitleMax);
+/** One choice of a race param: a bare value, or a value with a title. */
+const RaceOption = z.union([RaceParamValue, z.strictObject({
+	/** The value the game receives in `r.params[key]`. */
+	value: RaceParamValue,
+	/** What the creator sees. Defaults to the value. Checked like quick-chat text. */
+	title: RaceTitle.optional()
+})]);
+/** The value of an option, bare or titled. */
+function optionValue(option) {
+	return typeof option === "object" ? option.value : option;
+}
+/** A choice the race creator makes. The server only accepts declared values. */
+const RaceParam = z.strictObject({
+	/** The key the game reads, `r.params[key]`. */
+	key: RaceKey,
+	/** What the creator sees. Defaults to the key. Checked like quick-chat text. */
+	title: RaceTitle.optional(),
+	/** The choices, 1 to 12. */
+	options: z.array(RaceOption).min(1).max(MANIFEST_LIMITS.raceOptionsMax),
+	/** The preselected value; one of the options' values. Defaults to the first. */
+	default: RaceParamValue.optional()
+}).refine((p) => p.default === void 0 || p.options.some((option) => optionValue(option) === p.default), {
+	message: "default must be one of the option values",
+	path: ["default"]
+});
+/** How the live race HUD and the race history show a stat. */
+const RaceStatFormat = z.enum([
+	"int",
+	"percent",
+	"time",
+	"bool",
+	"color"
+]);
+/** A stat the live race HUD and the race history show. */
+const RaceStat = z.strictObject({
+	/** The key the game sends in `hub.race.status({ [key]: value })`. */
+	key: RaceKey,
+	/** The column label. Defaults to the key. Checked like quick-chat text. */
+	title: RaceTitle.optional(),
+	/** `int` (default), `percent`, `time` (ms), `bool` or `color` (`#rrggbb`). */
+	format: RaceStatFormat.default("int")
+});
+/** The `game.race` object form. */
+const RaceBlock = z.strictObject({
+	/** URL suffix race invites and Join open, relative to `/<slug>/`. Default `?race=lobby`. */
+	lobby: LobbySuffix.default("?race=lobby"),
+	/** `[min, max]` racers, within 2..8. Default `[2, 2]`. */
+	players: playerRange(2).default([2, 2]),
+	/** What the creator picks (at most 6, unique keys). */
+	params: z.array(RaceParam).max(MANIFEST_LIMITS.raceParamsMax).refine(hasUniqueKeys, "param keys must be unique").default([]),
+	/** What the live HUD and the history show (at most 8, unique keys; the HUD shows the first 3). */
+	stats: z.array(RaceStat).max(MANIFEST_LIMITS.raceStatsMax).refine(hasUniqueKeys, "stat keys must be unique").default([]),
+	/**
+	* The earliest a finish may count after the go, in ms (0 to 600000). A
+	* sooner finish is held until then. Default: the hub's `raceMinFinishMs`.
+	*/
+	minMs: z.number().int().min(0).max(MANIFEST_LIMITS.raceMinMsMax).optional()
+});
+/**
+* `game.race`: an object, `true` for all defaults (no params, no stats), or
+* `false` for off. `true` parses to the object form, `false` to `undefined`.
+*/
+const GameRace = z.preprocess((v) => v === true ? {} : v === false ? void 0 : v, RaceBlock.optional()).optional();
+//#endregion
+//#region src/api/catalog.ts
+/**
+* The game catalog, favorites and What's new notes.
+*/
+/** A `[min, max]` player count, each 1 to 8. */
+const PlayerRange = z.tuple([z.number().int().min(1).max(8), z.number().int().min(1).max(8)]);
+/**
+* What the menu needs to know about an online game (invite picker, Join and
+* Watch buttons, the catalog's Online tag), not the full manifest.
+*/
+const MultiplayerSummary = z.object({
+	/** `own-server` only for process apps that run their own game server. */
+	transport: z.enum(["hub-rooms", "own-server"]),
+	players: PlayerRange,
+	invites: z.boolean(),
+	join: z.boolean(),
+	spectate: z.boolean(),
+	modes: z.array(z.object({
+		key: z.string(),
+		title: z.string()
+	})),
+	/** Present (and `true`) when the block was made for a race-only game. */
+	raceOnly: z.literal(true).optional()
+});
+/** A race game's manifest summary (players, the creator's param choices, the stats the HUD shows). */
+const RaceSummary = z.object({
+	/** Each 2 to 8. */
+	players: PlayerRange,
+	/** Up to 6 choices the race creator picks. */
+	params: z.array(z.object({
+		key: z.string(),
+		title: z.string(),
+		/** Up to 12. */
+		options: z.array(z.object({
+			value: RaceParamValue,
+			title: z.string()
+		})),
+		/** One of the options' values. */
+		default: RaceParamValue
+	})),
+	/** Up to 8 stats the race HUD and history show. */
+	stats: z.array(z.object({
+		key: z.string(),
+		title: z.string(),
+		format: RaceStatFormat
+	}))
+});
+/** A listed game, as the menu's game list and the catalog show it. Broken apps are left out. */
+const GameInfo = z.object({
+	slug: Slug,
+	title: z.string(),
+	/** Its URL path, e.g. `/duel`. */
+	path: z.string(),
+	/** `process` apps run their own server behind the host. */
+	kind: z.enum(["static", "process"]),
+	hasImage: z.boolean(),
+	/** `false` when the game opted out of the injected hub menu. */
+	hubEnabled: z.boolean(),
+	/** `null` for single-player games. */
+	multiplayer: MultiplayerSummary.nullable(),
+	/** `null` unless the game supports races. */
+	race: RaceSummary.nullable()
+});
+/** `{ games }`: the caller's starred slugs, oldest star first. */
+const Favorites = z.object({ games: z.array(Slug) });
+/** One What's new note. */
+const ChangeNote = z.object({
+	id: z.number().int().positive(),
+	/** The game's slug, or `_hub` for the site's own notes. */
+	game: Slug,
+	/** The game's title, or `diffenderfer.games` for the site's own notes. */
+	title: z.string(),
+	text: z.string(),
+	/** When the note went live (the deploy that first saw it), epoch ms. */
+	at: Millis,
+	/** Not yet seen by this player (or since `?since=` when signed out). */
+	new: z.boolean()
+});
+/** The catalog endpoints. */
+const catalogEndpoints = {
+	...session.group({
+		listGames: {
+			method: "GET",
+			path: "/games",
+			response: z.object({ games: z.array(GameInfo) }),
+			doc: {
+				summary: "The game catalog, sorted by title",
+				tags: ["catalog"]
+			}
+		},
+		/**
+		* Notes from the last 30 days, newest first (at most 6 per game and 30
+		* in all). In a game, `?game=` limits them to that game's and the site's.
+		*/
+		listWhatsNewNotes: {
+			method: "GET",
+			path: "/changes",
+			query: z.object({
+				/** A game's slug. Empty means everything; an unknown one lists only the site's notes. */
+				game: z.string().optional(),
+				/**
+				* Signed out only: the device's last-cleared time (epoch ms); without
+				* it (or when it isn't a number) nothing is new.
+				*/
+				since: z.preprocess((value) => value === "" ? void 0 : value, LooseNumber.optional()).catch(void 0)
+			}),
+			response: z.object({
+				items: z.array(ChangeNote),
+				/** How many of `items` are new. */
+				unseen: z.number().int().nonnegative(),
+				signedIn: z.boolean()
+			}),
+			doc: {
+				summary: "What's new: recent change notes",
+				tags: ["catalog"]
+			}
+		}
+	}),
+	...requireUser.group({
+		listFavoriteGames: {
+			method: "GET",
+			path: "/favorites",
+			response: Favorites,
+			errors: { 401: ErrorBody },
+			doc: {
+				summary: "The caller's starred games",
+				tags: ["catalog"]
+			}
+		},
+		/**
+		* Star or unstar a game (idempotent). Starring needs a known game (404);
+		* unstarring any slug succeeds.
+		*/
+		setGameFavorite: {
+			method: "PUT",
+			path: "/favorites/:slug",
+			params: z.object({ slug: Slug }),
+			body: z.object({ 
+			/** `true` stars, `false` (or missing) unstars. */
+on: Truthy.optional() }),
+			response: Favorites,
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Star or unstar a game",
+				tags: ["catalog"]
+			}
+		},
+		/**
+		* Mark notes seen now. With `game`: that game's and the site's. With
+		* `all` (or neither): everything.
+		*/
+		markWhatsNewSeen: {
+			method: "POST",
+			path: "/changes/seen",
+			body: z.object({
+				/** A game's slug, read as text; an unknown one is a 404. Ignored with `all`. */
+				game: LooseText.nullish(),
+				all: Truthy.optional()
+			}),
+			response: z.object({
+				ok: z.literal(true),
+				/** The seen mark stored, epoch ms. */
+				seenAt: Millis
+			}),
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Mark What's new notes seen",
+				tags: ["catalog"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/leaderboards.ts
+/**
+* Leaderboards: score submission, boards and standings. A board belongs to a
+* game and is keyed by an app-chosen {@link Key}; it keeps each player's best
+* score only (highest for `desc` boards, lowest for `asc`).
+*/
+/** A board key in a path, with the old hub's message when it is malformed. */
+const BoardKeyParams = z.object({ key: z.string().refine((key) => Key.safeParse(key).success, { error: "board key must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars)." }) });
+/**
+* A row count the hub reads like `Number(x) || default`: anything that is not
+* an integer falls back to the default instead of failing.
+*/
+const LenientRowCount = RowCount.optional().catch(void 0);
+/** A board's sort direction: `desc` ranks high scores first, `asc` low scores (times) first. */
+const SortDir = z.enum(["asc", "desc"]);
+/** A 1-based rank on a board. */
+const Rank = z.number().int().positive();
+/** A leaderboard's identity, without entries. */
+const Board = z.object({
+	key: Key,
+	/** Set by the first submitter or the game's `package.json`; defaults to the key. */
+	title: z.string(),
+	sortDir: SortDir
+});
+/**
+* One ranked row of a board. Suspended players and (unless the board opts
+* in) zero scores are left out.
+*/
+const LeaderboardEntry = z.object({
+	rank: Rank,
+	userId: UserId,
+	username: z.string(),
+	score: z.number(),
+	/** The JSON the game stored with the score, or `null`. */
+	meta: Json
+});
+/** Every board of one game, each with its top entries (`GET /leaderboards`, the snapshot). */
+const GameLeaderboards = z.object({
+	slug: Slug,
+	/** The game's title (the slug when the game is no longer listed). */
+	title: z.string(),
+	boards: z.array(Board.extend({ top: z.array(LeaderboardEntry) }))
+});
+/**
+* The player's own standings in one game (`GET /me/records`, the snapshot):
+* their score and rank on each board they have an entry on.
+*/
+const GameRecords = z.object({
+	slug: Slug,
+	/** The game's title (the slug when the game is no longer listed). */
+	title: z.string(),
+	records: z.array(Board.extend({
+		score: z.number(),
+		rank: Rank
+	}))
+});
+/**
+* `?top=` for the cross-game views (`GET /leaderboards`, `GET /me/snapshot`):
+* entries per board, 1 to 50 (clamped), default 5.
+*/
+const TopQuery = z.object({ top: LenientRowCount });
+/** The leaderboards endpoints. */
+const leaderboardsEndpoints = {
+	...session.group({ 
+	/** Every board of every game, grouped by game, each with its top entries. */
+listTopOfEveryLeaderboard: {
+		method: "GET",
+		path: "/leaderboards",
+		query: TopQuery,
+		response: z.object({ games: z.array(GameLeaderboards) }),
+		doc: {
+			summary: "Every board across every game, with top entries",
+			tags: ["leaderboards"]
+		}
+	} }),
+	...use(session, game).path("/games/:slug").group({
+		listGameLeaderboards: {
+			method: "GET",
+			path: "/leaderboards",
+			response: z.object({ boards: z.array(Board) }),
+			errors: { 404: ErrorBody },
+			doc: {
+				summary: "The game's boards (no entries)",
+				tags: ["leaderboards"]
+			}
+		},
+		getLeaderboard: {
+			method: "GET",
+			path: "/leaderboards/:key",
+			params: BoardKeyParams,
+			/** `limit`: rows to return, 1 to 500 (clamped), default 50. */
+			query: z.object({ limit: LenientRowCount }),
+			response: z.object({
+				board: Board,
+				entries: z.array(LeaderboardEntry)
+			}),
+			errors: {
+				400: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "One board's ranked entries (404 if the board doesn't exist)",
+				tags: ["leaderboards"]
+			}
+		}
+	}),
+	...use(requireUser, game).path("/games/:slug").group({ 
+	/**
+	* Submit a score. The first submission creates the board (with `title`,
+	* `sort` and `showZeros`; later values are ignored). Only an improvement
+	* replaces the player's entry. Boards a game declares with
+	* `source: "server"` refuse client scores (403 `server_board`).
+	*/
+submitScore: {
+		method: "POST",
+		path: "/leaderboards/:key/scores",
+		params: BoardKeyParams,
+		body: z.object({
+			/** A finite number (numeric strings pass, as for the old hub's `Number(x)`). */
+			score: z.coerce.number({ error: "score must be a finite number." }),
+			/** Board title, used only when this call creates the board (non-text is ignored). */
+			title: z.string().optional().catch(void 0),
+			/** Sort direction, used only on creation. Anything but `asc` means `desc`. */
+			sort: SortDir.optional().catch(void 0),
+			/** Keep zero scores visible, used only on creation. */
+			showZeros: Truthy.optional(),
+			/** Any JSON stored with the entry (a character, a run seed). */
+			meta: Json.optional()
+		}),
+		response: z.object({
+			board: Board,
+			/** The player's stored best after this submission. */
+			best: z.number().nullable(),
+			/** The player's rank on the board (`null` if they have no entry). */
+			rank: Rank.nullable()
+		}),
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody
+		},
+		doc: {
+			summary: "Submit a score (best-only; creates the board on first use)",
+			tags: ["leaderboards"]
+		}
+	} })
+};
+//#endregion
+//#region src/api/daily.ts
+/**
+* Daily challenges: one deterministic challenge per UTC day for games with
+* `game.dailyChallenges: true`. Starting a day mints a signed token; the game
+* presents it on completion. Completions are counted on the game's `daily`
+* leaderboard. The client owns the calendar (its local date); the hub only
+* reports which days are done.
+*/
+/** One completed day. */
+const DailyCompletion = z.object({
+	/** Epoch ms (server clock). */
+	completedAt: Millis,
+	/** The JSON the game sent on completion, or `null`. */
+	meta: Json
+});
+/** A player's completions in one game, keyed by `YYYY-MM-DD`. */
+const DailyCompletions = z.record(DayKey, DailyCompletion);
+/** `:day` of a challenge: within 30 days back and 1 day ahead of UTC today. */
+const DayParams = z.object({ day: z.string().refine((day) => DayKey.safeParse(day).success, { error: "Invalid day (expected YYYY-MM-DD)." }) });
+/** The daily endpoints. */
+const dailyEndpoints = {
+	...session.group({ 
+	/**
+	* Every daily game with the caller's completions (empty maps when signed
+	* out), plus the top 10 players by completions across all games.
+	*/
+listDailyChallengesForAllGames: {
+		method: "GET",
+		path: "/daily",
+		response: z.object({
+			/** UTC today, a hint: clients use their local date. */
+			today: DayKey,
+			games: z.array(z.object({
+				slug: Slug,
+				title: z.string(),
+				completions: DailyCompletions
+			})),
+			global: z.array(z.object({
+				rank: Rank,
+				userId: UserId,
+				username: z.string(),
+				/** Daily challenges completed, across all games. */
+				score: z.number().int().nonnegative()
+			}))
+		}),
+		doc: {
+			summary: "Daily challenges across every game, plus global standings",
+			tags: ["daily"]
+		}
+	} }),
+	...use(session, game).path("/games/:slug").group({ getGameDailyChallenges: {
+		method: "GET",
+		path: "/daily",
+		response: z.object({
+			enabled: z.literal(true),
+			/** UTC today, a hint: clients use their local date. */
+			today: DayKey,
+			/** Empty when signed out. */
+			completions: DailyCompletions
+		}),
+		errors: { 404: ErrorBody },
+		doc: {
+			summary: "The caller's completions in this game (404 if it has no dailies)",
+			tags: ["daily"]
+		}
+	} }),
+	...use(requireUser, game).path("/games/:slug").group({
+		/**
+		* Start (or replay) a day: returns its seed and a signed token to present
+		* on completion. 400 when the day is outside the window.
+		*/
+		startDailyChallenge: {
+			method: "POST",
+			path: "/daily/:day/start",
+			params: DayParams,
+			response: z.object({
+				/** Present it to `dailyComplete` for the same day. */
+				token: z.string(),
+				day: DayKey,
+				/** Deterministic per (game, day), an unsigned 32-bit integer. */
+				seed: z.number().int().min(0).max(4294967295),
+				/** When the token stops working (epoch ms), about 26 hours out. */
+				expiresAt: Millis,
+				alreadyCompleted: z.boolean(),
+				/** Epoch ms, or `null` when not completed yet. */
+				completedAt: Millis.nullable(),
+				/** The earlier completion's JSON, or `null`. */
+				meta: Json
+			}),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Start a day's challenge and get its token",
+				tags: ["daily"]
+			}
+		},
+		/**
+		* Record a completion with the token from `dailyStart`. Idempotent: a
+		* replay of a done day changes nothing. 401 on a bad, expired or
+		* mismatched token.
+		*/
+		completeDailyChallenge: {
+			method: "POST",
+			path: "/daily/:day/complete",
+			params: DayParams,
+			body: z.object({
+				/** The token from `dailyStart`; a missing or non-text token is refused like a bad one (401). */
+				token: z.string().optional().catch(void 0),
+				/** Any JSON; a numeric `meta.score` is kept with the completion. */
+				meta: Json.optional()
+			}),
+			response: z.object({
+				ok: z.literal(true),
+				day: DayKey,
+				/** The caller's completions in this game. */
+				count: z.number().int().positive(),
+				/** The caller's rank on the game's `daily` board. */
+				rank: Rank.nullable()
+			}),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Complete a day with its token",
+				tags: ["daily"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/economy/bundle.ts
+/**
+* Economy shapes: a player's per-game holdings and the bundles that move
+* goods. Items are opaque, app-defined {@link Key}s; the hub only counts them.
+*/
+/**
+* The default largest quantity (or coin amount) one bundle entry may carry.
+* The hub's limit is `HUB_MAX_ITEM_QTY`, which defaults to this.
+*/
+const MAX_ITEM_QTY = 1e6;
+/**
+* The default most distinct item keys one bundle may name. The hub's limit
+* is `HUB_MAX_BUNDLE_ITEMS`, which defaults to this.
+*/
+const MAX_BUNDLE_ITEMS = 50;
+/** A player's holdings in one game: items with a positive count, and coins. */
+const Inventory = z.object({
+	/** Sorted by key. */
+	items: z.array(z.object({
+		key: Key,
+		qty: z.number().int().positive()
+	})),
+	coins: z.number().int().nonnegative()
+});
+/**
+* A bundle quantity, read like the hub's `Number(x)` (numeric strings pass).
+* A value that is not a number reads as `NaN` here rather than failing, so
+* the hub's own range check, which knows its configured limits, answers with
+* its message (e.g. `grant.coins must be an integer in [0, 1000000].`).
+* Clients should send a JSON integer.
+*/
+const BundleQuantity = z.coerce.number().catch(NaN);
+/**
+* Goods to grant, spend or trade, as a request sends them, for the request
+* field named `label` (`grant`, `take`, `give`, `want`), which the error
+* messages name. Both parts are optional (`null` or missing means none).
+* Item keys must be {@link Key}s, at most `HUB_MAX_BUNDLE_ITEMS` of them,
+* each with a quantity from 1 to `HUB_MAX_ITEM_QTY`; coins run from 0 to
+* `HUB_MAX_ITEM_QTY`. The hub checks those limits and the keys itself.
+*/
+function bundleInput(label) {
+	return z.object({
+		/** 0 to `HUB_MAX_ITEM_QTY`. */
+		coins: BundleQuantity.nullish(),
+		/** Item key to quantity (1 to `HUB_MAX_ITEM_QTY`). */
+		items: z.record(z.string(), BundleQuantity, { error: `${label}.items must be an object of key→quantity.` }).nullish()
+	}, { error: `${label} must be an object.` });
+}
+/** A request bundle, for documentation and clients. */
+const BundleInput = bundleInput("bundle");
+/** A bundle as the hub stores and returns it on a trade offer: both parts always present. */
+const Bundle = z.object({
+	items: z.record(Key, z.number().int().positive()),
+	coins: z.number().int().nonnegative()
+});
+//#endregion
+//#region src/api/economy/inventory.ts
+/**
+* Per-game inventory: the hub is the ledger (no negative balances, goods are
+* conserved in trades) but does not judge game rules, so granting is trusted
+* like scores are.
+*/
+const BAD_USER_ID = "Bad user id.";
+/** `:userId`: a positive integer, else 400 "Bad user id.". */
+const PlayerIdParam = z.coerce.number({ error: BAD_USER_ID }).int({ error: BAD_USER_ID }).positive({ error: BAD_USER_ID });
+/** The inventory endpoints. */
+const inventoryEndpoints = {
+	...use(requireUser, game).path("/games/:slug").group({
+		getMyInventory: {
+			method: "GET",
+			path: "/inventory",
+			response: Inventory,
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "The caller's items and coins in this game",
+				tags: ["economy"]
+			}
+		},
+		/** Add goods to the caller (gameplay rewards, opening a box). The body is the bundle. */
+		grantInventoryItems: {
+			method: "POST",
+			path: "/inventory/grant",
+			body: bundleInput("grant"),
+			response: Inventory,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Grant goods to the caller; returns the new holdings",
+				tags: ["economy"]
+			}
+		},
+		/**
+		* Atomically remove `take` from the caller and add `give`: selling (take
+		* items, give coins) and buying from the house (take coins, give items).
+		* 409 when the caller can't cover `take`.
+		*/
+		exchangeInventoryItems: {
+			method: "POST",
+			path: "/inventory/exchange",
+			body: z.object({
+				take: bundleInput("take").nullish(),
+				give: bundleInput("give").nullish()
+			}),
+			response: Inventory,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Swap goods with the house; returns the new holdings",
+				tags: ["economy"]
+			}
+		}
+	}),
+	...use(requireActive, game).path("/games/:slug").group({ 
+	/**
+	* Another claimed player's holdings in this game, for composing a trade
+	* offer. 404 for a guest or unknown id.
+	*/
+getPlayerInventory: {
+		method: "GET",
+		path: "/players/:userId/inventory",
+		params: z.object({ userId: PlayerIdParam }),
+		response: Inventory,
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody
+		},
+		doc: {
+			summary: "Another player's holdings (to compose a trade)",
+			tags: ["economy"]
+		}
+	} })
+};
+//#endregion
+//#region src/api/economy/trades.ts
+/**
+* Async player-to-player trades on the economy ledger. Making an offer
+* escrows its `give` side; the recipient accepts (atomic swap), declines or
+* counters, and the sender may cancel. Pending offers expire after 14 days
+* (`HUB_TRADE_TTL_MS`), refunding the escrow.
+*/
+/** Where an offer is in its life. Only `pending` offers can change. */
+const TradeStatus = z.enum([
+	"pending",
+	"accepted",
+	"declined",
+	"cancelled",
+	"countered",
+	"expired"
+]);
+/** A party to a trade, or a player the roster offers to trade with. */
+const TradePlayer = PlayerLite.pick({
+	id: true,
+	username: true
+});
+/** A trade offer, seen from the caller's side. */
+const TradeOffer = z.object({
+	id: z.number().int().positive(),
+	game: Slug,
+	status: TradeStatus,
+	/** `outgoing` when the caller sent it. */
+	direction: z.enum(["incoming", "outgoing"]),
+	from: TradePlayer,
+	to: TradePlayer,
+	/** What the sender offers (escrowed while pending). */
+	give: Bundle,
+	/** What the sender asks for in return. */
+	want: Bundle,
+	/** The sender's note, `''` when none. */
+	note: z.string(),
+	/** The offer this one counters, or `null`. */
+	parentId: z.number().int().positive().nullable(),
+	/** Epoch ms. */
+	createdAt: Millis,
+	/** When it stopped being pending (epoch ms), or `null`. */
+	resolvedAt: Millis.nullable(),
+	/** When a pending offer expires (epoch ms). */
+	expiresAt: Millis
+});
+/**
+* Active and a claimed account, for making, accepting and countering trades
+* (so escrow is never stranded on a guest). A guest gets 403 "Create a free
+* account (via the menu) to trade." with no `code`, before the game or the
+* body is checked; unlike the shared `requireClaimed`, which says
+* `claim_required`.
+*/
+const requireTrader = middleware("requireTrader", {
+	provides: ctx(),
+	requires: [requireActive]
+});
+/** `{ offer }`: the offer after a trade action. */
+const OfferResult = z.object({ offer: TradeOffer });
+/** The two sides of a new offer or counter, plus an optional note (moderated, up to 200 characters). */
+const OfferTerms = z.object({
+	give: bundleInput("give").nullish(),
+	want: bundleInput("want").nullish(),
+	/** Shown to the other player, so it is moderated. */
+	note: LooseText.nullish()
+});
+/**
+* `:id` of a trade offer, read with `Number()`: an id that is not a number
+* names no offer, so it is a 404 "No such trade offer." like an unknown one.
+*/
+const OfferParams = z.object({ id: LooseNumber.catch(NaN) });
+/** Errors from resolving an offer: not yours (403), unknown (404), no longer pending (409). */
+const ResolveErrors = {
+	401: ErrorBody,
+	403: ErrorBody,
+	404: ErrorBody,
+	409: ErrorBody
+};
+/** The trade endpoints. */
+const tradeEndpoints = {
+	...use(requireActive, game).path("/games/:slug").group({
+		/** Claimed players with a footprint in this game, excluding the caller (up to 500, by name). */
+		listTradePartners: {
+			method: "GET",
+			path: "/trades/players",
+			response: z.object({ players: z.array(TradePlayer) }),
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Players the caller can trade with in this game",
+				tags: ["trades"]
+			}
+		},
+		/** The caller's offers in this game, newest first (up to 100). Expired offers are settled first. */
+		listMyTrades: {
+			method: "GET",
+			path: "/trades",
+			query: z.object({
+				/** Only offers sent to (`incoming`) or by (`outgoing`) the caller; omit (or anything else) for both. */
+				box: z.enum(["incoming", "outgoing"]).optional().catch(void 0),
+				/** Only offers with this {@link TradeStatus}; an unknown status matches nothing, `''` means any. */
+				status: z.union([TradeStatus, z.string()]).optional()
+			}),
+			response: z.object({ offers: z.array(TradeOffer) }),
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "The caller's trade offers",
+				tags: ["trades"]
+			}
+		},
+		declineTrade: {
+			method: "POST",
+			path: "/trades/:id/decline",
+			params: OfferParams,
+			response: OfferResult,
+			errors: ResolveErrors,
+			doc: {
+				summary: "Decline an offer sent to the caller (refunds the escrow)",
+				tags: ["trades"]
+			}
+		},
+		cancelTrade: {
+			method: "POST",
+			path: "/trades/:id/cancel",
+			params: OfferParams,
+			response: OfferResult,
+			errors: ResolveErrors,
+			doc: {
+				summary: "Cancel an offer the caller sent (refunds the escrow)",
+				tags: ["trades"]
+			}
+		}
+	}),
+	...use(requireTrader, game).path("/games/:slug").group({
+		/**
+		* Offer a trade to the player named `toUser`. Escrows `give` (409 if the
+		* caller can't cover it); at least one side must be non-empty.
+		*/
+		createTrade: {
+			method: "POST",
+			path: "/trades",
+			body: OfferTerms.extend({ 
+			/** The recipient's username (case-insensitive). Missing or blank is a 400. */
+toUser: LooseText.nullish() }),
+			responses: { 201: OfferResult },
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody,
+				422: ContentRejected
+			},
+			doc: {
+				summary: "Make a trade offer",
+				tags: ["trades"]
+			}
+		},
+		/** Accept an offer sent to the caller: they must own its `want` side (409 otherwise). */
+		acceptTrade: {
+			method: "POST",
+			path: "/trades/:id/accept",
+			params: OfferParams,
+			response: OfferResult,
+			errors: ResolveErrors,
+			doc: {
+				summary: "Accept an offer (atomic swap)",
+				tags: ["trades"]
+			}
+		},
+		/**
+		* Counter an offer sent to the caller: the original is refunded and
+		* closed as `countered`, and a linked offer goes back to its sender.
+		*/
+		counterTradeOffer: {
+			method: "POST",
+			path: "/trades/:id/counter",
+			params: OfferParams,
+			body: OfferTerms,
+			responses: { 201: OfferResult },
+			errors: {
+				...ResolveErrors,
+				400: ErrorBody,
+				422: ContentRejected
+			},
+			doc: {
+				summary: "Counter an offer with a new one",
+				tags: ["trades"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/economy.ts
+/**
+* Per-game economy: inventory, grants, exchanges and trades. The endpoints
+* and shapes live in `economy/`.
+*/
+/** The economy endpoints. */
+const economyEndpoints = {
+	...inventoryEndpoints,
+	...tradeEndpoints
+};
+//#endregion
+//#region src/api/social/config.ts
+/**
+* The site-wide social configuration every social UI renders from
+* (`GET /social/config`, `ev:config`, the `hello` snapshot).
+*/
+/** A quick-chat phrase id: a hub phrase (`gg`), an emote (`e:<emoji>`) or a game phrase (`g:<slug>:<n>`). */
+const QuickId = z.string().min(1);
+/** A non-negative character limit. */
+const CharLimit = z.number().int().nonnegative();
+/** Text length limits, in characters. */
+const SocialLimits = z.object({
+	dmMaxChars: CharLimit,
+	roomChatMaxChars: CharLimit,
+	suggestionTitleMax: CharLimit,
+	suggestionBodyMax: CharLimit
+});
+/** The site-wide social configuration. */
+const SocialConfig = z.object({
+	/** The site-wide chat mode (operator setting tightened by the admin switch). */
+	chatMode: ChatMode,
+	/** The AI safety reviewer is configured. */
+	ai: z.boolean(),
+	/** Where parents can reach the operator, `''` when unset. */
+	contactUrl: z.string(),
+	/** The public "how chat is kept safe" page. */
+	parentsUrl: z.string(),
+	/** The Web Push VAPID public key (base64url), `''` when push isn't configured. */
+	vapidPublicKey: z.string(),
+	/** Every quick-chat phrase, id to text: hub phrases, emotes and every game's phrases. */
+	quickChat: z.record(QuickId, z.string()),
+	/** The emote emoji (also in `quickChat` as `e:<emoji>` ids). */
+	emotes: z.array(z.string()),
+	limits: SocialLimits,
+	/** The preset avatar ids (`a0` to `a23`). */
+	avatars: z.array(z.string()),
+	/** Present (`true`) only when the host runs in test mode (`HUB_TEST=1`). */
+	test: z.literal(true).optional()
+});
+//#endregion
+//#region src/api/messages.ts
+/**
+* Direct messages between mutual friends (multiplayer-impl.md §5.2).
+*
+* "Checked before delivered": text is moderated before it is stored or
+* pushed. Free text needs the conversation's chat mode to be `on` (both
+* claimed, friends, no parent lock, site switch on); otherwise only
+* quick-chat ids go through. Hidden messages and messages from currently
+* suspended senders are left out of every read.
+*/
+/** A message id: a positive integer, increasing over time. */
+const MessageId = z.number().int().positive();
+/** A direct message. */
+const Message = z.object({
+	id: MessageId,
+	/** The sender. */
+	from: UserId,
+	/** The recipient. */
+	to: UserId,
+	/** The delivered (possibly softened) text; a quick message carries its phrase's text. */
+	text: z.string(),
+	/** The quick-chat phrase id, for quick messages only. */
+	quick: QuickId.optional(),
+	/** When it was sent (epoch ms). */
+	at: Millis,
+	/** The recipient has read it. */
+	read: z.boolean(),
+	/** Words were swapped by the filter. Only on the sender's own copy. */
+	softened: z.literal(true).optional()
+});
+/** A conversation summary: the other player, the last message and how many of theirs you haven't read. */
+const Conversation = z.object({
+	user: PlayerLite,
+	last: Message,
+	unread: z.number().int().nonnegative()
+});
+/** One page of a conversation's history. */
+const MessagesPage = z.object({
+	/** Oldest to newest, at most 50. */
+	messages: z.array(Message),
+	/** Older messages exist (page with `?before=` the first id). */
+	more: z.boolean(),
+	/** The mode the chat UI should render: `off` when DMs are off, `quick` while you are muted. */
+	mode: ChatMode
+});
+/** A DM to send: free text, or a quick-chat phrase id (exactly one). */
+const SendMessageInput = z.object({
+	/** Free text (moderated; only when the conversation's mode is `on`). */
+	text: z.string().optional(),
+	/** A quick-chat phrase id (any mode but `off`). */
+	quick: QuickId.optional()
+}).refine((b) => b.text === void 0 !== (b.quick === void 0), "Send either text or a quick-chat id.");
+/**
+* Unread DMs (the `hello` snapshot's `unread`), ignoring hidden messages and
+* suspended senders.
+*/
+const UnreadSummary = z.object({
+	/** Total unread. */
+	dms: z.number().int().nonnegative(),
+	/** Unread per sender, keyed by the sender's user id (as a decimal string). */
+	byUser: z.record(z.string().regex(/^\d+$/), z.number().int().positive())
+});
+/**
+* `:userId`, the other side of the conversation: a claimed, non-suspended
+* player other than you, else 404 "No such player." Read like `Number(x)`:
+* anything that is not a player's id is the same 404.
+*/
+const Partner = z.object({ userId: LooseNumber.catch(NaN) });
+/** The direct-message endpoints. */
+const messagesEndpoints = { ...requireClaimed.group({
+	listConversations: {
+		method: "GET",
+		path: "/social/conversations",
+		response: z.object({ 
+		/** Newest first, one per partner, at most 200. */
+conversations: z.array(Conversation) }),
+		errors: {
+			401: ErrorBody,
+			403: ErrorBody
+		},
+		doc: {
+			summary: "Your conversations, newest first",
+			tags: ["messages"]
+		}
+	},
+	listDirectMessages: {
+		method: "GET",
+		path: "/social/messages/:userId",
+		params: Partner,
+		query: z.object({ 
+		/** Only messages older than this message id; `0` or anything not a number means from the newest. */
+before: LooseNumber.optional().catch(void 0) }),
+		response: MessagesPage,
+		errors: {
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody
+		},
+		doc: {
+			summary: "One page of history with a player",
+			tags: ["messages"]
+		}
+	},
+	sendDirectMessage: {
+		method: "POST",
+		path: "/social/messages/:userId",
+		params: Partner,
+		body: SendMessageInput,
+		response: z.object({ message: Message }),
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody,
+			422: ContentRejected
+		},
+		doc: {
+			summary: "Send a DM to a friend",
+			description: "403 `not_friends` or `dms_closed`; 422 when the text is rejected, the chat mode forbids it, or you are sending too fast.",
+			tags: ["messages"]
+		}
+	},
+	markDirectMessagesRead: {
+		method: "POST",
+		path: "/social/messages/:userId/read",
+		params: Partner,
+		body: z.object({ 
+		/** Mark their messages to you up to and including this id. */
+upTo: requiredId("upTo must be a message id.") }),
+		response: Ok,
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody
+		},
+		doc: {
+			summary: "Mark a friend's messages to you as read",
+			tags: ["messages"]
+		}
+	}
+}) };
+//#endregion
+//#region src/api/mp/parties.ts
+/**
+* Invites, parties and launches (multiplayer-impl.md §5.6): the shapes the
+* mp endpoints, the `invite` / `invite.update` / `party` socket events and
+* the `hello` snapshot share. All of it lives in the hub's memory; a restart
+* drops it.
+*/
+/** A game mode key, as the game's `multiplayer.modes[].key` declares it: `[A-Za-z0-9_-]{1,32}`. */
+const GameMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+/** An opaque hub-minted id (party, invite, room): base64url text. */
+const OpaqueId = z.string().min(1);
+/** A `joinInfo` key: `[A-Za-z0-9_]{1,32}`. */
+const JoinInfoKey = z.string().regex(/^[A-Za-z0-9_]{1,32}$/);
+/**
+* Where a party should connect, as its leader publishes it (e.g.
+* `{ room: 'ABCDE' }`): at most 8 short keys, string values of at most 64
+* characters. The hub accepts finite numbers and stores them as strings.
+*/
+const JoinInfo = z.record(JoinInfoKey, z.union([z.string().max(64), z.number().transform(String)])).refine((joinInfo) => Object.keys(joinInfo).length <= 8, "info may have at most 8 keys");
+/** A group of 2 to 8 players moving between games together. A user is in at most one. */
+const Party = z.object({
+	id: OpaqueId,
+	game: Slug,
+	/** Present when the party formed for a specific mode (`race` for race invites). */
+	mode: GameMode.optional(),
+	leaderId: UserId,
+	members: z.array(PlayerLite),
+	/** `null` until the leader publishes where to connect. */
+	joinInfo: JoinInfo.nullable(),
+	/** Epoch ms. */
+	createdAt: Millis
+});
+/** "Come play <game> with me": pending until accepted, declined, cancelled or expired. */
+const Invite = z.object({
+	id: OpaqueId,
+	from: PlayerLite,
+	to: PlayerLite,
+	game: Slug,
+	gameTitle: z.string(),
+	mode: GameMode.optional(),
+	/** The inviter's party the invitee joins on accept. */
+	partyId: OpaqueId,
+	/** Epoch ms. */
+	expiresAt: Millis
+});
+/** How an invite ended. */
+const InviteStatus = z.enum([
+	"accepted",
+	"declined",
+	"expired",
+	"cancelled"
+]);
+/** A single-use launch token plus the game URL that redeems it (`?hub_launch=<token>`). */
+const LaunchTicket = z.object({
+	launchToken: z.string(),
+	/** `/<slug>/<lobby>` with `hub_launch` appended. */
+	url: z.string()
+});
+/** Why the hub is bringing a player into a game. */
+const LaunchKind = z.enum([
+	"host",
+	"guest",
+	"join",
+	"watch"
+]);
+/**
+* What a game's `hub.mp.onLaunch` receives after redeeming a launch token.
+* Party fields reflect the party as it is at redemption time.
+*/
+const Launch = z.object({
+	kind: LaunchKind,
+	game: Slug,
+	mode: GameMode.optional(),
+	/** Host and guest launches: the party they belong to. */
+	partyId: OpaqueId.optional(),
+	/** The party now; `null` when it has dissolved since the token was minted. */
+	party: Party.nullable().optional(),
+	/** The party's join info now; `null` when unset or the party is gone. */
+	joinInfo: JoinInfo.nullable().optional(),
+	/** Join and watch launches: the room code the friend's presence advertised. */
+	room: z.string().optional(),
+	/** Guest launches: the party leader (`null` if the account is gone). */
+	host: PlayerLite.nullable().optional(),
+	/** Join and watch launches: the friend being joined (`null` if the account is gone). */
+	target: PlayerLite.nullable().optional()
+});
+//#endregion
+//#region src/api/mp/chat.ts
+/**
+* Group chat in hub rooms and parties (multiplayer.md §4.3, §4.8): what a
+* player sends, and the moderated line everyone receives.
+*/
+/**
+* A chat send: a quick-chat phrase id, or free text. When `quick` is set it
+* wins and `text` is ignored.
+*/
+const ChatSend = z.object({
+	/** Free text; only allowed in mode `on`, then moderated. */
+	text: z.string().optional(),
+	/** A quick-chat phrase id (hub phrase, `e:<emoji>` emote or game phrase). */
+	quick: z.string().optional()
+});
+/** The line as delivered: the (possibly softened) text, and the phrase id for quick-chat. */
+const ChatLine = z.object({
+	text: z.string(),
+	/** Set when the line is a quick-chat phrase. */
+	quick: z.string().optional(),
+	/** Moderation reworded the text. */
+	softened: z.literal(true).optional()
+});
+/** A chat line pushed to a room or party, with its sender. */
+const ChatLineEvent = ChatLine.extend({ from: UserId });
+/** The error codes a chat send can fail with (besides its surface's own). */
+const CHAT_ERRORS = [
+	"rate_limited",
+	"content_rejected",
+	"bad_quick"
+];
+//#endregion
+//#region src/api/mp/rooms.ts
+/**
+* Hub relay rooms (multiplayer-impl.md §6): realtime multiplayer for static
+* games, relayed (never refereed) by the hub. A race is a room with a
+* `race` block on top. Shared by the `room.*` / `race.*` ops and events and
+* the `hello` snapshot.
+*/
+/** A room's join code: 5 characters from `A-Z` and `2-9` (no `I`, `O`, `0`, `1`). */
+const RoomCode = z.string().regex(/^[A-HJ-NP-Z2-9]{5}$/);
+/** A room's lifecycle: new players join only in the lobby. */
+const RoomPhase = z.enum([
+	"lobby",
+	"playing",
+	"ended"
+]);
+/**
+* Who hears a send. `host` (default): guests' unaddressed sends reach the
+* host only. `relay`: every unaddressed send reaches everyone, sender
+* included.
+*/
+const RoomModel = z.enum(["host", "relay"]);
+/** A seat in a room, keyed by user (any tab of that user reclaims it). */
+const RoomSeat = z.object({
+	userId: UserId,
+	/** The player's username when they sat down. */
+	name: z.string(),
+	/** Avatar token; never empty. */
+	avatar: z.string(),
+	ready: z.boolean(),
+	/** `false` while the seat is held for a dropped player's reconnect grace. */
+	connected: z.boolean(),
+	/** Small per-seat game data (team, colour…), at most 2 KB of JSON. */
+	data: Json.optional()
+});
+/** The public description of a room (`room` event, room and race acks, the `hello` snapshot). */
+const RoomInfo = z.object({
+	id: OpaqueId,
+	code: RoomCode,
+	game: Slug,
+	/** `race` for race rooms. */
+	mode: GameMode.optional(),
+	hostId: UserId,
+	/** Listed in `room.list` / `race.list`. */
+	public: z.boolean(),
+	phase: RoomPhase,
+	maxPlayers: z.number().int().positive(),
+	model: RoomModel,
+	seats: z.array(RoomSeat),
+	/** How many are watching. */
+	spectators: z.number().int().nonnegative(),
+	/** The chat mode for the seated players. */
+	chatMode: ChatMode,
+	/** Present on race rooms. */
+	race: RaceState.optional()
+});
+/** A room's shared state for late joiners: a JSON object, at most 32 KB. */
+const RoomState = z.record(z.string(), Json);
+/** A relayed game message (`room.msg`, and a join's replay history). */
+const RoomMessage = z.object({
+	from: UserId,
+	data: Json,
+	/** Per-room sequence number, shared with state patches. */
+	seq: z.number().int().positive(),
+	/** Set when the message went to one seat only. */
+	to: UserId.optional()
+});
+/** How to find a room: by its code (case-insensitive) or its id. */
+const RoomTarget = z.object({
+	code: z.string().optional(),
+	id: z.string().optional(),
+	/** Watch instead of taking a seat (if the game allows spectators). */
+	spectate: z.boolean().optional()
+});
+/** Why a room went away for this tab (`room.closed`). */
+const RoomClosedReason = z.enum([
+	"empty",
+	"ended",
+	"host_left",
+	"moved",
+	"other_tab",
+	"removed"
+]);
+/** Why a seat was freed (`room.abandoned`). */
+const SeatGoneReason = z.enum([
+	"left",
+	"abandoned",
+	"kicked"
+]);
+//#endregion
+//#region src/api/mp/snapshot.ts
+/** The multiplayer part of the socket `hello` snapshot (multiplayer-impl.md §4.5). */
+/**
+* The multiplayer fields of the `hello` ack, to spread into the snapshot
+* schema (`z.object({ ...other, ...MultiplayerSnapshot.shape })`).
+*/
+const MultiplayerSnapshot = z.object({
+	/** Pending invites addressed to me. */
+	invites: z.array(Invite),
+	/** The party I'm in, or `null`. */
+	party: Party.nullable(),
+	/** The room seat I still hold (not ended), or `null`; `room.join` it again to reconnect. */
+	room: RoomInfo.nullable()
+});
+//#endregion
+//#region src/api/mp.ts
+/**
+* Multiplayer REST (multiplayer-impl.md §5.6): invites, launch tokens,
+* parties, joining a friend's game, and game-server tickets. Every route
+* needs an active account; invites need a claimed one. The live state is in
+* the hub's memory and changes are pushed over `/_ws` (`invite`,
+* `invite.update`, `party`).
+*/
+/** `:id` of an invite or party. */
+const IdParams = z.object({ id: OpaqueId });
+/** The answer to `POST /mp/invites`: the invite, plus the inviter's own `host` launch. */
+const InviteCreated = LaunchTicket.extend({ invite: Invite });
+/** A game-server identity ticket. */
+const GameTicket = z.object({
+	/** `base64url(payload).base64url(hmac)`, verified offline by the game's server with `HUB_APP_KEY`. */
+	ticket: z.string(),
+	/** Epoch ms; tickets live 60 s. */
+	expiresAt: Millis
+});
+/** The mp endpoints. */
+const mpEndpoints = {
+	...requireClaimed.group({
+		sendGameInvite: {
+			method: "POST",
+			path: "/mp/invites",
+			body: z.object({
+				/** The friend to invite. */
+				to: UserIdParam,
+				game: Slug,
+				/** One of the game's modes; race-only games default to `race`. */
+				mode: GameMode.nullish()
+			}),
+			response: InviteCreated,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Invite a friend to a game; creates or reuses your party and returns your host launch",
+				tags: ["mp"]
+			}
+		},
+		acceptGameInvite: {
+			method: "POST",
+			path: "/mp/invites/:id/accept",
+			params: IdParams,
+			response: LaunchTicket,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Accept an invite: join the inviter's party and get a guest launch",
+				tags: ["mp"]
+			}
+		},
+		declineGameInvite: {
+			method: "POST",
+			path: "/mp/invites/:id/decline",
+			params: IdParams,
+			response: Ok,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Decline an invite addressed to you",
+				tags: ["mp"]
+			}
+		},
+		cancelGameInvite: {
+			method: "DELETE",
+			path: "/mp/invites/:id",
+			params: IdParams,
+			response: Ok,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Cancel an invite you sent",
+				tags: ["mp"]
+			}
+		}
+	}),
+	...requireActive.group({
+		redeemLaunchToken: {
+			method: "GET",
+			path: "/mp/launch/:token",
+			params: z.object({ token: z.string() }),
+			response: z.object({ launch: Launch }),
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Redeem a launch token (single use, bound to the signed-in user)",
+				tags: ["mp"]
+			}
+		},
+		setPartyJoinInfo: {
+			method: "POST",
+			path: "/mp/parties/:id/join-info",
+			params: IdParams,
+			body: z.object({ info: JoinInfo }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Party leader: publish where the party should connect",
+				tags: ["mp"]
+			}
+		},
+		leaveParty: {
+			method: "POST",
+			path: "/mp/parties/:id/leave",
+			params: IdParams,
+			response: Ok,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Leave a party (the leader role passes on; an empty party dissolves)",
+				tags: ["mp"]
+			}
+		},
+		launchIntoFriendsRoom: {
+			method: "POST",
+			path: "/mp/join",
+			body: z.object({
+				/** The player whose game to join or watch. */
+				userId: UserIdParam,
+				/** Watch instead of play. */
+				watch: z.boolean().optional(),
+				/** Joining a stranger's public lobby from a `lobby_open` alert (not a friend's game). */
+				fromLobbyOpen: z.boolean().optional()
+			}),
+			response: LaunchTicket,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "A Join or Watch launch into the room a friend's presence advertises",
+				tags: ["mp"]
+			}
+		},
+		getGameServerTicket: {
+			method: "POST",
+			path: "/mp/ticket",
+			body: z.object({ slug: Slug }),
+			response: GameTicket,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "A 60 s identity ticket for a game's own server",
+				tags: ["mp"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/notify.ts
+/**
+* Notification preferences and Web Push subscriptions
+* (multiplayer-impl.md §5.4). Everything is off by default and claimed-only.
+* Which channel an alert takes (a live `ev:notice` toast or a push) is the
+* hub's decision; see `ev:notice`.
+*/
+/** Notification preferences (`GET`/`PUT /social/notify`, `GET /social/me`). */
+const NotifyPrefs = z.object({
+	/** Push a new DM when no tab is open. */
+	dm: z.boolean(),
+	/** Push a friend request when no tab is open. */
+	friend_request: z.boolean(),
+	/** "Tell me when any friend comes online", on top of the per-friend bells. */
+	friendOnlineAll: z.boolean(),
+	/** Friends whose bell is on, ascending. */
+	friendOnline: z.array(UserId),
+	/** Games followed for "someone's waiting in a lobby", sorted. */
+	lobbyOpen: z.array(Slug)
+});
+/** The preference kinds `PUT /social/notify` can flip. */
+const NotifyPrefKind = z.enum([
+	"dm",
+	"friend_request",
+	"friend_online",
+	"lobby_open"
+], { error: "kind must be dm, friend_request, friend_online or lobby_open." });
+/**
+* One `PUT /social/notify` change. `target`: for `friend_online`, a friend's
+* id (a number, or its decimal string) for that friend's bell, or absent
+* (`''`, `null`) for the "any friend" switch; for `lobby_open`, the game slug.
+* Ignored for `dm` and `friend_request`. Any other number or text is a 404
+* (not a friend, no such game), as on the old hub. `enabled` is checked
+* first, so its message wins when both fields are wrong.
+*/
+const NotifyChange = z.object({
+	enabled: z.boolean({ error: "enabled must be true or false." }),
+	kind: NotifyPrefKind,
+	target: z.union([z.string(), z.number()]).nullable().optional()
+});
+/** The 400 for a subscription the hub can't push to (malformed, or not on a known push service). */
+const UNSUPPORTED_SUBSCRIPTION = "That browser subscription isn't supported.";
+/**
+* A browser push subscription, as `PushSubscription.toJSON()` gives it. The
+* endpoint must be `https` on a known push service; `p256dh` is a 65-byte
+* and `auth` an at-least-16-byte base64url key.
+*/
+const PushSubscriptionJson = z.object({
+	endpoint: z.string().max(1e3, { error: UNSUPPORTED_SUBSCRIPTION }),
+	/** When the subscription expires (epoch ms), `null` when it doesn't. */
+	expirationTime: z.number().nullable().optional(),
+	keys: z.object({
+		p256dh: z.string().max(200, { error: UNSUPPORTED_SUBSCRIPTION }),
+		auth: z.string().max(100, { error: UNSUPPORTED_SUBSCRIPTION })
+	})
+});
+/** The notification endpoints. */
+const notifyEndpoints = {
+	...requireActive.group({
+		getNotificationPreferences: {
+			method: "GET",
+			path: "/social/notify",
+			response: NotifyPrefs,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Your notification preferences (all off for guests)",
+				tags: ["notify"]
+			}
+		},
+		unsubscribeFromPush: {
+			method: "DELETE",
+			path: "/social/push",
+			body: z.object({ endpoint: z.string({ error: "endpoint is required." }).min(1, { error: "endpoint is required." }) }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Forget one of this account's push subscriptions",
+				tags: ["notify"]
+			}
+		}
+	}),
+	...requireClaimed.group({
+		setNotificationPreferences: {
+			method: "PUT",
+			path: "/social/notify",
+			body: NotifyChange,
+			response: NotifyPrefs,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Flip one notification preference",
+				description: "404 for a friend bell on a non-friend or an unknown game; 409 past 50 followed games.",
+				tags: ["notify"]
+			}
+		},
+		subscribeToPush: {
+			method: "POST",
+			path: "/social/push",
+			body: z.object({ subscription: z.union([PushSubscriptionJson, z.never()], { error: UNSUPPORTED_SUBSCRIPTION }) }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Store this browser's push subscription",
+				description: "One browser is one endpoint: subscribing from another account moves it. Past the per-user cap the oldest is dropped.",
+				tags: ["notify"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/progress/game-data.ts
+/**
+* The caller's own per-game data: profile, save slots, numeric stats, and
+* resetting a game. Guests count: a guest is a real account row.
+*/
+/** A player's profile in one game. */
+const Profile = z.object({
+	game: Slug,
+	/** Shown to other players; `null` when never set. */
+	displayName: z.string().nullable(),
+	/** Any JSON the game stores (`{}` by default). */
+	data: Json,
+	/** Epoch ms. */
+	updatedAt: Millis
+});
+/** A save slot's metadata (no payload). */
+const SaveMeta = z.object({
+	slot: Key,
+	label: z.string().nullable(),
+	/** Epoch ms. */
+	updatedAt: Millis
+});
+/** A save slot with its payload. */
+const Save = SaveMeta.extend({ 
+/** The stored JSON (`null` if it could not be read back). */
+data: Json });
+/** A player's numeric stats in one game: stat {@link Key} to value. */
+const Stats = z.record(Key, z.number());
+/** How a stat update combines with the stored value. */
+const StatMode = z.enum([
+	"set",
+	"incr",
+	"max"
+]);
+/**
+* A {@link Key} read like the hub's `validKey` (`String(x || '')`), failing
+* with its message: "<label> must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars)."
+*/
+function keyField(label) {
+	const message = `${label} must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars).`;
+	return requiredText(message).refine((text) => Key.safeParse(text).success, message);
+}
+/** A number read like the hub's `finiteNumber` (`Number(x)`), failing with "<label> must be a finite number.". */
+function finiteNumberField(label) {
+	return z.coerce.number({ error: `${label} must be a finite number.` });
+}
+/**
+* A stat update's mode. The hub reads `body.mode || 'set'`, so a falsy value
+* (`null`, `''`, `0`, `false`) also means `set`. Clients should send a
+* {@link StatMode} or nothing.
+*/
+const StatModeField = z.union([
+	StatMode,
+	z.literal([
+		"",
+		0,
+		false
+	]),
+	z.null()
+], { error: "mode must be set, incr, or max." }).optional().transform((mode) => mode || "set");
+/**
+* A save's payload: any JSON, but present. (The union with `never` exists only
+* so a missing value fails with the hub's message rather than zod's.)
+*/
+const SaveData = z.union([Json, z.never()], { error: "Missing \"data\"." });
+/** `:slot` of a save. */
+const SlotParams = z.object({ slot: keyField("slot") });
+/** The per-game data endpoints. */
+const gameDataEndpoints = {
+	...use(session, game).path("/games/:slug").group({ 
+	/**
+	* A player's stats. Defaults to the caller's own (401 when signed out);
+	* `?user=<id>` reads anyone's, since stats are public like a profile.
+	*/
+getGameStats: {
+		method: "GET",
+		path: "/stats",
+		query: z.object({ 
+		/** Whose stats to read (a user id); omit for the caller's. */
+user: finiteNumberField("user").optional() }),
+		response: z.object({ stats: Stats }),
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			404: ErrorBody
+		},
+		doc: {
+			summary: "A player's stats in this game",
+			tags: ["progress"]
+		}
+	} }),
+	...use(requireUser, game).path("/games/:slug").group({
+		getGameProfile: {
+			method: "GET",
+			path: "/profile",
+			response: z.object({ profile: Profile.nullable() }),
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "The caller's profile in this game, or null",
+				tags: ["progress"]
+			}
+		},
+		/**
+		* Create or replace the caller's profile. A new or changed display name
+		* is moderated (422) because other players see it.
+		*/
+		setGameProfile: {
+			method: "PUT",
+			path: "/profile",
+			body: z.object({
+				/** Up to 60 characters (longer is clipped); `null` or missing clears it. */
+				displayName: LooseText.nullish(),
+				/** Replaces the stored data; missing stores `{}`. */
+				data: Json.optional()
+			}),
+			response: z.object({ profile: Profile }),
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody,
+				422: ContentRejected
+			},
+			doc: {
+				summary: "Create or replace the caller's profile in this game",
+				tags: ["progress"]
+			}
+		},
+		listSaves: {
+			method: "GET",
+			path: "/saves",
+			response: z.object({ saves: z.array(SaveMeta) }),
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "The caller's save slots, newest first (no payloads)",
+				tags: ["progress"]
+			}
+		},
+		getSave: {
+			method: "GET",
+			path: "/saves/:slot",
+			params: SlotParams,
+			response: z.object({ save: Save.nullable() }),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "One save slot, or null when empty",
+				tags: ["progress"]
+			}
+		},
+		writeSave: {
+			method: "PUT",
+			path: "/saves/:slot",
+			params: SlotParams,
+			body: z.object({
+				/** Any JSON up to 64 KB serialized (`HUB_MAX_SAVE_BYTES`); 413 over. */
+				data: SaveData,
+				/** Up to 80 characters (longer is clipped). */
+				label: LooseText.nullish()
+			}),
+			response: z.object({
+				ok: z.literal(true),
+				/** Epoch ms. */
+				updatedAt: Millis
+			}),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody,
+				413: ErrorBody
+			},
+			doc: {
+				summary: "Create or overwrite a save slot",
+				tags: ["progress"]
+			}
+		},
+		deleteSave: {
+			method: "DELETE",
+			path: "/saves/:slot",
+			params: SlotParams,
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Delete a save slot (idempotent)",
+				tags: ["progress"]
+			}
+		},
+		/** Update one stat. Backs the client's `setStat`, `incrStat` and `maxStat`. */
+		updateGameStat: {
+			method: "POST",
+			path: "/stats",
+			body: z.object({
+				key: keyField("key"),
+				value: finiteNumberField("value"),
+				/** Default `set`. */
+				mode: StatModeField
+			}),
+			response: z.object({
+				key: Key,
+				value: z.number()
+			}),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Set, add to, or raise one stat; returns its new value",
+				tags: ["progress"]
+			}
+		},
+		/**
+		* Wipe the caller's saves, stats, inventory and coins in this game.
+		* Pending trades are closed first, refunding other players' escrow.
+		* Leaderboard entries and the profile are kept.
+		*/
+		resetMyGameProgress: {
+			method: "POST",
+			path: "/reset",
+			response: Ok,
+			errors: {
+				401: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Reset the caller's progress in this game",
+				tags: ["progress"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/progress.ts
+/**
+* Per-game player data: profiles, saves, stats, game reset, and the player's
+* records and snapshot. The per-game endpoints live in `progress/game-data.ts`.
+*/
+/** Everything the caller has in one game, as the snapshot carries it. */
+const GameSnapshot = z.object({
+	profile: Profile.nullable(),
+	/** Newest first, with payloads. */
+	saves: z.array(Save),
+	stats: Stats,
+	inventory: Inventory
+});
+/** The progress endpoints. */
+const progressEndpoints = {
+	...gameDataEndpoints,
+	...session.group({
+		/**
+		* The caller's leaderboard standings, grouped by game (empty when
+		* signed out). `?game=` limits it to one game; empty means every game,
+		* and text that is no game's slug matches nothing, as in the old hub.
+		*/
+		listMyLeaderboardRecords: {
+			method: "GET",
+			path: "/me/records",
+			query: z.object({ game: z.string().optional() }),
+			response: z.object({ games: z.array(GameRecords) }),
+			doc: {
+				summary: "The caller's leaderboard standings",
+				tags: ["progress"]
+			}
+		},
+		/**
+		* Everything the caller has, in one request, to warm the offline cache
+		* for every game (the client's `prefetchAll`). Signed out, only the
+		* global boards are filled in.
+		*/
+		getMyOfflineSnapshot: {
+			method: "GET",
+			path: "/me/snapshot",
+			query: TopQuery,
+			response: z.object({
+				user: SessionUser.nullable(),
+				/** By slug: every game the caller has any profile, save, stat or holding in. */
+				games: z.record(Slug, GameSnapshot),
+				records: z.array(GameRecords),
+				leaderboards: z.array(GameLeaderboards)
+			}),
+			doc: {
+				summary: "The caller's data across every game, plus the global boards",
+				tags: ["progress"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/race.ts
+/**
+* Races: the signed-in player's own race history (docs/plans/race.md §7).
+* The live race runs over the socket (`race.*` ops and events).
+*/
+/** An optional positive-integer query param; empty means "not set". */
+const OptionalCount = z.union([z.literal(""), z.coerce.number().int().positive()]).optional();
+/** `GET /race/history` filters. */
+const RaceHistoryQuery = z.object({
+	/** Only this game (default: every game). */
+	game: z.union([z.literal(""), z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)]).optional(),
+	/** Only races with this player (a user id). */
+	with: OptionalCount,
+	/** Only races older than this race id (paging). */
+	before: OptionalCount,
+	/** Page size, 1 to 50 (default 20; larger values are capped). */
+	limit: OptionalCount
+});
+/** A page of the player's races, newest first. */
+const RaceHistory = z.object({
+	races: z.array(RaceRecord),
+	/** More races exist before the last one. */
+	more: z.boolean(),
+	/** Totals over every race matching the filters (not just this page). */
+	summary: z.object({
+		races: z.number().int().nonnegative(),
+		wins: z.number().int().nonnegative(),
+		losses: z.number().int().nonnegative()
+	})
+});
+/** The race endpoints. */
+const raceEndpoints = { ...requireActive.group({ listMyRaceHistory: {
+	method: "GET",
+	path: "/race/history",
+	query: RaceHistoryQuery,
+	response: RaceHistory,
+	errors: {
+		400: ErrorBody,
+		401: ErrorBody,
+		403: ErrorBody
+	},
+	doc: {
+		summary: "The signed-in player's decided races, newest first",
+		tags: ["race"]
+	}
+} }) };
+//#endregion
+//#region src/api/social/presence.ts
+/**
+* Presence: what a player is doing right now, as their friends see it, and
+* the anonymous online counts (multiplayer-impl.md §4.4). Games report a
+* {@link PresenceInput} per tab (socket op `presence`); the hub folds a
+* user's tabs into one {@link Presence} and pushes it to friends
+* (`ev:presence`).
+*/
+/** Activity kinds, least engaged first. The most engaged tab wins; hidden or idle tabs count as `away`. */
+const PresenceKind = z.enum([
+	"away",
+	"menu",
+	"lobby",
+	"watching",
+	"playing"
+]);
+/** A room reference friends can join with: 1 to 64 of `A-Z a-z 0-9 _ : -`. */
+const PresenceRoom = z.string().regex(/^[A-Za-z0-9_:-]{1,64}$/);
+/** A game mode key: 1 to 32 of `A-Z a-z 0-9 _ -`. */
+const PresenceMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+/** The fields a tab reports and friends see back, with the limits the hub enforces. */
+const PresenceFields = z.object({
+	kind: PresenceKind,
+	/** A short status line (at most 40 characters), filtered; a rejected one is dropped. */
+	detail: z.string().max(40).optional(),
+	/** Friends may join. Only ever `true` when present. */
+	joinable: z.boolean().optional(),
+	/** Friends may watch. Only ever `true` when present. */
+	watchable: z.boolean().optional(),
+	/** Join info for friends: the game's own room reference, or the hub room's code. */
+	room: PresenceRoom.optional(),
+	/** A public lobby: friends who follow the game may get a `lobby_open` alert. */
+	public: z.boolean().optional(),
+	/** Free seats, 0 to 64. */
+	openSeats: z.number().int().min(0).max(64).optional(),
+	mode: PresenceMode.optional()
+});
+/**
+* What a game reports for its tab (socket op `presence`). The hub is
+* lenient: an unknown `kind`, or input that isn't an object at all (`null`),
+* counts as `{kind:'menu'}`; unknown fields, and fields that break a rule (a
+* bad `room`, a fractional `openSeats`, a field of the wrong type), are
+* ignored one by one, so friends only ever
+* see {@link Presence}'s fields; `detail` is trimmed to 40 characters before
+* filtering.
+*/
+const PresenceInput = z.looseObject({
+	kind: PresenceKind.catch("menu"),
+	detail: z.string().optional().catch(void 0),
+	joinable: z.boolean().optional().catch(void 0),
+	watchable: z.boolean().optional().catch(void 0),
+	room: z.string().optional().catch(void 0),
+	public: z.boolean().optional().catch(void 0),
+	openSeats: z.number().optional().catch(void 0),
+	mode: z.string().optional().catch(void 0)
+}).catch({ kind: "menu" });
+/** A user's aggregated presence: their most engaged tab, decorated by the hub. */
+const Presence = PresenceFields.extend({
+	/** The game the tab is on, `null` on the catalog and other hub pages. */
+	game: Slug.nullable(),
+	/** That game's title, `null` with `game`. */
+	gameTitle: z.string().nullable(),
+	/** When this activity (kind + game) started (epoch ms). */
+	since: Millis,
+	/** Party size, present when the user is in a party of two or more. */
+	partySize: z.number().int().min(2).optional()
+});
+/** A non-negative head count. */
+const HeadCount = z.number().int().nonnegative();
+/**
+* Anonymous online counts (`GET /social/counts`, `ev:counts`, the `hello`
+* snapshot): everyone with a live presence, guests and hidden players
+* included.
+*/
+const Counts = z.object({
+	/** Everyone online. */
+	online: HeadCount,
+	/** Players per game slug (games with nobody are absent). */
+	byGame: z.record(Slug, HeadCount)
+});
+//#endregion
+//#region src/api/reports.ts
+/**
+* Reports and suggestions: players flagging problems (multiplayer-impl.md
+* §5.3) and proposing game ideas (§5.5).
+*
+* A report only says *what* is reported; the hub builds the evidence
+* snapshot from its own records. Suggestions are filtered, reviewed by an
+* admin, and only approved ones reach the public board.
+*/
+/** What is being reported. */
+const ReportKind = z.enum([
+	"message",
+	"user",
+	"username",
+	"suggestion",
+	"room_chat",
+	"presence"
+], { error: "kind must be one of message, user, username, suggestion, room_chat, presence." });
+/** Why, from a fixed list (there is no free text). */
+const ReportReason = z.enum([
+	"mean",
+	"bad_words",
+	"personal",
+	"inappropriate",
+	"spam",
+	"other"
+], { error: "reason must be one of mean, bad_words, personal, inappropriate, spam, other." });
+/**
+* `POST /social/reports`. Loose on purpose: anything else the client sends
+* (an evidence snapshot, quoted text) is ignored, because the hub builds the
+* snapshot from its own records.
+*/
+const ReportInput = z.looseObject({
+	kind: ReportKind,
+	/**
+	* The reported player. `0` for a suggestion: the hub finds its author from
+	* `refId`. Read like `Number(x)`: anything that is not a player's id is a 404.
+	*/
+	targetUserId: LooseNumber.catch(NaN),
+	/**
+	* What exactly: the message id (`message`), the suggestion id
+	* (`suggestion`) or the room code (`room_chat`). Kept to 64 characters.
+	*/
+	refId: z.union([z.string(), z.number()]).nullable().optional(),
+	reason: ReportReason
+});
+/** A direct message as a report snapshot keeps it. */
+const ReportedMessage = z.object({
+	id: z.number().int().positive(),
+	/** The sender's user id. */
+	from: z.number().int(),
+	/** The recipient's user id. */
+	to: z.number().int(),
+	/** When it was sent (epoch ms). */
+	at: Millis,
+	/** The text, or the quick-chat phrase's text (`''` for an unknown phrase). */
+	text: z.string(),
+	/** The quick-chat phrase id, when it was one. */
+	quick: z.string().optional()
+});
+/**
+* The evidence the hub records with a report, from its own records (stored
+* as `snapshot_json`; the admin console shows it). Always the reported
+* player; then per kind: `message` adds the message and up to 5 before it in
+* the conversation (oldest first), `suggestion` its title, body and status,
+* `presence` their status line (`null` when offline), `room_chat` the room
+* code (room chat isn't stored).
+*/
+const ReportSnapshot = z.object({
+	userId: z.number().int(),
+	username: z.string(),
+	message: ReportedMessage.optional(),
+	context: z.array(ReportedMessage).optional(),
+	title: z.string().optional(),
+	body: z.string().optional(),
+	status: z.string().optional(),
+	detail: z.string().optional(),
+	presence: Presence.nullable().optional(),
+	room: z.string().optional()
+});
+/** A suggestion's review status. Only `approved`, `planned` and `done` are on the public board. */
+const SuggestionStatus = z.enum([
+	"pending",
+	"approved",
+	"planned",
+	"done",
+	"removed",
+	"withdrawn"
+]);
+/** A suggestion id. */
+const SuggestionId = z.number().int().positive();
+/** A game suggestion. */
+const Suggestion = z.object({
+	id: SuggestionId,
+	title: z.string(),
+	/** The description. */
+	body: z.string(),
+	status: SuggestionStatus,
+	/** Upvotes. */
+	votes: z.number().int().nonnegative(),
+	/** You upvoted it. */
+	voted: z.boolean(),
+	/** You suggested it. */
+	mine: z.boolean(),
+	/** The reviewer's note to the author, `''` when none. */
+	adminNote: z.string(),
+	/** When it was suggested (epoch ms). */
+	createdAt: Millis,
+	/** The author's username: only once it is on the public board (and always in admin views). */
+	author: z.string().optional()
+});
+/** A vote's result: the new count and whether you are voting. */
+const VoteResult = z.object({
+	votes: z.number().int().nonnegative(),
+	voted: z.boolean()
+});
+/**
+* `:id`, a suggestion: one on the public board to vote, your own pending one
+* to withdraw. Read like `Number(x)`: anything that isn't one is a 404.
+*/
+const SuggestionParams = z.object({ id: LooseNumber.catch(NaN) });
+/** The old hub's one message for a missing or non-text title or description. */
+const SuggestionText = z.string({ error: "A suggestion needs a title and a description." });
+/** The report and suggestion endpoints. */
+const reportsEndpoints = {
+	...requireActive.group({ fileReport: {
+		method: "POST",
+		path: "/social/reports",
+		body: ReportInput,
+		response: z.object({
+			ok: z.literal(true),
+			/** The report's id (the open one, when you already reported the same thing). */
+			id: z.number().int().positive()
+		}),
+		errors: {
+			400: ErrorBody,
+			401: ErrorBody,
+			403: ErrorBody,
+			404: ErrorBody,
+			429: ErrorBody
+		},
+		doc: {
+			summary: "Report a player, a message, a suggestion or a status line",
+			description: "404 when `refId` is nothing you could have seen from that player.",
+			tags: ["reports"]
+		}
+	} }),
+	...session.group({ listPublicSuggestions: {
+		method: "GET",
+		path: "/suggestions",
+		query: z.object({ 
+		/** `votes` (default) or `new`. */
+sort: z.enum(["votes", "new"]).optional().catch(void 0) }),
+		response: z.object({
+			/** The public board (approved, planned, done), at most 200. Ideas from suspended authors drop off. */
+			approved: z.array(Suggestion),
+			/** Your own ideas except withdrawn ones, newest first; empty unless signed in to a claimed account. */
+			mine: z.array(Suggestion)
+		}),
+		errors: { 403: ErrorBody },
+		doc: {
+			summary: "The ideas board, plus your own ideas",
+			tags: ["suggestions"]
+		}
+	} }),
+	...requireClaimed.group({
+		submitSuggestion: {
+			method: "POST",
+			path: "/suggestions",
+			body: z.object({
+				title: SuggestionText,
+				body: SuggestionText
+			}),
+			response: z.object({ suggestion: Suggestion }),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				409: ErrorBody,
+				422: ContentRejected,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Suggest a game idea (filtered; a few a day, a capped number pending)",
+				description: "409 `too_many_pending`; 429 `rate_limited` with `retryAfterMs` past the daily limit.",
+				tags: ["suggestions"]
+			}
+		},
+		voteForSuggestion: {
+			method: "POST",
+			path: "/suggestions/:id/vote",
+			params: SuggestionParams,
+			response: VoteResult,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Upvote an idea (idempotent)",
+				tags: ["suggestions"]
+			}
+		},
+		removeSuggestionVote: {
+			method: "DELETE",
+			path: "/suggestions/:id/vote",
+			params: SuggestionParams,
+			response: VoteResult,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Take an upvote back (idempotent)",
+				tags: ["suggestions"]
+			}
+		},
+		withdrawSuggestion: {
+			method: "DELETE",
+			path: "/suggestions/:id",
+			params: SuggestionParams,
+			response: Ok,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Withdraw your own idea while it is still pending",
+				tags: ["suggestions"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/social/people.ts
+/**
+* People shapes: your own social settings, friends, requests, player cards
+* and recent players. Several are also part of the socket `hello` snapshot.
+*
+* Privacy rules behind them: a block in either direction looks to the
+* blocked side like an ordinary unfriend (or a missing player), suspended
+* players are invisible, and guests have no friends.
+*/
+/** Who may see my presence, or message me: friends, or nobody. */
+const Audience = z.enum(["friends", "nobody"]);
+/**
+* Your own account's social fields (`GET`/`PUT /social/me`, the `hello`
+* snapshot's `me`). Never shown to other players.
+*/
+const SocialMe = SessionUser.extend({
+	/** Avatar token; never empty (a default is derived from the id). */
+	avatar: PlayerLite.shape.avatar,
+	/** Who sees my presence and last-seen time. */
+	privacy: Audience,
+	/** Who may message me (and invite me). */
+	dmPolicy: Audience
+});
+/** A friend, with what you may see of their presence. Online friends sort first. */
+const FriendEntry = PlayerLite.extend({
+	/** `null` when offline or hiding their presence. */
+	presence: Presence.nullable(),
+	/** "Tell me when they come online" is on for this friend. */
+	notifyOnline: z.boolean(),
+	/** When you became friends (epoch ms). */
+	since: Millis,
+	/** When they were last online (epoch ms); `0` when unknown or they hide their presence. */
+	lastSeenAt: Millis
+});
+/** Pending friend requests both ways, newest first (blocked and suspended players left out). */
+const FriendRequests = z.object({
+	/** Requests waiting for you. */
+	incoming: z.array(PlayerLite),
+	/** Requests you sent. */
+	outgoing: z.array(PlayerLite)
+});
+/** `GET /social/friends`: friends, requests and the players you blocked. Guests get empty lists. */
+const FriendsList = FriendRequests.extend({
+	friends: z.array(FriendEntry),
+	/** Players you blocked, newest first. */
+	blocked: z.array(PlayerLite)
+});
+/**
+* What changed in `ev:friends` (the client refetches `GET /social/friends`).
+* `restored`: a friend's suspension ended. A player you blocked only ever
+* sees `removed`.
+*/
+const FriendChange = z.enum([
+	"request",
+	"accepted",
+	"removed",
+	"declined",
+	"cancelled",
+	"blocked",
+	"restored"
+]);
+/** My relation to another player, as their card shows it. */
+const Relation = z.enum([
+	"self",
+	"friend",
+	"incoming",
+	"outgoing",
+	"blocked",
+	"none"
+]);
+/**
+* A player card (`GET /social/players/:id`). Someone who blocked you, or who
+* is suspended, answers 404 exactly like a player who doesn't exist.
+*/
+const PlayerCard = PlayerLite.extend({
+	relation: Relation,
+	/** Friends only; `null` otherwise, or when offline or hidden. */
+	presence: Presence.nullable(),
+	/** A friend request can be sent (both claimed, no relation yet or theirs is pending, requests on). */
+	canFriend: z.boolean(),
+	/** Friends who take messages, while DMs are on. */
+	canMessage: z.boolean(),
+	/** Friends who take messages. */
+	canInvite: z.boolean(),
+	/** Anyone but yourself. */
+	canReport: z.boolean()
+});
+/** Someone you recently played with (`GET /social/recent`). */
+const RecentPlayer = PlayerLite.extend({
+	/** The game you played together. */
+	game: Slug,
+	/** When you last played together (epoch ms). */
+	lastAt: Millis
+});
+//#endregion
+//#region src/api/social/endpoints.ts
+/**
+* Social core REST (multiplayer-impl.md §5.1): config, your own social
+* settings, friends and requests, blocks, player cards, recent players and
+* online counts. Every route here is closed to suspended accounts (403
+* `suspended`) except `GET /social/config` and `GET /social/me`, which a
+* suspended player's UI needs to explain what happened.
+*/
+/** `{ me }`: your social settings after a change. */
+const SocialMeResult = z.object({ me: SocialMe });
+/** `:id`, another player's user id. A malformed id is a 400. */
+const OtherUser = z.object({ id: requiredId("id must be a user id.") });
+/** An {@link Audience} field, with the old hub's message for anything else. */
+const audienceField = (field) => z.enum(Audience.options, { error: `${field} must be friends or nobody.` });
+/**
+* `POST /social/friends`: who to befriend, by id or by name, and an optional
+* first message. `userId` wins when both are given; with neither, the player
+* is not found (404 `no_player`).
+*/
+const FriendRequestInput = z.object({
+	userId: requiredId("userId must be a user id.").nullish(),
+	/** A username, case-insensitive. */
+	username: z.string().optional(),
+	message: z.string().optional()
+});
+/** The result of `POST /social/friends`. */
+const FriendRequestStatus = z.enum(["requested", "friends"]);
+/** The social core endpoints. */
+const socialEndpoints = {
+	...session.group({
+		getSocialConfig: {
+			method: "GET",
+			path: "/social/config",
+			response: SocialConfig,
+			doc: {
+				summary: "The site-wide social configuration",
+				tags: ["social"]
+			}
+		},
+		getOnlineCounts: {
+			method: "GET",
+			path: "/social/counts",
+			response: Counts,
+			errors: { 403: ErrorBody },
+			doc: {
+				summary: "Anonymous online counts, overall and per game",
+				tags: ["social"]
+			}
+		}
+	}),
+	...requireUser.group({ getMySocialProfile: {
+		method: "GET",
+		path: "/social/me",
+		response: z.object({
+			me: SocialMe,
+			notify: NotifyPrefs,
+			/** How many browsers have a push subscription for this account. */
+			pushSubs: z.number().int().nonnegative()
+		}),
+		errors: { 401: ErrorBody },
+		doc: {
+			summary: "Your social settings, notification preferences and push subscription count",
+			tags: ["social"]
+		}
+	} }),
+	...requireActive.group({
+		listFriendsAndRequests: {
+			method: "GET",
+			path: "/social/friends",
+			response: FriendsList,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Friends (online first), requests both ways and blocks",
+				tags: ["social"]
+			}
+		},
+		findPlayerByName: {
+			method: "GET",
+			path: "/social/players/by-name/:name",
+			params: z.object({ name: z.string() }),
+			response: PlayerCard,
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "A player card, by username",
+				tags: ["social"]
+			}
+		},
+		getPlayerCard: {
+			method: "GET",
+			path: "/social/players/:id",
+			params: OtherUser,
+			response: PlayerCard,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "A player card, by id (404 `no_player` when blocked by them or suspended)",
+				tags: ["social"]
+			}
+		}
+	}),
+	...requireClaimed.group({
+		updateMySocialProfile: {
+			method: "PUT",
+			path: "/social/me",
+			body: z.object({
+				/** One of the config's preset avatar ids (else 400 `bad_avatar`). */
+				avatar: z.string().optional(),
+				privacy: audienceField("privacy").optional(),
+				dmPolicy: audienceField("dmPolicy").optional()
+			}),
+			response: SocialMeResult,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Change your avatar, presence privacy or who may message you",
+				tags: ["social"]
+			}
+		},
+		setParentChatLock: {
+			method: "POST",
+			path: "/social/chat-lock",
+			body: z.union([z.object({ on: z.literal(true) }), z.object({
+				on: z.literal(false),
+				/** The account password; required to turn the lock off. */
+				password: z.string().optional()
+			})], { error: "on must be true or false." }),
+			response: SocialMeResult,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Parent chat lock: on with one tap, off only with the account password",
+				description: "A wrong password is 403 `bad_password` (logged and rate-limited).",
+				tags: ["social"]
+			}
+		},
+		sendFriendRequest: {
+			method: "POST",
+			path: "/social/friends",
+			body: FriendRequestInput,
+			response: z.object({ status: FriendRequestStatus }),
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody,
+				422: ContentRejected,
+				429: ErrorBody
+			},
+			doc: {
+				summary: "Send a friend request (a reverse request accepts at once)",
+				description: "Answers `requested` without doing anything when the target blocked you or is suspended. `message` is moderated now and delivered as the first DM once you are friends.",
+				tags: ["social"]
+			}
+		},
+		acceptFriendRequest: {
+			method: "POST",
+			path: "/social/friends/:id/accept",
+			params: OtherUser,
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Accept the request from `:id`",
+				tags: ["social"]
+			}
+		},
+		declineFriendRequest: {
+			method: "POST",
+			path: "/social/friends/:id/decline",
+			params: OtherUser,
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Quietly drop the request from `:id`",
+				tags: ["social"]
+			}
+		},
+		removeFriend: {
+			method: "DELETE",
+			path: "/social/friends/:id",
+			params: OtherUser,
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Unfriend `:id`, or cancel your request to them",
+				tags: ["social"]
+			}
+		},
+		setFriendNotifications: {
+			method: "PUT",
+			path: "/social/friends/:id/notify",
+			params: OtherUser,
+			body: z.object({ online: z.boolean({ error: "online must be true or false." }) }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody
+			},
+			doc: {
+				summary: "Turn a friend's \"tell me when they're online\" bell on or off",
+				tags: ["social"]
+			}
+		},
+		blockPlayer: {
+			method: "POST",
+			path: "/social/blocks",
+			body: z.object({ userId: requiredId("userId must be a user id.") }),
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody,
+				404: ErrorBody,
+				409: ErrorBody
+			},
+			doc: {
+				summary: "Block a player",
+				description: "Also unfriends, drops requests both ways and splits a shared party.",
+				tags: ["social"]
+			}
+		},
+		unblockPlayer: {
+			method: "DELETE",
+			path: "/social/blocks/:id",
+			params: OtherUser,
+			response: Ok,
+			errors: {
+				400: ErrorBody,
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "Unblock a player",
+				tags: ["social"]
+			}
+		},
+		listRecentPlayers: {
+			method: "GET",
+			path: "/social/recent",
+			response: z.object({ 
+			/** Newest first, at most 50. */
+players: z.array(RecentPlayer) }),
+			errors: {
+				401: ErrorBody,
+				403: ErrorBody
+			},
+			doc: {
+				summary: "People you recently played with",
+				tags: ["social"]
+			}
+		}
+	})
+};
+//#endregion
+//#region src/api/version.ts
+/**
+* `GET /version`: which client versions this hub serves (plan §4.3.3). Games'
+* clients read it once per page, and `hub-doctor` reads it in a game's CI.
+* The old hub has no such route and answers 404 "No such API endpoint.", which
+* clients read as "a hub from before versioning".
+*/
+/**
+* A semver range in the npm form: comparators (`>=2.0.0-0`, `<3.0.0`)
+* separated by spaces are all required; `||` separates alternatives.
+*/
+const VersionRange = z.string().min(1);
+/** What `GET /version` answers. */
+const HubVersion = z.object({
+	/** The hub release this server was built from: the version of the client it serves at `/_hub/hub.js`. */
+	server: z.string(),
+	/** The version of `@diffenderfer-games/hub-contract` the server implements. */
+	contract: z.string(),
+	/** Client versions the server supports (`x-hub-client`); a client outside it should be updated. */
+	supported: VersionRange,
+	/** Supported client versions that are deprecated: they still work, and `hub-doctor` warns. */
+	deprecated: VersionRange
+});
+/** The version endpoints. */
+const versionEndpoints = { ...session.group({ getHubVersion: {
+	method: "GET",
+	path: "/version",
+	response: HubVersion,
+	doc: {
+		summary: "The hub version and the client versions it supports",
+		tags: ["catalog"]
+	}
+} }) };
+//#endregion
+//#region src/api/index.ts
+/**
+* The public REST API: every endpoint a game, the menu or the social runtime
+* calls, as one ayepi spec. Paths are relative to `/_api`. One file per area.
+*/
+/** Every public endpoint, by name. */
+const publicEndpoints = {
+	...authEndpoints,
+	...catalogEndpoints,
+	...progressEndpoints,
+	...leaderboardsEndpoints,
+	...dailyEndpoints,
+	...economyEndpoints,
+	...analyticsEndpoints,
+	...socialEndpoints,
+	...messagesEndpoints,
+	...notifyEndpoints,
+	...reportsEndpoints,
+	...mpEndpoints,
+	...raceEndpoints,
+	...versionEndpoints
+};
+/** The public API spec (paths relative to `/_api`). */
+const publicApi = spec({ endpoints: publicEndpoints });
+//#endregion
+//#region src/realtime/define.ts
+/** Declare an op (identity at runtime; keeps the literal types). */
+function op(def) {
+	return def;
+}
+/** Declare an event (identity at runtime; keeps the literal types). */
+function event(def) {
+	return def;
+}
+//#endregion
+//#region src/realtime/events/parties.ts
+/** Invite and party events (multiplayer-impl.md §5.6). */
+/** The invite and party events, by event name. */
+const partyEvents = {
+	invite: event({
+		d: Invite,
+		doc: "A friend invited you to a game."
+	}),
+	"invite.update": event({
+		d: z.object({
+			id: OpaqueId,
+			status: InviteStatus,
+			/** Who accepted or declined (absent for cancelled and expired). */
+			by: PlayerLite.optional()
+		}),
+		doc: "An invite ended; sent to the inviter and the invitee (so its toast closes)."
+	}),
+	party: event({
+		d: Party.nullable(),
+		doc: "Your party's current state, or null when you left it or it dissolved."
+	}),
+	"party.chat": event({
+		d: ChatLineEvent,
+		doc: "A party chat line."
+	})
+};
+//#endregion
+//#region src/realtime/events/races.ts
+/** Race events (docs/plans/race.md §4). */
+/** The race events, by event name. */
+const raceEvents = {
+	"race.start": event({
+		d: RaceStart,
+		doc: "The countdown began: the seed is revealed now."
+	}),
+	"race.status": event({
+		d: z.object({
+			userId: UserId,
+			stats: RaceStats,
+			progress: RaceProgress.optional(),
+			/** ms since the go (server clock). */
+			at: z.number().int().nonnegative()
+		}),
+		doc: "Another racer's live status, for the race HUD."
+	}),
+	"race.result": event({
+		d: z.object({ result: RaceResult }),
+		doc: "The race was decided."
+	})
+};
+//#endregion
+//#region src/realtime/events/rooms.ts
+/** Hub relay room events (multiplayer-impl.md §6). Race rooms send these too. */
+/** The room events, by event name. */
+const roomEvents = {
+	room: event({
+		d: z.object({
+			room: RoomInfo,
+			/** What the host passed to `room.end`; present once, on that update. */
+			results: Json.optional()
+		}),
+		doc: "The room changed: roster, ready flags, phase, host, race state."
+	}),
+	"room.msg": event({
+		d: RoomMessage,
+		doc: "A relayed game message."
+	}),
+	"room.state": event({
+		d: z.object({
+			/** Shallow-merged into the state unless `replace`; a `null` value deletes its key. */
+			patch: RoomState,
+			replace: z.boolean(),
+			seq: z.number().int().positive()
+		}),
+		doc: "The shared state changed."
+	}),
+	"room.chat": event({
+		d: ChatLineEvent,
+		doc: "A room chat line."
+	}),
+	"room.kicked": event({
+		d: z.object({ roomId: OpaqueId }),
+		doc: "The host removed you from the room."
+	}),
+	"room.closed": event({
+		d: z.object({ reason: RoomClosedReason }),
+		doc: "The room is gone for this tab (emptied, ended, host left, moved, another tab took the seat, removed)."
+	}),
+	"room.abandoned": event({
+		d: z.object({
+			userId: UserId,
+			reason: SeatGoneReason
+		}),
+		doc: "A player left mid-game (or their reconnect grace ran out); the game decides what that means."
+	})
+};
+//#endregion
+//#region src/realtime/events/multiplayer.ts
+/** The multiplayer events, by event name. */
+const multiplayerEvents = {
+	...partyEvents,
+	...roomEvents,
+	...raceEvents
+};
+//#endregion
+//#region src/realtime/events/social.ts
+/**
+* Socket events for presence, counts, friends, typing, config, DMs, notices
+* and suspension (multiplayer-impl.md §4.6). Every event goes to all of the
+* recipient's tabs.
+*/
+/** What kind of thing a notice is about. `renamed`: an admin changed your username. */
+const NoticeKind = z.enum([
+	"dm",
+	"friend_request",
+	"friend_online",
+	"lobby_open",
+	"invite",
+	"suggestion",
+	"renamed"
+]);
+/** A toast (`ev:notice`), sent instead of a push when the player has a visible tab. */
+const Notice = z.object({
+	kind: NoticeKind,
+	title: z.string(),
+	body: z.string().optional(),
+	/** A button: its label and the page it opens. */
+	action: z.object({
+		label: z.string(),
+		url: z.string()
+	}).optional()
+});
+/** The social events, by event name. */
+const socialEvents = {
+	presence: event({
+		d: z.object({
+			userId: UserId,
+			/** `null`: offline, or no longer visible to you. */
+			p: Presence.nullable()
+		}),
+		doc: "A friend's presence changed."
+	}),
+	counts: event({
+		d: Counts,
+		doc: "The online counts changed (broadcast to every tab, at most every 15 s)."
+	}),
+	friends: event({
+		d: z.object({
+			change: FriendChange,
+			user: PlayerLite
+		}),
+		doc: "Your friends list changed (refetch `GET /social/friends`)."
+	}),
+	typing: event({
+		d: z.object({ from: UserId }),
+		doc: "A friend is typing to you."
+	}),
+	config: event({
+		d: SocialConfig,
+		doc: "The site-wide social configuration changed (broadcast)."
+	}),
+	dm: event({
+		d: z.object({
+			message: Message,
+			/** The other side of the conversation, from your point of view. */
+			conversationWith: UserId
+		}),
+		doc: "A DM was delivered: to the recipient, and to the sender's other tabs."
+	}),
+	"dm.read": event({
+		d: z.object({
+			/** Who read. */
+			by: UserId,
+			/** Their messages up to and including this id are read. */
+			upTo: MessageId
+		}),
+		doc: "Messages were read (to the sender, and to the reader's own tabs to sync badges)."
+	}),
+	"dm.hidden": event({
+		d: z.object({ ids: z.array(MessageId) }),
+		doc: "A moderator hid these messages: drop them from both sides of the conversation."
+	}),
+	notice: event({
+		d: Notice,
+		doc: "A toast to show."
+	}),
+	suspended: event({
+		d: z.object({
+			/** When the suspension ends (epoch ms). */
+			until: Millis,
+			/** The moderator's reason, when given. */
+			reason: z.string().optional()
+		}),
+		doc: "The account is suspended; the socket then closes with 4003."
+	})
+};
+/** The `hello` op (allowed before `hello`, obviously). */
+const helloOps = { hello: op({
+	d: z.object({
+		/** The game this tab is in, or `null` on the home page. Unknown slugs count as `null`. */
+		slug: z.string().nullable().optional(),
+		/** A per-tab id (`[A-Za-z0-9_-]{1,64}`); other values are ignored. */
+		tab: z.string().optional(),
+		/** The document is visible (default `true`). */
+		visible: z.boolean().optional(),
+		/** The client package version that opened the socket (`2.3.0`); v1 vendored copies send none. */
+		client: z.string().optional()
+	}),
+	ack: z.object({
+		me: SocialMe,
+		config: SocialConfig,
+		counts: Counts,
+		friends: z.array(FriendEntry),
+		requests: FriendRequests,
+		unread: UnreadSummary,
+		...MultiplayerSnapshot.shape
+	}),
+	errors: [],
+	doc: "Start the session on this socket; answers with the snapshot."
+}) };
+//#endregion
+//#region src/realtime/ops/parties.ts
+/** The party socket op: party chat. Invites and party membership are REST (`/mp/*`). */
+/** The party ops, by op name. */
+const partyOps = { "party.chat": op({
+	d: ChatSend,
+	ack: ChatLine,
+	errors: ["party_gone", ...CHAT_ERRORS],
+	doc: "Chat to your party: free text only when every member is a mutual friend, quick-chat otherwise."
+}) };
+//#endregion
+//#region src/realtime/ops/empty.ts
+/** The empty input and ack many socket ops share. */
+/** An op that takes no input (`d` absent or `{}`). */
+const NoInput = z.object({});
+/** An ack with no payload (`{}`). */
+const EmptyAck = z.object({});
+//#endregion
+//#region src/realtime/ops/races.ts
+/**
+* Race ops (docs/plans/race.md §4). A race is a hub room with a referee: the
+* countdown starts when every seat is filled, the seed is revealed with it,
+* and the first valid finish wins. Reports come from browsers, so the hub
+* measures time itself and enforces what it can (`minMs`, one result each).
+*/
+/** A racer's report (status, finish, lose): stats (`null` means none) and optional 0..1 progress. */
+const RaceReport = z.object({
+	stats: RaceStats.nullish(),
+	progress: RaceProgress.nullish()
+});
+/** The refusal a malformed report gets (old wording). */
+const BAD_STATS = {
+	code: "bad_stats",
+	error: "Race stats must be numbers, true/false or #rrggbb colours."
+};
+/** A race room ack. */
+const RoomAck = z.object({ room: RoomInfo });
+/** The race ops, by op name. */
+const raceOps = {
+	"race.create": op({
+		d: z.object({
+			game: Slug,
+			/** The creator's choices; undeclared keys and values fall back to the defaults. */
+			params: RaceParams.optional(),
+			/** Shown in Open races and can alert followers (default true). */
+			public: z.boolean().optional(),
+			/** Seats, within the game's `race.players` (default its min). */
+			maxPlayers: z.number().optional(),
+			/** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
+			partyId: OpaqueId.optional()
+		}),
+		ack: RoomAck,
+		errors: ["not_race", "too_many_rooms"],
+		doc: "Open a race room with the caller seated; the countdown starts once every seat is filled."
+	}),
+	"race.join": op({
+		d: RoomTarget,
+		ack: RoomAck,
+		errors: [
+			"room_not_found",
+			"banned",
+			"in_progress",
+			"room_full",
+			"not_multiplayer",
+			"not_supported"
+		],
+		doc: "Join (or watch) a race room, like `room.join` but only for races."
+	}),
+	"race.list": op({
+		d: z.object({ game: Slug }),
+		ack: z.object({ rooms: z.array(RoomInfo) }),
+		errors: [],
+		doc: "Public races waiting for racers (at most 50), minus rooms with blocked players."
+	}),
+	"race.start": op({
+		d: NoInput,
+		ack: EmptyAck,
+		errors: [
+			"not_in_race",
+			"not_host",
+			"in_progress",
+			"not_ready"
+		],
+		doc: "Creator: start the countdown early once the minimum racers are in."
+	}),
+	"race.status": op({
+		d: RaceReport,
+		ack: EmptyAck,
+		errors: [
+			"not_in_race",
+			"not_started",
+			"race_over",
+			"rate_limited",
+			"bad_stats"
+		],
+		invalid: BAD_STATS,
+		doc: "Live status for the race HUD. Numbers, booleans and #rrggbb only: never text."
+	}),
+	"race.finish": op({
+		d: RaceReport,
+		ack: z.object({ result: RaceResult }),
+		errors: [
+			"not_in_race",
+			"not_started",
+			"race_over",
+			"too_fast",
+			"bad_stats"
+		],
+		invalid: BAD_STATS,
+		doc: "Report a finish with final stats; the first valid finish wins the race."
+	}),
+	"race.lose": op({
+		d: RaceReport,
+		ack: EmptyAck,
+		errors: [
+			"not_in_race",
+			"not_started",
+			"race_over",
+			"bad_stats"
+		],
+		invalid: BAD_STATS,
+		doc: "Game over for this racer (out of lives, stuck…); the last racer left wins."
+	}),
+	"race.forfeit": op({
+		d: NoInput,
+		ack: EmptyAck,
+		errors: ["not_in_race", "race_over"],
+		doc: "Give up (leaving the room mid-race counts the same)."
+	}),
+	"race.rematch": op({
+		d: z.object({ 
+		/** Creator only: params for the next round. */
+params: RaceParams.optional() }),
+		ack: EmptyAck,
+		errors: ["not_in_race", "in_progress"],
+		doc: "Ask for another round; it starts when every seated racer has asked."
+	})
+};
+//#endregion
+//#region src/realtime/ops/rooms.ts
+/**
+* Hub relay room ops (multiplayer-impl.md §6). Rooms hold up to 8 seats;
+* the hub relays messages and state but never referees, so results are
+* untrusted. Race rooms refuse `room.start`, `room.state` and `room.end`
+* (`race_room`): the race ops drive them.
+*/
+/** A per-room sequence number ack (`room.send`, `room.state`). */
+const SeqAck = z.object({ seq: z.number().int().positive() });
+/** The room ops, by op name. */
+const roomOps = {
+	"room.create": op({
+		d: z.object({
+			game: Slug,
+			/** One of the game's modes (`race` is refused: use `race.create`). */
+			mode: GameMode.nullish(),
+			/** Listed in `room.list` (default false). */
+			public: z.boolean().optional(),
+			/** Seats; clamped to the game's max (and 8). Defaults to the max. */
+			maxPlayers: z.number().optional(),
+			model: RoomModel.optional(),
+			/** The caller's party: when they lead it, its join info becomes `{ room: code }`. */
+			partyId: OpaqueId.optional()
+		}),
+		ack: z.object({
+			room: RoomInfo,
+			state: RoomState
+		}),
+		errors: [
+			"not_multiplayer",
+			"not_supported",
+			"bad_mode",
+			"too_many_rooms"
+		],
+		doc: "Open a room for a hub-rooms game with the caller seated as host (leaving any other seat)."
+	}),
+	"room.join": op({
+		d: RoomTarget,
+		ack: z.object({
+			room: RoomInfo,
+			state: RoomState,
+			/** Recent messages this member may see, oldest first. */
+			history: z.array(RoomMessage)
+		}),
+		errors: [
+			"room_not_found",
+			"banned",
+			"in_progress",
+			"room_full",
+			"not_multiplayer",
+			"not_supported"
+		],
+		doc: "Take a seat (lobby only), reclaim your own seat (any phase, any tab), or watch."
+	}),
+	"room.leave": op({
+		d: NoInput,
+		ack: EmptyAck,
+		errors: [],
+		doc: "Give up your seat, or stop watching."
+	}),
+	"room.ready": op({
+		d: z.object({ ready: z.boolean() }),
+		ack: EmptyAck,
+		errors: ["not_in_room", "in_progress"],
+		doc: "Mark yourself ready in the lobby."
+	}),
+	"room.seat": op({
+		d: z.object({ data: Json.optional() }),
+		ack: EmptyAck,
+		errors: ["not_in_room", "too_large"],
+		doc: "Set your seat data (team, colour…), at most 2 KB of JSON."
+	}),
+	"room.start": op({
+		d: NoInput,
+		ack: EmptyAck,
+		errors: [
+			"not_in_room",
+			"not_host",
+			"race_room",
+			"in_progress",
+			"not_ready"
+		],
+		doc: "Host: start once the game's minimum players are seated and everyone else is ready."
+	}),
+	"room.send": op({
+		d: z.object({
+			/** The game message, at most 8 KB of JSON. */
+			data: Json.optional(),
+			/** Address one seat; otherwise the room model decides who hears it. */
+			to: UserId.nullish()
+		}),
+		ack: SeqAck,
+		errors: [
+			"not_in_room",
+			"ended",
+			"too_large",
+			"rate_limited",
+			"bad_target"
+		],
+		doc: "Relay a game message (at most 30 a second)."
+	}),
+	"room.state": op({
+		d: z.object({
+			/** Shallow-merged into the state; a `null` value deletes its key. */
+			patch: RoomState,
+			/** Replace the whole state with `patch`. */
+			replace: z.boolean().optional()
+		}),
+		ack: SeqAck,
+		errors: [
+			"not_in_room",
+			"race_room",
+			"not_host",
+			"bad_patch",
+			"too_large"
+		],
+		invalid: {
+			code: "bad_patch",
+			error: "patch must be an object."
+		},
+		doc: "Update the shared state (host only in the host model), at most 32 KB."
+	}),
+	"room.chat": op({
+		d: ChatSend,
+		ack: ChatLine,
+		errors: [
+			"not_in_room",
+			"room_not_found",
+			...CHAT_ERRORS
+		],
+		doc: "Moderated room chat: free text only when every seated player is a mutual friend."
+	}),
+	"room.kick": op({
+		d: z.object({ userId: UserId }),
+		ack: EmptyAck,
+		errors: [
+			"not_in_room",
+			"not_host",
+			"bad_target"
+		],
+		doc: "Host: remove a player; they can't rejoin this room."
+	}),
+	"room.end": op({
+		d: z.object({ 
+		/** Relayed to everyone in the final `room` event, untrusted; at most 8 KB of JSON. */
+results: Json.optional() }),
+		ack: EmptyAck,
+		errors: [
+			"not_in_room",
+			"not_host",
+			"race_room",
+			"too_large"
+		],
+		doc: "Host: end the match. Players become recent players; the room closes after a delay."
+	}),
+	"room.list": op({
+		d: z.object({
+			game: Slug,
+			mode: GameMode.optional()
+		}),
+		ack: z.object({ rooms: z.array(RoomInfo) }),
+		errors: [],
+		doc: "Public lobbies with a free seat (at most 50), minus rooms with blocked players."
+	})
+};
+//#endregion
+//#region src/realtime/ops/multiplayer.ts
+/** The multiplayer ops, by op name. */
+const multiplayerOps = {
+	...partyOps,
+	...roomOps,
+	...raceOps
+};
+//#endregion
+//#region src/realtime/ops/social.ts
+/**
+* Socket ops for presence, visibility, typing and the heartbeat
+* (multiplayer-impl.md §4.3). `hello` is declared with the snapshot.
+*/
+/**
+* `visibility` input: the tab's document visibility and idle state. Input
+* that isn't an object counts as `{}` (visible, not idle); a field that isn't a
+* boolean takes its default.
+*/
+const VisibilityInput = z.object({
+	/** The document is visible (default `true`). */
+	visible: z.boolean().optional().catch(void 0),
+	/** The player has been idle (default `false`). Hidden or idle tabs count as `away`. */
+	idle: z.boolean().optional().catch(void 0)
+}).catch({});
+/** The social ops, by op name. */
+const socialOps = {
+	presence: op({
+		d: PresenceInput,
+		ack: EmptyAck,
+		errors: ["rate_limited"],
+		doc: "Report this tab's activity. Rate-limited per user; a rejected `detail` is dropped silently."
+	}),
+	visibility: op({
+		d: VisibilityInput,
+		ack: EmptyAck,
+		errors: [],
+		doc: "Report this tab's visibility and idle state (hidden or idle tabs count as `away`)."
+	}),
+	typing: op({
+		d: z.object({ 
+		/**
+		* The friend you're typing to. Anything that isn't a friend's id is a
+		* silent no-op; a value that isn't a user id at all parses as `0` (no one).
+		*/
+to: UserId.catch(0) }),
+		ack: EmptyAck,
+		errors: [],
+		doc: "Tell a friend you are typing (`ev:typing`), at most once per 2 s per pair."
+	}),
+	ping: op({
+		d: NoInput,
+		ack: z.object({ 
+		/** The server clock (epoch ms). */
+t: Millis }),
+		errors: [],
+		doc: "Heartbeat and clock check; allowed before `hello`."
+	})
+};
+//#endregion
+//#region src/realtime/envelope.ts
+/**
+* The legacy `/_ws` envelope (multiplayer-impl.md §4.2), unchanged since v1
+* and kept indefinitely (plan D6):
+*
+* ```
+* client → server  {t:'op',  id, op, d}
+* server → client  {t:'ack', id, ok:true,  d}
+*                  {t:'ack', id, ok:false, err: ErrorBody}
+*                  {t:'ev',  ev, d}
+* ```
+*/
+/** A client's op frame. `id` is the client's own counter, echoed in the ack. */
+const OpFrame = z.object({
+	t: z.literal("op"),
+	id: z.number(),
+	op: z.string(),
+	d: Json.optional()
+});
+/** A successful ack. */
+const OkAckFrame = z.object({
+	t: z.literal("ack"),
+	id: z.number(),
+	ok: z.literal(true),
+	d: Json
+});
+/** A failed ack. */
+const ErrAckFrame = z.object({
+	t: z.literal("ack"),
+	id: z.number(),
+	ok: z.literal(false),
+	err: ErrorBody
+});
+/** An ack frame: the server's answer to one op. */
+const AckFrame = z.discriminatedUnion("ok", [OkAckFrame, ErrAckFrame]);
+/** A server-pushed event frame. */
+const EvFrame = z.object({
+	t: z.literal("ev"),
+	ev: z.string(),
+	d: Json
+});
+/** Any frame the server sends. */
+const ServerFrame = z.union([AckFrame, EvFrame]);
+/** Close codes the client understands. */
+const CloseCode = {
+	/** Service restart: reconnect quietly. */
+	restart: 1012,
+	/** The account is suspended. */
+	suspended: 4003,
+	/** Too many sockets for this user or IP. */
+	tooMany: 4029,
+	/** A frame that wasn't a valid op. */
+	badMessage: 4400
+};
+/**
+* Codes any op can fail with, raised by the envelope rather than the op:
+* the per-socket rate limit, an unknown op name, and ops sent before `hello`.
+*/
+const ENVELOPE_ERRORS = [
+	"rate_limited",
+	"unknown_op",
+	"hello_required"
+];
+/** Ops the server accepts before `hello`. */
+const PRE_HELLO_OPS = ["hello", "ping"];
+//#endregion
+//#region src/realtime/index.ts
+/**
+* The `/_ws` socket contract: the legacy envelope plus every op and event,
+* by name.
+*/
+/** Every socket op, by op name (an intersection type keeps the .d.ts small). */
+const ops = {
+	...helloOps,
+	...socialOps,
+	...multiplayerOps
+};
+/** Every socket event, by event name (an intersection type keeps the .d.ts small). */
+const events = {
+	...socialEvents,
+	...multiplayerEvents
+};
+//#endregion
+//#region src/manifest/changes.ts
+/**
+* `game.changes`: player-facing "What's new" notes (docs/hub.md "What's new").
+*/
+/** The text of one note: plain words for a player, at most 280 characters. */
+const ChangeText = trimmedText(MANIFEST_LIMITS.changeTextMax);
+/**
+* One note: a string (identified by its text, so rewording re-announces it)
+* or `{ id, text }` (identified by `id`, so it can be reworded).
+*/
+const ChangeEntry = z.union([ChangeText, z.strictObject({
+	/** A stable id: letters, digits and `_ . : -`, 1 to 64 characters. */
+	id: Key,
+	/** The note. */
+	text: ChangeText
+})]);
+/**
+* The form a string note is identified by: lowercase, whitespace collapsed,
+* trailing punctuation dropped. Two notes with the same form are duplicates.
+*/
+function normalizeChangeText(text) {
+	return text.toLowerCase().replace(/\s+/g, " ").trim().replace(/[\s.!?…]+$/u, "");
+}
+/** The identity the hub stores a note under. */
+function noteIdentity(note) {
+	return typeof note === "string" ? `h:${normalizeChangeText(note)}` : `id:${note.id}`;
+}
+/** `game.changes`: at most 200 notes, no duplicates. Newest last. */
+const GameChanges = z.array(ChangeEntry).max(MANIFEST_LIMITS.changesMax).superRefine((notes, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	notes.forEach((note, i) => {
+		const id = noteIdentity(note);
+		if (seen.has(id)) ctx.addIssue({
+			code: "custom",
+			message: "duplicate note (same id, or the same text ignoring case and trailing punctuation)",
+			path: [i]
+		});
+		seen.add(id);
+	});
+});
+//#endregion
+//#region src/manifest/controls.ts
+/**
+* `game.controls`: the gamepad-to-keyboard map zero-config games use, so a
+* controller or arcade stick works in a game that never calls
+* `hub.input.define()` (docs/hub.md "Mapping controls per game").
+*/
+/** A `KeyboardEvent.code`, such as `ArrowUp`, `Space`, `KeyZ` or `ShiftLeft`. */
+const KeyCode = z.string().regex(/^[A-Za-z0-9]{1,32}$/, "must be a KeyboardEvent.code such as ArrowUp, Space or KeyZ");
+/** A standard-gamepad button index, `"0"` to `"19"`. */
+const ButtonIndex = z.string().regex(/^(?:1?[0-9])$/, "must be a gamepad button index 0-19");
+/** One player's map. Unset directions and buttons keep the defaults. */
+const ControlMap = z.strictObject({
+	/** Key pressed for stick/d-pad up. Default `ArrowUp`. */
+	up: KeyCode.optional(),
+	/** Key pressed for stick/d-pad down. Default `ArrowDown`. */
+	down: KeyCode.optional(),
+	/** Key pressed for stick/d-pad left. Default `ArrowLeft`. */
+	left: KeyCode.optional(),
+	/** Key pressed for stick/d-pad right. Default `ArrowRight`. */
+	right: KeyCode.optional(),
+	/**
+	* Button index → key. Defaults: `0` Space, `1` Enter, `2` KeyZ, `3` KeyX,
+	* `8` Escape, `9` Enter.
+	*/
+	buttons: z.record(ButtonIndex, KeyCode).optional()
+});
+/** `game.controls`: one map for every pad, or one per player in `players`. */
+const GameControls = ControlMap.extend({ 
+/** Per-player maps, by gamepad order; pads past the end use the first. Overrides the shared map. */
+players: z.array(ControlMap).min(1).max(SEAT_LIMITS.maxSeats).optional() });
+//#endregion
+//#region src/manifest/leaderboards.ts
+/**
+* `game.leaderboards`: boards declared up front, so they show on the catalog
+* before the first score.
+*/
+/** One declared leaderboard. */
+const LeaderboardDecl = z.strictObject({
+	/** The board key `hub.submitScore(key, score)` uses: letters, digits and `_ . : -`, 1 to 64. */
+	key: Key,
+	/** What players see, at most 80 characters. Defaults to the key. */
+	title: Trimmed.max(MANIFEST_LIMITS.leaderboardTitleMax).optional(),
+	/** Which scores rank first. Default `desc`. */
+	sort: SortDir.default("desc"),
+	/** List players whose best is 0. Default `false`. */
+	showZeros: z.boolean().optional(),
+	/**
+	* `server`: only the game's own server may submit (trusted multiplayer
+	* results); the client endpoint refuses. Default `client`.
+	*/
+	source: z.enum(["client", "server"]).default("client")
+});
+/** `game.leaderboards`: unique keys. */
+const GameLeaderboardDecls = z.array(LeaderboardDecl).refine(hasUniqueKeys, "leaderboard keys must be unique");
+//#endregion
+//#region src/manifest/multiplayer.ts
+/**
+* `game.multiplayer`: the opt-in that makes a game an online invite/join
+* target (docs/multiplayer.md §7).
+*/
+/**
+* How players connect: `hub-rooms` (the hub relays room messages) or
+* `own-server` (a process app runs its own game server; process apps only).
+*/
+const Transport = z.enum(["hub-rooms", "own-server"]);
+/** A mode key: letters, digits, `_` or `-`, 1 to 32 characters. */
+const ModeKey = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, "must be 1-32 letters, digits, _ or -");
+/** A game mode players can be invited into. */
+const MultiplayerMode = z.strictObject({
+	/** Sent with invites and launches as `mode`. */
+	key: ModeKey,
+	/** What players see. Defaults to the key. */
+	title: trimmedText(MANIFEST_LIMITS.modeTitleMax).optional(),
+	/** `[min, max]` players for this mode, within 1..8. Defaults to the game's. */
+	players: playerRange(1).optional()
+});
+/**
+* A soften-list word this game's chat may keep (e.g. `shot` for a pool game):
+* one lowercase word of 2 to 20 letters. Reject-list words never pass.
+*/
+const ChatAllowWord = z.string().trim().toLowerCase().regex(/^[a-z]{2,20}$/, "must be a single word of 2-20 letters");
+/** The `game.multiplayer` block. */
+const GameMultiplayer = z.strictObject({
+	/** URL suffix invites and Join open, relative to `/<slug>/`. Default `''` (the game's root). */
+	lobby: LobbySuffix.default(""),
+	/** `[min, max]` players, within 1..8. Default `[2, 8]`. */
+	players: playerRange(1).default([2, 8]),
+	/**
+	* `hub-rooms` or `own-server`. Default: `own-server` for process apps,
+	* `hub-rooms` for static apps (which cannot use `own-server`).
+	*/
+	transport: Transport.optional(),
+	/** Friends can invite each other into this game. Default `true`. */
+	invites: z.boolean().default(true),
+	/** Friends can join a game in progress. Default `true`. */
+	join: z.boolean().default(true),
+	/** Friends can watch. Default `false`. */
+	spectate: z.boolean().default(false),
+	/** Offer quick match. Default `false`. */
+	quickMatch: z.boolean().default(false),
+	/** Modes players can be invited into (at most 16, unique keys). */
+	modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, "mode keys must be unique").default([]),
+	/**
+	* Extra quick-chat phrases for this game (at most 24, each at most 40
+	* characters). Checked by the content filter at boot; failing ones are dropped.
+	*/
+	quickChat: z.array(trimmedText(MANIFEST_LIMITS.quickChatTextMax)).max(MANIFEST_LIMITS.quickChatMax).default([]),
+	/** Soften-list words this game's chat may keep (at most 20). */
+	chatAllow: z.array(ChatAllowWord).max(MANIFEST_LIMITS.chatAllowMax).default([])
+});
+/** `game.multiplayer` for a static app: `own-server` needs a process app. */
+const StaticGameMultiplayer = GameMultiplayer.refine((multiplayer) => multiplayer.transport !== "own-server", {
+	message: "own-server needs a process app; static apps use hub-rooms",
+	path: ["transport"]
+});
+//#endregion
+//#region src/manifest/game.ts
+/**
+* The `game` block of an app's `package.json`: how the host builds, serves
+* and shows the game (HANDOFF.md "The game block").
+*
+* This is the **strict** authoring schema `hub-doctor` runs in a game: a
+* mistake fails the parse. The host stays lenient at boot (a bad field falls
+* back to its default with a warning), so one typo never takes a game down.
+*/
+/** The corner the injected hub menu button sits in. Default `top-left`. */
+const MenuPosition = z.enum([
+	"top-left",
+	"top-right",
+	"bottom-left",
+	"bottom-right"
+]);
+/** Pixels to push the menu button away from its corner, 0 to 600. */
+const OffsetPx = z.number().int().min(0).max(MANIFEST_LIMITS.menuOffsetMax);
+/** The menu offset as the host sends it: both axes, in px. */
+const MenuOffsetXY = z.strictObject({
+	/** Inward from the left or right edge, px. */
+	x: OffsetPx,
+	/** Down from a top corner or up from a bottom one, px. */
+	y: OffsetPx
+});
+/**
+* `game.menuOffset`: how far to push the menu button away from its corner so
+* it clears the game's own bars. A number moves it vertically only.
+*/
+const MenuOffset = z.union([OffsetPx, MenuOffsetXY.partial()]);
+/** Fields both app types share. */
+const commonFields = {
+	/** Shown on the catalog card and in the menu. */
+	title: Trimmed,
+	/** Catalog, search and link-preview text. Falls back to `package.json` `description`. */
+	description: Trimmed.optional(),
+	/**
+	* Credit shown on the tile, e.g. `"Mason & Phil"` (split into authors for the
+	* catalog filter). Falls back to `package.json` `author`.
+	*/
+	author: z.string().trim().min(1).optional(),
+	/** Runs at boot when the source changed. May use `{{PORT}}`, `{{GAME_PATH}}`, `{{GAME_SLUG}}`. */
+	build: Command.optional(),
+	/** Tile and preview image, relative to the project root (not `serveDir`); must stay inside it. */
+	image: AppFilePath.optional(),
+	/** `true` leaves the app out of the catalog entirely. */
+	hidden: z.boolean().optional(),
+	/** `false` opts out of the injected hub menu and SDK. */
+	hub: z.boolean().optional(),
+	/** `false` opts out of the PWA install tags and service worker. */
+	pwa: z.boolean().optional(),
+	/** The corner the hub menu button sits in. Default `top-left`. */
+	menuPosition: MenuPosition.optional(),
+	/** Push the menu button away from its corner, px: a number (vertical) or `{ x, y }`. */
+	menuOffset: MenuOffset.optional(),
+	/** `true` opts into the shared daily challenges (`hub.daily.define(...)`). */
+	dailyChallenges: z.boolean().optional(),
+	/** Boards to create up front, so they show before the first score. */
+	leaderboards: GameLeaderboardDecls.optional(),
+	/** The gamepad-to-keyboard map for games that never call `hub.input.define()`. */
+	controls: GameControls.optional(),
+	/** Turns a single-player game into a race target; `true` for all defaults, `false` for off. */
+	race: GameRace,
+	/** Player-facing "What's new" notes, one per change, newest last. Keep it updated. */
+	changes: GameChanges.optional()
+};
+/** A static app: the build emits a folder the host serves. */
+const StaticGame = z.strictObject({
+	/** `static`: no running process. */
+	type: z.literal("static"),
+	/** The folder served at `/<slug>/`; must exist after `build`. */
+	serveDir: Trimmed,
+	/** Makes the game an online invite/join target (`hub-rooms` only); `false` for off. */
+	multiplayer: orFalse(StaticGameMultiplayer),
+	...commonFields
+});
+/** A process app: the host runs a long-lived server and proxies to it. */
+const ProcessGame = z.strictObject({
+	/** `process`: the host starts `start` and proxies `/<slug>/` to it. */
+	type: z.literal("process"),
+	/** The long-lived server command; must listen on the assigned port (`{{PORT}}` or `PORT`). */
+	start: Command,
+	/** The path the host polls until it answers below 500. Default `/`. */
+	healthPath: Trimmed.startsWith("/").optional(),
+	/** Makes the game an online invite/join target; `false` for off. */
+	multiplayer: orFalse(GameMultiplayer),
+	...commonFields
+});
+/** The `game` block of a game's `package.json`. */
+const GameManifest = z.discriminatedUnion("type", [StaticGame, ProcessGame]);
+/** A game's `package.json`: the `game` block plus the npm fields the host falls back to. */
+const GamePackageJson = z.looseObject({
+	/** The npm name; the title fallback. */
+	name: z.string().optional(),
+	/** The description fallback. */
+	description: z.string().optional(),
+	/** The author fallback: npm's string or `{ name }` form. */
+	author: z.union([z.string(), z.looseObject({ name: z.string().optional() })]).optional(),
+	/** How the host treats the app. */
+	game: GameManifest
+});
+/**
+* The host repo's own `game` block: only its "What's new" notes (shown as
+* "diffenderfer.games"). It is not an app, so it has no `type`.
+*/
+const HostManifest = z.strictObject({
+	/** The host's display name. */
+	title: Trimmed.optional(),
+	/** The host's own notes (menu, friends, home page). */
+	changes: GameChanges.optional()
+});
+//#endregion
+//#region src/manifest/inject.ts
+/**
+* `window.__HUB__`: the small config object the host writes into every page
+* it injects (game pages, and the catalog page). The SDK and the menu read it
+* to find the game's slug, the API base and the menu placement.
+*
+* The same inline script may also set `window.__hubDailyDeep` (a
+* `?daily=YYYY-MM-DD` deep link captured before game code runs) and
+* `window.__hubInstall` (the PWA install prompt); those are not part of this
+* object.
+*/
+/** The injected `window.__HUB__` config. */
+const HubInject = z.strictObject({
+	/** The game's slug. Missing on the catalog page. */
+	slug: Slug.optional(),
+	/** Where the REST API lives. Always `/_api` today. */
+	apiBase: z.literal("/_api"),
+	/** The menu button's corner (from `game.menuPosition`). Missing on the catalog page. */
+	menu: MenuPosition.optional(),
+	/** The menu button's offset from its corner (from `game.menuOffset`); only sent when not 0,0. */
+	menuOffset: MenuOffsetXY.optional(),
+	/** The game's `game.controls`, as written; only sent when set. */
+	controls: GameControls.optional()
+});
+//#endregion
+//#region src/logic/daily.ts
+/**
+* Daily-challenge day keys and seeds: UTC `YYYY-MM-DD` keys, the playable
+* window, and the deterministic per-(game, day) seed both the hub and the
+* game compute. Pure; the signed tokens stay server-only.
+*/
+const DAY_MS = 864e5;
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** The UTC day key (`YYYY-MM-DD`) of a timestamp. */
+function dayKey(ts) {
+	return new Date(ts).toISOString().slice(0, 10);
+}
+/**
+* The playable window, newest first: today and the `count - 1` days before it.
+* @param count - how many days (the back-fill window, 30 by default on the hub)
+*/
+function windowDays(now, count) {
+	return Array.from({ length: count }, (_, i) => dayKey(now - i * DAY_MS));
+}
+/**
+* Is `day` playable? A player's local "today" can be UTC±1, so one day into
+* the future is accepted, plus `backfillDays` into the past. Compared in
+* whole UTC days, so it is locale-independent.
+*/
+function inWindow(day, now, backfillDays) {
+	if (!DAY_RE.test(day)) return false;
+	const dayStart = Date.parse(`${day}T00:00:00Z`);
+	const today = Date.parse(`${dayKey(now)}T00:00:00Z`);
+	if (Number.isNaN(dayStart) || Number.isNaN(today)) return false;
+	const diff = Math.round((dayStart - today) / DAY_MS);
+	return diff <= 1 && diff >= -backfillDays;
+}
+/**
+* The deterministic uint32 seed for a (game, day): FNV-1a over `game#day`.
+* The game derives its level or difficulty from it, so everyone plays the
+* same challenge.
+*/
+function seedForDay(game, day) {
+	let hash = 2166136261;
+	const seedInput = `${game}#${day}`;
+	for (let i = 0; i < seedInput.length; i++) {
+		hash ^= seedInput.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+//#endregion
+//#region src/logic/time.ts
+/**
+* Time and count wording shared by every hub UI (the social drawer, the menu,
+* the home page, race cards). One copy, so "3h ago" reads the same everywhere
+* (plan §8.4: the menu and the catalog page each had their own).
+*/
+const padTwoDigits = (count) => String(count).padStart(2, "0");
+/**
+* `m:ss` (or `h:mm:ss`) elapsed since `since`.
+* @example elapsed(0, 252_000) // "4:12"
+*/
+function elapsed(since, now) {
+	const total = Math.max(0, Math.floor((now - since) / 1e3));
+	const hours = Math.floor(total / 3600);
+	const minutes = Math.floor(total % 3600 / 60);
+	const paddedSeconds = padTwoDigits(total % 60);
+	return hours ? `${String(hours)}:${padTwoDigits(minutes)}:${paddedSeconds}` : `${String(minutes)}:${paddedSeconds}`;
+}
+/**
+* "just now", "5m ago", "3h ago", "2d ago", then a short date (in the
+* viewer's locale) after a week.
+*/
+function relativeTime(then, now) {
+	const seconds = Math.max(0, Math.floor((now - then) / 1e3));
+	if (seconds < 60) return "just now";
+	if (seconds < 3600) return `${String(Math.floor(seconds / 60))}m ago`;
+	if (seconds < 86400) return `${String(Math.floor(seconds / 3600))}h ago`;
+	if (seconds < 604800) return `${String(Math.floor(seconds / 86400))}d ago`;
+	return new Date(then).toLocaleDateString(void 0, {
+		month: "short",
+		day: "numeric"
+	});
+}
+/**
+* A seconds countdown for mutes and rate limits: "42s" or "3:05".
+* @param ms - time left, in ms
+*/
+function countdown(ms) {
+	const seconds = Math.max(0, Math.ceil(ms / 1e3));
+	return seconds < 60 ? `${String(seconds)}s` : `${String(Math.floor(seconds / 60))}:${padTwoDigits(seconds % 60)}`;
+}
+/** Badge text: `''` for 0, the number up to 9, then `'9+'`. */
+function badgeText(count) {
+	if (count <= 0) return "";
+	return count > 9 ? "9+" : String(count);
+}
+/**
+* When a suspension or mute ends, for the "can't use online play" notice.
+* `''` when there is no end (0, or a permanent suspension far in the future).
+*/
+function untilText(until) {
+	if (!until || until > 8e15) return "";
+	return new Date(until).toLocaleString(void 0, {
+		month: "short",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit"
+	});
+}
+/**
+* A race clock: `83_400` → `"1:23.4"`; past an hour `"1:02:03"`.
+* @param ms - elapsed race time, in ms
+*/
+function raceClock(ms) {
+	const tenths = Math.max(0, Math.floor(ms / 100));
+	const seconds = Math.floor(tenths / 10);
+	const hours = Math.floor(seconds / 3600);
+	const minutes = Math.floor(seconds % 3600 / 60);
+	const paddedSeconds = padTwoDigits(seconds % 60);
+	return hours ? `${String(hours)}:${padTwoDigits(minutes)}:${paddedSeconds}` : `${String(minutes)}:${paddedSeconds}.${String(tenths % 10)}`;
+}
+//#endregion
+//#region src/logic/presence.ts
+/** Status line pieces for a friend; `p` is `null` when they are offline. */
+function statusParts(presence, now, lastSeenAt = 0) {
+	const base = {
+		game: "",
+		detail: "",
+		elapsed: "",
+		online: true,
+		joinable: false,
+		watchable: false
+	};
+	if (!presence) return {
+		...base,
+		online: false,
+		dot: "⚪",
+		label: lastSeenAt ? `Last seen ${relativeTime(lastSeenAt, now)}` : "Offline"
+	};
+	const game = presence.gameTitle ?? "";
+	const detail = presence.detail ?? "";
+	const hasRoom = presence.room !== void 0 && presence.room !== "";
+	const flags = {
+		joinable: presence.joinable === true && hasRoom,
+		watchable: presence.watchable === true && hasRoom
+	};
+	switch (presence.kind) {
+		case "playing": return {
+			...base,
+			...flags,
+			dot: "🟢",
+			label: "Playing",
+			game,
+			detail,
+			elapsed: elapsed(presence.since, now)
+		};
+		case "watching": return {
+			...base,
+			...flags,
+			dot: "🟢",
+			label: "Watching",
+			game,
+			detail
+		};
+		case "lobby": return {
+			...base,
+			...flags,
+			dot: "🟠",
+			label: "In lobby",
+			game,
+			detail
+		};
+		case "away": return {
+			...base,
+			dot: "🟡",
+			label: "Away",
+			game
+		};
+		case "menu": return {
+			...base,
+			dot: "🟢",
+			label: "Online",
+			game
+		};
+	}
+}
+/** The status line as one string, e.g. "🟢 Playing 8 Ball Pool · Table vs Sam · 4:12". */
+function statusText(parts) {
+	const head = parts.label === "Playing" || parts.label === "Watching" ? [parts.game ? `${parts.label} ${parts.game}` : parts.label] : [parts.label, parts.game];
+	return `${parts.dot} ${[
+		...head,
+		parts.detail,
+		parts.elapsed
+	].filter(Boolean).join(" · ")}`;
+}
+/** The drawer header: "👥 3 friends online · 41 playing now". */
+function headerLine(friendsOnline, online) {
+	return `👥 ${String(friendsOnline)} friend${friendsOnline === 1 ? "" : "s"} online · ${String(online)} playing now`;
+}
+//#endregion
+//#region src/logic/race.ts
+/** A stat value for display, per its declared format. Unknown or absent values show as `'–'`. */
+function formatStat(value, format) {
+	if (value === void 0) return "–";
+	switch (format) {
+		case "percent": return typeof value === "number" ? `${String(Math.round(Math.max(0, Math.min(1, value)) * 100))}%` : "–";
+		case "time": return typeof value === "number" ? raceClock(value) : "–";
+		case "bool": return typeof value === "boolean" ? value ? "✓" : "✗" : "–";
+		case "color": return typeof value === "string" ? "●" : "–";
+		case "int":
+			if (typeof value === "number") return String(Math.round(value));
+			return typeof value === "boolean" ? value ? "✓" : "✗" : "–";
+	}
+}
+/** The declared stats with their values (the HUD shows at most `max`). */
+function shownStats(spec, stats, max = 3) {
+	return spec ? spec.stats.slice(0, max).map((s) => ({
+		spec: s,
+		value: stats[s.key]
+	})) : [];
+}
+/** "Board 4x4 · Level Hard" from the manifest's option titles; unknown values are skipped. */
+function paramsText(spec, params) {
+	if (!spec) return "";
+	const parts = [];
+	for (const param of spec.params) {
+		const matchingOption = param.options.find((option) => option.value === params[param.key]);
+		if (matchingOption) parts.push(param.title === matchingOption.title ? matchingOption.title : `${param.title} ${matchingOption.title}`);
+	}
+	return parts.join(" · ");
+}
+/** A racer's live state as a short tag (`''` while racing and connected). */
+function racerStateTag(state, isConnected) {
+	switch (state) {
+		case "finished": return "🏁 Finished";
+		case "lost": return "Out";
+		case "forfeit": return "Gave up";
+		case "disconnected": return "Dropped out";
+		case "racing": return isConnected ? "" : "Reconnecting…";
+	}
+}
+const RESULT_LABEL = {
+	won: "🏆 Won",
+	beaten: "Didn't finish",
+	lost: "Out",
+	forfeit: "Gave up",
+	disconnected: "Dropped out",
+	timeout: "Time's up"
+};
+/** A racer's line in the result card and history. */
+function resultLabel(racerResult) {
+	return RESULT_LABEL[racerResult];
+}
+/** The result card's title from my point of view (`me` is `null` when watching). */
+function resultTitle(result, me) {
+	const winner = result.players.find((player) => player.userId === result.winnerId);
+	if (!winner) return "Time's up!";
+	return winner.userId === me ? "You won! 🏆" : `${winner.name} won`;
+}
+/** Names joined for a sentence: "Sam", "Sam and Ali", "Sam, Ali and Jo". */
+function nameList(names) {
+	const last = names.at(-1);
+	if (names.length <= 1 || last === void 0) return names[0] ?? "Everyone";
+	return `${names.slice(0, -1).join(", ")} and ${last}`;
+}
+/** How the race ended, in one friendly sentence, from my point of view. */
+function outcomeLine(result, me) {
+	const winner = result.players.find((player) => player.userId === result.winnerId);
+	if (!winner) return "Nobody finished before the time ran out.";
+	const mine = result.players.find((player) => player.userId === me);
+	const others = result.players.filter((player) => player.userId !== result.winnerId);
+	const namesWithOutcome = (outcome) => others.filter((player) => player.result === outcome).map((player) => player.name);
+	const didIWin = winner.userId === me;
+	if (result.outcome === "finished") return `${didIWin ? "You" : winner.name} finished first in ${raceClock(winner.ms)}.`;
+	if (mine && !didIWin) {
+		if (mine.result === "forfeit") return "You gave up.";
+		if (mine.result === "lost") return "You're out — better luck next race!";
+		if (mine.result === "disconnected") return "Your connection dropped.";
+	}
+	const lost = namesWithOutcome("lost");
+	const gaveUp = namesWithOutcome("forfeit");
+	const dropped = namesWithOutcome("disconnected");
+	const bits = [];
+	if (gaveUp.length > 0) bits.push(`${nameList(gaveUp)} gave up`);
+	if (lost.length > 0) bits.push(`${nameList(lost)} ${lost.length === 1 ? "is" : "are"} out`);
+	if (dropped.length > 0) bits.push(`${nameList(dropped)} dropped out`);
+	const why = bits.length > 0 ? bits.join(", ") : "Everyone else is out";
+	return `${why.charAt(0).toUpperCase()}${why.slice(1)} — ${didIWin ? "you win" : `${winner.name} wins`}!`;
+}
+const HISTORY_VERB = {
+	won: "Won",
+	beaten: "Lost",
+	lost: "Out",
+	forfeit: "Gave up",
+	disconnected: "Dropped out",
+	timeout: "Time's up"
+};
+/** My race's headline verb in the history ("Won vs Sam", "Lost vs Sam"). */
+function historyVerb(racerResult) {
+	return HISTORY_VERB[racerResult];
+}
+/** True when a racer's time means something (they finished or dropped out themselves). */
+function hasOwnTime(racerResult) {
+	return racerResult !== "beaten" && racerResult !== "timeout";
+}
+/** The history badge for my result. */
+function historyBadge(racerResult) {
+	switch (racerResult) {
+		case "won": return "🏆";
+		case "forfeit": return "🏳️";
+		case "disconnected": return "📶";
+		case "timeout": return "⏱️";
+		default: return "🏁";
+	}
+}
+//#endregion
+export { ACCOUNT_LIMITS, AckFrame, AppFilePath, Audience, AuthResult, AuthUser, Board, Bundle, BundleInput, ButtonIndex, CHAT_ERRORS, COMMAND_PLACEHOLDERS, ChangeEntry, ChangeNote, ChangeText, ChatAllowWord, ChatLine, ChatLineEvent, ChatMode, ChatSend, CloseCode, Command, ContentRejected, ControlMap, Conversation, Counts, Credentials, DailyCompletion, DailyCompletions, DayKey, ENVELOPE_ERRORS, ErrAckFrame, ErrorBody, ErrorCode, EvFrame, FriendChange, FriendEntry, FriendRequestInput, FriendRequestStatus, FriendRequests, FriendsList, GameChanges, GameControls, GameInfo, GameLeaderboardDecls, GameLeaderboards, GameManifest, GameMode, GameMultiplayer, GamePackageJson, GameRace, GameRecords, GameSnapshot, GameTicket, HexColor, HostManifest, HubInject, HubVersion, IdParam, Inventory, Invite, InviteCreated, InviteStatus, JoinInfo, Json, Key, KeyCode, Launch, LaunchKind, LaunchTicket, LeaderboardDecl, LeaderboardEntry, LobbySuffix, MANIFEST_LIMITS, MAX_BUNDLE_ITEMS, MAX_ITEM_QTY, MenuOffset, MenuOffsetXY, MenuPosition, Message, MessageId, MessagesPage, Metrics, Millis, ModeKey, MultiplayerMode, MultiplayerSnapshot, MultiplayerSummary, NotifyChange, NotifyPrefKind, NotifyPrefs, Ok, OkAckFrame, OpFrame, OpaqueId, PRE_HELLO_OPS, Party, PlayerCard, PlayerLite, PlayerRange, Presence, PresenceInput, PresenceKind, PresenceMode, PresenceRoom, ProcessGame, Profile, PushSubscriptionJson, QuickId, RACE_STATS_LIMITS, RaceBlock, RaceHistory, RaceHistoryQuery, RaceKey, RaceOption, RaceOutcome, RaceParam, RaceParamValue, RaceParams, RacePhase, RaceProgress, RaceRecord, RaceRecordPlayer, RaceResult, RaceResultPlayer, RaceStart, RaceStat, RaceStatFormat, RaceStatValue, RaceState, RaceStats, RaceSummary, Racer, RacerResult, RacerState, Rank, RecentPlayer, RejectReason, Relation, ReportInput, ReportKind, ReportReason, ReportSnapshot, ReportedMessage, Role, RoomClosedReason, RoomCode, RoomInfo, RoomMessage, RoomModel, RoomPhase, RoomSeat, RoomState, RoomTarget, SEAT_LIMITS, Save, SaveMeta, SeatGoneReason, SendMessageInput, ServerFrame, SessionUser, Slug, SocialConfig, SocialLimits, SocialMe, SocialMeResult, SortDir, StatMode, StaticGame, StaticGameMultiplayer, Stats, Suggestion, SuggestionId, SuggestionStatus, TopQuery, TradeOffer, TradePlayer, TradeStatus, Transport, UI_LIMIT_DEFAULTS, UNSUPPORTED_SUBSCRIPTION, USERNAME_PATTERN, UiLimits, UnreadSummary, UserId, UserIdParam, VersionRange, VoteResult, analyticsEndpoints, authEndpoints, badgeText, bundleInput, catalogEndpoints, countdown, dailyEndpoints, dayKey, economyEndpoints, elapsed, event, events, formatStat, game, hasOwnTime, headerLine, historyBadge, historyVerb, inWindow, leaderboardsEndpoints, messagesEndpoints, mpEndpoints, nameList, normalizeChangeText, notifyEndpoints, op, ops, outcomeLine, paramsText, progressEndpoints, publicApi, publicEndpoints, raceClock, raceEndpoints, racerStateTag, relativeTime, reportsEndpoints, requireActive, requireClaimed, requireTrader, requireUser, resultLabel, resultTitle, seedForDay, session, shownStats, socialEndpoints, statusParts, statusText, untilText, versionEndpoints, windowDays };
+
+//# sourceMappingURL=index.js.map