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

package/src/avatar/render/walker.ts

@@ -1,48 +1,60 @@
 /**
- * The world walker (`figure: 'walker'`): a small full-body character for
- * maps and crowds, with legs, arms, a shirt, trousers and shoes, and the
- * head drawn smaller on top ({@link WALKER_HEAD_SCALE}). It takes the blob's
- * pose names: `walk` and `run` swing the legs and arms along the facing,
- * `sit` folds the legs over a seat, `idle` breathes, `wave` and `cheer` lift
- * the arms.
+ * The world walker (`figure: 'walker'`): a small, chunky, chibi-like
+ * full-body character for maps and crowds: a short round body with stubby
+ * legs and arms, a shirt, trousers and shoes, and a big head on top
+ * ({@link WALKER_HEAD_SCALE}). It takes the blob's pose names: `walk` and
+ * `run` waddle (quick steps that bounce and rock from foot to foot), `sit`
+ * folds the legs over a seat, `idle` breathes, `wave` and `cheer` lift the
+ * arms.
  *
  * Standing, the origin is the feet. Sitting (`sit`, `play`), the origin is
- * the seat: the hips rest on it and the feet hang {@link WALKER_SEAT_DROP}
- * units below, on the floor in front of it.
+ * the seat: the hips rest on it and the short legs dangle over its front
+ * edge, the feet {@link WALKER_SEAT_DROP} units below it.
  */
-import { ellipse, type SceneNode } from '../scene';
+import { ellipse, g, rot, type SceneNode } from '../scene';
 import type { BodyLayout } from './body';
 import type { Colours } from './colours';
 import type { BodyPose } from './types';
 import { hand, hips, limb, neck, outfitFor, shirt, shoe, type Outfit, type Vec } from './walker-parts';
 
 /** The head's scale on a walker (the blob draws it at 1). */
-export const WALKER_HEAD_SCALE = 0.58;
+export const WALKER_HEAD_SCALE = 0.62;
 
-/** How far below the seat a sitter's feet reach (rig units). */
-export const WALKER_SEAT_DROP = 26;
+/** How far below the seat a sitter's dangling feet reach (rig units): short legs swing clear of the floor. */
+export const WALKER_SEAT_DROP = 13;
 
 /** Heights of the hips, shoulders and head centre above the origin. */
-interface Heights {
+export interface WalkerHeights {
   readonly hip: number;
   readonly shoulder: number;
   readonly head: number;
 }
 
-const STANDING: Heights = { hip: -35, shoulder: -72, head: -103 };
-const SEATED: Heights = { hip: -3, shoulder: -40, head: -71 };
-const LEG = 32;
-const UPPER_ARM = 13;
-const FOREARM = 12;
-const LEG_W = 10.5;
-const SLEEVE_W = 10;
-const ARM_W = 7.5;
+/** Standing: a short, round body (half the first walker's 72 units to the shoulders) under the head. */
+export const WALKER_STANDING: WalkerHeights = { hip: -18, shoulder: -38, head: -70 };
+const SEATED: WalkerHeights = { hip: -3, shoulder: -23, head: -55 };
+const LEG = 18;
+const UPPER_ARM = 8;
+const FOREARM = 7;
+const LEG_W = 13;
+const SLEEVE_W = 12.5;
+const ARM_W = 9;
+/** How far out the hips and shoulders sit from the middle. */
+const HIP_X = 7.5;
+const SHOULDER_X = 19;
+/** The seated thigh, along the facing. */
+const THIGH = 9;
 const DEG = Math.PI / 180;
 
-/** A walker's layout: the blob's fields plus where the head goes and its scale. */
+/** The contact shadow's half-width under a walker (the round body is wide). */
+export const WALKER_SHADOW = 22;
+
+/** A walker's layout: the blob's fields plus where the head goes, its scale and the long-hair split. */
 export interface WalkerLayout extends BodyLayout {
   readonly headY: number;
   readonly headScale: number;
+  /** The shoulder line in head space: long hair below it hangs behind the body. */
+  readonly shoulderLine: number;
 }
 
 /** One side of the body: −1 is the character's right, +1 its left. */
@@ -64,7 +76,7 @@ interface View {
 function viewOf(angleDeg: number): View {
   const side = Math.sin(angleDeg * DEG);
   const front = Math.cos(angleDeg * DEG);
-  return { side, front, forward: [side, front * 0.45], isBack: angleDeg > 90, width: 1 - 0.36 * Math.abs(side) };
+  return { side, front, forward: [side, front * 0.45], isBack: angleDeg > 90, width: 1 - 0.26 * Math.abs(side) };
 }
 
 /** A body side's screen x for a lateral distance (sides overlap when turned). */
@@ -82,64 +94,87 @@ interface Limbs {
   readonly arm: (sideOf: Side) => readonly [Vec, Vec, Vec];
 }
 
-function standingLimbs(v: View, h: Heights, pose: BodyPose, phase: number, bob: number): Limbs {
-  const isRun = pose === 'run';
-  const isWalking = pose === 'walk' || isRun || pose === 'dance';
-  const stride = isRun ? 38 : 27;
-  const swingOf = (sideOf: Side): number => (isWalking ? Math.sin((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2) : 0);
+/** The walk's and run's step: stride angle, foot lift, bounce and side-to-side rock (degrees). */
+const GAIT = {
+  walk: { stride: 36, lift: 3.6, bounce: 3.2, rock: 5 },
+  run: { stride: 46, lift: 5.4, bounce: 4.4, rock: 3.5 },
+} as const;
+
+/** A gait's numbers. */
+type Gait = (typeof GAIT)[keyof typeof GAIT];
+
+/** The gait a pose steps with, if it steps. */
+function gaitOf(pose: BodyPose): Gait | null {
+  return pose === 'run' ? GAIT.run : pose === 'walk' || pose === 'dance' ? GAIT.walk : null;
+}
+
+/** A shoulder joint: out at the torso's edge (narrower when turned), nudged along the facing. */
+const shoulderAt = (v: View, h: WalkerHeights, sideOf: Side, bob: number): Vec => [lateralX(v, sideOf, SHOULDER_X * v.width) + v.forward[0] * 1.5, h.shoulder + 4 + bob];
+
+function standingLimbs(v: View, h: WalkerHeights, pose: BodyPose, phase: number, bob: number): Limbs {
+  const gait = gaitOf(pose);
+  const stepOf = (sideOf: Side): number => (phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2;
+  const swingOf = (sideOf: Side): number => (gait ? Math.sin(stepOf(sideOf)) : 0);
   return {
     leg: (sideOf) => {
-      const hip: Vec = [lateralX(v, sideOf, 6), h.hip + bob];
-      const swing = swingOf(sideOf);
-      const lift = isWalking ? Math.max(0, Math.cos((phase + (sideOf === 1 ? 0 : 0.5)) * Math.PI * 2)) * (isRun ? 7 : 4.5) : 0;
-      const reach = Math.sin(stride * DEG) * LEG * swing;
+      const hip: Vec = [lateralX(v, sideOf, HIP_X), h.hip + bob];
+      const lift = gait ? Math.max(0, Math.cos(stepOf(sideOf))) * gait.lift : 0;
+      const reach = gait ? Math.sin(gait.stride * DEG) * LEG * swingOf(sideOf) : 0;
       const foot: Vec = [hip[0] + v.forward[0] * reach, -bob * 0.2 + v.forward[1] * reach - lift];
-      const knee: Vec = [(hip[0] + foot[0]) / 2 + v.forward[0] * lift * 0.9, (hip[1] + foot[1]) / 2 + v.forward[1] * lift * 0.9];
+      const knee: Vec = [(hip[0] + foot[0]) / 2 + v.forward[0] * lift, (hip[1] + foot[1]) / 2 + v.forward[1] * lift];
       return [hip, knee, foot];
     },
     arm: (sideOf) => {
-      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4 + bob];
-      const out = sideOf * v.front * 2.2;
+      const shoulder = shoulderAt(v, h, sideOf, bob);
+      // The arms stand off the round belly.
+      const out = sideOf * v.front * 3.4;
       if (pose === 'cheer' || (pose === 'wave' && sideOf === -1)) {
-        const wave = pose === 'wave' ? Math.sin(phase * Math.PI * 2) * 4 : 0;
-        const elbow: Vec = [shoulder[0] + out * 3, shoulder[1] - 10];
-        return [shoulder, elbow, [elbow[0] + out * 1.5 + wave, elbow[1] - 12]];
+        const wave = pose === 'wave' ? Math.sin(phase * Math.PI * 2) * 3 : 0;
+        const elbow: Vec = [shoulder[0] + out * 2.2, shoulder[1] - 7];
+        return [shoulder, elbow, [elbow[0] + out * 0.8 + wave, elbow[1] - 10]];
       }
-      const swing = isWalking ? -swingOf(sideOf) * (isRun ? 1.3 : 1) : Math.sin(phase * Math.PI * 2) * 0.06;
-      const reach = Math.sin(24 * DEG) * swing;
+      const swing = gait ? -swingOf(sideOf) * (pose === 'run' ? 1.4 : 1.1) : Math.sin(phase * Math.PI * 2) * 0.06;
+      const reach = Math.sin(30 * DEG) * swing;
       const elbow: Vec = [shoulder[0] + out + v.forward[0] * UPPER_ARM * reach * 0.6, shoulder[1] + UPPER_ARM + v.forward[1] * UPPER_ARM * reach];
-      const wrist: Vec = [elbow[0] + out * 0.4 + v.forward[0] * FOREARM * reach * 1.6, elbow[1] + FOREARM - Math.abs(reach) * 3 + v.forward[1] * FOREARM * reach];
+      const wrist: Vec = [elbow[0] + out * 0.35 + v.forward[0] * FOREARM * reach * 1.6, elbow[1] + FOREARM - Math.abs(reach) * 2 + v.forward[1] * FOREARM * reach];
       return [shoulder, elbow, wrist];
     },
   };
 }
 
-function seatedLimbs(v: View, h: Heights, pose: BodyPose): Limbs {
-  const thigh: Vec = [v.forward[0] * 15, v.forward[1] * 16];
+function seatedLimbs(v: View, h: WalkerHeights, pose: BodyPose): Limbs {
+  const thigh: Vec = [v.forward[0] * THIGH, v.forward[1] * (THIGH + 1)];
   return {
     leg: (sideOf) => {
-      const hip: Vec = [lateralX(v, sideOf, 6), h.hip];
+      const hip: Vec = [lateralX(v, sideOf, HIP_X), h.hip];
       const knee = add(hip, thigh);
-      return [hip, knee, [knee[0] + v.forward[0] * 3, WALKER_SEAT_DROP - 2]];
+      return [hip, knee, [knee[0] + v.forward[0] * 2, WALKER_SEAT_DROP - 2]];
     },
     arm: (sideOf) => {
-      const shoulder: Vec = [lateralX(v, sideOf, 15.5 * v.width) + v.forward[0] * 1.5, h.shoulder + 4];
-      const elbow: Vec = [shoulder[0] + sideOf * v.front * 2 + v.forward[0] * 3, shoulder[1] + UPPER_ARM];
-      const lap = add([lateralX(v, sideOf, pose === 'play' ? 4 : 7), h.hip - 4], thigh, pose === 'play' ? 0.9 : 0.6);
+      const shoulder = shoulderAt(v, h, sideOf, 0);
+      const elbow: Vec = [shoulder[0] + sideOf * v.front * 3 + v.forward[0] * 2, shoulder[1] + UPPER_ARM];
+      const lap = add([lateralX(v, sideOf, pose === 'play' ? 4 : 8), h.hip - 3], thigh, pose === 'play' ? 0.9 : 0.6);
       return [shoulder, elbow, lap];
     },
   };
 }
 
+/** The long-hair split in head space: a little above the torso's top edge (the first walker's line sat 12 head units above it). */
+function shoulderLineOf(torsoTop: number, headY: number): number {
+  return (torsoTop - 3 - headY) / WALKER_HEAD_SCALE - 12;
+}
+
 /** The walker's drawing for a pose, at a facing angle (0 = S, 180 = N; west facings are mirrored by the caller). */
 export function walkerLayout(c: Colours, pose: BodyPose, angleDeg: number, phase: number, outfit: Outfit = outfitFor(c)): WalkerLayout {
   const v = viewOf(angleDeg);
   const isSitting = pose === 'sit' || pose === 'play';
-  const h = isSitting ? SEATED : STANDING;
+  const h = isSitting ? SEATED : WALKER_STANDING;
   const cycle = Math.sin(phase * Math.PI * 2);
-  const isWalking = pose === 'walk' || pose === 'run' || pose === 'dance';
-  const hop = pose === 'jump' || pose === 'cheer' ? Math.abs(Math.sin(phase * Math.PI)) * (pose === 'jump' ? 16 : 8) : 0;
-  const bob = isWalking ? -2.2 * (1 - Math.abs(cycle)) : pose === 'idle' ? cycle * 0.6 : 0;
+  const gait = isSitting ? null : gaitOf(pose);
+  const hop = pose === 'jump' || pose === 'cheer' ? Math.abs(Math.sin(phase * Math.PI)) * (pose === 'jump' ? 12 : 6) : 0;
+  // Short legs: a quick, bouncy waddle that rocks from foot to foot.
+  const bob = gait ? -gait.bounce * (1 - Math.abs(cycle)) : pose === 'idle' ? cycle * 0.6 : 0;
+  const rock = gait ? cycle * gait.rock * (0.4 + 0.6 * Math.abs(v.front)) : 0;
   const limbs = isSitting ? seatedLimbs(v, h, pose) : standingLimbs(v, h, pose, phase, bob);
   const o = outfit;
   const [farSide, nearSide]: readonly [Side, Side] = nearness(v, 1) > nearness(v, -1) ? [-1, 1] : [1, -1];
@@ -147,14 +182,15 @@ export function walkerLayout(c: Colours, pose: BodyPose, angleDeg: number, phase
   const lean = v.side * (isSitting ? 0.6 : 1);
   const armNodes = (sideOf: Side): SceneNode[] => {
     const [shoulder, elbow, wrist] = limbs.arm(sideOf);
-    return [...limb([shoulder, elbow, wrist], ARM_W, c.skin, c.skinInk), ...limb([shoulder, add(shoulder, [elbow[0] - shoulder[0], elbow[1] - shoulder[1]], 0.62)], SLEEVE_W, c.body, c.bodyInk), hand(c, wrist)];
+    return [...limb([shoulder, elbow, wrist], ARM_W, c.skin, c.skinInk), ...limb([shoulder, add(shoulder, [elbow[0] - shoulder[0], elbow[1] - shoulder[1]], 0.7)], SLEEVE_W, c.body, c.bodyInk), hand(c, wrist)];
   };
   const legNodes = (sideOf: Side): SceneNode[] => {
     const points = limbs.leg(sideOf);
     const foot = points[2];
     return [...limb(points, LEG_W, o.trousers, o.trousersInk), shoe(foot, v.forward, o)];
   };
-  const torso = shirt(c, v.width, h.shoulder + (isWalking ? bob : 0), h.hip + 3 + (isWalking ? bob : 0), lean, v.isBack);
+  const torsoTop = h.shoulder + bob;
+  const torso = shirt(c, v.width, torsoTop, h.hip + 3 + bob, lean, v.isBack);
   // Seated with our back to us, the arms reach forward and the legs are under the seat: both hide behind the back.
   const isTucked = isSitting && v.isBack;
   const behind: SceneNode[] = isTucked ? [...armNodes(farSide), ...armNodes(nearSide)] : isTurned ? armNodes(farSide) : [];
@@ -163,17 +199,21 @@ export function walkerLayout(c: Colours, pose: BodyPose, angleDeg: number, phase
   const legs = isTucked ? [] : [...legNodes(farSide), ...legNodes(nearSide)];
   const body: SceneNode[] = [
     ...(isLegsFirst ? legs : []),
-    hips(o, v.width, h.hip + (isWalking ? bob : 0)),
-    neck(c, h.shoulder + bob, v.forward[0] * 2),
+    hips(o, v.width, h.hip + bob),
+    neck(c, torsoTop, v.forward[0] * 2),
     ...torso,
     ...(isLegsFirst ? [] : legs),
     ...(isTucked ? [] : isTurned ? armNodes(nearSide) : [...armNodes(-1), ...armNodes(1)]),
   ];
-  const prop = add([0, h.hip - 12], v.forward, 8);
+  // The rock turns the body about the feet; the head rides it and nods with it.
+  const rocked = (nodes: SceneNode[]): SceneNode[] => (rock === 0 || nodes.length === 0 ? nodes : [g(nodes, { tf: [rot(rock)] })]);
+  const headY = h.head + bob * 1.1;
+  const prop = add([0, h.hip - 6], v.forward, 8);
   return {
-    behind, body, front: [],
-    headDx: v.forward[0] * 1.5, headDy: 0, headY: h.head + bob * 1.1, headScale: WALKER_HEAD_SCALE,
-    tilt: isWalking ? v.side * 2 : 0, lift: hop, prop: { x: prop[0], y: prop[1] },
+    behind: rocked(behind), body: rocked(body), front: [],
+    headDx: v.forward[0] * 1.5 - headY * Math.sin(rock * DEG), headDy: 0, headY, headScale: WALKER_HEAD_SCALE,
+    shoulderLine: shoulderLineOf(torsoTop, headY),
+    tilt: (gait ? v.side * 2 : 0) + rock, lift: hop, prop: { x: prop[0], y: prop[1] },
   };
 }
 

package/src/core/hub.ts

@@ -186,6 +186,7 @@ export class Hub extends HubEconomy {
       setNotify: async (id, mode) => { await rest.call('setTurnGameNotify', { id, mode }); },
       rematch: (id) => rest.call('rematchTurnGame', { id }),
       invite: (id, userIds) => rest.call('inviteToTurnGame', { id, userIds: [...userIds] }),
+      kick: (id, seat) => rest.call('kickFromTurnGame', { id, seat }),
       share: (id, share) => rest.call('shareTurnGame', { id, ...share }),
       autoPlay: (id) => rest.call('autoPlayTurn', { id }),
       chat: (id, send) => rest.call('chatInTurnGame', { id, ...send }),

package/src/core/rest/routes.gen.ts

@@ -132,6 +132,7 @@ export const ROUTES = {
   setTurnGameNotify: { method: 'PUT', path: '/turns/:id/notify', query: [], offline: null },
   rematchTurnGame: { method: 'POST', path: '/turns/:id/rematch', query: [], offline: null },
   inviteToTurnGame: { method: 'POST', path: '/turns/:id/invite', query: [], offline: null },
+  kickFromTurnGame: { method: 'POST', path: '/turns/:id/kick', query: [], offline: null },
   shareTurnGame: { method: 'POST', path: '/turns/:id/share', query: [], offline: null },
   autoPlayTurn: { method: 'POST', path: '/turns/:id/auto', query: [], offline: null },
   chatInTurnGame: { method: 'POST', path: '/turns/:id/chat', query: [], offline: null },

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

@@ -71,6 +71,7 @@ export interface TurnGameHost {
   setNotify(id: string, mode: 'on' | 'off'): Promise<void>;
   rematch(id: string): Promise<TurnGameView>;
   invite(id: string, userIds: readonly number[]): Promise<TurnGameView>;
+  kick(id: string, seat: number): Promise<TurnGameView>;
   share(id: string, share: { readonly link?: boolean; readonly public?: boolean }): Promise<TurnGameView>;
   autoPlay(id: string): Promise<TurnGameView>;
   chat(id: string, send: { readonly text?: string; readonly quick?: string }): Promise<TurnChatLine>;
@@ -248,6 +249,15 @@ export class TurnGame<View = GamePayload, Move extends GamePayload = GamePayload
     this.update(await this.host.invite(this.id, userIds));
   }
 
+  /**
+   * Creator: take the player in `seat` out. Before the start their seat opens up
+   * again (an invite is withdrawn); once it has started, the computer plays
+   * the seat for the rest of the game, as when a player leaves.
+   */
+  async kick(seat: number): Promise<void> {
+    this.update(await this.host.kick(this.id, seat));
+  }
+
   /**
    * Whether "Let the computer play for <name>" may work now: another
    * player is due, the hub's hand-over wait (`summary.handOverAt`) has

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

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

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`, `manifest` or `world`. */
-  readonly check: 'version' | 'vendored' | 'manifest' | 'world';
+  /** 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;
 }

package/src/doctor/cli.ts

@@ -12,7 +12,9 @@
  *   `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;
- * - a `game.world.map` file must exist and be a valid `dg-world@1` map within the size limit.
+ * - 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.
  */
@@ -22,6 +24,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 { checkEmbed } from './embed-check';
 import { checkWorld } from './world-check';
 
 const DEFAULT_HUB_URL = 'https://diffenderfer.games';
@@ -82,7 +85,7 @@ async function runDoctor(options: DoctorOptions): Promise<Finding[]> {
   findings.push(...checkVendoredCopies(options.gameDir));
   try {
     const packageJson = readJsonFile(join(options.gameDir, 'package.json'));
-    findings.push(...checkManifest(packageJson), ...checkWorld(options.gameDir, packageJson));
+    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`,
+  }];
+}