@fabi-play/protocol 0.1.0 → 0.3.0

package/README.md

@@ -18,6 +18,36 @@ if ('errors' in result) console.error(result.errors)
 The manifest's JSON Schema: `@fabi-play/protocol/fabi-play.schema.json` (also served next to the SDK on
 https://cdn.fabiplay.app). ESM only, types included, no dependencies. Docs: https://docs.fabiplay.app.
 
+## The game intro
+
+A manifest's optional `intro` (`GameIntro`: 1 to 4 steps, each a sentence over an image or a move) is what Fabi
+says on the TV before calibration; see "Fabi explains your game" in the
+[`@fabi-play/sdk` README](https://www.npmjs.com/package/@fabi-play/sdk). `parseManifest` reports what is wrong with
+it; `parseIntro` gives the intro or null (the TV skips a bad one, unknown fields included), `introText` the
+sentence for a locale and age.
+
+- **Sentences**: up to 90 characters per language, counted as Unicode code points of the NFC form (an emoji is
+  one); no white space at either end; no control characters, lone surrogates or bidirectional controls
+  (U+202A–U+202E, U+2066–U+2069). The JSON Schema says the same, except lone surrogates and the NFC count, which
+  portable JSON Schema regexes can't express: `parseManifest` is the reference.
+- **Paths** (`entry`, a step's `image`): relative to the game's address, no scheme, no leading `/`, no empty, `.` or
+  `..` segments, up to 200 characters; segments of ASCII letters, digits, `_` and `-` (dots inside, not first);
+  extensions in lowercase: `.html` for `entry`, `.jpg` or `.png` for images (`intro/track.jpg`, not
+  `intro/Track.PNG`). No WebP: old TV browsers (WebKit-based Tizen 2.x, webOS 1–2) may not decode it. JPG (quality
+  about 80) for screenshots, PNG only for flat art.
+- **Voice clips**: a sentence's clip is at `voiceUrl(base, voiceKeySync(text, locale))` (`voiceKey` is the same as
+  a promise). The key is the first 32 lowercase hex characters of SHA-256 of the UTF-8 bytes of
+  `` `${FABI_VOICE}\n${locale}\n${t}` `` (`FABI_VOICE` is `fabi-v1`), where `t` is the text in Unicode NFC with
+  JavaScript's `trim()` applied; a valid sentence has no white space around it, so for a generator in any language
+  `t` is just the NFC text. So `voiceKeySync('Salta!', 'it')` is `cbd16ba39816bdc5afd34a3e84082331` and its clip
+  `https://cdn.fabiplay.app/voice/fabi-v1/cbd16ba39816bdc5afd34a3e84082331.mp3`. The SHA-256 is plain JavaScript,
+  synchronous: no `crypto.subtle`, so it works on TV pages served over http, old TV browsers and Node 18 (the
+  package's `engines`).
+- **The phone's buttons**: during the intro the phone sends `{ type: 'intro', action }`, with action `next`,
+  `repeat`, `skip`, or `replay` (from the pause menu: the explanation again); the screen tells it what Fabi is
+  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`.
+
 ## Poses on the wire
 
 The phone streams `{ type: 'pose', t, bodies }` about 30 times a second over an unordered, no-retransmit data
@@ -44,3 +74,21 @@ from this package.
 ## License
 
 Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. See [LICENSE](./LICENSE).
+
+## The TV remote
+
+A manifest's optional `inputs` (`GameInput[]`, from `GAME_INPUTS`: `body`, `remote`; absent `["body"]`, see
+`gameInputs`) says whether the game can be played with the TV remote when there is no phone; `parseManifest`
+requires `body` in it, no repeats and no unknown values. The screen tells the game how a session is played in
+`init.input` (absent `'body'`) and, with `'remote'`, whether the remote points (`init.pointer`, LG's Magic Remote:
+plain pointer and mouse events in the game's page). The screen turns keys into gestures (↑ or OK `jump`, ↓ held
+`squat`/`stand`, ← → lanes, OK twice `clap`, Back the platform's pause) and plays one child at a time: init's
+`players` is the child playing now (one id). Several children take turns only with games whose manifest says `"turns": true`
+(valid only with `remote` in `inputs`; it means the game follows the turn contract; without it, one child only): `init.turns`
+lists every child in turn order (`parseTurnOrder`; absent: `players`). The game plays a round per child; when a
+child's round ends (a crash too) and turns remain, it asks `break('turn')`, and the screen always answers
+`break-start` (its turn screen), `{ type: 'turn', players: [2] }` (exactly one id, the next in the order;
+`parseTurnPlayers` checks its shape) and `break-done`, the next child's puppet recentred in the middle lane. After
+the last round the game ends with every child's scores. `level` and `gameover` breaks never swap players; hosts
+before turns answer `turn` as an unknown reason, at once. Games keep scores by player id. See "Playing with the TV remote" in the
+[`@fabi-play/sdk` README](https://www.npmjs.com/package/@fabi-play/sdk).

package/dist/index.d.ts

@@ -140,6 +140,14 @@ export type ControllerMessage =
 	type: "command";
 	command: "pause" | "resume" | "quit";
 }
+/**
+ * The intro's buttons (see GameIntro): next (the next step), repeat (the step again), skip (straight to
+ * calibration); replay: watch the game's explanation again, from the pause menu.
+ */
+ | {
+	type: "intro";
+	action: "next" | "repeat" | "skip" | "replay";
+}
 /**
  * Mirror mode, the phone's side: 'on' while it sends its camera video to the screen, 'off' when the parent switch
  * is off, 'blocked' when the switch is on but video may not be sent (reason: not the home network, or the game).
@@ -160,11 +168,16 @@ export type ScreenMessage =
 	screen: string;
 	binaryPose?: number[];
 }
-/** What the phone should show: place the phone, step into the circle, playing, paused. */
+/**
+ * What the phone should show: place the phone, step into the circle, playing, paused. intro: true when the current
+ * game has an intro (GameIntro), so the phone can offer the explanation again (the intro message, action 'replay');
+ * absent otherwise, and on screens before the intro.
+ */
  | {
 	type: "phase";
 	phase: Phase;
 	game?: string;
+	intro?: true;
 }
 /** The games for these players, so the phone can pick one too. */
  | {
@@ -180,6 +193,18 @@ export type ScreenMessage =
 	allowed: boolean;
 	reason?: VideoBlock;
 }
+/**
+ * The intro: what Fabi is saying on the TV now, so the phone shows it too (and its next, repeat and skip buttons).
+ * step: 0-based; steps: how many there are, the platform's final "ready" step included; text: the sentence, in the
+ * screen's language and for the children's age; voice: whether a voice clip is playing (false: only the bubble).
+ */
+ | {
+	type: "intro";
+	step: number;
+	steps: number;
+	text: string;
+	voice: boolean;
+}
 /**
  * The screen's size. ask true: the screen is asking «Quanto è grande questa TV?» now (detected: the band read from
  * the TV's model, with model, its name), and the phone shows the same choice. ask false: settled; size is the
@@ -261,7 +286,8 @@ export declare function sizeForInches(inches: number, kind: "tv" | "tablet"): Sc
 export declare const SCREEN_SIZE_KEY = "fabi-play.screen-size";
 /** Where the app keeps «Pausa se un bambino è troppo vicino» ('on' / 'off'; on when missing). */
 export declare const TOO_CLOSE_KEY = "fabi-play.too-close-pause";
-export type Phase = "setup" | "calibrate" | "play" | "pause" | "break" | "end";
+/** intro: Fabi explains the game before calibration (only for games whose manifest has one, see GameIntro). */
+export type Phase = "setup" | "intro" | "calibrate" | "play" | "pause" | "break" | "end";
 export declare const PHASES: Phase[];
 export interface CatalogueGame {
 	id: string;
@@ -281,10 +307,15 @@ export declare const wire: <T extends object>(m: T) => Wire<T>;
 /**
  * Why the game stops, when it asks for a break:
  * - level: a level is over (the best moment);
- * - gameover: the game is over and a new one may start.
- * Never at the game's own pause menu: a child who stops for a moment must not get an ad for it.
- */
-export type BreakReason = "level" | "gameover";
+ * - gameover: the game is over and a new one may start;
+ * - turn: with input 'remote' and turns remaining, the child playing now finished their round (whatever happened in
+ *   it: a crash or a fall ends a round too). The screen always answers with break-start (its turn screen is the
+ *   break, and may host an ad), then turn (the next child), then break-done. Hosts before turns answer it as an
+ *   unknown reason (break-done at once), but they never send turns either.
+ * Only 'turn' ever swaps players; 'level' and 'gameover' never do. Never at the game's own pause menu: a child who
+ * stops for a moment must not get an ad for it.
+ */
+export type BreakReason = "level" | "gameover" | "turn";
 export declare const BREAK_REASONS: BreakReason[];
 /**
  * The movements the host recognises, per player:
@@ -340,7 +371,9 @@ export type Backdrop = "video" | "none";
  * image is cropped to fill the screen), with any backdrop, so avatars and hands are where the children stand (a
  * "virtual mirror"). The screen decides it: with 'video', where the video is drawn (cover or contain); with 'none',
  * the whole image contained at 92% of the viewport's height, bottom-aligned. Games don't compute it: they just use
- * it. Body points are in player space (0–1 of the camera image, already mirrored like the video), so a point p is on
+ * it. It is not fixed: with automatic framing (the default, see GameManifest.framing) the screen zooms in on children
+ * standing far away, up to 1.8×, so the image may reach past every edge; it changes only at calibration and in breaks
+ * (pause, level, turn), never during play, and arrives in a backdrop message. Body points are in player space (0–1 of the camera image, already mirrored like the video), so a point p is on
  * screen at (x + p.x·w, y + p.y·h): see toScreen.
  */
 export interface BackdropView {
@@ -392,6 +425,22 @@ export type HostMessage =
 /** view: where the camera image is, with any backdrop (see BackdropView); absent if the screen doesn't know. */
 /** stats: a debug host (the simulator) asks the game to say how often it draws (stats messages); absent on the TV. */
 /** device: what the screen knows about the device (a starting tier, the display's rate); absent if it knows nothing. */
+/**
+ * input: how this session is played (see GameInput); absent = 'body'. Only games whose manifest lists 'remote' ever
+ * get 'remote'. With 'remote', players is exactly one id: the child playing now (see turn).
+ */
+/**
+ * turns: only with input 'remote', and only to games whose manifest says "turns": true: every child who
+ * will play this game, one id each, in turn order, players[0] first (see parseTurnOrder); absent = players (one
+ * child, no turns). A round per child: at the end of each child's round, while turns remain, the game calls
+ * break('turn'); the screen answers break-start, turn (the next child), break-done. After the last child's round
+ * the game calls end() with every child's scores. An order that is not valid, or doesn't start with players[0],
+ * makes the session one child only.
+ */
+/**
+ * pointer: only with input 'remote', true when the TV's remote also points (LG's Magic Remote): it reaches the game
+ * as ordinary pointer and mouse events (hover, click with OK). Absent = false.
+ */
 {
 	type: "init";
 	v: number;
@@ -404,8 +453,11 @@ export type HostMessage =
 	view?: BackdropView;
 	stats?: boolean;
 	device?: DeviceHint;
+	input?: GameInput;
+	turns?: number[];
+	pointer?: boolean;
 }
-/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit changed). */
+/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
 	type: "backdrop";
 	backdrop: Backdrop;
@@ -444,7 +496,24 @@ export type HostMessage =
  | {
 	type: "break-done";
 	shown: boolean;
+}
+/**
+ * Turns (input 'remote' only): from now on this child plays, in place of the one before. One remote is one child,
+ * so with several children the screen plays one at a time: the same game goes on with the next child in init's
+ * turns (players [2] after [1], …), exactly one id. Sent only inside the break of a break('turn') the game asked
+ * for (after break-start, before break-done); never at other breaks, so a round never changes hands midway. The
+ * new child's puppet starts recentred, in the middle lane (lane 0), with no lane gesture. Ids keep their meaning
+ * (slots, avatars): keep each player's score by id across turns, and end with the scores of every child who
+ * played. Never sent with input 'body', where init's players stay for the whole game.
+ */
+ | {
+	type: "turn";
+	players: number[];
 };
+/** The players of a turn message, or undefined if they are not valid: exactly one integer id from 1 to MAX_PLAYERS. A copy. */
+export declare function parseTurnPlayers(v: unknown): number[] | undefined;
+/** init's turns, or undefined if they are not valid: 1 to MAX_PLAYERS distinct integer ids from 1 to MAX_PLAYERS, in order. A copy. */
+export declare function parseTurnOrder(v: unknown): number[] | undefined;
 /** Why a game is paused (see HostMessage pause). */
 export type PauseReason = "user" | "distance";
 export declare const PAUSE_REASONS: PauseReason[];
@@ -500,7 +569,11 @@ export type Movement = "hands" | "jump" | "squat" | "clap" | "freeze" | "lanes"
  *   "title": { "it": "Acchiappastelle", "en": "Star catcher" },
  *   "description": { "it": "Prendi le stelle con le mani.", "en": "Catch the stars with your hands." },
  *   "ageRanges": ["3-5", "6-8"], "movements": ["hands"], "players": { "min": 1, "max": 2 },
- *   "minutes": 3, "entry": "index.html", "sdk": 1
+ *   "minutes": 3, "entry": "index.html", "sdk": 1,
+ *   "intro": { "steps": [
+ *     { "say": { "it": "Prendi le stelle!", "en": "Catch the stars!" }, "image": "intro/stars.jpg" },
+ *     { "say": { "it": "Alza le braccia!", "en": "Arms up!" }, "move": "arms-up", "practice": true }
+ *   ] }
  * }
  */
 export interface GameManifest {
@@ -525,13 +598,56 @@ export interface GameManifest {
 	};
 	/** Minutes of a typical game, 1 to 20. */
 	minutes: number;
-	/** Page that starts the game, an .html file relative to the game's address (same site, no ".."). */
+	/**
+	 * Page that starts the game: a path relative to the game's address (no scheme, no leading /, no "." or ".."
+	 * segments, up to 200 characters), of letters, digits, _ and -, ending in lowercase .html: index.html, play/index.html.
+	 */
 	entry: string;
 	/** Protocol version of the SDK it was built with: 1 (PROTOCOL_VERSION). */
 	sdk: number;
 	/** Optional: the backdrops it can draw over besides its own; ['video'] opts in to mirror mode. */
 	backdrop?: GameBackdrop[];
+	/** Optional: Fabi explains the game on the TV before calibration (see GameIntro). Absent: straight to calibration. */
+	intro?: GameIntro;
+	/** 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[];
+	/**
+	 * Optional, only with 'remote' in inputs: true when the game follows the turns contract, so the screen may let
+	 * several children play with the remote, a round each (init.turns): play a round with the child in players; when
+	 * it ends (a crash too) and turns remain, ask break('turn') (the screen answers break-start, turn, break-done);
+	 * after the last round, end with every child's scores. Absent or false: remote mode is one child only.
+	 */
+	turns?: boolean;
+	/**
+	 * Optional: 'auto' (the default) lets the screen frame the children: when they stand far from the camera it zooms
+	 * in on them (up to 1.8×), so every child's avatar is about the same size and reaches the same things, near or
+	 * far; the view changes only at calibration and in breaks. 'fixed' keeps the whole camera image, as before (for
+	 * a game drawn on exact spots of the live video).
+	 */
+	framing?: GameFraming;
 }
+/** How the screen frames the camera image for a game: see GameManifest.framing. */
+export type GameFraming = "auto" | "fixed";
+export declare const GAME_FRAMINGS: GameFraming[];
+/** The framing of a manifest, with the default. */
+export declare function gameFraming(m: Pick<GameManifest, "framing">): GameFraming;
+/**
+ * How a game can be played: with the body (camera on the phone), or with the TV remote (keys become gestures).
+ *
+ * 'remote' is for TV apps without a phone (Samsung, LG, Android TV, Fire TV): one remote is one child, and with
+ * several children the screen runs turns, only for games whose manifest says "turns": true (see GameManifest.turns,
+ * BreakReason turn, HostMessage turn). The screen turns keys into the gestures the body makes (↑ or OK jump;
+ * ↓ held squat, stand on release; ← → lanes; OK twice quickly clap; Back is the platform's pause, never the game's)
+ * and animates a puppet body in the frames, so with one child most games need no code. On LG the Magic
+ * Remote also points: it reaches the game as ordinary pointer and mouse events (init.pointer says when). A game that
+ * lists 'remote' must play with those keys alone and, where it has things to pick (bubbles, answers, buttons), let a
+ * pointer click them too (pointer events, large hit areas, a hover highlight). Games aimed with the hands should not
+ * list it unless they offer a selection the keys can drive.
+ */
+export type GameInput = "body" | "remote";
+export declare const GAME_INPUTS: GameInput[];
+/** The inputs of a manifest, with the default. */
+export declare function gameInputs(m: Pick<GameManifest, "inputs">): GameInput[];
 /** The backdrops a game may declare in its manifest (its own background is always supported). */
 export type GameBackdrop = Exclude<Backdrop, "none">;
 export declare const GAME_BACKDROPS: GameBackdrop[];
@@ -543,6 +659,64 @@ export declare function parseManifest(data: unknown): {
 } | {
 	errors: string[];
 };
+/** 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[];
+/** One sentence in every language, or one per age range (each with every language). */
+export type IntroText = Record<Locale, string> | Partial<Record<AgeRange, Record<Locale, string>>>;
+/** One step of the intro: Fabi says one sentence, over an image of the game or a move shown with the avatars. */
+export interface IntroStep {
+	say: IntroText;
+	/**
+	 * An image of the game, 16:9: a path relative to the game's address with the same rules as entry (no scheme, no
+	 * leading /, no "." or ".." segments), ending in lowercase .jpg or .png (no WebP: old TV browsers may not decode it): intro/track.jpg.
+	 */
+	image?: string;
+	/** Or a move, shown with the avatars. Exactly one of image and move. */
+	move?: IntroMove;
+	/** Only with move: the children try it and each gets a tick; the step moves on when all did, or after 8 s. Default false: Fabi only shows it. */
+	practice?: boolean;
+}
+/**
+ * Fabi explains the game on the TV, before calibration, in 1 to 4 steps (the platform adds its own final "ready"
+ * step). Only data: Fabi Play draws it, and speaks each sentence with a voice clip generated at publication from the
+ * text (voiceKey); a text without its clip yet is shown in the bubble only.
+ */
+export interface GameIntro {
+	steps: IntroStep[];
+}
+export declare const INTRO_MAX_STEPS = 4;
+/**
+ * The longest sentence of a step, per language, in Unicode code points of its NFC form (an emoji counts as one, as
+ * in the JSON Schema's maxLength).
+ */
+export declare const INTRO_MAX_CHARS = 90;
+/**
+ * The intro, or null if absent or invalid, unknown fields included (the TV then skips it: a bad intro never blocks
+ * a game). A copy: practice: false is dropped (it is the default).
+ */
+export declare function parseIntro(data: unknown): GameIntro | null;
+/**
+ * The sentence for a locale and age: the age-specific one if present, else (for age-keyed text) the closest range
+ * present (the younger of two as close: simpler words), else the plain one.
+ */
+export declare function introText(say: IntroText, locale: Locale, ageRange: AgeRange): string;
+/** The voice Fabi speaks with; a new voice becomes fabi-v2 and every clip is generated again. */
+export declare const FABI_VOICE = "fabi-v1";
+/**
+ * Key of a voice clip: the first 32 lowercase hex characters of SHA-256 of the UTF-8 bytes of
+ * `${voice}\n${locale}\n${t}` (\n: one U+000A), where t is the text in Unicode NFC, then with JavaScript's
+ * String.prototype.trim applied (it drops white space and line terminators at both ends: Unicode Zs, tab, vertical
+ * tab, form feed, U+FEFF, LF, CR, U+2028, U+2029). A valid intro sentence has none of those around it, so for a
+ * generator in another language t is simply the NFC text. The same text always finds the same clip; a changed text
+ * (or voice) finds none until it is generated, and the TV shows only the bubble meanwhile. Plain JavaScript,
+ * synchronous: no crypto.subtle needed (TV pages over http, old browsers, Node 18).
+ */
+export declare function voiceKeySync(text: string, locale: Locale, voice?: string): string;
+/** voiceKeySync, as a promise (the same key). */
+export declare const voiceKey: (text: string, locale: Locale, voice?: string) => Promise<string>;
+/** URL of a clip: `${base}/voice/${voice}/${key}.mp3` (base without trailing slash, e.g. https://cdn.fabiplay.app; one is dropped). */
+export declare const voiceUrl: (base: string, key: string, voice?: string) => string;
 /** The games for a range and a number of players, in catalogue order. */
 export declare const gamesFor: <T extends Pick<GameManifest, "ageRanges" | "players">>(games: T[], range: AgeRange, players?: number) => T[];
 export declare const isGameId: (v: string) => boolean;

package/dist/index.js

@@ -1,3 +1,138 @@
+// src/sha256.ts
+function utf8(s) {
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i);
+    if (c >= 55296 && c <= 56319 && i + 1 < s.length) {
+      const d = s.charCodeAt(i + 1);
+      if (d >= 56320 && d <= 57343) {
+        c = 65536 + (c - 55296 << 10) + (d - 56320);
+        i++;
+      }
+    }
+    if (c >= 55296 && c <= 57343) c = 65533;
+    if (c < 128) out.push(c);
+    else if (c < 2048) out.push(192 | c >> 6, 128 | c & 63);
+    else if (c < 65536) out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+    else out.push(240 | c >> 18, 128 | c >> 12 & 63, 128 | c >> 6 & 63, 128 | c & 63);
+  }
+  return Uint8Array.from(out);
+}
+var K = Uint32Array.from([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var rotr = (x, n) => x >>> n | x << 32 - n;
+function sha256(bytes) {
+  const blocks = Math.ceil((bytes.length + 9) / 64);
+  const data = new Uint8Array(blocks * 64);
+  data.set(bytes);
+  data[bytes.length] = 128;
+  const view = new DataView(data.buffer);
+  const bits = bytes.length * 8;
+  view.setUint32(data.length - 8, Math.floor(bits / 4294967296));
+  view.setUint32(data.length - 4, bits >>> 0);
+  const h = Uint32Array.from([1779033703, 3144134277, 1013904242, 2773480762, 1359893119, 2600822924, 528734635, 1541459225]);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < data.length; off += 64) {
+    for (let t = 0; t < 16; t++) w[t] = view.getUint32(off + t * 4);
+    for (let t = 16; t < 64; t++) {
+      const a2 = w[t - 15];
+      const b2 = w[t - 2];
+      const s0 = rotr(a2, 7) ^ rotr(a2, 18) ^ a2 >>> 3;
+      const s1 = rotr(b2, 17) ^ rotr(b2, 19) ^ b2 >>> 10;
+      w[t] = w[t - 16] + s0 + w[t - 7] + s1 | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7]];
+    for (let t = 0; t < 64; t++) {
+      const t1 = hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + K[t] + w[t] | 0;
+      const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + t1 | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 | 0;
+    }
+    h[0] = h[0] + a;
+    h[1] = h[1] + b;
+    h[2] = h[2] + c;
+    h[3] = h[3] + d;
+    h[4] = h[4] + e;
+    h[5] = h[5] + f;
+    h[6] = h[6] + g;
+    h[7] = h[7] + hh;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) outView.setUint32(i * 4, h[i]);
+  return out;
+}
+
 // src/index.ts
 var PROTOCOL_VERSION = 1;
 var LANDMARKS = 33;
@@ -66,10 +201,10 @@ function sizeForInches(inches, kind) {
 }
 var SCREEN_SIZE_KEY = "fabi-play.screen-size";
 var TOO_CLOSE_KEY = "fabi-play.too-close-pause";
-var PHASES = ["setup", "calibrate", "play", "pause", "break", "end"];
+var PHASES = ["setup", "intro", "calibrate", "play", "pause", "break", "end"];
 var NS = "fabi-play";
 var wire = (m) => ({ ns: NS, ...m });
-var BREAK_REASONS = ["level", "gameover"];
+var BREAK_REASONS = ["level", "gameover", "turn"];
 function parseView(v) {
   if (!isObject(v)) return void 0;
   const { x, y, w, h } = v;
@@ -92,7 +227,23 @@ function parseGameStats(v) {
   if (DEVICE_TIERS.includes(v.tier)) out.tier = v.tier;
   return out;
 }
+var isPlayerId = (id) => Number.isInteger(id) && id >= 1 && id <= MAX_PLAYERS;
+function parseTurnPlayers(v) {
+  return Array.isArray(v) && v.length === 1 && isPlayerId(v[0]) ? [v[0]] : void 0;
+}
+function parseTurnOrder(v) {
+  if (!Array.isArray(v) || v.length < 1 || v.length > MAX_PLAYERS || !v.every(isPlayerId) || new Set(v).size !== v.length) return void 0;
+  return [...v];
+}
 var PAUSE_REASONS = ["user", "distance"];
+var GAME_FRAMINGS = ["auto", "fixed"];
+function gameFraming(m) {
+  return m.framing ?? "auto";
+}
+var GAME_INPUTS = ["body", "remote"];
+function gameInputs(m) {
+  return m.inputs?.length ? m.inputs : ["body"];
+}
 var GAME_BACKDROPS = ["video"];
 var MOVEMENTS = ["hands", "jump", "squat", "clap", "freeze", "lanes", "shapes"];
 function parseManifest(data) {
@@ -109,15 +260,89 @@ function parseManifest(data) {
   const pl = isObject(m.players) ? m.players : {};
   if (!(isNumber(pl.min) && isNumber(pl.max) && pl.min >= 1 && pl.max <= 4 && pl.min <= pl.max)) errors.push("players: min and max between 1 and 4");
   if (!(isNumber(m.minutes) && m.minutes >= 1 && m.minutes <= 20)) errors.push("minutes: from 1 to 20");
-  if (!(typeof m.entry === "string" && /^[\w./-]+\.html$/.test(m.entry) && !m.entry.includes(".."))) errors.push("entry: an .html page of the game, relative to its address");
+  if (!isGamePath(m.entry, "html")) errors.push("entry: an .html page of the game, a path relative to its address (no scheme, no leading /)");
   if (m.sdk !== PROTOCOL_VERSION) errors.push(`sdk: this version of Fabi Play uses protocol ${PROTOCOL_VERSION}`);
   if (m.backdrop !== void 0 && !(Array.isArray(m.backdrop) && m.backdrop.every((b) => GAME_BACKDROPS.includes(b)) && new Set(m.backdrop).size === m.backdrop.length))
     errors.push(`backdrop: optional, from ${GAME_BACKDROPS.join(", ")}, without repeats`);
+  if (m.inputs !== void 0 && !(Array.isArray(m.inputs) && m.inputs.includes("body") && m.inputs.every((i) => GAME_INPUTS.includes(i)) && new Set(m.inputs).size === m.inputs.length))
+    errors.push(`inputs: optional, from ${GAME_INPUTS.join(", ")}, without repeats, always with body`);
+  if (m.turns !== void 0 && !(typeof m.turns === "boolean" && (!m.turns || Array.isArray(m.inputs) && m.inputs.includes("remote"))))
+    errors.push('turns: 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));
   return errors.length ? { errors } : { manifest: m };
 }
+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;
+var LOCALES = ["it", "en"];
+var STEP_KEYS = ["say", "image", "move", "practice"];
+var UNSPEAKABLE = /[\p{Cc}\p{Cs}\u202A-\u202E\u2066-\u2069]/u;
+var sentence = (v) => typeof v === "string" && v.length > 0 && v === v.trim() && [...v.normalize("NFC")].length <= INTRO_MAX_CHARS && !UNSPEAKABLE.test(v);
+var sentences = (v) => isObject(v) && Object.keys(v).every((k) => LOCALES.includes(k)) && LOCALES.every((l) => sentence(v[l]));
+var isPlainText = (say) => LOCALES.some((l) => l in say);
+function sayErrors(say, path) {
+  const plain = `Italian and English, up to ${INTRO_MAX_CHARS} characters, no spaces around, no control characters`;
+  if (!isObject(say)) return [`${path}: ${plain}`];
+  const keys = Object.keys(say);
+  if (keys.some((k) => LOCALES.includes(k))) return sentences(say) ? [] : [`${path}: ${plain}`];
+  if (keys.length === 0 || !keys.every(isAgeRange)) return [`${path}: ${plain}, or that for one or more of ${AGE_RANGES.join(", ")}`];
+  return keys.flatMap((k) => sentences(say[k]) ? [] : [`${path}.${k}: ${plain}`]);
+}
+function introErrors(intro) {
+  const steps = isObject(intro) ? intro.steps : void 0;
+  if (!(Array.isArray(steps) && steps.length >= 1 && steps.length <= INTRO_MAX_STEPS)) return [`intro: 1 to ${INTRO_MAX_STEPS} steps`];
+  const unknown = Object.keys(intro).filter((k) => k !== "steps").map((k) => `intro.${k}: not a field of intro (only steps)`);
+  return unknown.concat(steps.flatMap((step, i) => {
+    const path = `intro.steps[${i}]`;
+    if (!isObject(step)) return [`${path}: an object with say, and an image or a move`];
+    const errors = Object.keys(step).filter((k) => !STEP_KEYS.includes(k)).map((k) => `${path}.${k}: not a field of a step (${STEP_KEYS.join(", ")})`);
+    errors.push(...sayErrors(step.say, `${path}.say`));
+    const { image, move, practice } = step;
+    if (image !== void 0 && move !== void 0) errors.push(`${path}: an image or a move, not both`);
+    else if (image === void 0 && move === void 0) errors.push(`${path}: an image or a move`);
+    if (image !== void 0 && !isGamePath(image, "jpg|png"))
+      errors.push(`${path}.image: a .jpg or .png of the game, a path relative to its address (no scheme, no leading /)`);
+    if (move !== void 0 && !INTRO_MOVES.includes(move)) errors.push(`${path}.move: one of ${INTRO_MOVES.join(", ")}`);
+    if (practice !== void 0 && typeof practice !== "boolean") errors.push(`${path}.practice: true or false`);
+    else if (practice === true && move === void 0) errors.push(`${path}.practice: only with a move`);
+    return errors;
+  }));
+}
+function parseIntro(data) {
+  if (data === void 0 || introErrors(data).length) return null;
+  const steps = data.steps.map((s) => {
+    const say = s.say;
+    const copy = Object.fromEntries(Object.entries(say).map(([k, v]) => [k, typeof v === "string" ? v : { it: v.it, en: v.en }]));
+    return {
+      say: copy,
+      ...typeof s.image === "string" ? { image: s.image } : { move: s.move },
+      ...s.practice === true ? { practice: true } : {}
+    };
+  });
+  return { steps };
+}
+function introText(say, locale, ageRange) {
+  if (isPlainText(say)) return say[locale] ?? "";
+  const at = AGE_RANGES.indexOf(ageRange);
+  const present = AGE_RANGES.filter((r) => say[r]);
+  const closest = present.reduce((best, r) => best === void 0 || Math.abs(AGE_RANGES.indexOf(r) - at) < Math.abs(AGE_RANGES.indexOf(best) - at) ? r : best, void 0);
+  return closest ? say[closest]?.[locale] ?? "" : "";
+}
+var FABI_VOICE = "fabi-v1";
+function voiceKeySync(text, locale, voice = FABI_VOICE) {
+  const hash = sha256(utf8(`${voice}
+${locale}
+${text.normalize("NFC").trim()}`));
+  return Array.from(hash.subarray(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+var voiceKey = (text, locale, voice = FABI_VOICE) => Promise.resolve(voiceKeySync(text, locale, voice));
+var voiceUrl = (base, key, voice = FABI_VOICE) => `${base.replace(/\/+$/, "")}/voice/${voice}/${key}.mp3`;
 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 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;
 var isBody = (v) => Array.isArray(v) && v.length === LANDMARKS * 3 && v.every(isNumber);
 function parseGameMessage(data) {
@@ -142,6 +367,8 @@ function parseGameMessage(data) {
       return null;
   }
 }
+var COMMANDS = ["pause", "resume", "quit"];
+var INTRO_ACTIONS = ["next", "repeat", "skip", "replay"];
 function parseControllerMessage(data) {
   if (!isObject(data)) return null;
   switch (data.type) {
@@ -174,7 +401,9 @@ function parseControllerMessage(data) {
     case "pick":
       return typeof data.game === "string" && isGameId(data.game) ? { type: "pick", game: data.game } : null;
     case "command":
-      return data.command === "pause" || data.command === "resume" || data.command === "quit" ? { type: "command", command: data.command } : null;
+      return COMMANDS.includes(data.command) ? { type: "command", command: data.command } : null;
+    case "intro":
+      return INTRO_ACTIONS.includes(data.action) ? { type: "intro", action: data.action } : null;
     case "video":
       return VIDEO_STATES.includes(data.state) ? { type: "video", state: data.state, ...VIDEO_BLOCKS.includes(data.reason) ? { reason: data.reason } : {} } : null;
     default:
@@ -191,7 +420,12 @@ function parseScreenMessage(data) {
         return { type: "welcome", v: data.v, screen: data.screen, ...binaryPose.length ? { binaryPose } : {} };
       }
     case "phase":
-      return PHASES.includes(data.phase) ? { type: "phase", phase: data.phase, ...typeof data.game === "string" ? { game: data.game } : {} } : null;
+      return PHASES.includes(data.phase) ? {
+        type: "phase",
+        phase: data.phase,
+        ...typeof data.game === "string" ? { game: data.game } : {},
+        ...data.intro === true ? { intro: true } : {}
+      } : null;
     case "catalogue": {
       if (!Array.isArray(data.games) || data.games.length > 50) return null;
       const games = data.games.flatMap(
@@ -203,6 +437,12 @@ function parseScreenMessage(data) {
       return isNumber(data.ms) ? { type: "vibrate", ms: Math.min(Math.max(data.ms, 0), 500) } : null;
     case "video-allowed":
       return typeof data.allowed === "boolean" ? { type: "video-allowed", allowed: data.allowed, ...VIDEO_BLOCKS.includes(data.reason) ? { reason: data.reason } : {} } : null;
+    case "intro": {
+      const { step, steps, text, voice } = data;
+      if (!(Number.isInteger(step) && Number.isInteger(steps) && typeof text === "string" && typeof voice === "boolean")) return null;
+      const [s, n] = [step, steps];
+      return s >= 0 && s < n && n <= INTRO_MAX_STEPS + 1 ? { type: "intro", step: s, steps: n, text: Array.from(text.trim()).slice(0, 200).join(""), voice } : null;
+    }
     case "screen-size": {
       if (typeof data.ask !== "boolean") return null;
       const zone = parseZone(data.zone);
@@ -324,7 +564,13 @@ export {
   DEFAULT_AVATARS,
   DEFAULT_AVATARS_BY_AGE,
   DEVICE_TIERS,
+  FABI_VOICE,
   GAME_BACKDROPS,
+  GAME_FRAMINGS,
+  GAME_INPUTS,
+  INTRO_MAX_CHARS,
+  INTRO_MAX_STEPS,
+  INTRO_MOVES,
   LANDMARKS,
   MAX_AVATAR_LENGTH,
   MAX_PLAYERS,
@@ -348,7 +594,10 @@ export {
   decodePose,
   defaultAvatarFor,
   encodePose,
+  gameFraming,
+  gameInputs,
   gamesFor,
+  introText,
   isAgeRange,
   isAvatarName,
   isBody,
@@ -362,8 +611,11 @@ export {
   parseFov,
   parseGameMessage,
   parseGameStats,
+  parseIntro,
   parseManifest,
   parseScreenMessage,
+  parseTurnOrder,
+  parseTurnPlayers,
   parseView,
   parseZone,
   poseBytes,
@@ -372,6 +624,9 @@ export {
   sizeForInches,
   toPlayerSpace,
   toScreen,
+  voiceKey,
+  voiceKeySync,
+  voiceUrl,
   wire,
   youngest
 };

package/fabi-play.schema.json

@@ -5,6 +5,10 @@
   "type": "object",
   "required": ["id", "version", "title", "description", "ageRanges", "movements", "players", "minutes", "entry", "sdk"],
   "additionalProperties": false,
+  "anyOf": [
+    { "not": { "required": ["turns"], "properties": { "turns": { "const": true } } } },
+    { "required": ["inputs"], "properties": { "inputs": { "contains": { "const": "remote" } } } }
+  ],
   "properties": {
     "$schema": {
       "type": "string",
@@ -63,9 +67,9 @@
     },
     "entry": {
       "type": "string",
-      "description": "The page that starts the game: an .html file relative to the game's address (same site, no \"..\").",
-      "pattern": "^[\\w./-]+\\.html$",
-      "not": { "pattern": "\\.\\." },
+      "description": "The page that starts the game: a path relative to the game's address (no scheme, no leading /, no \".\" or \"..\" segments, up to 200 characters) of letters, digits, _ and -, ending in lowercase .html.",
+      "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_-]+)*\\.(?:html)$",
+      "maxLength": 200,
       "examples": ["index.html"]
     },
     "sdk": {
@@ -77,9 +81,100 @@
       "description": "Optional: the backdrops the game can draw over besides its own background. [\"video\"] opts in to mirror mode (paint no opaque background while backdrop is 'video').",
       "uniqueItems": true,
       "items": { "enum": ["video"] }
+    },
+    "inputs": {
+      "type": "array",
+      "description": "Optional: how the game can be played; absent = [\"body\"]. Must include \"body\" (Fabi Play is a movement platform). Add \"remote\" to be offered on TVs without a phone: the TV remote's keys become gestures (up or OK jump, down held squat, left and right lanes, OK twice clap), one child at a time; on LG the Magic Remote also points, so let what the game has to pick be clicked too.",
+      "minItems": 1,
+      "uniqueItems": true,
+      "contains": { "const": "body" },
+      "items": { "enum": ["body", "remote"] },
+      "examples": [["body", "remote"]]
+    },
+    "turns": {
+      "type": "boolean",
+      "description": "Optional, true only with \"remote\" in inputs: the game follows the turns contract, so several children may play with the remote, a round each. When a child's round ends (a crash too) and turns remain, the game asks break('turn') (the screen answers break-start, turn, break-done); after the last round it ends with every child's scores. Absent or false: remote mode is one child only."
+    },
+    "framing": {
+      "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)."
+    },
+    "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.",
+      "required": ["steps"],
+      "additionalProperties": false,
+      "properties": {
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": { "anyOf": [{ "$ref": "#/definitions/imageStep" }, { "$ref": "#/definitions/moveStep" }] }
+        }
+      }
     }
   },
   "definitions": {
+    "imageStep": {
+      "type": "object",
+      "description": "A step over an image of the game.",
+      "required": ["say", "image"],
+      "additionalProperties": false,
+      "properties": {
+        "say": { "$ref": "#/definitions/say" },
+        "image": {
+          "type": "string",
+          "description": "An image of the game, 16:9, at least 1280×720: a path relative to the game's address, with the same rules as entry (no scheme, no leading /, no \".\" or \"..\" segments, up to 200 characters), ending in lowercase .jpg or .png (no WebP: old TV browsers may not decode it). JPG (quality about 80) for screenshots, PNG only for flat art.",
+          "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|png)$",
+          "maxLength": 200,
+          "examples": ["intro/track.jpg"]
+        },
+        "practice": { "const": false, "description": "Only with a move." }
+      }
+    },
+    "moveStep": {
+      "type": "object",
+      "description": "A step showing a move with the children's avatars.",
+      "required": ["say", "move"],
+      "additionalProperties": false,
+      "properties": {
+        "say": { "$ref": "#/definitions/say" },
+        "move": {
+          "description": "The move Fabi shows, drawn with each child's avatar.",
+          "enum": ["jump", "squat", "clap", "lane-left", "lane-right", "arms-up", "arms-wide", "arms-v", "star"]
+        },
+        "practice": {
+          "type": "boolean",
+          "description": "true: the children try it and each gets a tick; the step moves on when all did, or after 8 s. Default false: Fabi only shows it."
+        }
+      }
+    },
+    "say": {
+      "description": "What Fabi says: Italian and English, up to 90 characters each; or one such per age range (at least one; the closest range present is used for the others).",
+      "anyOf": [
+        { "$ref": "#/definitions/texts90" },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": false,
+          "properties": {
+            "3-5": { "$ref": "#/definitions/texts90" },
+            "6-8": { "$ref": "#/definitions/texts90" },
+            "9-12": { "$ref": "#/definitions/texts90" }
+          }
+        }
+      ]
+    },
+    "texts90": {
+      "type": "object",
+      "description": "One sentence in Italian and English: up to 90 characters (code points), no white space at either end, no control or bidirectional control characters. Fabi Play's check (parseIntro) also rejects lone surrogates and counts the characters of the NFC form.",
+      "required": ["it", "en"],
+      "additionalProperties": false,
+      "properties": {
+        "it": { "type": "string", "minLength": 1, "maxLength": 90, "pattern": "^[^\\s\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069](?:[^\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069]*[^\\s\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069])?$" },
+        "en": { "type": "string", "minLength": 1, "maxLength": 90, "pattern": "^[^\\s\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069](?:[^\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069]*[^\\s\\u0000-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069])?$" }
+      }
+    },
     "texts60": {
       "type": "object",
       "required": ["it", "en"],

package/package.json

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