@fabi-play/protocol 0.4.0 → 0.7.0

package/README.md

@@ -48,6 +48,45 @@ 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.
+
+**Aiming.** `aimPoint(body | frame, side, { orientation, view })` is the one rule for where a hand aims on the
+screen (what it touches), in fractions: in landscape `toScreen(view, wrist)`; in portrait, where the camera image is
+small at the bottom of a phone, the wrist stretched around the shoulders to the whole screen (`HAND_SPACE`, the
+stretch of `PlayerFrame.leftHand`, clamped to 0–1; with the hips unseen the torso is at least
+`TORSO_PER_SHOULDER_WIDTH` shoulder widths). null when the wrist (in portrait, the shoulders too) isn't seen
+(`AIM_VISIBLE`). `AimHold` keeps a lost hand where it was for `AIM_HOLD_MS` (300). The SDK's `play.aim` and the
+engine's `hands()` apply it.
+
+**Safe area.** `init.safeArea` (optional) is what a phone's notch, rounded corners and home bar cover, in fractions
+of the game's viewport: `{ top, bottom, left, right }` (`SafeArea`). `parseSafeArea` clamps each side to 0–0.25
+(`MAX_SAFE_INSET`), 0 when missing; `NO_SAFE_AREA` is all zeros, what hosts that don't send it mean.
+
+## 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;
@@ -591,6 +611,87 @@ export interface BackdropView {
 export declare function parseView(v: unknown): BackdropView | undefined;
 /** A point of player space (a body point) on the game's viewport, in fractions; unchanged without a view. */
 export declare const toScreen: (view: BackdropView | null | undefined, p: Point) => Point;
+/** A hand: the child's own left or right. */
+export type HandSide = "left" | "right";
+/** aimPoint's options: the screen's orientation (absent = 'landscape') and the view (see BackdropView). */
+export interface AimOptions {
+	orientation?: Orientation;
+	view?: BackdropView | null;
+}
+/** A body point counts for aiming when the camera sees it this well (as the avatars and the engine do). */
+export declare const AIM_VISIBLE = 0.5;
+/**
+ * The space the arms reach, around the shoulders, in torsos (shoulders to hips): HAND_SPACE.left and .top from the
+ * shoulders' midpoint, HAND_SPACE.w × HAND_SPACE.h wide and high. It is stretched to the whole screen: the space of
+ * PlayerFrame.leftHand and rightHand (@fabi-play/motion's hands() and handSpace()), and of aimPoint in portrait.
+ */
+export declare const HAND_SPACE: {
+	readonly left: 1.6;
+	readonly top: 1.6;
+	readonly w: 3.2;
+	readonly h: 3;
+};
+/**
+ * The torso when the hips are not seen (a phone close by, hips out of the image, where their points are guesses
+ * clamped to its edge): at least this many shoulder widths, so the stretch does not blow up.
+ */
+export declare const TORSO_PER_SHOULDER_WIDTH = 1.2;
+/**
+ * Where a hand aims on the game's viewport, in fractions (0–1): what the hand touches, picks, catches. One rule for
+ * every game, by orientation:
+ *
+ * - 'landscape' (a TV, a tablet; the default): on the body, toScreen(view, wrist), where the child sees their hand
+ *   (in the video, or the avatar's when body is the smoothed body the avatar is drawn with). Not clamped.
+ * - 'portrait' (a phone held upright): the camera image is small (the view sits at the bottom) and raised hands leave
+ *   it, so the wrist is stretched instead (HAND_SPACE, as PlayerFrame.leftHand): the space the arms reach around the
+ *   shoulders becomes the whole screen, clamped to 0–1. Arms straight up land near the top (y ≈ 0.15), arms out to
+ *   the sides at the edges (x ≈ 0.02 and 0.98), the wrist on the shoulder line at y ≈ 0.53, hands down by the hips
+ *   near the bottom (y ≈ 0.87). The view does not matter. When the hips are not seen the torso is at least
+ *   TORSO_PER_SHOULDER_WIDTH shoulder widths.
+ *
+ * null when the camera doesn't see the wrist well enough (AIM_VISIBLE), and in portrait the shoulders too. Pure:
+ * AimHold keeps a hand that is lost for a moment. Draw on the body with toScreen(wrist); aim with this.
+ */
+export declare function aimPoint(who: Body | Pick<PlayerFrame, "body">, side: HandSide, opts?: AimOptions): Point | null;
+/** How long AimHold keeps a lost hand where it last was, ms: a wrist the camera misses for a few frames. */
+export declare const AIM_HOLD_MS = 300;
+/**
+ * Keeps each hand's aim through short losses: a hand the camera misses for up to holdMs stays where it last was,
+ * so it does not blink out and back (and a touch is not lost and made again). Past that it is gone (null). One per
+ * game; a key per hand, e.g. AimHold.key(player, side).
+ */
+export declare class AimHold {
+	readonly holdMs: number;
+	private readonly last;
+	constructor(holdMs?: number);
+	/** A number for a player's hand. */
+	static key(player: number, side: HandSide): number;
+	/** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+	at(key: number, p: Point | null, t: number): Point | null;
+	/** Forgets every hand. */
+	clear(): void;
+}
+/**
+ * The parts of the game's viewport a phone's notch, rounded corners or home bar may cover, in fractions of the
+ * viewport (top and bottom of its height, left and right of its width; each 0–0.25). The game's frame cannot read
+ * env(safe-area-inset-*), so the screen sends it (init.safeArea): keep buttons, scores and targets out of it, and
+ * still paint the background under it. Zeros where nothing is covered (a TV, a tablet, older hosts).
+ */
+export interface SafeArea {
+	top: number;
+	bottom: number;
+	left: number;
+	right: number;
+}
+/** The largest inset parseSafeArea keeps, a fraction of the viewport. */
+export declare const MAX_SAFE_INSET = 0.25;
+/** No inset: what a game gets from hosts that don't send one. */
+export declare const NO_SAFE_AREA: Readonly<SafeArea>;
+/**
+ * A safe area, or undefined if it is not an object: each of top, bottom, left, right a finite number clamped to
+ * 0–MAX_SAFE_INSET, 0 if missing or not a number. Extra fields are dropped.
+ */
+export declare function parseSafeArea(v: unknown): SafeArea | undefined;
 /** Quality tiers for drawing, best first: what @fabi-play/engine calls engine.tier.name. */
 export type DeviceTier = "high" | "medium" | "low";
 export declare const DEVICE_TIERS: DeviceTier[];
@@ -648,6 +749,15 @@ 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'.
+ */
+/**
+ * safeArea: what a phone's notch, rounded corners and home bar cover, in fractions of the viewport (see SafeArea;
+ * parseSafeArea clamps each side to 0–0.25). Absent (a TV, a tablet, older hosts) = nothing covered.
+ */
 {
 	type: "init";
 	v: number;
@@ -664,6 +774,8 @@ export type HostMessage =
 	turns?: number[];
 	pointer?: boolean;
 	pictures?: boolean;
+	orientation?: Orientation;
+	safeArea?: SafeArea;
 }
 /** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
@@ -868,6 +980,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 +1012,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 +1064,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

@@ -406,6 +406,73 @@ function parseView(v) {
   return isNumber(x) && isNumber(y) && isNumber(w) && isNumber(h) && w > 0 && h > 0 ? { x, y, w, h } : void 0;
 }
 var toScreen = (view, p) => view ? { x: view.x + p.x * view.w, y: view.y + p.y * view.h } : { x: p.x, y: p.y };
+var AIM_VISIBLE = 0.5;
+var HAND_SPACE = { left: 1.6, top: 1.6, w: 3.2, h: 3 };
+var TORSO_PER_SHOULDER_WIDTH = 1.2;
+function aimPoint(who, side, opts = {}) {
+  const body = Array.isArray(who) ? who : who.body;
+  if (!Array.isArray(body)) return null;
+  const w = side === "left" ? P.leftWrist : P.rightWrist;
+  const at = (i) => isNumber(body[i * 3]) && isNumber(body[i * 3 + 1]) && (body[i * 3 + 2] ?? 0) >= AIM_VISIBLE ? i : -1;
+  if (at(w) < 0) return null;
+  const wx = body[w * 3];
+  const wy = body[w * 3 + 1];
+  if (opts.orientation !== "portrait") return toScreen(opts.view, { x: wx, y: wy });
+  if (at(P.leftShoulder) < 0 || at(P.rightShoulder) < 0) return null;
+  const ls = P.leftShoulder * 3;
+  const rs = P.rightShoulder * 3;
+  const sx = (body[ls] + body[rs]) / 2;
+  const sy = (body[ls + 1] + body[rs + 1]) / 2;
+  const lh = P.leftHip * 3;
+  const rh = P.rightHip * 3;
+  const hx = (body[lh] + body[rh]) / 2;
+  const hy = (body[lh + 1] + body[rh + 1]) / 2;
+  let torso = isNumber(hx) && isNumber(hy) ? Math.hypot(hx - sx, hy - sy) : 0;
+  if (at(P.leftHip) < 0 || at(P.rightHip) < 0) torso = Math.max(torso, TORSO_PER_SHOULDER_WIDTH * Math.hypot(body[ls] - body[rs], body[ls + 1] - body[rs + 1]));
+  torso = Math.max(torso, 0.01);
+  return {
+    x: clamp012((wx - sx + HAND_SPACE.left * torso) / (HAND_SPACE.w * torso)),
+    y: clamp012((wy - sy + HAND_SPACE.top * torso) / (HAND_SPACE.h * torso))
+  };
+}
+var AIM_HOLD_MS = 300;
+var AimHold = class {
+  constructor(holdMs = AIM_HOLD_MS) {
+    __publicField(this, "holdMs", holdMs);
+    __publicField(this, "last", /* @__PURE__ */ new Map());
+  }
+  /** A number for a player's hand. */
+  static key(player, side) {
+    return player * 2 + (side === "right" ? 1 : 0);
+  }
+  /** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+  at(key, p, t) {
+    const l = this.last.get(key);
+    if (p) {
+      if (l) {
+        l.x = p.x;
+        l.y = p.y;
+        l.t = t;
+      } else this.last.set(key, { x: p.x, y: p.y, t });
+      return p;
+    }
+    if (!l) return null;
+    if (t - l.t <= this.holdMs) return { x: l.x, y: l.y };
+    this.last.delete(key);
+    return null;
+  }
+  /** Forgets every hand. */
+  clear() {
+    this.last.clear();
+  }
+};
+var MAX_SAFE_INSET = 0.25;
+var NO_SAFE_AREA = Object.freeze({ top: 0, bottom: 0, left: 0, right: 0 });
+function parseSafeArea(v) {
+  if (!isObject(v)) return void 0;
+  const f = (n) => isNumber(n) ? Math.min(Math.max(n, 0), MAX_SAFE_INSET) : 0;
+  return { top: f(v.top), bottom: f(v.bottom), left: f(v.left), right: f(v.right) };
+}
 var DEVICE_TIERS = ["high", "medium", "low"];
 function parseDeviceHint(v) {
   if (!isObject(v)) return void 0;
@@ -440,6 +507,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 +549,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;
@@ -547,6 +632,7 @@ var voiceUrl = (base, key, voice = FABI_VOICE) => `${base.replace(/\/+$/, "")}/v
 var gamesFor = (games, range, players = 1) => games.filter((g) => g.ageRanges.includes(range) && players >= g.players.min && players <= g.players.max);
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var clamp012 = (n) => Math.min(Math.max(n, 0), 1);
 var SEGMENT = "[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*";
 var isGamePath = (v, ext) => typeof v === "string" && v.length <= 200 && new RegExp(`^(?:${SEGMENT}/)*${SEGMENT}\\.(?:${ext})$`).test(v);
 var isGameId = (v) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v) && v.length <= 60;
@@ -611,7 +697,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 +735,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":
@@ -779,7 +868,16 @@ async function migrateStorageKeyAsync(store, newKey, oldKey = legacyStorageKey(n
 }
 export {
   AGE_RANGES,
+  AIM_HOLD_MS,
+  AIM_VISIBLE,
+  AimHold,
   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,
@@ -787,6 +885,7 @@ export {
   GAME_BACKDROPS,
   GAME_FRAMINGS,
   GAME_INPUTS,
+  HAND_SPACE,
   INTRO_MAX_CHARS,
   INTRO_MAX_STEPS,
   INTRO_MOVES,
@@ -797,9 +896,12 @@ export {
   MAX_PICTURE_SIDE,
   MAX_PICTURE_TITLE,
   MAX_PLAYERS,
+  MAX_SAFE_INSET,
   MIRROR_ENABLED,
   MOVEMENTS,
+  NO_SAFE_AREA,
   NS,
+  ORIENTATIONS,
   P,
   PAUSE_REASONS,
   PHASES,
@@ -817,9 +919,11 @@ export {
   SCREEN_SIZES,
   SCREEN_SIZE_KEY,
   TOO_CLOSE_KEY,
+  TORSO_PER_SHOULDER_WIDTH,
   VIDEO_BLOCKS,
   VIDEO_STATES,
   acceptsBinaryPose,
+  aimPoint,
   checkPicture,
   chunkPicture,
   decodePose,
@@ -827,17 +931,22 @@ export {
   encodePose,
   gameFraming,
   gameInputs,
+  gameOrientations,
   gamesFor,
   introText,
   isAgeRange,
   isAvatarName,
   isBody,
+  isCoverAspect,
+  isCoverPath,
   isGameId,
+  isOrientation,
   isPictureId,
   isScreenSizeId,
   legacyStorageKey,
   migrateStorageKey,
   migrateStorageKeyAsync,
+  orientationOf,
   parseControllerMessage,
   parseCursor,
   parseDeviceHint,
@@ -849,6 +958,7 @@ export {
   parsePictureMessage,
   parsePictureResult,
   parsePictureTitle,
+  parseSafeArea,
   parseScreenMessage,
   parseTurnOrder,
   parseTurnPlayers,

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.7.0",
   "description": "Messages between the phone, the screen and the games, with their checks.",
   "keywords": [
     "fabi-play",