@diffenderfer-games/hub 2.0.0-next.7 → 2.0.0-next.8

package/dist/turns.js

@@ -1,5 +1,6 @@
 import { c as parseJsonText } from "./shared/json-guards.js";
-import { createTurnRng, createTurnRng as createTurnRng$1, defineTurnRules, turnRngStateFromSeed, turnRngStateFromSeed as turnRngStateFromSeed$1 } from "@diffenderfer-games/hub-contract";
+import { createTurnRng, defineTurnRules, turnRngStateFromSeed } from "./turns-rules.js";
+import { createTurnRng as createTurnRng$1, turnRngStateFromSeed as turnRngStateFromSeed$1 } from "@diffenderfer-games/hub-contract/turns-rules";
 //#region src/turns-kit/check-rules.ts
 /**
 * The rules conformance kit (docs/multiplayer.md "Turn games: testing"):
@@ -7,12 +8,18 @@ import { createTurnRng, createTurnRng as createTurnRng$1, defineTurnRules, turnR
 * module the way the hub does and throws on the first broken promise:
 *
 * - every game reaches an outcome within `maxMoves`, and `toAct` is never
-*   empty before it;
+*   empty before it; every seat in `toAct` gets to move (not only the
+*   first), and so do the seats in `mayAct` (out of turn: a jump-in, a
+*   catch) whose `autoReact` (or `options.reactMove`) has a move;
+* - `toAct` and `mayAct` only name seats that exist;
 * - the state survives a JSON round trip after every move, and the same seed
 *   plays the same game (no `Math.random`, no hidden globals);
-* - `autoMove` (when the rules have it) is always legal;
+* - `autoMove` and `autoReact` (when the rules have them) are always legal;
 * - no seat's `view` or `eventView` shows another seat's secrets: markers
-*   planted with `options.plant` never appear in anyone else's view;
+*   planted with `options.plant` never appear in anyone else's view until
+*   the rules reveal them (`options.revealed`: a card played face up);
+* - with `options.shuffleHidden` (the "twin table"): shuffling everything a
+*   seat may not see never changes that seat's view;
 * - stored fixtures from older versions `migrate` to a state that views;
 * - views, events and moves stay within the hub's size caps.
 *
@@ -45,43 +52,99 @@ function pickMove(rules, options, state, seat, rng) {
 	if (rules.autoMove === void 0) return fail("the rules have no autoMove: pass options.randomMove");
 	return rules.autoMove(state, seat, rng);
 }
+/** An out-of-turn move for `seat`: the check's own chooser, else the rules' autoReact, else none. */
+function pickReaction(rules, options, state, seat, rng) {
+	if (options.reactMove !== void 0) return options.reactMove(state, seat, rng);
+	return rules.autoReact?.(state, seat, rng) ?? null;
+}
+/** Fail unless every seat in `list` exists. */
+function checkSeats(list, seats, what, seed) {
+	if (list.some((seat) => !Number.isInteger(seat) || seat < 0 || seat >= seats)) fail(`${what} named a seat that doesn't exist: [${list.join(", ")}] (seed ${String(seed)})`);
+}
+/**
+* The next move of a game: half the time a seat in `mayAct` that has an
+* out-of-turn move, else a seat in `toAct` (any of them, not only the
+* first). The kit's own `pick` RNG chooses, so the game's RNG sees only
+* the rules' own draws.
+*/
+function nextMove(rules, options, state, toAct, rng, pick) {
+	const optional = (rules.mayAct?.(state) ?? []).filter((seat) => !toAct.includes(seat));
+	if (optional.length > 0 && pick.int(2) === 0) {
+		const seat = pick.pick(optional);
+		const move = pickReaction(rules, options, state, seat, rng);
+		if (move !== null) return {
+			seat,
+			move,
+			by: options.reactMove === void 0 ? "autoReact" : "reactMove"
+		};
+	}
+	const seat = toAct.length === 0 ? void 0 : pick.pick(toAct);
+	return seat === void 0 ? null : {
+		seat,
+		move: pickMove(rules, options, state, seat, rng),
+		by: options.randomMove === void 0 ? "autoMove" : "randomMove"
+	};
+}
 /** Play one seeded game; answers its moves and a trace for the determinism check. */
 function playGame(rules, seats, seed, options) {
 	const rng = createTurnRng$1(turnRngStateFromSeed$1(seed));
+	const pick = createTurnRng$1(turnRngStateFromSeed$1(seed ^ 1540483477));
+	const twinRng = createTurnRng$1(turnRngStateFromSeed$1(seed ^ 668265263));
 	const marker = `MARKER-${String(seed)}-`;
+	const markerOf = (owner) => `${marker}${String(owner)}`;
 	let state = rules.setup({
 		seats,
 		options: options.setupOptions ?? null,
 		mode: options.mode ?? null,
 		rng
 	});
-	if (options.plant !== void 0) for (let seat = 0; seat < seats; seat++) state = options.plant(state, seat, `${marker}${String(seat)}`);
+	if (options.plant !== void 0) for (let seat = 0; seat < seats; seat++) state = options.plant(state, seat, markerOf(seat));
 	const maxMoves = options.maxMoves ?? 2e3;
 	const trace = [];
+	let outOfTurn = 0;
+	/** The twin table: each seat's view is the same after what it can't see is shuffled. */
+	const checkTwin = () => {
+		if (options.shuffleHidden === void 0) return;
+		for (let viewer = 0; viewer < seats; viewer++) {
+			const real = JSON.stringify(rules.view(state, viewer));
+			if (JSON.stringify(rules.view(roundTrip(options.shuffleHidden(roundTrip(state), viewer, twinRng)), viewer)) !== real) fail(`seat ${String(viewer)}'s view changed when what it can't see was shuffled: it shows something hidden (seed ${String(seed)})`);
+		}
+	};
+	/** The seats whose planted marker is still secret (the rules haven't revealed it). */
+	const secret = new Set(options.plant === void 0 ? [] : Array.from({ length: seats }, (_, seat) => seat));
 	const checkViews = (events) => {
+		for (const owner of secret) if (options.revealed?.(state, markerOf(owner)) === true) secret.delete(owner);
 		for (let viewer = 0; viewer < seats; viewer++) {
 			const seen = JSON.stringify(rules.view(state, viewer)) + JSON.stringify(events.map((event) => rules.eventView?.(event, viewer) ?? null));
-			for (let owner = 0; owner < seats; owner++) if (owner !== viewer && options.plant !== void 0 && seen.includes(`${marker}${String(owner)}`)) fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+			for (const owner of secret) if (owner !== viewer && seen.includes(markerOf(owner))) fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
 		}
-		if (options.plant !== void 0 && JSON.stringify(rules.view(state, null)).includes(marker)) fail(`the public view shows a seat's secret (seed ${String(seed)})`);
+		const shown = JSON.stringify(rules.view(state, null));
+		for (const owner of secret) if (shown.includes(markerOf(owner))) fail(`the public view shows seat ${String(owner)}'s secret (seed ${String(seed)})`);
+		checkTwin();
 	};
 	checkViews([]);
 	for (let moves = 0; moves < maxMoves; moves++) {
 		if (rules.outcome(state) !== null) return {
 			moves,
+			outOfTurn,
 			trace: trace.join("|")
 		};
-		const seat = rules.toAct(state)[0];
-		if (seat === void 0) fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
-		const move = pickMove(rules, options, state, seat, rng);
+		const toAct = rules.toAct(state);
+		checkSeats(toAct, seats, "toAct", seed);
+		checkSeats(rules.mayAct?.(state) ?? [], seats, "mayAct", seed);
+		if (toAct.length === 0) fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+		const next = nextMove(rules, options, state, toAct, rng, pick);
+		if (next === null) return fail(`no seat could move (seed ${String(seed)}, move ${String(moves)})`);
+		const { seat, move } = next;
+		outOfTurn += toAct.includes(seat) ? 0 : 1;
 		if (bytesOf(JSON.stringify(move)) > MOVE_MAX_BYTES) fail(`a move is over ${String(MOVE_MAX_BYTES)} bytes`);
 		const result = rules.apply(roundTrip(state), seat, roundTrip(move), rng);
-		if ("error" in result) fail(`${options.randomMove === void 0 ? "autoMove" : "randomMove"} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+		if ("error" in result) fail(`${next.by} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
 		state = roundTrip(result.state);
 		if (bytesOf(JSON.stringify(state)) > STATE_MAX_BYTES) fail(`the state is over ${String(STATE_MAX_BYTES)} bytes`);
 		checkViews(result.events ?? []);
 		rules.progress(state, seat);
-		trace.push(JSON.stringify(move));
+		trace.push(`${String(seat)}:${JSON.stringify(move)}`);
 	}
 	return fail(`a game did not end within ${String(maxMoves)} moves (seed ${String(seed)})`);
 }
@@ -91,6 +154,7 @@ function checkTurnRules(rules, options = {}) {
 	let games = 0;
 	let moves = 0;
 	let longestGame = 0;
+	let outOfTurn = 0;
 	for (const seats of options.seats ?? [2]) for (let game = 0; game < (options.games ?? 25); game++) {
 		const seed = seats * 100003 + game;
 		const played = playGame(rules, seats, seed, options);
@@ -98,6 +162,7 @@ function checkTurnRules(rules, options = {}) {
 		games += 1;
 		moves += played.moves;
 		longestGame = Math.max(longestGame, played.moves);
+		outOfTurn += played.outOfTurn;
 	}
 	for (const fixture of options.fixtures ?? []) if (fixture.version < rules.version) {
 		if (rules.migrate === void 0) fail(`a version ${String(fixture.version)} fixture needs rules.migrate`);
@@ -108,7 +173,8 @@ function checkTurnRules(rules, options = {}) {
 	return {
 		games,
 		moves,
-		longestGame
+		longestGame,
+		outOfTurn
 	};
 }
 //#endregion

package/dist/turns.js.map

@@ -1 +1 @@
-{"version":3,"file":"turns.js","names":["createTurnRng","turnRngStateFromSeed"],"sources":["../src/turns-kit/check-rules.ts"],"mappings":"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"}
+{"version":3,"file":"turns.js","names":["createTurnRng","turnRngStateFromSeed"],"sources":["../src/turns-kit/check-rules.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,MAAM,kBAAkB;AACxB,MAAM,iBAAiB;;AAwDvB,SAAS,QAAQ,MAAsB;CACrC,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;AACxC;;AAGA,SAAS,KAAK,SAAwB;CACpC,MAAM,IAAI,MAAM,mBAAmB,SAAS;AAC9C;;AAGA,SAAS,UAAa,OAAa;CACjC,MAAM,OAAO,cAAc,KAAK,UAAU,KAAK,CAAC;CAChD,IAAI,SAAS,QAAQ,UAAU,MAC7B,KAAK,6BAA6B;CAEpC,OAAO,WAAW,MAAM,KAAK,IAAI,OAAO,KAAK,6BAA6B;AAC5E;;AAIA,SAAS,WAAc,QAAiB,OAAuB;CAC7D,OAAO;AACT;;AAGA,SAAS,SAA4C,OAAqD,SAAsD,OAAc,MAAc,KAAoB;CAC9M,IAAI,QAAQ,eAAe,KAAA,GACzB,OAAO,QAAQ,WAAW,OAAO,MAAM,GAAG;CAE5C,IAAI,MAAM,aAAa,KAAA,GACrB,OAAO,KAAK,qDAAqD;CAEnE,OAAO,MAAM,SAAS,OAAO,MAAM,GAAG;AACxC;;AAGA,SAAS,aAAgD,OAAqD,SAAsD,OAAc,MAAc,KAA2B;CACzN,IAAI,QAAQ,cAAc,KAAA,GACxB,OAAO,QAAQ,UAAU,OAAO,MAAM,GAAG;CAE3C,OAAO,MAAM,YAAY,OAAO,MAAM,GAAG,KAAK;AAChD;;AAGA,SAAS,WAAW,MAAyB,OAAe,MAAc,MAAoB;CAC5F,IAAI,KAAK,MAAM,SAAS,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,QAAQ,KAAK,GAC1E,KAAK,GAAG,KAAK,qCAAqC,KAAK,KAAK,IAAI,EAAE,UAAU,OAAO,IAAI,EAAE,EAAE;AAE/F;;;;;;;AAQA,SAAS,SACP,OAAqD,SAAsD,OAAc,OAA0B,KAAc,MAChH;CACjD,MAAM,YAAY,MAAM,SAAS,KAAK,KAAK,CAAC,EAAA,CAAG,QAAQ,SAAS,CAAC,MAAM,SAAS,IAAI,CAAC;CACrF,IAAI,SAAS,SAAS,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG;EAC5C,MAAM,OAAO,KAAK,KAAK,QAAQ;EAC/B,MAAM,OAAO,aAAa,OAAO,SAAS,OAAO,MAAM,GAAG;EAC1D,IAAI,SAAS,MACX,OAAO;GAAE;GAAM;GAAM,IAAI,QAAQ,cAAc,KAAA,IAAY,cAAc;EAAY;CAEzF;CACA,MAAM,OAAO,MAAM,WAAW,IAAI,KAAA,IAAY,KAAK,KAAK,KAAK;CAC7D,OAAO,SAAS,KAAA,IAAY,OAAO;EAAE;EAAM,MAAM,SAAS,OAAO,SAAS,OAAO,MAAM,GAAG;EAAG,IAAI,QAAQ,eAAe,KAAA,IAAY,aAAa;CAAa;AAChK;;AAGA,SAAS,SACP,OAAqD,OAAe,MAAc,SAC7B;CACrD,MAAM,MAAMA,gBAAcC,uBAAqB,IAAI,CAAC;CACpD,MAAM,OAAOD,gBAAcC,uBAAqB,OAAO,UAAU,CAAC;CAClE,MAAM,UAAUD,gBAAcC,uBAAqB,OAAO,SAAU,CAAC;CACrE,MAAM,SAAS,UAAU,OAAO,IAAI,EAAE;CACtC,MAAM,YAAY,UAA0B,GAAG,SAAS,OAAO,KAAK;CACpE,IAAI,QAAQ,MAAM,MAAM;EAAE;EAAO,SAAS,QAAQ,gBAAgB;EAAM,MAAM,QAAQ,QAAQ;EAAM;CAAI,CAAC;CACzG,IAAI,QAAQ,UAAU,KAAA,GACpB,KAAK,IAAI,OAAO,GAAG,OAAO,OAAO,QAC/B,QAAQ,QAAQ,MAAM,OAAO,MAAM,SAAS,IAAI,CAAC;CAGrD,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,QAAkB,CAAC;CACzB,IAAI,YAAY;;CAEhB,MAAM,kBAAwB;EAC5B,IAAI,QAAQ,kBAAkB,KAAA,GAC5B;EAEF,KAAK,IAAI,SAAS,GAAG,SAAS,OAAO,UAAU;GAC7C,MAAM,OAAO,KAAK,UAAU,MAAM,KAAK,OAAO,MAAM,CAAC;GAErD,IADa,KAAK,UAAU,MAAM,KAAK,UAAU,QAAQ,cAAc,UAAU,KAAK,GAAG,QAAQ,OAAO,CAAC,GAAG,MAAM,CAC3G,MAAM,MACX,KAAK,QAAQ,OAAO,MAAM,EAAE,uFAAuF,OAAO,IAAI,EAAE,EAAE;EAEtI;CACF;;CAEA,MAAM,SAAS,IAAI,IAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,SAAS,IAAI,CAAC;CAC1G,MAAM,cAAc,WAAmC;EACrD,KAAK,MAAM,SAAS,QAClB,IAAI,QAAQ,WAAW,OAAO,SAAS,KAAK,CAAC,MAAM,MACjD,OAAO,OAAO,KAAK;EAGvB,KAAK,IAAI,SAAS,GAAG,SAAS,OAAO,UAAU;GAC7C,MAAM,OAAO,KAAK,UAAU,MAAM,KAAK,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,OAAO,KAAK,UAAU,MAAM,YAAY,OAAO,MAAM,KAAK,IAAI,CAAC;GACvI,KAAK,MAAM,SAAS,QAClB,IAAI,UAAU,UAAU,KAAK,SAAS,SAAS,KAAK,CAAC,GACnD,KAAK,QAAQ,OAAO,MAAM,EAAE,gBAAgB,OAAO,KAAK,EAAE,kBAAkB,OAAO,IAAI,EAAE,EAAE;EAGjG;EACA,MAAM,QAAQ,KAAK,UAAU,MAAM,KAAK,OAAO,IAAI,CAAC;EACpD,KAAK,MAAM,SAAS,QAClB,IAAI,MAAM,SAAS,SAAS,KAAK,CAAC,GAChC,KAAK,8BAA8B,OAAO,KAAK,EAAE,kBAAkB,OAAO,IAAI,EAAE,EAAE;EAGtF,UAAU;CACZ;CACA,WAAW,CAAC,CAAC;CACb,KAAK,IAAI,QAAQ,GAAG,QAAQ,UAAU,SAAS;EAC7C,IAAI,MAAM,QAAQ,KAAK,MAAM,MAC3B,OAAO;GAAE;GAAO;GAAW,OAAO,MAAM,KAAK,GAAG;EAAE;EAEpD,MAAM,QAAQ,MAAM,MAAM,KAAK;EAC/B,WAAW,OAAO,OAAO,SAAS,IAAI;EACtC,WAAW,MAAM,SAAS,KAAK,KAAK,CAAC,GAAG,OAAO,UAAU,IAAI;EAC7D,IAAI,MAAM,WAAW,GACnB,KAAK,oDAAoD,OAAO,IAAI,EAAE,SAAS,OAAO,KAAK,EAAE,EAAE;EAEjG,MAAM,OAAO,SAAS,OAAO,SAAS,OAAO,OAAO,KAAK,IAAI;EAC7D,IAAI,SAAS,MACX,OAAO,KAAK,4BAA4B,OAAO,IAAI,EAAE,SAAS,OAAO,KAAK,EAAE,EAAE;EAEhF,MAAM,EAAE,MAAM,SAAS;EACvB,aAAa,MAAM,SAAS,IAAI,IAAI,IAAI;EACxC,IAAI,QAAQ,KAAK,UAAU,IAAI,CAAC,IAAI,gBAClC,KAAK,kBAAkB,OAAO,cAAc,EAAE,OAAO;EAEvD,MAAM,SAAS,MAAM,MAAM,UAAU,KAAK,GAAG,MAAM,UAAU,IAAI,GAAG,GAAG;EACvE,IAAI,WAAW,QACb,KAAK,GAAG,KAAK,GAAG,iCAAiC,OAAO,IAAI,EAAE,IAAI,OAAO,MAAM,SAAS,OAAO,IAAI,EAAE,SAAS,OAAO,KAAK,EAAE,EAAE;EAEhI,QAAQ,UAAU,OAAO,KAAK;EAC9B,IAAI,QAAQ,KAAK,UAAU,KAAK,CAAC,IAAI,iBACnC,KAAK,qBAAqB,OAAO,eAAe,EAAE,OAAO;EAE3D,WAAW,OAAO,UAAU,CAAC,CAAC;EAC9B,MAAM,SAAS,OAAO,IAAI;EAC1B,MAAM,KAAK,GAAG,OAAO,IAAI,EAAE,GAAG,KAAK,UAAU,IAAI,GAAG;CACtD;CACA,OAAO,KAAK,6BAA6B,OAAO,QAAQ,EAAE,eAAe,OAAO,IAAI,EAAE,EAAE;AAC1F;;AAGA,SAAgB,eACd,OAAqD,UAAuD,CAAC,GAC5F;CACjB,IAAI,CAAC,OAAO,UAAU,MAAM,OAAO,KAAK,MAAM,UAAU,GACtD,KAAK,sCAAsC;CAE7C,IAAI,QAAQ;CACZ,IAAI,QAAQ;CACZ,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,KAAK,MAAM,SAAS,QAAQ,SAAS,CAAC,CAAC,GACrC,KAAK,IAAI,OAAO,GAAG,QAAQ,QAAQ,SAAS,KAAK,QAAQ;EACvD,MAAM,OAAO,QAAQ,SAAU;EAC/B,MAAM,SAAS,SAAS,OAAO,OAAO,MAAM,OAAO;EACnD,IAAI,SAAS,OAAO,OAAO,MAAM,OAAO,CAAC,CAAC,UAAU,OAAO,OACzD,KAAK,+CAA+C,OAAO,IAAI,EAAE,gDAAgD;EAEnH,SAAS;EACT,SAAS,OAAO;EAChB,cAAc,KAAK,IAAI,aAAa,OAAO,KAAK;EAChD,aAAa,OAAO;CACtB;CAEF,KAAK,MAAM,WAAW,QAAQ,YAAY,CAAC,GACzC,IAAI,QAAQ,UAAU,MAAM,SAAS;EACnC,IAAI,MAAM,YAAY,KAAA,GACpB,KAAK,aAAa,OAAO,QAAQ,OAAO,EAAE,6BAA6B;EAEzE,MAAM,WAAW,MAAM,QAAQ,UAAU,QAAQ,KAAK,GAAG,QAAQ,OAAO;EACxE,MAAM,KAAK,UAAU,IAAI;EACzB,MAAM,MAAM,QAAQ;CACtB;CAEF,OAAO;EAAE;EAAO;EAAO;EAAa;CAAU;AAChD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffenderfer-games/hub",
-  "version": "2.0.0-next.7",
+  "version": "2.0.0-next.8",
   "description": "The diffenderfer.games hub client for games: accounts, saves, stats, leaderboards, inventory, daily challenges, the input system and the social/multiplayer forwarders, typed from the hub contract.",
   "license": "MIT",
   "type": "module",
@@ -64,6 +64,11 @@
       "types": "./dist/turns.d.ts",
       "default": "./dist/turns.js"
     },
+    "./turns-rules": {
+      "source": "./src/turns-rules.ts",
+      "types": "./dist/turns-rules.d.ts",
+      "default": "./dist/turns-rules.js"
+    },
     "./types": {
       "source": "./src/types.ts",
       "types": "./dist/types.d.ts",
@@ -106,7 +111,7 @@
   },
   "dependencies": {
     "@ayepi/core": "0.4.1",
-    "@diffenderfer-games/hub-contract": "2.0.0-next.7"
+    "@diffenderfer-games/hub-contract": "2.0.0-next.8"
   },
   "publishConfig": {
     "access": "public"

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

@@ -17,7 +17,8 @@ import type { CreateTurnGame, OpenTurnGame, TurnDeadline } from '@diffenderfer-g
 import { toStoredJson, type GamePayload } from '../game-data';
 import { isBrowserPage } from '../page';
 import type { SavedEntry } from '../saved/saved-types';
-import { TurnGame, type TurnGameHost } from './turn-game';
+import { TurnGame, type TurnGameHost, type TurnGameOptions } from './turn-game';
+import { readYourTurnBuzz, saveYourTurnBuzz } from './your-turn-buzz';
 
 /** The query parameter an invite link carries (`/<slug>/?hub_turn_link=<key>`); the client strips it. */
 export const TURN_LINK_PARAM = 'hub_turn_link';
@@ -89,11 +90,31 @@ function isGameId(idOrKey: string): boolean {
 /** `hub.turns`. */
 export class HubTurns {
   private readonly host: TurnsHost;
+  private isBuzzOn = true;
+  private readonly gameOptions: TurnGameOptions = { isBuzzOn: () => this.isBuzzOn };
 
   constructor(host: TurnsHost) {
     this.host = host;
   }
 
+  /**
+   * This page's "your turn" buzz (a short vibration when the player becomes
+   * due in an open game, see `TurnGame.setYourTurnBuzz`): pass `false` if
+   * your game gives its own signal. On by default.
+   */
+  setYourTurnBuzz(isOn: boolean): void {
+    this.isBuzzOn = isOn;
+  }
+
+  /** The player's own "Buzz when it's my turn" switch on this device (the menu's Settings show it too). */
+  get playerYourTurnBuzz(): boolean {
+    return readYourTurnBuzz();
+  }
+
+  set playerYourTurnBuzz(isOn: boolean) {
+    saveYourTurnBuzz(isOn);
+  }
+
   /** The invite link key this page was opened with (`?hub_turn_link=`), taken out of the address bar; `null` when none. Synchronous. */
   get link(): string | null {
     return linkOnPage();
@@ -114,18 +135,18 @@ export class HubTurns {
       ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
       ...(options.autoStart === undefined ? {} : { autoStart: options.autoStart }),
     };
-    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body));
+    return new TurnGame<View, Move, Event>(this.host, await this.host.create(body), this.gameOptions);
   }
 
   /** Take a seat: by the game's id (an invite, an open seat) or by an invite link's key. */
   async join<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(idOrLinkKey: string): Promise<TurnGame<View, Move, Event>> {
     const joined = isGameId(idOrLinkKey) ? await this.host.join(idOrLinkKey) : await this.host.joinByLink(idOrLinkKey);
-    return new TurnGame<View, Move, Event>(this.host, joined);
+    return new TurnGame<View, Move, Event>(this.host, joined, this.gameOptions);
   }
 
   /** Open a game the player sits in (from `hub.saved.opened`, the Continue list, an invite). */
   async open<View = GamePayload, Move extends GamePayload = GamePayload, Event = GamePayload>(id: string): Promise<TurnGame<View, Move, Event>> {
-    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id));
+    return new TurnGame<View, Move, Event>(this.host, await this.host.get(id), this.gameOptions);
   }
 
   /** This game's online games the player sits in (the same rows as `hub.saved.list({ kinds: ['turns'] })`). */

package/src/core/turns/turn-game.ts

@@ -9,13 +9,18 @@
  * change, `on('ended')` at the end, `on('chat')` for chat lines. Moves made
  * while the page was away are replayed from `history` when it comes back
  * (and, without the runtime, every so often while the page is visible).
+ * A safety net: while the page is visible and it is someone else's move, a
+ * page that has heard nothing for {@link TURN_QUIET_MS} fetches the game
+ * again (a lost live event never leaves it stuck), so games need no
+ * polling of their own.
  */
-import type { Json, TurnChatLine, TurnGameView, TurnSeat, TurnSummary } from '@diffenderfer-games/hub-contract';
+import type { Json, TurnChatLine, TurnGameView, TurnSeat, TurnSummary, TurnTournament } from '@diffenderfer-games/hub-contract';
 import { HubError } from '../errors';
 import { toGameData, type GamePayload } from '../game-data';
 import { isBrowserPage } from '../page';
 import { isJson, parseJsonText } from '../storage/json-guards';
 import { readField } from '../../realtime/cross-bundle';
+import { buzzYourTurn, isNewlyDue } from './your-turn-buzz';
 
 /** The window event the social runtime fires for each `ev:turn`. */
 export const TURN_EVENT = 'hub:turn';
@@ -29,6 +34,12 @@ export const TURN_CHAT_EVENT = 'hub:turn-chat';
 /** How often a page without the live runtime looks for moves, ms. */
 export const TURN_POLL_MS = 20_000;
 
+/** How long a visible page waiting on another player's move may hear nothing before it fetches the game again, ms. */
+export const TURN_QUIET_MS = 15_000;
+
+/** How often the page checks whether it should fetch, ms. */
+const TURN_CHECK_MS = 5_000;
+
 /** A game's end: the winning seats, and optionally places and scores by seat. */
 export type TurnOutcome = NonNullable<TurnGameView['outcome']>;
 
@@ -72,6 +83,12 @@ export interface TurnGameHost {
 
 type Listener<Payload> = (payload: Payload) => void;
 
+/** How `hub.turns` sets a game up. */
+export interface TurnGameOptions {
+  /** Whether this page wants the "your turn" buzz (`hub.turns.setYourTurnBuzz`); read at each buzz. Default on. */
+  readonly isBuzzOn?: () => boolean;
+}
+
 /** One online game. `View`, `Move` and `Ev` (its events) are the game's own JSON types from its rules. */
 export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload, Ev = GamePayload> {
   readonly id: string;
@@ -85,9 +102,15 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
   private catchingUp: Promise<void> | null = null;
   /** The move count this page's own move in flight will make (its live echo is not another player's move). */
   private ownSeq: number | null = null;
+  /** When the page last heard from the hub about this game (a live event or an answer), epoch ms. */
+  private heardAt = Date.now();
+  private readonly options: TurnGameOptions;
+  /** This game's own "your turn" buzz switch (`setYourTurnBuzz`). */
+  private isBuzzOn = true;
 
-  constructor(host: TurnGameHost, initial: TurnGameView) {
+  constructor(host: TurnGameHost, initial: TurnGameView, options: TurnGameOptions = {}) {
     this.host = host;
+    this.options = options;
     this.id = initial.id;
     this.state = initial;
     host.opened(this);
@@ -129,25 +152,58 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     return this.state.link === null ? null : new URL(this.state.link, location.origin).href;
   }
 
+  /** Whether this player may move now without it being their turn (the rules' `mayAct`: a jump-in, calling or catching "UNO"): offer that action. */
+  get mayActNow(): boolean {
+    const { mySeat } = this.state;
+    return mySeat !== null && this.state.summary.phase === 'playing' && (this.state.summary.mayAct ?? []).includes(mySeat);
+  }
+
+  /** The tournament match this game is, or `null` (show it if you like: "Saturday Cup: your match"). */
+  get tournament(): TurnTournament | null {
+    return this.state.tournament ?? null;
+  }
+
+  /**
+   * The "your turn" buzz for this game: a short vibration when this player
+   * becomes due on a live update while the page is visible (never for the
+   * next step of their own turn, a move out of turn, a game just opened or a
+   * catch-up; never when the player turned it off or asks for less motion;
+   * silently nothing where the device can't vibrate). On by default.
+   */
+  setYourTurnBuzz(isOn: boolean): void {
+    this.isBuzzOn = isOn;
+  }
+
   /** Creator: start the game (empty seats go to the computer when the game allows). */
   async start(): Promise<void> {
     this.update(await this.host.start(this.id));
   }
 
   /**
-   * Make a move. Rejects with a `HubError`: 403 `not_your_turn`, 409
-   * `stale` (the game moved on: the view is refreshed first), 422 `illegal`
-   * with the rules' own code in `rule`.
+   * Make a move: when it is your turn (`summary.isMyTurn`), or out of turn
+   * when the rules allow it (`mayActNow`). Rejects with a `HubError`: 403
+   * `not_your_turn`, 409 `stale` (the game moved on, or another player's
+   * move got there first: the view is refreshed first), 422 `illegal` with
+   * the rules' own code in `rule`, 500 `rules_error` or 503 `rules_busy`
+   * (the move was not made; the game is fetched again). The answer's `view` is the newest this
+   * page has: moves that arrived live while the answer was on its way (the
+   * computer's, another player's) are never rolled back.
    */
   async move(move: Move): Promise<{ seq: number; view: View; events: Ev[] }> {
     this.ownSeq = this.state.summary.seq + 1;
     try {
       const answer = await this.host.move(this.id, this.state.summary.seq, toPayload(move));
-      this.update(answer.game);
+      // A late answer: live events already brought a newer state, which stays.
+      if (answer.game.summary.seq >= this.state.summary.seq) {
+        this.update(answer.game);
+      }
       return { seq: answer.game.summary.seq, view: this.view, events: answer.events.map((event) => toGameData<Ev>(event)) };
     } catch (failure) {
       if (failure instanceof HubError && failure.code === 'stale') {
         await this.refresh();
+      } else if (failure instanceof HubError && (failure.code === 'rules_error' || failure.code === 'rules_busy')) {
+        // The move was not made (the hub writes nothing when its rules fail), but the page may be behind: fetch the truth.
+        await this.catchUp();
       }
       throw failure;
     } finally {
@@ -179,7 +235,7 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
 
   /** A finished game: a new one with the same friends (they get an invite). */
   async rematch(): Promise<TurnGame<View, Move, Ev>> {
-    return new TurnGame<View, Move, Ev>(this.host, await this.host.rematch(this.id));
+    return new TurnGame<View, Move, Ev>(this.host, await this.host.rematch(this.id), this.options);
   }
 
   /** Creator, before the start: add an invite link (`link: true`, then read `link`) or list the open seats for anyone (`public`). */
@@ -192,7 +248,40 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     this.update(await this.host.invite(this.id, userIds));
   }
 
-  /** The turn's deadline passed (or its player is suspended): let the computer play it. */
+  /**
+   * Whether "Let the computer play for <name>" may work now: another
+   * player is due, the hub's hand-over wait (`summary.handOverAt`) has
+   * passed and a due player isn't connected (`TurnSeat.connected` false
+   * or unknown), or the turn's `deadline` passed. `false` in a
+   * tournament match, and from a hub too old to say. Re-check it on each
+   * `turn` event (a player coming or going fires one) and when
+   * `handOverAt` comes.
+   */
+  canLetComputerPlay(now: number = Date.now()): boolean {
+    const { summary, mySeat } = this.state;
+    if (summary.phase !== 'playing' || mySeat === null || this.state.tournament !== undefined) {
+      return false;
+    }
+    const due = summary.seats.filter((seat) => summary.toAct.includes(seat.seat) && seat.seat !== mySeat && seat.status === 'joined');
+    if (due.length === 0) {
+      return false;
+    }
+    if (summary.deadline !== null && summary.deadline <= now) {
+      return true;
+    }
+    const { handOverAt } = summary;
+    return handOverAt !== undefined && handOverAt !== null && handOverAt <= now && due.some((seat) => seat.connected !== true);
+  }
+
+  /**
+   * Let the computer play for whoever is due: a turn whose deadline passed
+   * (or whose player is suspended) is played once; otherwise, when that
+   * player has been due a while (2 minutes) and isn't connected at all, the
+   * computer plays their seat for the rest of the game (it shows as `bot`,
+   * named with who chose it) until they open the game again. Rejects with
+   * 409 `deadline_not_passed` when neither (it never says whether they are
+   * online), and 409 `not_supported` in a tournament match.
+   */
   async letComputerPlay(): Promise<void> {
     this.update(await this.host.autoPlay(this.id));
   }
@@ -202,18 +291,26 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     return this.host.chat(this.id, send);
   }
 
-  /** Fetch the game again, and replay moves missed since the last one this page saw. */
+  /**
+   * Fetch the game again, and replay moves missed since the last one this
+   * page saw. An answer older than what the page has by then (live moves
+   * arrived while it was on its way) is dropped, never rolled back to, and
+   * a move that arrived live is never replayed twice.
+   */
   async refresh(): Promise<void> {
-    const before = this.state.summary.seq;
     const fresh = await this.host.get(this.id);
-    if (fresh.summary.seq > before) {
-      const missed = await this.host.history(this.id, before);
+    const seen = this.state.summary.seq;
+    if (fresh.summary.seq <= seen) {
       this.update(fresh);
-      for (const move of missed) {
+      return;
+    }
+    const missed = await this.host.history(this.id, seen);
+    const since = this.state.summary.seq;
+    this.update(fresh);
+    for (const move of missed) {
+      if (move.seq > since && move.seq <= fresh.summary.seq) {
         this.emit('move', { seq: move.seq, seat: move.seat, view: this.view, events: move.events.map((event) => toGameData<Ev>(event)) });
       }
-    } else {
-      this.update(fresh);
     }
   }
 
@@ -238,12 +335,16 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     this.host.closed(this);
   }
 
-  /** Take a fresh answer from the hub; fire `turn` and `ended` when they changed. */
+  /** Take a fresh answer from the hub (one older than what the page has is dropped: no rollback); fire `turn` and `ended` when they changed. */
   private update(next: TurnGameView): void {
+    this.heardAt = Date.now();
     const previous = this.state;
+    if (next.summary.seq < previous.summary.seq) {
+      return;
+    }
     this.state = next;
     const isChanged = previous.summary.seq !== next.summary.seq || previous.summary.phase !== next.summary.phase || !sameSeats(previous.summary, next.summary)
-      || previous.chatMode !== next.chatMode || previous.link !== next.link;
+      || previous.summary.handOverAt !== next.summary.handOverAt || previous.chatMode !== next.chatMode || previous.link !== next.link;
     if (isChanged) {
       this.emit('turn', next.summary);
     }
@@ -259,8 +360,15 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     }
   }
 
+  /** Whether it is another player's move now (the page is waiting on someone). */
+  private isWaitingOnOthers(): boolean {
+    const { summary } = this.state;
+    return summary.phase === 'playing' && !summary.isMyTurn;
+  }
+
   /** A live `hub:turn` for this game: a move (or a missed run of them), or another change. */
   private onLive(detail: object): void {
+    this.heardAt = Date.now();
     const seq = readField(detail, 'seq');
     const view = readField(detail, 'view');
     const summary = readField(detail, 'summary');
@@ -271,6 +379,10 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
       void this.catchUp();
       return;
     }
+    if (seq < this.state.summary.seq) {
+      // Older than what the page has (a late event): nothing to roll back to.
+      return;
+    }
     const seat = readField(detail, 'seat');
     const events = readField(detail, 'events');
     const outcome = readField(detail, 'outcome');
@@ -279,7 +391,11 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
       // Who sits where changed (a join, the start, a leave): the chat mode and link may have too, and the live event doesn't carry them.
       void this.catchUp();
     }
+    const before = this.state.summary;
     this.update({ ...this.state, summary, view: toPayloadJson(view), outcome: isOutcome(outcome) ? outcome : this.state.outcome });
+    if (this.isBuzzOn && (this.options.isBuzzOn?.() ?? true) && isNewlyDue(before, this.state.summary)) {
+      buzzYourTurn();
+    }
     if (isMove) {
       this.emit('move', { seq, seat, view: this.view, events: Array.isArray(events) ? events.map((event) => toGameData<Ev>(toPayloadJson(event))) : [] });
     }
@@ -327,10 +443,16 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     window.addEventListener(TURN_RESYNC_EVENT, onResync);
     document.addEventListener('visibilitychange', onVisible);
     const poll = setInterval(() => {
-      if (!this.host.isLive() && document.visibilityState === 'visible') {
+      if (document.visibilityState !== 'visible' || this.catchingUp !== null) {
+        return;
+      }
+      const quietMs = Date.now() - this.heardAt;
+      // Without the live runtime: poll. With it: the safety net, while waiting on someone else's move.
+      if (this.host.isLive() ? this.isWaitingOnOthers() && quietMs >= TURN_QUIET_MS : quietMs >= TURN_POLL_MS) {
+        this.heardAt = Date.now();
         void this.catchUp();
       }
-    }, TURN_POLL_MS);
+    }, TURN_CHECK_MS);
     this.stopListening.push(
       () => { window.removeEventListener(TURN_EVENT, onTurn); },
       () => { window.removeEventListener(TURN_CHAT_EVENT, onChat); },
@@ -354,9 +476,9 @@ function sameSeating(a: TurnSummary, b: TurnSummary): boolean {
   return eachSeat(a, b, (seat, other) => seat.status === other.status && seat.userId === other.userId);
 }
 
-/** The same seating, and the same looks (a player's new avatar is a change: `turn` fires). */
+/** The same seating, looks and who is connected (a player's new avatar, or a player coming or going, is a change: `turn` fires). */
 function sameSeats(a: TurnSummary, b: TurnSummary): boolean {
-  return sameSeating(a, b) && eachSeat(a, b, (seat, other) => seat.look === other.look);
+  return sameSeating(a, b) && eachSeat(a, b, (seat, other) => seat.look === other.look && seat.connected === other.connected);
 }
 
 /** A game's move as the JSON the hub takes. */

package/src/core/turns/your-turn-buzz.ts

@@ -0,0 +1,69 @@
+/**
+ * "Your turn" buzz: a short vibration when this player becomes due in an
+ * online game whose page they have open and visible (a phone held while
+ * waiting). Every online game gets it from `TurnGame`, with no game code.
+ *
+ * It buzzes only when the player **becomes** due on a live update: not for
+ * the next step of their own turn, not for a move they may make out of turn
+ * (`mayAct`), not for a game they just opened or a catch-up after being
+ * away, and not in a game they muted. It stays quiet when the player turned
+ * it off (the menu's Settings, stored on this device), when the page asks
+ * for less motion (the hub's `data-hub-motion="reduce"` or the system's
+ * reduced motion), and where `navigator.vibrate` doesn't exist (iOS Safari).
+ * A page can turn it off for itself (`hub.turns.setYourTurnBuzz(false)`) or
+ * for one game (`TurnGame.setYourTurnBuzz(false)`).
+ */
+import type { TurnSummary } from '@diffenderfer-games/hub-contract';
+
+/** The pattern: two short pulses, ms. */
+export const YOUR_TURN_BUZZ: readonly number[] = [60, 40, 60];
+
+/** Where this device keeps the player's choice (`off` turns it off). */
+export const YOUR_TURN_BUZZ_KEY = 'dg:your-turn-buzz';
+
+/** Whether going from `previous` to `next` makes this player newly due (the moment to buzz). */
+export function isNewlyDue(previous: Pick<TurnSummary, 'phase' | 'isMyTurn'>, next: Pick<TurnSummary, 'phase' | 'isMyTurn' | 'isMuted'>): boolean {
+  const wasDue = previous.phase === 'playing' && previous.isMyTurn;
+  return next.phase === 'playing' && next.isMyTurn && !wasDue && !next.isMuted;
+}
+
+/** The player's own switch on this device (on unless they turned it off). */
+export function readYourTurnBuzz(): boolean {
+  try {
+    return localStorage.getItem(YOUR_TURN_BUZZ_KEY) !== 'off';
+  } catch {
+    return true;
+  }
+}
+
+/** Save the player's switch on this device. */
+export function saveYourTurnBuzz(isOn: boolean): void {
+  try {
+    localStorage.setItem(YOUR_TURN_BUZZ_KEY, isOn ? 'on' : 'off');
+  } catch {
+    // No storage: it stays on.
+  }
+}
+
+/** Whether the page asks for less motion (the hub's setting, else the system's). */
+function prefersLessMotion(): boolean {
+  if (typeof document !== 'undefined' && document.documentElement.dataset.hubMotion === 'reduce') {
+    return true;
+  }
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/** Buzz now, when this page is visible and nothing says not to; fails silently. Answers whether it buzzed. */
+export function buzzYourTurn(): boolean {
+  if (typeof document === 'undefined' || document.visibilityState !== 'visible' || !readYourTurnBuzz() || prefersLessMotion()) {
+    return false;
+  }
+  if (typeof navigator === 'undefined' || typeof navigator.vibrate !== 'function') {
+    return false;
+  }
+  try {
+    return navigator.vibrate([...YOUR_TURN_BUZZ]);
+  } catch {
+    return false;
+  }
+}

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

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