@fabi-play/protocol 0.4.0 → 0.5.0

package/README.md

@@ -48,6 +48,33 @@ sentence for a locale and age.
   saying with `{ type: 'intro', step, steps, text, voice }`. Its `phase` message carries `intro: true` when the
   game has an intro: only then does the phone offer `replay`.
 
+## The cover
+
+A manifest's optional `cover` is the game's card in the catalogue: a 16:9 image (1280×720 recommended) of the game's
+own files, `cover.jpg`. `parseManifest` checks the path (`isCoverPath`: relative, no scheme, no leading `/`, no
+backslash, no empty, `.` or `..` segments, `.jpg`, `.jpeg`, `.png` or `.webp` in lowercase, up to `COVER_MAX_PATH`,
+128, characters). The file itself is checked by Fabi Play's review, with the constants exported here:
+`COVER_MAX_BYTES` (150 000), `COVER_ASPECT` (16 / 9) and `COVER_ASPECT_TOLERANCE` (0.02, relative), with
+`isCoverAspect(width, height)`; `COVER_EXTENSIONS` and `COVER_RECOMMENDED` (1280×720) too.
+
+## Orientations
+
+A manifest's optional `orientations` lists the screen orientations a game can be played in (`Orientation`:
+`'landscape' | 'portrait'`, all of them in `ORIENTATIONS`): non-empty, without repeats; absent means
+`['landscape']`, which `gameOrientations(manifest)` applies. A phone alone («Gioca qui / Play here») is held upright
+and offers only games that list `'portrait'`; the TV and the tablet are landscape. The screen says the orientation a
+game starts in with `init.orientation` (`orientationOf(width, height)`: width ≥ height is `'landscape'`); absent from
+older hosts, it means `'landscape'`. It is informational: a game lays out from its real viewport size.
+
+## The carousel on two screens
+
+The phone can show the TV's carousel of games, and both move together. While the grown-up swipes, the phone sends
+`{ type: 'focus', game }` (ControllerMessage) for the card it centred: a preview only, nothing starts (`pick` starts
+a game). The screen centres the same card and says the game's name with its voice (the screen owns the voice; the
+phone stays silent). When the screen's carousel moves for any other reason (the remote, the hand cursor, another
+phone), it sends `{ type: 'focus', game }` (ScreenMessage) and the phones follow. Both are checked like `pick`
+(`isGameId`); a side that doesn't have the game in its catalogue ignores the message.
+
 ## Poses on the wire
 
 The phone streams `{ type: 'pose', t, bodies }` about 30 times a second over an unordered, no-retransmit data

package/dist/index.d.ts

@@ -261,8 +261,9 @@ export declare const MAX_AVATAR_LENGTH = 32;
 export declare const isAvatarName: (v: unknown) => v is string;
 /**
  * The avatars of the four player slots when a child has not picked one, by age band: the first four of each band's
- * own avatars in @fabi-play/avatars (AVATAR_BANDS without the mascot, which is first in every band but is never a
- * default; a test checks they match there; the protocol does not depend on that package).
+ * list in @fabi-play/avatars (AVATAR_BANDS, where the band's own come first; the mascot, Fabi, is the host and in no
+ * band, so never a default, though a child saved with 'mascot' keeps it: any valid id is accepted). A test checks
+ * they match there; the protocol does not depend on that package.
  */
 export declare const DEFAULT_AVATARS_BY_AGE: Readonly<Record<AgeRange, readonly string[]>>;
 /** The slot defaults when the age is not known: 6–8's. */
@@ -320,6 +321,16 @@ export type ControllerMessage =
 	type: "pick";
 	game: string;
 }
+/**
+ * The phone's carousel centred this game's card while the grown-up swipes (the phone shows the TV's carousel and
+ * both move together). Preview only: nothing starts (that is pick). The screen centres the same card and says the
+ * game's name with its voice (the screen owns the voice; the phone stays silent), and tells the other phones with
+ * its own focus message. A screen that does not know the game ignores it.
+ */
+ | {
+	type: "focus";
+	game: string;
+}
 /** Buttons for the grown-up: pause, resume, quit (back to the games). */
  | {
 	type: "command";
@@ -377,6 +388,15 @@ export type ScreenMessage =
  | {
 	type: "catalogue";
 	games: CatalogueGame[];
+}
+/**
+ * The screen's carousel centred this game's card (the remote, the hand cursor, or another phone's focus), so the
+ * phone's carousel follows. Preview only, like the controller's focus: nothing starts. A phone that does not have
+ * the game in its catalogue ignores it.
+ */
+ | {
+	type: "focus";
+	game: string;
 } | {
 	type: "vibrate";
 	ms: number;
@@ -648,6 +668,11 @@ export type HostMessage =
  * pictures: a phone that can save pictures is linked now (its hello said pictures), so the game may send picture
  * messages; it changes with a capabilities message. Absent = false.
  */
+/**
+ * orientation: the screen's orientation when the game starts (width ≥ height: 'landscape', see orientationOf);
+ * only a game whose manifest lists 'portrait' gets 'portrait'. Informational, to choose a layout: lay out from the
+ * real viewport size all the same. Absent (older hosts) = 'landscape'.
+ */
 {
 	type: "init";
 	v: number;
@@ -664,6 +689,7 @@ export type HostMessage =
 	turns?: number[];
 	pointer?: boolean;
 	pictures?: boolean;
+	orientation?: Orientation;
 }
 /** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
@@ -868,6 +894,14 @@ export interface GameManifest {
 	backdrop?: GameBackdrop[];
 	/** Optional: Fabi explains the game on the TV before calibration (see GameIntro). Absent: straight to calibration. */
 	intro?: GameIntro;
+	/**
+	 * Optional: the game's cover, the card in the catalogue (TV carousel, phone, admin): a path relative to the game's
+	 * address (no scheme, no leading /, no "." or ".." segments, no backslash, up to COVER_MAX_PATH characters, see
+	 * isCoverPath), ending in lowercase .jpg, .jpeg, .png or .webp: cover.jpg. A 16:9 image (COVER_ASPECT, within
+	 * COVER_ASPECT_TOLERANCE), recommended 1280×720 and at most COVER_MAX_BYTES; JPEG is the safest for old TV
+	 * browsers. The review checks the file; absent or broken, the catalogue falls back to another image.
+	 */
+	cover?: string;
 	/** Optional: how it can be played; absent = ['body']. Must include 'body' (Fabi Play is a movement platform); add 'remote' to be offered without a phone. */
 	inputs?: GameInput[];
 	/**
@@ -892,7 +926,25 @@ export interface GameManifest {
 	 * false: arrows and OK make gestures.
 	 */
 	remoteCursor?: boolean;
+	/**
+	 * Optional: the screen orientations the game can be played in; absent = ['landscape'] (see gameOrientations).
+	 * Non-empty, without repeats, from ORIENTATIONS. A phone alone («Gioca qui / Play here») is held upright, so it
+	 * offers only games that list 'portrait'; the TV and the tablet are landscape. A game that lists both still lays
+	 * out from its real viewport size; init.orientation says which one it started in.
+	 */
+	orientations?: Orientation[];
 }
+/**
+ * A screen's orientation: 'landscape' when its width is at least its height, else 'portrait' (see orientationOf).
+ * GameManifest.orientations lists those a game supports; HostMessage init.orientation says the one it starts in.
+ */
+export type Orientation = "landscape" | "portrait";
+export declare const ORIENTATIONS: Orientation[];
+export declare const isOrientation: (v: unknown) => v is Orientation;
+/** The orientations of a manifest, with the default (['landscape']). */
+export declare function gameOrientations(m: Pick<GameManifest, "orientations">): Orientation[];
+/** The orientation of a width × height screen: landscape when width ≥ height. */
+export declare const orientationOf: (width: number, height: number) => Orientation;
 /** How the screen frames the camera image for a game: see GameManifest.framing. */
 export type GameFraming = "auto" | "fixed";
 export declare const GAME_FRAMINGS: GameFraming[];
@@ -926,6 +978,34 @@ export declare function parseManifest(data: unknown): {
 } | {
 	errors: string[];
 };
+/** The longest cover path a manifest may give (GameManifest.cover). */
+export declare const COVER_MAX_PATH = 128;
+/** The largest cover file the review accepts, in bytes (150 KB): a 1280×720 JPEG at about quality 80. */
+export declare const COVER_MAX_BYTES = 150000;
+/** A cover's shape: width / height, 16:9. */
+export declare const COVER_ASPECT: number;
+/** How far a cover's width / height may be from COVER_ASPECT, relative to it (0.02: 2%; 1280×720 is exact). */
+export declare const COVER_ASPECT_TOLERANCE = 0.02;
+/** The cover's extensions, lowercase: JPEG, PNG or WebP. */
+export declare const COVER_EXTENSIONS: readonly [
+	"jpg",
+	"jpeg",
+	"png",
+	"webp"
+];
+/** The recommended size of a cover, in pixels. */
+export declare const COVER_RECOMMENDED: {
+	readonly width: 1280;
+	readonly height: 720;
+};
+/**
+ * Whether v is a valid cover path (GameManifest.cover): a path of the game's own files, relative to its address (no
+ * scheme, no leading /, no backslash, no empty, "." or ".." segments; segments of letters, digits, _ and -, dots
+ * inside), up to COVER_MAX_PATH characters, ending in .jpg, .jpeg, .png or .webp (lowercase).
+ */
+export declare const isCoverPath: (v: unknown) => v is string;
+/** Whether an image of width × height pixels has the cover's shape (COVER_ASPECT within COVER_ASPECT_TOLERANCE). */
+export declare const isCoverAspect: (width: number, height: number) => boolean;
 /** The moves an intro step can show; the platform draws them with each child's avatar. Same names the SDK detects. */
 export type IntroMove = "jump" | "squat" | "clap" | "lane-left" | "lane-right" | "arms-up" | "arms-wide" | "arms-v" | "star";
 export declare const INTRO_MOVES: IntroMove[];

package/dist/index.js

@@ -440,6 +440,12 @@ function parseTurnOrder(v) {
   return [...v];
 }
 var PAUSE_REASONS = ["user", "distance"];
+var ORIENTATIONS = ["landscape", "portrait"];
+var isOrientation = (v) => ORIENTATIONS.includes(v);
+function gameOrientations(m) {
+  return m.orientations?.length ? m.orientations : ["landscape"];
+}
+var orientationOf = (width, height) => width >= height ? "landscape" : "portrait";
 var GAME_FRAMINGS = ["auto", "fixed"];
 function gameFraming(m) {
   return m.framing ?? "auto";
@@ -476,8 +482,20 @@ function parseManifest(data) {
     errors.push('remoteCursor: optional, true or false; true only with "remote" in inputs');
   if (m.framing !== void 0 && !GAME_FRAMINGS.includes(m.framing)) errors.push(`framing: optional, ${GAME_FRAMINGS.join(" or ")}`);
   if (m.intro !== void 0) errors.push(...introErrors(m.intro));
+  if (m.cover !== void 0 && !isCoverPath(m.cover))
+    errors.push(`cover: optional, a .jpg, .jpeg, .png or .webp of the game, a path relative to its address (no scheme, no leading /, no ..), up to ${COVER_MAX_PATH} characters`);
+  if (m.orientations !== void 0 && !(Array.isArray(m.orientations) && m.orientations.length > 0 && m.orientations.every(isOrientation) && new Set(m.orientations).size === m.orientations.length))
+    errors.push(`orientations: optional, at least one of ${ORIENTATIONS.join(", ")}, without repeats`);
   return errors.length ? { errors } : { manifest: m };
 }
+var COVER_MAX_PATH = 128;
+var COVER_MAX_BYTES = 15e4;
+var COVER_ASPECT = 16 / 9;
+var COVER_ASPECT_TOLERANCE = 0.02;
+var COVER_EXTENSIONS = ["jpg", "jpeg", "png", "webp"];
+var COVER_RECOMMENDED = { width: 1280, height: 720 };
+var isCoverPath = (v) => typeof v === "string" && v.length <= COVER_MAX_PATH && isGamePath(v, COVER_EXTENSIONS.join("|"));
+var isCoverAspect = (width, height) => isNumber(width) && isNumber(height) && width > 0 && height > 0 && Math.abs(width / height / COVER_ASPECT - 1) <= COVER_ASPECT_TOLERANCE;
 var INTRO_MOVES = ["jump", "squat", "clap", "lane-left", "lane-right", "arms-up", "arms-wide", "arms-v", "star"];
 var INTRO_MAX_STEPS = 4;
 var INTRO_MAX_CHARS = 90;
@@ -611,7 +629,8 @@ function parseControllerMessage(data) {
       if (!isScreenSizeId(data.size)) return null;
       return data.change === true ? { type: "screen-size", size: data.size, change: true } : { type: "screen-size", size: data.size };
     case "pick":
-      return typeof data.game === "string" && isGameId(data.game) ? { type: "pick", game: data.game } : null;
+    case "focus":
+      return typeof data.game === "string" && isGameId(data.game) ? { type: data.type, game: data.game } : null;
     case "command":
       return COMMANDS.includes(data.command) ? { type: "command", command: data.command } : null;
     case "intro":
@@ -648,6 +667,8 @@ function parseScreenMessage(data) {
       );
       return games.length === data.games.length ? { type: "catalogue", games } : null;
     }
+    case "focus":
+      return typeof data.game === "string" && isGameId(data.game) ? { type: "focus", game: data.game } : null;
     case "vibrate":
       return isNumber(data.ms) ? { type: "vibrate", ms: Math.min(Math.max(data.ms, 0), 500) } : null;
     case "video-allowed":
@@ -780,6 +801,12 @@ async function migrateStorageKeyAsync(store, newKey, oldKey = legacyStorageKey(n
 export {
   AGE_RANGES,
   BREAK_REASONS,
+  COVER_ASPECT,
+  COVER_ASPECT_TOLERANCE,
+  COVER_EXTENSIONS,
+  COVER_MAX_BYTES,
+  COVER_MAX_PATH,
+  COVER_RECOMMENDED,
   DEFAULT_AVATARS,
   DEFAULT_AVATARS_BY_AGE,
   DEVICE_TIERS,
@@ -800,6 +827,7 @@ export {
   MIRROR_ENABLED,
   MOVEMENTS,
   NS,
+  ORIENTATIONS,
   P,
   PAUSE_REASONS,
   PHASES,
@@ -827,17 +855,22 @@ export {
   encodePose,
   gameFraming,
   gameInputs,
+  gameOrientations,
   gamesFor,
   introText,
   isAgeRange,
   isAvatarName,
   isBody,
+  isCoverAspect,
+  isCoverPath,
   isGameId,
+  isOrientation,
   isPictureId,
   isScreenSizeId,
   legacyStorageKey,
   migrateStorageKey,
   migrateStorageKeyAsync,
+  orientationOf,
   parseControllerMessage,
   parseCursor,
   parseDeviceHint,

package/fabi-play.schema.json

@@ -113,6 +113,21 @@
       "enum": ["auto", "fixed"],
       "description": "Optional, \"auto\" by default: the screen zooms in on children standing far away (up to 1.8×), so every child's avatar is about the same size near or far; the view changes only at calibration and in breaks, never during play. \"fixed\": always the whole camera image (for a game drawn on exact spots of the live video)."
     },
+    "cover": {
+      "type": "string",
+      "description": "Optional: the game's cover, its card in the catalogue (TV carousel, phone, admin). A 16:9 image (1280×720 recommended, at most 150 KB; JPEG is the safest on old TV browsers): a path relative to the game's address, with the same rules as entry (no scheme, no leading /, no backslash, no \".\" or \"..\" segments), up to 128 characters, ending in lowercase .jpg, .jpeg, .png or .webp. The review checks the file; absent or broken, the catalogue shows another image.",
+      "pattern": "^(?:[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*/)*[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*\\.(?:jpg|jpeg|png|webp)$",
+      "maxLength": 128,
+      "examples": ["cover.jpg"]
+    },
+    "orientations": {
+      "type": "array",
+      "description": "Optional, [\"landscape\"] by default: the screen orientations the game can be played in. A phone alone (Play here) is held upright and offers only games that list \"portrait\"; the TV and the tablet are landscape. Lay out from the real viewport size all the same; the SDK's play.orientation says the one the game started in.",
+      "items": { "enum": ["landscape", "portrait"] },
+      "minItems": 1,
+      "uniqueItems": true,
+      "examples": [["landscape", "portrait"]]
+    },
     "intro": {
       "type": "object",
       "description": "Optional: Fabi explains the game on the TV before calibration, in 1 to 4 steps. Each step: one sentence (Italian and English, up to 90 characters; or one per age range) over an image of the game or a move shown with the children's avatars. The voice is generated by Fabi Play at publication from the text. Without intro the game goes straight to calibration; an invalid one is skipped by the TV.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/protocol",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Messages between the phone, the screen and the games, with their checks.",
   "keywords": [
     "fabi-play",