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

package/src/doctor/checks.ts

@@ -15,8 +15,8 @@ export type FindingLevel = 'error' | 'warning' | 'info';
 export interface Finding {
   /** How serious it is. */
   readonly level: FindingLevel;
-  /** Which check found it: `version`, `vendored` or `manifest`. */
-  readonly check: 'version' | 'vendored' | 'manifest';
+  /** Which check found it: `version`, `vendored`, `manifest` or `world`. */
+  readonly check: 'version' | 'vendored' | 'manifest' | 'world';
   /** What to tell the developer, with the fix. */
   readonly message: string;
 }

package/src/doctor/cli.ts

@@ -11,7 +11,8 @@
  *   `/_api/version` (`--hub`, default `https://diffenderfer.games`): outside
  *   `supported` fails, `deprecated` warns (`--offline` skips this check);
  * - a stale vendored `src/hub/` copy or `scripts/sync-hub.mjs` warns;
- * - the `package.json` `game.*` block must match the contract's schema.
+ * - the `package.json` `game.*` block must match the contract's schema;
+ * - a `game.world.map` file must exist and be a valid `dg-world@1` map within the size limit.
  *
  * Exits 1 when any check fails.
  */
@@ -21,6 +22,7 @@ import { parseArgs } from 'node:util';
 import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
 import { checkClientVersion, checkManifest, checkVendoredCopies, type Finding } from './checks';
 import { DEFAULT_HUB_TIMEOUT_MS, fetchHubVersion } from './hub-version-fetch';
+import { checkWorld } from './world-check';
 
 const DEFAULT_HUB_URL = 'https://diffenderfer.games';
 
@@ -79,7 +81,8 @@ async function runDoctor(options: DoctorOptions): Promise<Finding[]> {
   }
   findings.push(...checkVendoredCopies(options.gameDir));
   try {
-    findings.push(...checkManifest(readJsonFile(join(options.gameDir, 'package.json'))));
+    const packageJson = readJsonFile(join(options.gameDir, 'package.json'));
+    findings.push(...checkManifest(packageJson), ...checkWorld(options.gameDir, packageJson));
   } catch (failure) {
     findings.push({ level: 'error', check: 'manifest', message: `could not read package.json: ${failure instanceof Error ? failure.message : String(failure)}` });
   }

package/src/doctor/world-check.ts

@@ -0,0 +1,61 @@
+/**
+ * `hub-doctor`'s world check (docs/plans/world.md §14.6): a `game.world.map`
+ * file must exist inside the game, be within the size limit and be a valid
+ * `dg-world@1` map (the same `parseWorldMapText` the hub runs at load); a
+ * `game.world.generate.type` the hub doesn't know is a warning.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { GamePackageJson } from '@diffenderfer-games/hub-contract';
+import { BUILT_IN_WORLD_TYPES, WORLD_LIMITS, parseWorldMapText } from '@diffenderfer-games/world';
+import type { Finding } from './checks';
+
+/** The most map problems listed (the rest are counted). */
+const MAX_LISTED_PROBLEMS = 20;
+
+/** Checks the map file and world type `game.world` names. A manifest that doesn't parse is left to `checkManifest`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's package.json, parsed by GamePackageJson next
+export function checkWorld(gameDir: string, packageJson: unknown): Finding[] {
+  const parsed = GamePackageJson.safeParse(packageJson);
+  const world = parsed.success ? parsed.data.game.world : undefined;
+  if (world === undefined) {
+    return [];
+  }
+  const findings: Finding[] = [];
+  const type = world.generate?.type;
+  if (type !== undefined && !BUILT_IN_WORLD_TYPES.some((known) => known.id === type)) {
+    findings.push({ level: 'warning', check: 'world', message: `game.world.generate.type: the hub has no world type "${type}"; use one of ${BUILT_IN_WORLD_TYPES.map((known) => known.id).join(', ')}` });
+  }
+  return world.map === undefined ? findings : [...findings, ...checkMapFile(gameDir, world.map)];
+}
+
+/** One map file's findings. */
+export function checkMapFile(gameDir: string, mapFile: string): Finding[] {
+  const path = join(gameDir, mapFile);
+  const error = (message: string): Finding => ({ level: 'error', check: 'world', message: `game.world.map (${mapFile}): ${message}` });
+  if (!existsSync(path) || !statSync(path).isFile()) {
+    return [error('the file does not exist (build or commit it)')];
+  }
+  const bytes = statSync(path).size;
+  if (bytes > WORLD_LIMITS.bytes) {
+    return [error(`${String(bytes)} bytes is over the ${String(WORLD_LIMITS.bytes)}-byte limit (save layers as "rle")`)];
+  }
+  const result = parseWorldMapText(readFileSync(path, 'utf8'));
+  const listed = result.problems.slice(0, MAX_LISTED_PROBLEMS).map((problem): Finding => ({
+    level: problem.severity === 'error' ? 'error' : 'warning',
+    check: 'world',
+    message: `game.world.map (${mapFile}): ${problem.message}`,
+  }));
+  const more = result.problems.length - listed.length;
+  if (more > 0) {
+    listed.push(error(`and ${String(more)} more problems`));
+  }
+  if (!result.ok) {
+    return listed;
+  }
+  const { map } = result;
+  return [...listed, {
+    level: 'info', check: 'world',
+    message: `game.world.map (${mapFile}) is a valid dg-world@1 map: ${map.title}, ${String(map.width)} × ${String(map.height)}, ${String(map.objects.length)} objects, ${String(bytes)} bytes`,
+  }];
+}

package/src/index.ts

@@ -46,7 +46,8 @@ export { HubSaved, SAVED_CHANGE_QUIET_MS, type SavedChangeListener, type SavedOp
 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 { 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';

package/src/realtime/runtime-api.ts

@@ -8,14 +8,15 @@ import type { HubMpApi, InviteLinkMethods } from './multiplayer-types';
 import type { HubRaceApi } from './race-types';
 import type { HubRoomsApi, RoomReclaimMethods } from './room-types';
 import type { HubNotifyApi, HubPresenceApi, HubSocialApi, PlayOnlineMethods } from './social-types';
+import type { RuntimeWorldApi } from './world-types';
 
 /**
  * The realtime feature version the runtime reports in {@link RealtimeApi.version}.
  * 2 added races; 3 added invite links and taking back a held seat; 4 added
- * "Play online" (tournaments); 5 added avatars (the designer and `ev:avatar`).
+ * "Play online" (tournaments); 5 added avatars (the designer and `ev:avatar`); 6 added the world (`world`).
  * A client feature-detects newer additions with it (or by the optional method).
  */
-export const REALTIME_FEATURE_VERSION = 5;
+export const REALTIME_FEATURE_VERSION = 6;
 
 /** `hub.social` as a runtime installs it: version 4's `openPlayOnline` is missing on older runtimes. */
 export type RuntimeSocialApi = Omit<HubSocialApi, keyof PlayOnlineMethods> & Partial<PlayOnlineMethods>;
@@ -68,4 +69,6 @@ export interface RealtimeApi {
   race?: HubRaceApi;
   /** Avatars: the designer and live changes (feature version 5 and later). */
   avatar?: RuntimeAvatarApi;
+  /** The world's ops and events (feature version 6 and later). */
+  world?: RuntimeWorldApi;
 }

package/src/realtime/types.ts

@@ -51,3 +51,4 @@ export type * from './multiplayer-types';
 export type * from './room-types';
 export type * from './race-types';
 export type { RealtimeApi } from './runtime-api';
+export type { RuntimeWorldApi, WorldEventName, WorldOpName } from './world-types';

package/src/realtime/world-types.ts

@@ -0,0 +1,20 @@
+/**
+ * The world over the runtime's socket (docs/plans/world.md §8.3): the
+ * `world.*` ops and events, typed from the contract. The hub's world client
+ * calls it; games don't need it.
+ */
+import type { EventData, EventName, events, OpAck, OpInput, OpName, ops } from '@diffenderfer-games/hub-contract';
+
+/** A `world.*` op name. */
+export type WorldOpName = Extract<OpName, `world.${string}`>;
+
+/** A `world.*` event name. */
+export type WorldEventName = Extract<EventName, `world.${string}`>;
+
+/** `rt.world` (realtime feature version 6 and later). */
+export interface RuntimeWorldApi {
+  /** Send a world op on the page's socket; rejects with the hub's refusal. */
+  op<Name extends WorldOpName>(name: Name, input: OpInput<(typeof ops)[Name]>): Promise<OpAck<(typeof ops)[Name]>>;
+  /** Hear a world event; returns the unsubscribe. */
+  on<Name extends WorldEventName>(name: Name, listener: (payload: EventData<(typeof events)[Name]>) => void): () => void;
+}

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';