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

package/src/index.ts

@@ -1,67 +1,68 @@
-/**
- * `@diffenderfer-games/hub`: the hub client for games on diffenderfer.games.
- *
- * ```ts
- * import { hub } from '@diffenderfer-games/hub';
- *
- * const { user } = await hub.me();
- * await hub.putSave('auto', { level: 7, gold: 120 });
- * await hub.submitScore('highscore', 9001, { title: 'High Score' });
- * ```
- *
- * In a hosted game the slug and API base are detected from the page; use
- * {@link createHub} for others. Every call rejects with a {@link HubError}
- * when it fails, except the fire-and-forget analytics (`recordPlay`,
- * `heartbeat`, `event`). When the hub can't be reached, reads come from an
- * offline cache and writes are queued in an outbox until it is back; games
- * queue their own operations with `hub.offline` (docs: "Offline and replay").
- *
- * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `hub.resume`, `hub.saved`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
- * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
- * only that part.
- *
- * @packageDocumentation
- */
-export { createHub, Hub, hub } from './core/hub';
-export {
-  ContentRejectedError,
-  HubError,
-  OfflineError,
-  SAVE_UNKNOWN_CODE,
-  UNSUPPORTED_BY_HUB,
-  type HubErrorCode,
-  type HubErrorDetails,
-} from './core/errors';
-export type { SyncConflict, SyncResult } from './core/connection';
-export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
-export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
-export type { HubMenuControl } from './core/menu-control';
-export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
-export { HubAvatar, type AvatarHost, type AvatarModule } from './core/avatar/hub-avatar';
-export type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions, RuntimeAvatarApi } from './core/avatar/avatar-types';
-export type { CarriesLook } from './core/avatar/avatar-ref';
-export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
-export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOpenDetail, type SavedOpenHandler } from './core/saved/hub-saved';
-export { SAVED_CHANGE_EVENT, SAVED_KIND_PARAM, SAVED_OPEN_EVENT, SAVED_OPEN_PARAM, savedGameUrl } from './core/saved/saved-open';
-export type * from './core/saved/saved-types';
-export { HubTurns, TURN_LINK_PARAM, type TurnCreateOptions } from './core/turns/hub-turns';
-export { TURN_CHAT_EVENT, TURN_EVENT, TURN_POLL_MS, TURN_RESYNC_EVENT, TurnGame, type TurnGameEvents, type TurnMoveEvent, type TurnOutcome } from './core/turns/turn-game';
-export type { OpenTurnGame, TurnChatLine, TurnDeadline, TurnGameView } from '@diffenderfer-games/hub-contract';
-export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
-export { OfflineApi } from './core/offline/offline-api';
-export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';
-export type { OfflineHandler, OfflineKindDefinition, ReplayContext } from './core/offline/outbox-kinds';
-export { OUTBOX_MAX_CHARS, OUTBOX_MAX_ENTRIES } from './core/offline/outbox-store';
-export type { BufferedEvent } from './core/offline/events';
-export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
-export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';
-export type { ClientSupport } from './core/version/hub-version';
-export { HUB_CLIENT_VERSION } from './core/version/client-version.gen';
-export type * from './core/types';
-export * from './daily';
-export * from './input';
-export type * from './social';
-export type * from './mp';
-export type * from './race';
-export type * from './rooms';
+/**
+ * `@diffenderfer-games/hub`: the hub client for games on diffenderfer.games.
+ *
+ * ```ts
+ * import { hub } from '@diffenderfer-games/hub';
+ *
+ * const { user } = await hub.me();
+ * await hub.putSave('auto', { level: 7, gold: 120 });
+ * await hub.submitScore('highscore', 9001, { title: 'High Score' });
+ * ```
+ *
+ * In a hosted game the slug and API base are detected from the page; use
+ * {@link createHub} for others. Every call rejects with a {@link HubError}
+ * when it fails, except the fire-and-forget analytics (`recordPlay`,
+ * `heartbeat`, `event`). When the hub can't be reached, reads come from an
+ * offline cache and writes are queued in an outbox until it is back; games
+ * queue their own operations with `hub.offline` (docs: "Offline and replay").
+ *
+ * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
+ * `hub.daily`, `hub.resume`, `hub.saved`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
+ * only that part.
+ *
+ * @packageDocumentation
+ */
+export { createHub, Hub, hub } from './core/hub';
+export {
+  ContentRejectedError,
+  HubError,
+  OfflineError,
+  SAVE_UNKNOWN_CODE,
+  UNSUPPORTED_BY_HUB,
+  type HubErrorCode,
+  type HubErrorDetails,
+} from './core/errors';
+export type { SyncConflict, SyncResult } from './core/connection';
+export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
+export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
+export type { HubMenuControl } from './core/menu-control';
+export { HubResume, RESUME_DEBOUNCE_MS, RESUME_MAX_STATE_BYTES } from './core/resume/hub-resume';
+export { HubAvatar, type AvatarHost, type AvatarModule } from './core/avatar/hub-avatar';
+export type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions, RuntimeAvatarApi } from './core/avatar/avatar-types';
+export type { CarriesLook } from './core/avatar/avatar-ref';
+export type { ResumeBlocker, ResumeEntry, ResumeLoadOptions, ResumeProgress, ResumeRun, ResumeSaveInput } from './core/resume/resume-types';
+export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOpenDetail, type SavedOpenHandler } from './core/saved/hub-saved';
+export { SAVED_CHANGE_EVENT, SAVED_KIND_PARAM, SAVED_OPEN_EVENT, SAVED_OPEN_PARAM, savedGameUrl } from './core/saved/saved-open';
+export type * from './core/saved/saved-types';
+export { HubTurns, TURN_LINK_PARAM, type TurnCreateOptions } from './core/turns/hub-turns';
+export { isNewlyDue, readYourTurnBuzz, saveYourTurnBuzz, YOUR_TURN_BUZZ, YOUR_TURN_BUZZ_KEY } from './core/turns/your-turn-buzz';
+export { TURN_CHAT_EVENT, TURN_EVENT, TURN_POLL_MS, TURN_QUIET_MS, TURN_RESYNC_EVENT, TurnGame, type TurnGameEvents, type TurnGameOptions, type TurnMoveEvent, type TurnOutcome } from './core/turns/turn-game';
+export type { OpenTurnGame, TurnChatLine, TurnDeadline, TurnGameView } from '@diffenderfer-games/hub-contract';
+export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
+export { OfflineApi } from './core/offline/offline-api';
+export { OUTBOX_FULL_CODE, type OfflineEventDetails, type OfflineEventName, type OfflineListener, type OfflineOp } from './core/offline/outbox';
+export type { OfflineHandler, OfflineKindDefinition, ReplayContext } from './core/offline/outbox-kinds';
+export { OUTBOX_MAX_CHARS, OUTBOX_MAX_ENTRIES } from './core/offline/outbox-store';
+export type { BufferedEvent } from './core/offline/events';
+export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
+export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';
+export type { ClientSupport } from './core/version/hub-version';
+export { HUB_CLIENT_VERSION } from './core/version/client-version.gen';
+export type * from './core/types';
+export * from './daily';
+export * from './input';
+export type * from './social';
+export type * from './mp';
+export type * from './race';
+export type * from './rooms';

package/src/turns-kit/check-rules.ts

@@ -4,18 +4,24 @@
  * 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.
  *
  * It needs no hub: run it in a game's own unit tests (vitest, node:test).
  */
-import { createTurnRng, turnRngStateFromSeed, type TurnRng, type TurnRules } from '@diffenderfer-games/hub-contract';
+import { createTurnRng, turnRngStateFromSeed, type TurnRng, type TurnRules } from '@diffenderfer-games/hub-contract/turns-rules';
 import { parseJsonText } from '../core/storage/json-guards';
 
 /** The hub's caps. */
@@ -35,6 +41,8 @@ export interface TurnRulesCheckOptions<State, Move, Options = never> {
   readonly mode?: string | null;
   /** A legal move for `seat` (default: the rules' own `autoMove`). At least one of the two is needed. */
   readonly randomMove?: (state: State, seat: number, rng: TurnRng) => Move;
+  /** A legal out-of-turn move for `seat` while it is in `mayAct`, or `null` to pass (default: the rules' own `autoReact`). */
+  readonly reactMove?: (state: State, seat: number, rng: TurnRng) => Move | null;
   /**
    * Put `marker` somewhere only `seat` may see (a card in their hand, their
    * secret goal) and return the state; the kit then checks no other seat's
@@ -42,6 +50,23 @@ export interface TurnRulesCheckOptions<State, Move, Options = never> {
    * information.
    */
   readonly plant?: (state: State, seat: number, marker: string) => State;
+  /**
+   * Whether a planted `marker` is now public by the rules (the card was
+   * played or discarded face up, a secret was shown at the end): from then
+   * on the kit stops checking it in that game, so a card that is rightly
+   * revealed isn't a leak. Leave it out when planted markers never become
+   * public.
+   */
+  readonly revealed?: (state: State, marker: string) => boolean;
+  /**
+   * The "twin table": a copy of `state` with everything `seat` may not see
+   * shuffled or redealt (the deck's order, the other hands' cards, keeping
+   * their counts), drawing from `rng`. After every move the kit checks
+   * that each seat's `view` of the twin is exactly its view of the real
+   * state: a view that changes depends on something that seat must not
+   * know. Catches leaks `plant` can't (a count, an order, a derived hint).
+   */
+  readonly shuffleHidden?: (state: State, seat: number, rng: TurnRng) => State;
   /** States saved by older rules versions, which `migrate` must bring up to date. */
   // eslint-disable-next-line no-restricted-syntax -- trust boundary: states stored by older rules versions
   readonly fixtures?: readonly { readonly version: number; readonly state: unknown }[];
@@ -52,6 +77,8 @@ export interface TurnRulesReport {
   readonly games: number;
   readonly moves: number;
   readonly longestGame: number;
+  /** Moves made out of turn (by a seat in `mayAct`, not `toAct`). */
+  readonly outOfTurn: number;
 }
 
 /** The UTF-8 bytes of a JSON text. */
@@ -90,50 +117,120 @@ function pickMove<State, Move, View, Event, Options>(rules: TurnRules<State, Mov
   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<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move | null {
+  if (options.reactMove !== undefined) {
+    return options.reactMove(state, seat, rng);
+  }
+  return rules.autoReact?.(state, seat, rng) ?? null;
+}
+
+/** Fail unless every seat in `list` exists. */
+function checkSeats(list: readonly number[], seats: number, what: string, seed: number): void {
+  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<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, toAct: readonly number[], rng: TurnRng, pick: TurnRng,
+): { seat: number; move: Move; by: string } | null {
+  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 === undefined ? 'autoReact' : 'reactMove' };
+    }
+  }
+  const seat = toAct.length === 0 ? undefined : pick.pick(toAct);
+  return seat === undefined ? null : { seat, move: pickMove(rules, options, state, seat, rng), by: options.randomMove === undefined ? 'autoMove' : 'randomMove' };
+}
+
 /** Play one seeded game; answers its moves and a trace for the determinism check. */
 function playGame<State, Move, View, Event, Options>(
   rules: TurnRules<State, Move, View, Event, Options>, seats: number, seed: number, options: TurnRulesCheckOptions<State, Move, Options>,
-): { moves: number; trace: string } {
+): { moves: number; outOfTurn: number; trace: string } {
   const rng = createTurnRng(turnRngStateFromSeed(seed));
+  const pick = createTurnRng(turnRngStateFromSeed(seed ^ 0x5bd1e995));
+  const twinRng = createTurnRng(turnRngStateFromSeed(seed ^ 0x27d4eb2f));
   const marker = `MARKER-${String(seed)}-`;
+  const markerOf = (owner: number): string => `${marker}${String(owner)}`;
   let state = rules.setup({ seats, options: options.setupOptions ?? null, mode: options.mode ?? null, rng });
   if (options.plant !== undefined) {
     for (let seat = 0; seat < seats; seat++) {
-      state = options.plant(state, seat, `${marker}${String(seat)}`);
+      state = options.plant(state, seat, markerOf(seat));
     }
   }
   const maxMoves = options.maxMoves ?? 2000;
   const trace: string[] = [];
+  let outOfTurn = 0;
+  /** The twin table: each seat's view is the same after what it can't see is shuffled. */
+  const checkTwin = (): void => {
+    if (options.shuffleHidden === undefined) {
+      return;
+    }
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const real = JSON.stringify(rules.view(state, viewer));
+      const twin = JSON.stringify(rules.view(roundTrip(options.shuffleHidden(roundTrip(state), viewer, twinRng)), viewer));
+      if (twin !== 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 === undefined ? [] : Array.from({ length: seats }, (_, seat) => seat));
   const checkViews = (events: readonly Event[]): void => {
+    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 !== undefined && seen.includes(`${marker}${String(owner)}`)) {
+      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 !== undefined && 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, trace: trace.join('|') };
+      return { moves, outOfTurn, trace: trace.join('|') };
     }
     const toAct = rules.toAct(state);
-    const seat = toAct[0];
-    if (seat === undefined) {
+    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 move = pickMove(rules, options, state, seat, rng);
+    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 === undefined ? 'autoMove' : 'randomMove'} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+      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) {
@@ -141,7 +238,7 @@ function playGame<State, Move, View, Event, Options>(
     }
     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)})`);
 }
@@ -156,6 +253,7 @@ export function checkTurnRules<State, Move, View, Event, 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 * 100_003 + game;
@@ -166,6 +264,7 @@ export function checkTurnRules<State, Move, View, Event, Options>(
       games += 1;
       moves += played.moves;
       longestGame = Math.max(longestGame, played.moves);
+      outOfTurn += played.outOfTurn;
     }
   }
   for (const fixture of options.fixtures ?? []) {
@@ -178,5 +277,5 @@ export function checkTurnRules<State, Move, View, Event, Options>(
       rules.toAct(migrated);
     }
   }
-  return { games, moves, longestGame };
+  return { games, moves, longestGame, outOfTurn };
 }

package/src/turns-rules.ts

@@ -0,0 +1,12 @@
+/**
+ * `@diffenderfer-games/hub/turns-rules`: what an online turn game's rules
+ * module imports (docs/multiplayer.md §16): `defineTurnRules` to type the
+ * rules object, the rules contract's types, and the seeded RNG the hub
+ * hands the rules. Nothing else comes with it (no zod, no client), so a
+ * rules bundle that imports it stays a few KB. The conformance kit for
+ * tests is `@diffenderfer-games/hub/turns`.
+ *
+ * @packageDocumentation
+ */
+export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract/turns-rules';
+export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract/turns-rules';

package/src/turns.ts

@@ -4,10 +4,11 @@
  * rules contract, `defineTurnRules` to type a rules object, the seeded RNG
  * the hub hands the rules (to replay a game in tests), and the conformance
  * kit, `checkTurnRules`, for the game's own CI. The page-side API is
- * `hub.turns` on the main entry.
+ * `hub.turns` on the main entry. A rules module itself imports
+ * `@diffenderfer-games/hub/turns-rules` (the same `defineTurnRules` and
+ * types, nothing else), so its bundle stays a few KB.
  *
  * @packageDocumentation
  */
-export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract';
-export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract';
+export * from './turns-rules';
 export { checkTurnRules, type TurnRulesCheckOptions, type TurnRulesReport } from './turns-kit/check-rules';