@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.11

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` in next/.
+// 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.1';
+export const HUB_CLIENT_VERSION = '2.0.0-next.11';

package/src/daily/daily-system.ts

@@ -9,7 +9,8 @@
  * registered `play` on. Deep links (`/<slug>/?daily=YYYY-MM-DD`) auto-start.
  */
 import { readField } from '../realtime/cross-bundle';
-import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailyStatus } from './types';
+import type { SavedEntry } from '../core/saved/saved-types';
+import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailySaveInput, DailyStartResponse, DailyStatus } from './types';
 
 const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -39,16 +40,32 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** The challenge a start or resume answered. */
+function challengeOf(started: DailyStartResponse): DailyChallenge {
+  return {
+    day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted,
+    instanceId: started.instanceId, saved: started.saved, savedVersion: started.savedVersion, resumed: started.resumed,
+  };
+}
+
 /** Daily challenges (`hub.daily`). */
 export class DailySystem {
   /**
-   * The challenge in progress (set when a day starts, cleared on complete).
-   * A game's win handler checks it: `if (hub.daily.active) hub.daily.complete(…)`.
+   * The challenge in progress: set when a day starts; cleared the moment the
+   * game calls `complete` (whatever the hub answers, and before it answers)
+   * or `cancel` (or `discard`). A game's win handler checks it:
+   * `if (hub.daily.active) hub.daily.complete(…)`. While it is set the page
+   * is in a daily run, so `hub.resume.save` saves to the day instead of the
+   * game's run: a game whose player leaves a daily unfinished must call
+   * `cancel()`.
    */
   active: DailyChallenge | null = null;
   private readonly host: DailyHost;
   private play: DailyDefinition['play'] | null = null;
   private pendingDay: string | null = null;
+  private pendingInstance: string | null = null;
+  /** A start on its way to the hub, so a resume of the same day waits for it instead of starting it twice. */
+  private inFlight: Promise<void> | null = null;
   private isRelaying = false;
 
   constructor(host: DailyHost) {
@@ -80,9 +97,13 @@ export class DailySystem {
   define(definition: DailyDefinition): void {
     this.play = definition.play;
     const day = readDeepLinkDay() ?? this.pendingDay;
+    const instanceId = this.pendingInstance;
     this.pendingDay = null;
+    this.pendingInstance = null;
     if (day !== null) {
       void this.startAndPlay(day);
+    } else if (instanceId !== null) {
+      void this.resume(instanceId);
     }
   }
 
@@ -99,30 +120,112 @@ export class DailySystem {
       this.relayStart(day);
       return;
     }
+    const starting = (async (): Promise<void> => {
+      try {
+        this.begin(play, challengeOf(await this.host.start(day)));
+      } catch (error) {
+        this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+      }
+    })();
+    this.inFlight = starting;
+    await starting;
+    if (this.inFlight === starting) {
+      this.inFlight = null;
+    }
+  }
+
+  /**
+   * Pick up a day in progress by its saved game's id (from `hub.saved`):
+   * a fresh token, then the game's `play` with `challenge.saved`. Finishing
+   * it any time later gives that day's credit. A no-op while that day is
+   * already being played.
+   */
+  async resume(instanceId: string): Promise<void> {
+    // A start may be on its way for the same day (the `?daily=` link of the same open): let it land first.
+    await this.inFlight;
+    if (this.active?.instanceId === instanceId) {
+      return;
+    }
+    const play = this.play;
+    if (play === null) {
+      this.pendingInstance = instanceId;
+      return;
+    }
     try {
-      const started = await this.host.start(day);
-      const challenge: DailyChallenge = { day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted };
-      this.active = challenge;
-      this.host.emit('hub:daily-started', { day: started.day, seed: started.seed, alreadyCompleted: started.alreadyCompleted });
-      play({ ...challenge });
+      this.begin(play, challengeOf(await this.host.resume(instanceId)));
     } catch (error) {
-      this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+      this.host.emit('hub:daily-error', { day: '', error: messageOf(error) });
+    }
+  }
+
+  /** Make `challenge` the active day and hand it to the game. */
+  private begin(play: DailyDefinition['play'], challenge: DailyChallenge): void {
+    this.active = challenge;
+    this.host.emit('hub:daily-started', { day: challenge.day, seed: challenge.seed, alreadyCompleted: challenge.alreadyCompleted === true, resumed: challenge.resumed === true });
+    if (challenge.resumed === true) {
+      this.host.emit('hub:daily-resumed', { day: challenge.day, seed: challenge.seed, alreadyCompleted: false, resumed: true });
     }
+    play({ ...challenge });
+  }
+
+  /**
+   * Save the active day's state, so it can be picked up later (a reload,
+   * another device, next week) and still give that day's credit. Kept on
+   * the device at once and sent after a short quiet spell (works offline).
+   * `hub.resume.save` during a daily lands here too. Returns `false` with
+   * no daily active, or for a replay of a completed day (nothing to save).
+   */
+  save(input: DailySaveInput): boolean {
+    const challenge = this.active;
+    if (challenge === null || challenge.instanceId === null) {
+      return false;
+    }
+    return this.host.save(challenge, input);
+  }
+
+  /** This game's days in progress (the calendar marks them, the game can list them). */
+  inProgress(): Promise<SavedEntry[]> {
+    return this.host.inProgress();
+  }
+
+  /**
+   * Give up the active day: its progress is discarded and nothing is
+   * recorded. The day can be started again fresh while it is in the 30-day
+   * window. (The hub's lists ask the player first; a game asks for itself.)
+   */
+  async discard(): Promise<void> {
+    const challenge = this.active;
+    if (challenge === null) {
+      return;
+    }
+    this.active = null;
+    if (challenge.instanceId !== null) {
+      await this.host.discard(challenge);
+    }
+    this.host.emit('hub:daily-discarded', { day: challenge.day, discarded: true });
   }
 
   /**
    * Record completion of the active challenge with optional metadata.
    * Resolves with the new completion count and rank, or `null` when no
-   * challenge is active or the hub refused.
+   * challenge is active, the hub refused, or the hub can't be reached: then
+   * the completion is queued (`hub:daily-queued`) and replays when it is
+   * back (`hub:daily-complete` follows). The daily run ends at the call,
+   * so `active` is `null` at once, even if the hub then refuses it.
    */
   async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
     const challenge = this.active;
     if (challenge === null) {
       return null;
     }
+    this.active = null;
     try {
       const completed = await this.host.complete(challenge.day, challenge.token, meta);
-      this.active = null;
+      if (completed === null) {
+        // Queued offline: `hub:daily-complete` follows when it replays.
+        this.host.emit('hub:daily-queued', { day: challenge.day, queued: true, meta });
+        return null;
+      }
       this.host.emit('hub:daily-complete', { day: challenge.day, count: completed.count, rank: completed.rank, meta });
       return completed;
     } catch (error) {
@@ -144,9 +247,21 @@ export class DailySystem {
     }
   }
 
-  /** Abandon the active challenge without recording it (e.g. the player quit). */
+  /**
+   * Pause the active day: the player left it unfinished (quit, picked
+   * another level, started a normal game). Nothing is recorded, and the day
+   * stays in progress in "Your games" and the calendar, to finish later
+   * (its last save is sent now). Until then the page counts as in a daily,
+   * so `hub.resume.save` saves to the day: call `cancel()` on every path
+   * that leaves a daily without `complete`. To give a day up, `discard()`.
+   */
   cancel(): void {
+    const challenge = this.active;
     this.active = null;
+    if (challenge !== null) {
+      void this.host.flush().catch(() => undefined);
+      this.host.emit('hub:daily-paused', { day: challenge.day, paused: true });
+    }
   }
 
   /** This game's window and the player's completions. */

package/src/daily/page-daily.ts

@@ -8,8 +8,8 @@ import { hasMethods } from '../realtime/cross-bundle';
 import { DailySystem } from './daily-system';
 import type { DailyHost } from './types';
 
-/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
-export const DAILY_SINGLETON_API = 1;
+/** The cross-bundle shape number of the `daily` singleton (2 added save, resume, discard and inProgress). Bump only on an incompatible change. */
+export const DAILY_SINGLETON_API = 2;
 
 /** Whether `candidate` is some bundle's daily system (v1 copies included). */
 // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle

package/src/daily/types.ts

@@ -3,12 +3,14 @@
  * answers (typed from the contract's daily endpoints).
  */
 import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
+import type { GamePayload } from '../core/game-data';
+import type { SavedEntry } from '../core/saved/saved-types';
 import type { SchemaOutput } from '../realtime/wire-types';
 
 /** The response type of a daily endpoint. */
 type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
 
-/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
+/** This game's daily window, the player's completions and days in progress (`GET /games/:slug/daily`). */
 export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
 
 /** Every daily game and the global standings (`GET /daily`). */
@@ -17,7 +19,7 @@ export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
 /** One game's row in {@link DailyAll}. */
 export type DailyGameStatus = DailyAll['games'][number];
 
-/** The answer to starting a day: its seed and the signed token to present on completion. */
+/** The answer to starting (or resuming) a day: its seed, the signed token to present on completion, and its saved game. */
 export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
 
 /** The answer to completing a day: the player's new completion count and rank. */
@@ -25,26 +27,49 @@ export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
 
 /** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
 export interface DailyChallenge {
-  /** The day, `YYYY-MM-DD`. */
+  /** The day, `YYYY-MM-DD` (a UTC day key). */
   day: string;
   /** Deterministic per game and day. */
   seed: number;
-  /** The signed token `complete` presents. */
+  /** The signed token `complete` presents (empty for a day started offline: it is fetched when the hub is back). */
   token: string;
-  /** The player already completed this day (a replay). */
+  /** The player already completed this day (a replay for fun: nothing is saved or recorded). */
   alreadyCompleted?: boolean;
+  /** The day's saved game; `null` for a replay of a completed day. */
+  instanceId: string | null;
+  /**
+   * The state last saved for this day (`hub.daily.save`, or `hub.resume.save`
+   * during the daily), or `null` when the day starts fresh. A game that
+   * saves restores from it: `if (challenge.saved) startFrom(challenge.saved)`.
+   */
+  saved: GamePayload | null;
+  /** The game's state version of `saved` (0 when none). */
+  savedVersion: number;
+  /** The day was already in progress and was picked up again. */
+  resumed?: boolean;
 }
 
 /** What `hub.daily.define` takes. */
 export interface DailyDefinition {
-  /** Start this challenge now. */
+  /** Start this challenge now (restore `challenge.saved` when it has one). */
   play: (challenge: DailyChallenge) => void;
 }
 
 /** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
 export type DailyCompletionMeta = Record<string, Json>;
 
-/** What the daily system needs from the hub client: the REST calls and its window events. */
+/** A daily state save (the same shape as `hub.resume.save`). */
+export interface DailySaveInput {
+  /** Everything needed to rebuild the day's run (up to 512 KB as JSON). */
+  readonly state: GamePayload;
+  /** A short line ("34 cards left") and an optional 0 to 1 fraction. */
+  readonly progress: { readonly label: string; readonly fraction?: number | null };
+  readonly title?: string | null;
+  /** The game's state version (default 0). */
+  readonly version?: number;
+}
+
+/** What the daily system needs from the hub client: the REST calls, the device copy and its window events. */
 export interface DailyHost {
   /** This page's game slug. */
   readonly slug: string | null;
@@ -52,16 +77,29 @@ export interface DailyHost {
   status(): Promise<DailyStatus>;
   /** `GET /daily`. */
   all(): Promise<DailyAll>;
-  /** `POST /games/:slug/daily/:day/start`. */
+  /** Start (or pick up) a day: `POST /games/:slug/daily/:day/start`, or a device-only start while offline. */
   start(day: string): Promise<DailyStartResponse>;
-  /** `POST /games/:slug/daily/:day/complete`. */
-  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse>;
+  /** Pick a day in progress up again by its saved game's id. */
+  resume(instanceId: string): Promise<DailyStartResponse>;
+  /** `POST /games/:slug/daily/:day/complete`; `null` when it was queued offline, to replay when the hub is back. */
+  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse | null>;
+  /** Keep the day's state on the device at once and send it soon (works offline); `false` when it can't be stored. */
+  save(challenge: DailyChallenge, input: DailySaveInput): boolean;
+  /** Send a waiting save now. */
+  flush(): Promise<void>;
+  /** Give the day up: discard its saved game (works offline). */
+  discard(challenge: DailyChallenge): Promise<void>;
+  /** This game's days in progress (the saved games of kind daily). */
+  inProgress(): Promise<SavedEntry[]>;
   /** Fire a `hub:*` window event (the menu listens). */
   emit(name: string, detail: DailyEventDetail): void;
 }
 
 /** The detail of the `hub:daily-*` window events. */
 export type DailyEventDetail =
-  | { day: string; seed: number; alreadyCompleted: boolean }
+  | { day: string; seed: number; alreadyCompleted: boolean; resumed?: boolean }
   | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
+  | { day: string; queued: true; meta: DailyCompletionMeta }
+  | { day: string; paused: true }
+  | { day: string; discarded: true }
   | { day: string; error: string };

package/src/doctor/checks.ts

@@ -4,7 +4,7 @@
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { GamePackageJson, type HubVersion } from '@diffenderfer-games/hub-contract';
+import { GAME_LABELS, GamePackageJson, splitGameLabels, type HubVersion } from '@diffenderfer-games/hub-contract';
 import { clientSupport } from '../core/version/hub-version';
 import { isHubUnreachable, type HubUnreachable } from './hub-version-fetch';
 
@@ -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`, `world` or `embed`. */
+  readonly check: 'version' | 'vendored' | 'manifest' | 'world' | 'embed';
   /** What to tell the developer, with the fix. */
   readonly message: string;
 }
@@ -68,7 +68,15 @@ export function checkVendoredCopies(gameDir: string): Finding[] {
 export function checkManifest(packageJson: unknown): Finding[] {
   const parsed = GamePackageJson.safeParse(packageJson);
   if (parsed.success) {
-    return [{ level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` }];
+    const unknownLabels = splitGameLabels(parsed.data.game.labels ?? []).unknown;
+    return [
+      { level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` },
+      ...unknownLabels.map((label): Finding => ({
+        level: 'warning',
+        check: 'manifest',
+        message: `game.labels: "${label}" is not a known label (the catalog ignores it); use any of ${GAME_LABELS.join(', ')}`,
+      })),
+    ];
   }
   return parsed.error.issues.map((issue) => ({
     level: 'error',

package/src/doctor/cli.ts

@@ -11,7 +11,10 @@
  *   `/_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;
+ * - a `game.embed.frame` must exist and be a valid, safe frame SVG within the size limit, its screen
+ *   shaped like `game.embed.size` (docs/hub.md "Playing over the world").
  *
  * Exits 1 when any check fails.
  */
@@ -21,6 +24,8 @@ 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 { checkEmbed } from './embed-check';
+import { checkWorld } from './world-check';
 
 const DEFAULT_HUB_URL = 'https://diffenderfer.games';
 
@@ -79,7 +84,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), ...checkEmbed(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/embed-check.ts

@@ -0,0 +1,61 @@
+/**
+ * `hub-doctor`'s embed check (docs/hub.md "Playing over the world"): a
+ * `game.embed.frame` must exist inside the game, be within the size limit
+ * and pass the same sanitiser the hub runs at load (a valid SVG with one
+ * screen rect, nothing that runs or fetches anything); its screen should be
+ * shaped like `game.embed.size`.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { FRAME_LIMITS, GamePackageJson, embedSizeOf, frameAspectMismatch, sanitizeFrameSvg } from '@diffenderfer-games/hub-contract';
+import type { Finding } from './checks';
+
+/** How far the screen's shape may be from `game.embed.size` before a warning. */
+const ASPECT_TOLERANCE = 0.03;
+
+/** Checks the frame `game.embed` 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 checkEmbed(gameDir: string, packageJson: unknown): Finding[] {
+  const parsed = GamePackageJson.safeParse(packageJson);
+  const embed = parsed.success ? parsed.data.game.embed : undefined;
+  if (embed === undefined) {
+    return [];
+  }
+  const size = embedSizeOf(embed.size);
+  const summary = `game.embed: ${embed.supported ? 'plays over the world' : 'opens as its own page from the world'} at ${String(size.w)} × ${String(size.h)}`;
+  if (embed.frame === undefined) {
+    return [{ level: 'info', check: 'embed', message: `${summary}, in the hub's bezel` }];
+  }
+  return [{ level: 'info', check: 'embed', message: summary }, ...checkFrameFile(gameDir, embed.frame, size)];
+}
+
+/** One frame file's findings. */
+export function checkFrameFile(gameDir: string, frameFile: string, size: { readonly w: number; readonly h: number }): Finding[] {
+  const path = join(gameDir, frameFile);
+  const label = `game.embed.frame (${frameFile})`;
+  const error = (message: string): Finding => ({ level: 'error', check: 'embed', message: `${label}: ${message}` });
+  if (!existsSync(path) || !statSync(path).isFile()) {
+    return [error('the file does not exist (commit it)')];
+  }
+  const bytes = statSync(path).size;
+  if (bytes > FRAME_LIMITS.bytes) {
+    return [error(`${String(bytes)} bytes is over the ${String(FRAME_LIMITS.bytes)}-byte limit (simplify the paths or drop embedded data)`)];
+  }
+  const result = sanitizeFrameSvg(readFileSync(path, 'utf8'));
+  const listed = result.problems.map((problem): Finding => ({ level: problem.severity, check: 'embed', message: `${label}: ${problem.message}` }));
+  if (!result.ok) {
+    return listed;
+  }
+  const { viewBox, screen } = result.geometry;
+  const mismatch = frameAspectMismatch(result.geometry, size);
+  if (mismatch > ASPECT_TOLERANCE) {
+    listed.push({
+      level: 'warning', check: 'embed',
+      message: `${label}: the screen is ${screen.w.toFixed(0)} × ${screen.h.toFixed(0)}, ${(mismatch * 100).toFixed(0)} % off the shape of game.embed.size (${String(size.w)} × ${String(size.h)}); the game will be shown at the screen's shape`,
+    });
+  }
+  return [...listed, {
+    level: 'info', check: 'embed',
+    message: `${label} is a valid frame: viewBox ${String(viewBox.w)} × ${String(viewBox.h)}, screen at ${String(screen.x)}, ${String(screen.y)} (${String(screen.w)} × ${String(screen.h)}), ${String(bytes)} bytes`,
+  }];
+}

package/src/doctor/hub-version-fetch.ts

@@ -1,43 +1,43 @@
-/**
- * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
- * hung or unreachable hub fails a game's CI quickly instead of stalling it.
- */
-import { HubVersion } from '@diffenderfer-games/hub-contract';
-
-/** How long the doctor waits for the hub by default, ms. */
-export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
-
-/** The hub could not be asked: down, slow, or answering with an error. */
-export interface HubUnreachable {
-  /** The URL that was asked. */
-  readonly unreachableUrl: string;
-  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
-  readonly reason: string;
-}
-
-/** Whether a version lookup failed. */
-export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
-  return lookup !== null && 'unreachableUrl' in lookup;
-}
-
-/**
- * The hub's version: `null` for a hub from before versioning (404), a
- * {@link HubUnreachable} when it can't be read within `timeoutMs`.
- */
-export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
-  const url = new URL('/_api/version', hubUrl).toString();
-  try {
-    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-    if (response.status === 404) {
-      return null;
-    }
-    if (!response.ok) {
-      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
-    }
-    return HubVersion.parse(await response.json());
-  } catch (failure) {
-    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
-    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
-    return { unreachableUrl: url, reason };
-  }
-}
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}