@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/doctor/tsconfig.json

@@ -1,12 +1,12 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "."
-  ],
-  "exclude": []
-}
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "."
+  ],
+  "exclude": []
+}

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/globals.ts

@@ -1,110 +1,115 @@
-/**
- * Page-wide singletons across client versions (plan §4.4). One page often
- * runs two client builds: the game's bundled copy and the host's injected
- * `/_hub/hub.js`. The input system, daily challenges and the realtime API
- * must exist once per page, so each is registered here with the version that
- * created it and a small `api` number that changes only when the
- * cross-bundle shape does.
- *
- * - Same `api`: the first creator wins and everyone shares it.
- * - Different `api`: the caller decides who owns the page (see
- *   {@link claimSingleton}'s `onMismatch`); the mismatch is logged once with the fix.
- * - The v1 names (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
- *   aliases while vendored v1 copies are still around.
- */
-
-/** A page-wide singleton's name. */
-export type SingletonName = 'input' | 'daily' | 'rt';
-
-/** One registered singleton. */
-export interface SingletonRecord {
-  /** The client version that created it. */
-  readonly version: string;
-  /** Its cross-bundle shape number. */
-  readonly api: number;
-  /** The instance itself; another bundle's object, so callers check it before use. */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle on the page
-  readonly instance: unknown;
-}
-
-/** The registry on `window.__DG__`. */
-export type DgGlobals = { [K in SingletonName]?: SingletonRecord };
-
-/** The v1 window names, kept as aliases. */
-export const LEGACY_GLOBAL_NAMES = { input: '__HUB_INPUT__', daily: '__HUB_DAILY__', rt: '__HUB_RT__' } as const satisfies Record<SingletonName, string>;
-
-declare global {
-  interface Window {
-    __DG__?: DgGlobals;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_INPUT__?: unknown;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_DAILY__?: unknown;
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
-    __HUB_RT__?: unknown;
-  }
-}
-
-/** How to claim a singleton. */
-export interface SingletonClaim<T> {
-  readonly name: SingletonName;
-  /** This bundle's client version. */
-  readonly version: string;
-  /** This bundle's shape number for the singleton. */
-  readonly api: number;
-  /** Make the instance when nobody has yet. */
-  readonly create: () => T;
-  /** Whether a registered instance is usable as `T` (it may come from another bundle). */
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: checks another bundle's object
-  readonly isInstance: (candidate: unknown) => candidate is T;
-  /**
-   * The registered one has a different `api`: return `true` to replace it
-   * with this bundle's instance, `false` to keep it (then `create` makes a
-   * private instance for this bundle only). Default: keep it.
-   */
-  readonly onMismatch?: (registered: SingletonRecord) => boolean;
-}
-
-const warnedMismatches = new Set<SingletonName>();
-
-/** The page registry, created on first use (`undefined` outside a browser). */
-function registryOf(page: Window | undefined): DgGlobals | undefined {
-  if (page === undefined) {
-    return undefined;
-  }
-  page.__DG__ ??= {};
-  return page.__DG__;
-}
-
-/** Register (or join) a page-wide singleton and return the instance this bundle should use. */
-export function claimSingleton<T>(claim: SingletonClaim<T>): T {
-  const page = typeof window === 'undefined' ? undefined : window;
-  const registry = registryOf(page);
-  if (page === undefined || registry === undefined) {
-    return claim.create();
-  }
-  const registered = registry[claim.name];
-  if (registered !== undefined && claim.isInstance(registered.instance)) {
-    if (registered.api === claim.api) {
-      return registered.instance;
-    }
-    if (!warnedMismatches.has(claim.name)) {
-      warnedMismatches.add(claim.name);
-      // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
-      console.warn(`[hub] two clients on this page disagree on "${claim.name}" (v${registered.version} api ${String(registered.api)}, v${claim.version} api ${String(claim.api)}). Fix: npm update @diffenderfer-games/hub`);
-    }
-    if (claim.onMismatch?.(registered) !== true) {
-      return claim.create();
-    }
-  } else {
-    const legacy = page[LEGACY_GLOBAL_NAMES[claim.name]];
-    if (registered === undefined && claim.isInstance(legacy)) {
-      // A v1 vendored copy got there first: share it, as v1 bundles did.
-      return legacy;
-    }
-  }
-  const instance = claim.create();
-  registry[claim.name] = { version: claim.version, api: claim.api, instance };
-  page[LEGACY_GLOBAL_NAMES[claim.name]] = instance;
-  return instance;
-}
+/**
+ * Page-wide singletons across client versions (plan §4.4). One page often
+ * runs two client builds: the game's bundled copy and the host's injected
+ * `/_hub/hub.js`. The input system, daily challenges and the realtime API
+ * must exist once per page, so each is registered here with the version that
+ * created it and a small `api` number that changes only when the
+ * cross-bundle shape does.
+ *
+ * - Same `api`: the first creator wins and everyone shares it.
+ * - Different `api`: the caller decides who owns the page (see
+ *   {@link claimSingleton}'s `onMismatch`); the mismatch is logged once with the fix.
+ * - The v1 names (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
+ *   aliases while vendored v1 copies are still around.
+ */
+
+/** A page-wide singleton's name. */
+export type SingletonName = 'input' | 'daily' | 'rt';
+
+/** One registered singleton. */
+export interface SingletonRecord {
+  /** The client version that created it. */
+  readonly version: string;
+  /** Its cross-bundle shape number. */
+  readonly api: number;
+  /** The instance itself; another bundle's object, so callers check it before use. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle on the page
+  readonly instance: unknown;
+}
+
+/** The registry on `window.__DG__`. */
+export type DgGlobals = { [K in SingletonName]?: SingletonRecord };
+
+/** The version recorded for a singleton adopted from a v1 (vendored) client, which predates the registry. */
+export const V1_CLIENT_VERSION = 'v1';
+
+/** The v1 window names, kept as aliases. */
+export const LEGACY_GLOBAL_NAMES = { input: '__HUB_INPUT__', daily: '__HUB_DAILY__', rt: '__HUB_RT__' } as const satisfies Record<SingletonName, string>;
+
+declare global {
+  interface Window {
+    __DG__?: DgGlobals;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_INPUT__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_DAILY__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_RT__?: unknown;
+  }
+}
+
+/** How to claim a singleton. */
+export interface SingletonClaim<T> {
+  readonly name: SingletonName;
+  /** This bundle's client version. */
+  readonly version: string;
+  /** This bundle's shape number for the singleton. */
+  readonly api: number;
+  /** Make the instance when nobody has yet. */
+  readonly create: () => T;
+  /** Whether a registered instance is usable as `T` (it may come from another bundle). */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: checks another bundle's object
+  readonly isInstance: (candidate: unknown) => candidate is T;
+  /**
+   * The registered one has a different `api`: return `true` to replace it
+   * with this bundle's instance, `false` to keep it (then `create` makes a
+   * private instance for this bundle only). Default: keep it.
+   */
+  readonly onMismatch?: (registered: SingletonRecord) => boolean;
+}
+
+const warnedMismatches = new Set<SingletonName>();
+
+/** The page registry, created on first use (`undefined` outside a browser). */
+function registryOf(page: Window | undefined): DgGlobals | undefined {
+  if (page === undefined) {
+    return undefined;
+  }
+  page.__DG__ ??= {};
+  return page.__DG__;
+}
+
+/** Register (or join) a page-wide singleton and return the instance this bundle should use. */
+export function claimSingleton<T>(claim: SingletonClaim<T>): T {
+  const page = typeof window === 'undefined' ? undefined : window;
+  const registry = registryOf(page);
+  if (page === undefined || registry === undefined) {
+    return claim.create();
+  }
+  const registered = registry[claim.name];
+  if (registered !== undefined && claim.isInstance(registered.instance)) {
+    if (registered.api === claim.api) {
+      return registered.instance;
+    }
+    if (!warnedMismatches.has(claim.name)) {
+      warnedMismatches.add(claim.name);
+      // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
+      console.warn(`[hub] two clients on this page disagree on "${claim.name}" (v${registered.version} api ${String(registered.api)}, v${claim.version} api ${String(claim.api)}). Fix: npm update @diffenderfer-games/hub`);
+    }
+    if (claim.onMismatch?.(registered) !== true) {
+      return claim.create();
+    }
+  } else {
+    const legacy = page[LEGACY_GLOBAL_NAMES[claim.name]];
+    if (registered === undefined && claim.isInstance(legacy)) {
+      // A v1 vendored copy got there first: share it, as v1 bundles did, and
+      // record it so later bundles (and diagnostics) see which client owns it.
+      registry[claim.name] = { version: V1_CLIENT_VERSION, api: claim.api, instance: legacy };
+      return legacy;
+    }
+  }
+  const instance = claim.create();
+  registry[claim.name] = { version: claim.version, api: claim.api, instance };
+  page[LEGACY_GLOBAL_NAMES[claim.name]] = instance;
+  return instance;
+}

package/src/index.ts

@@ -1,50 +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 until it is back.
- *
- * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
- * `hub.daily`, `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,
-  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 type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
-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';