@fabi-play/protocol 0.1.0 → 0.2.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

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;
@@ -500,7 +526,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,12 +555,17 @@ 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;
 }
 /** The backdrops a game may declare in its manifest (its own background is always supported). */
 export type GameBackdrop = Exclude<Backdrop, "none">;
@@ -543,6 +578,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,7 +201,7 @@ 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"];
@@ -109,15 +244,84 @@ 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.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 +346,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 +380,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 +399,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 +416,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 +543,11 @@ export {
   DEFAULT_AVATARS,
   DEFAULT_AVATARS_BY_AGE,
   DEVICE_TIERS,
+  FABI_VOICE,
   GAME_BACKDROPS,
+  INTRO_MAX_CHARS,
+  INTRO_MAX_STEPS,
+  INTRO_MOVES,
   LANDMARKS,
   MAX_AVATAR_LENGTH,
   MAX_PLAYERS,
@@ -349,6 +572,7 @@ export {
   defaultAvatarFor,
   encodePose,
   gamesFor,
+  introText,
   isAgeRange,
   isAvatarName,
   isBody,
@@ -362,6 +586,7 @@ export {
   parseFov,
   parseGameMessage,
   parseGameStats,
+  parseIntro,
   parseManifest,
   parseScreenMessage,
   parseView,
@@ -372,6 +597,9 @@ export {
   sizeForInches,
   toPlayerSpace,
   toScreen,
+  voiceKey,
+  voiceKeySync,
+  voiceUrl,
   wire,
   youngest
 };

package/fabi-play.schema.json

@@ -63,9 +63,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 +77,83 @@
       "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"] }
+    },
+    "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.2.0",
   "description": "Messages between the phone, the screen and the games, with their checks.",
   "keywords": [
     "fabi-play",