@fabi-play/protocol 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,741 @@
+// @fabi-play/protocol: Messages between the phone, the screen and the games, with their checks. See https://docs.fabiplay.app.
+// Generated by scripts/build-lib.mjs (fabiplay-kit) from the sources: do not edit.
+
+/**
+ * The messages of Fabi Play, between three parties:
+ *
+ *   phone (controller) ──link──▶ screen (host) ──postMessage──▶ game (sandboxed frame)
+ *
+ * The camera stays on the phone: it sends only body landmarks, never images. The game gets the landmarks and the
+ * movements recognised by the host, and can only answer with what is listed in GameMessage.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/** MediaPipe Pose landmarks: 33 points, the ones the games use by name. */
+export declare const LANDMARKS = 33;
+export declare const P: {
+	readonly nose: 0;
+	readonly leftShoulder: 11;
+	readonly rightShoulder: 12;
+	readonly leftElbow: 13;
+	readonly rightElbow: 14;
+	readonly leftWrist: 15;
+	readonly rightWrist: 16;
+	readonly leftHip: 23;
+	readonly rightHip: 24;
+	readonly leftKnee: 25;
+	readonly rightKnee: 26;
+	readonly leftAnkle: 27;
+	readonly rightAnkle: 28;
+};
+/**
+ * One body: for each landmark x, y (0–1, y downwards) and visibility (0–1), so 33 × 3 numbers.
+ * In "player space": mirrored like a mirror, whatever camera took it, so a child moving to their left moves left.
+ */
+export type Body = number[];
+export type Camera = "back" | "front";
+/** The languages Fabi Play speaks: Italian and English. */
+export type Locale = "it" | "en";
+/**
+ * Age ranges: each has its own games. Only the range is kept, never a birth date: it is all the catalogue and the
+ * games need (simpler rules and no losing for the little ones, scores and challenges for the older ones).
+ */
+export type AgeRange = "3-5" | "6-8" | "9-12";
+/** Every age range, youngest first. */
+export declare const AGE_RANGES: readonly [
+	"3-5",
+	"6-8",
+	"9-12"
+];
+export declare const isAgeRange: (v: unknown) => v is AgeRange;
+/** Children of different ranges play the games of the youngest. */
+export declare const youngest: (ranges: AgeRange[]) => AgeRange;
+/**
+ * Who plays tonight, as chosen on the phone: a first name (it stays in the house), the range, and the avatar the
+ * child picked (an id of @fabi-play/avatars; none: the default of the player's slot, see defaultAvatarFor).
+ */
+export interface Player {
+	name: string;
+	ageRange: AgeRange;
+	avatar?: string;
+}
+export declare const MAX_PLAYERS = 4;
+/**
+ * The colour of each play slot (index 0 is player 1), as the TV draws them: name tags, calibration circles, the
+ * ring of a playing child on the phone. Slots past the fourth wrap around.
+ */
+export declare const PLAYER_COLORS: readonly [
+	"#EE6A43",
+	"#6FA0E0",
+	"#8CC9A0",
+	"#C49BE0"
+];
+/** The longest avatar id the protocol carries. */
+export declare const MAX_AVATAR_LENGTH = 32;
+/**
+ * Whether v looks like an avatar id: kebab-case (lowercase letters and digits, single hyphens), at most 32
+ * characters. The protocol checks only the form; an id the screen or the game does not know falls back to the
+ * slot's default (see defaultAvatarFor), so new avatars can ship to phones before every screen knows them.
+ */
+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).
+ */
+export declare const DEFAULT_AVATARS_BY_AGE: Readonly<Record<AgeRange, readonly string[]>>;
+/** The slot defaults when the age is not known: 6–8's. */
+export declare const DEFAULT_AVATARS: readonly string[];
+/**
+ * The default avatar of a player slot, for the child's age band (6–8 when there is none, or it is not a band):
+ * slot is the 0-based index in the players list, so player id n (frames, gestures) is slot n − 1. Slots past the
+ * fourth wrap around; anything that is not a whole number ≥ 0 gets the band's first.
+ */
+export declare const defaultAvatarFor: (slot: number, ageRange?: AgeRange) => string;
+export type ControllerMessage = 
+/**
+ * aspect: width / height of the camera image, so the screen draws the bodies undistorted. fov: the camera's field
+ * of view for that image (degrees, h across its width, v down its height), when the phone knows it (the app reads
+ * it from the camera); the screen estimates each child's distance with it, or with DEFAULT_FOV when absent.
+ */
+{
+	type: "hello";
+	v: number;
+	camera: Camera;
+	device: string;
+	aspect: number;
+	fov?: Fov;
+}
+/** A camera frame read on the phone: t in ms on the phone's clock, one body per player seen. */
+ | {
+	type: "pose";
+	t: number;
+	bodies: Body[];
+}
+/**
+ * Who plays: the screen shows the games of the youngest range. tooClosePause: the grown-up's choice «Pausa se un
+ * bambino è troppo vicino» (on when absent: phones before it, and the web phone, which has no switch).
+ */
+ | {
+	type: "players";
+	players: Player[];
+	tooClosePause?: boolean;
+}
+/**
+ * The size of the TV, as the grown-up confirmed it on the phone. An answer to the TV's question (change absent)
+ * counts only while the TV still asks: the first confirmation wins, on the TV or on a phone. change: true, a
+ * deliberate change from «Area genitori», always counts.
+ */
+ | {
+	type: "screen-size";
+	size: ScreenSizeId;
+	change?: boolean;
+}
+/** Start a game of the catalogue (again, after the end screen). */
+ | {
+	type: "pick";
+	game: string;
+}
+/** Buttons for the grown-up: pause, resume, quit (back to the games). */
+ | {
+	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).
+ */
+ | {
+	type: "video";
+	state: VideoState;
+	reason?: VideoBlock;
+};
+export type ScreenMessage = 
+/**
+ * binaryPose: the binary pose versions this screen decodes (POSE_CODEC_VERSIONS); the phone streams poses in binary
+ * only when its own version is listed (acceptsBinaryPose), else JSON. Absent on screens before binary poses.
+ */
+{
+	type: "welcome";
+	v: number;
+	screen: string;
+	binaryPose?: number[];
+}
+/**
+ * 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. */
+ | {
+	type: "catalogue";
+	games: CatalogueGame[];
+} | {
+	type: "vibrate";
+	ms: number;
+}
+/** Mirror mode: whether the current game and the screen's own home-network check allow video from the phone. */
+ | {
+	type: "video-allowed";
+	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
+ * confirmed band (absent: not known, e.g. a phone answered elsewhere and the TV forgot), zone the distances (metres)
+ * the children should play at, for the parents' area.
+ */
+ | ScreenSizeNews;
+/**
+ * Mirror mode on or off, for every app at build time: the one switch for the phone's camera video on the TV. On:
+ * the parent's switch on the phone decides, within the rules of docs/test.md section 13. Off: the phones (web page and app) never send video and never open a camera for it, their video switch and
+ * its explanations are hidden, saved switch choices are ignored (kept, not deleted); the TV never allows video, shows
+ * the avatars and tells every game backdrop 'none'; the simulator hides «Mirror (webcam)». All the code stays: set it
+ * to false to turn mirror mode off everywhere (docs/test.md, section 13). The pure mirror logic takes it as a parameter, so
+ * its tests run with mirror mode on whatever this says.
+ */
+export declare const MIRROR_ENABLED: boolean;
+/** Mirror mode: the phone's video full screen on the TV, under the game. */
+export type VideoState = "on" | "off" | "blocked";
+export declare const VIDEO_STATES: VideoState[];
+/**
+ * Why video is blocked: the two ends are not on the same home network ('not-local'), the game paints an opaque
+ * background ('game'), or no game is running ('idle': home, end screen, between games; video is needed only while a
+ * game that supports it runs, so this is not an error).
+ */
+export type VideoBlock = "not-local" | "game" | "idle";
+export declare const VIDEO_BLOCKS: VideoBlock[];
+/** What the screen says about its size (see ScreenMessage). */
+export interface ScreenSizeNews {
+	type: "screen-size";
+	ask: boolean;
+	size?: ScreenSizeId;
+	detected?: ScreenSizeId;
+	model?: string;
+	zone?: Zone;
+}
+/** A camera's field of view, in degrees: h across the image's width, v down its height. */
+export interface Fov {
+	h: number;
+	v: number;
+}
+/** A field of view, or undefined: both angles finite, from 10° to 170°. Extra fields are dropped. */
+export declare function parseFov(v: unknown): Fov | undefined;
+/** Where the children should play, in metres from the screen. */
+export interface Zone {
+	min: number;
+	max: number;
+}
+/** A zone, or undefined: 0 < min < max ≤ 10 m. */
+export declare function parseZone(v: unknown): Zone | undefined;
+/**
+ * The sizes a screen can be, as the grown-up picks them: five TV bands and, for a tablet (or phone) playing alone,
+ * four tablet bands. inches: the diagonal the distances are computed with (the band's largest, so the children
+ * never stand too close for the screen's real size); cm: what is written under it.
+ */
+export type ScreenSizeId = "32" | "40-43" | "50-55" | "65" | "75+" | "phone" | "tablet-8" | "tablet-11" | "tablet-13";
+export interface ScreenSize {
+	id: ScreenSizeId;
+	kind: "tv" | "tablet";
+	/** The diagonal used for the distances, inches. */
+	inches: number;
+	/** As written on the choice: 50–55″. */
+	label: string;
+	/** The diagonal in centimetres, as written under the choice. */
+	cm: string;
+	/** The band's range of diagonals, inches (from, up to): to map a measured diagonal to its band. */
+	range: [
+		number,
+		number
+	];
+}
+export declare const SCREEN_SIZES: readonly ScreenSize[];
+export declare const isScreenSizeId: (v: unknown) => v is ScreenSizeId;
+export declare const screenSize: (id: ScreenSizeId) => ScreenSize;
+/** The bands of one kind of screen, smallest first. */
+export declare const screenSizesOf: (kind: "tv" | "tablet") => ScreenSize[];
+/** The band of a measured or read diagonal (inches), or null when it is outside every band of that kind. */
+export declare function sizeForInches(inches: number, kind: "tv" | "tablet"): ScreenSizeId | null;
+/** Where the TV keeps its confirmed size (the TV page's localStorage, one per TV). */
+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";
+/** 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;
+	title: string;
+}
+/**
+ * Every postMessage between screen and game carries ns: 'fabi-play', so engines and other scripts in the page
+ * (which also use postMessage) never mistake theirs for ours. Engines that don't use the SDK (Unity, Godot) send
+ * the same objects themselves: window.parent.postMessage({ ns: 'fabi-play', type: 'break', reason: 'level' }, '*').
+ */
+export declare const NS = "fabi-play";
+/** A message as it travels: the object plus the ns marker (a literal type, so declaration files need no constant). */
+export type Wire<T> = T & {
+	ns: "fabi-play";
+};
+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";
+export declare const BREAK_REASONS: BreakReason[];
+/**
+ * The movements the host recognises, per player:
+ * - `jump`, then `land` when the feet are back on the ground;
+ * - `squat`, then `stand`;
+ * - `clap`: the hands meet;
+ * - `freeze` (the child stands still, a statue), then `move`;
+ * - `lane-left`, `lane-center`, `lane-right`: a sideways step into a lane (the child's own left, as in a mirror).
+ */
+export type Gesture = "jump" | "land" | "squat" | "stand" | "clap" | "freeze" | "move" | "lane-left" | "lane-center" | "lane-right";
+/** A pose the whole body holds: arms up, arms wide, arms in a V, a star (arms and legs apart), arms down. */
+export type Shape = "arms-up" | "arms-wide" | "arms-v" | "star" | "arms-down";
+/** A point: in player space (0–1 of the camera image, y downwards) or, after toScreen, in fractions of the screen. */
+export interface Point {
+	/** 0 left, 1 right. */
+	x: number;
+	/** 0 top, 1 bottom. */
+	y: number;
+}
+/** One player in a frame the game gets: the body, its hands as pointers, its shape, its avatar. */
+export interface PlayerFrame {
+	/** The player, from 1. */
+	id: number;
+	/** The 33 landmarks, in player space (see Body; P names the indices). */
+	body: Body;
+	/**
+	 * The left hand as a pointer, in fractions of the screen (0–1): the wrist, with the space the arms reach around the
+	 * shoulders stretched to the whole screen and clamped to it, so a child reaches every corner without walking. Not
+	 * where the wrist is on screen: draw on the body with toScreen(wrist). null when the camera doesn't see the wrist (or the child holds Fabi Play's crossed arms).
+	 */
+	leftHand: Point | null;
+	/** The right hand as a pointer, as leftHand. */
+	rightHand: Point | null;
+	/** The pose held right now, if any. */
+	shape: Shape | null;
+	/** Which lane the child stands in: -1 left, 0 centre, 1 right. */
+	lane: -1 | 0 | 1;
+	/**
+	 * The avatar of player id (slot id − 1): the one the child picked on the phone, or the slot's default
+	 * (defaultAvatarFor). It rides on every frame, so a game never misses a change and needs no extra message. Hosts
+	 * before avatars don't send it; the SDK's avatarOf falls back to the slot's default then, and for ids it does not
+	 * know.
+	 */
+	avatar?: string;
+}
+/**
+ * What is behind the game's frame: 'video', the phone's camera video (mirror mode; the game paints no opaque
+ * background), or 'none', the screen's plain background (the game paints its own).
+ */
+export type Backdrop = "video" | "none";
+/**
+ * Where the whole camera image is, in fractions of the game's viewport (0–1; it may reach past the edges when the
+ * 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
+ * screen at (x + p.x·w, y + p.y·h): see toScreen.
+ */
+export interface BackdropView {
+	/** Left edge, a fraction of the viewport's width. */
+	x: number;
+	/** Top edge, a fraction of the viewport's height. */
+	y: number;
+	/** Width, a fraction of the viewport's width. */
+	w: number;
+	/** Height, a fraction of the viewport's height. */
+	h: number;
+}
+/** A view, or undefined if it is not one: finite numbers, w and h above 0. Extra fields are dropped. */
+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;
+/** 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[];
+/**
+ * What the screen knows about the device it runs on (init.device), so a game need not measure it again: each game
+ * has its own origin, so what one game measured and cached is not seen by the next. A hint, not an order: a game
+ * still lowers its tier during play when its frames are slow. Every field is optional; older hosts send none.
+ */
+export interface DeviceHint {
+	/** A starting quality tier: the TV platform's default, or lower when the screen's own drawing fell back to Canvas 2D. */
+	tier?: DeviceTier;
+	/** The display's refresh rate, Hz (50, 60, …), measured by the screen on idle frames. */
+	hz?: number;
+}
+/** A device hint, or undefined if it holds nothing valid: tier one of DEVICE_TIERS, hz from 20 to 240 (rounded). Extra fields are dropped. */
+export declare function parseDeviceHint(v: unknown): DeviceHint | undefined;
+/**
+ * What a game may add to its stats message (debug, only when init said stats): how it draws. renderer is a short
+ * lowercase name ('webgl2', 'webgl1', 'canvas2d', or another engine's own), up to 16 characters.
+ */
+export interface GameStats {
+	/** Frames the game drew in the last second (all of its drawing, not only the avatars). */
+	fps?: number;
+	/** What draws: 'webgl2', 'webgl1', 'canvas2d', … */
+	renderer?: string;
+	/** The quality tier it draws at now. */
+	tier?: DeviceTier;
+}
+/** The valid part of a game's stats (see GameStats); empty if nothing is valid. Extra fields are dropped. */
+export declare function parseGameStats(v: unknown): GameStats;
+/** What the screen (the host) sends to the game. The SDK checks it and hands it out as events. */
+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. */
+{
+	type: "init";
+	v: number;
+	locale: Locale;
+	mode: "tv" | "solo";
+	players: number[];
+	muted: boolean;
+	ageRange: AgeRange;
+	backdrop: Backdrop;
+	view?: BackdropView;
+	stats?: boolean;
+	device?: DeviceHint;
+}
+/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit changed). */
+ | {
+	type: "backdrop";
+	backdrop: Backdrop;
+	view?: BackdropView;
+}
+/** Every camera frame (about 30 a second): t, when it was taken (ms), and each player seen. */
+ | {
+	type: "frame";
+	t: number;
+	players: PlayerFrame[];
+}
+/** A player made a movement (see Gesture). */
+ | {
+	type: "gesture";
+	t: number;
+	player: number;
+	gesture: Gesture;
+}
+/**
+ * The game is paused: stop the clock until resume. reason: 'user', a grown-up (phone, remote) or a child's
+ * crossed arms; 'distance', a child stood too close to the screen for 2 s (it resumes by itself once they are back
+ * in the green zone). Absent from hosts before it: take it as 'user'. Either way Fabi Play draws the pause
+ * itself.
+ */
+ | {
+	type: "pause";
+	reason?: PauseReason;
+} | {
+	type: "resume";
+}
+/** A break starts: mute, stop timers, wait for break-done. */
+ | {
+	type: "break-start";
+}
+/** The answer to break: true if a break was shown; either way the game goes on now. */
+ | {
+	type: "break-done";
+	shown: boolean;
+};
+/** Why a game is paused (see HostMessage pause). */
+export type PauseReason = "user" | "distance";
+export declare const PAUSE_REASONS: PauseReason[];
+/** What the game may send to the screen; anything else is dropped. */
+export type GameMessage = 
+/** Assets loaded: the screen hides its loader. */
+{
+	type: "ready";
+}
+/**
+ * The game has stopped by itself (see BreakReason): Fabi Play may show an ad there, if its rules allow. Never asked
+ * in the middle of play; the answer is always a break-done. 'unknown': a reason we don't take (e.g. 'pause'),
+ * answered at once with no break.
+ */
+ | {
+	type: "break";
+	reason: BreakReason | "unknown";
+}
+/** A player's score so far, shown by the screen. */
+ | {
+	type: "score";
+	player: number;
+	score: number;
+}
+/** The game is over: each player's score and stars (0–3). */
+ | {
+	type: "end";
+	scores: {
+		player: number;
+		score: number;
+		stars: 0 | 1 | 2 | 3;
+	}[];
+}
+/**
+ * Debug, only when init said stats: how many times a second the game drew its avatars (the SDK counts the
+ * animation frames drawAvatar or smoothedBody ran in), about once a second; from a game on the engine, also its
+ * frame rate, renderer and tier (GameStats). Hosts may ignore it.
+ */
+ | ({
+	type: "stats";
+	renderFps: number;
+} & GameStats);
+/** The movements a game is played with, as its manifest lists them. */
+export type Movement = "hands" | "jump" | "squat" | "clap" | "freeze" | "lanes" | "shapes";
+/**
+ * What a game declares about itself (fabi-play.json at its address): the catalogue filters on it. Checked by
+ * parseManifest; fabi-play.schema.json (in @fabi-play/sdk) describes the same rules for editors.
+ *
+ * @example
+ * {
+ *   "$schema": "./node_modules/@fabi-play/sdk/dist/fabi-play.schema.json",
+ *   "id": "star-catcher", "version": "1.0",
+ *   "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,
+ *   "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 {
+	/** For editors only (the JSON Schema to check the file against); ignored by Fabi Play. */
+	$schema?: string;
+	/** Lowercase letters, digits and single hyphens, up to 60 characters: the game's id in the catalogue. */
+	id: string;
+	/** The game's version: 1.0 or 1.0.2. */
+	version: string;
+	/** The name, in Italian and English, up to 60 characters each. */
+	title: Record<Locale, string>;
+	/** One or two sentences, in Italian and English, up to 300 characters each. */
+	description: Record<Locale, string>;
+	/** The ranges it is made for; the catalogue shows it only to players in one of them. */
+	ageRanges: AgeRange[];
+	/** The movements it is played with (at least one). */
+	movements: Movement[];
+	/** How many children can play together: 1 to 4, min ≤ max. */
+	players: {
+		min: number;
+		max: number;
+	};
+	/** Minutes of a typical game, 1 to 20. */
+	minutes: number;
+	/**
+	 * 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">;
+export declare const GAME_BACKDROPS: GameBackdrop[];
+/** Every movement a manifest may list. */
+export declare const MOVEMENTS: Movement[];
+/** A manifest, or the list of what is wrong with it (in English: it is shown in the Studio). */
+export declare function parseManifest(data: unknown): {
+	manifest: GameManifest;
+} | {
+	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;
+export declare const isBody: (v: unknown) => v is Body;
+/** A message from a game (with ns), or null: games are third-party code, so nothing else gets through. */
+export declare function parseGameMessage(data: unknown): GameMessage | null;
+/** A message from the phone, or null. */
+export declare function parseControllerMessage(data: unknown): ControllerMessage | null;
+/** A message from the screen, or null. */
+export declare function parseScreenMessage(data: unknown): ScreenMessage | null;
+/**
+ * Landmarks in player space, rounded (smaller messages). Whichever camera faces the child, the raw frame shows them
+ * as someone standing in front of us: their right hand on the left. Mirroring it makes the screen a mirror. Pass
+ * mirrored when the frames come already mirrored (some front-camera pipelines do).
+ */
+export declare function toPlayerSpace(points: {
+	x: number;
+	y: number;
+	visibility?: number;
+}[], mirrored?: boolean): Body;
+/**
+ * Poses on the wire, in binary: the phone sends one about 30 times a second, so it goes as a few hundred bytes
+ * instead of ~3 KB of JSON (and no JSON.stringify on the phone's JS thread, no JSON.parse on the TV). Every other
+ * message stays JSON. Little-endian, 12 bytes of header, then 132 bytes per body:
+ *
+ *   offset  size  field
+ *   0       1     magic 0xFB
+ *   1       1     codec version (POSE_CODEC_VERSION)
+ *   2       1     kind: 1 = pose (the only one so far)
+ *   3       1     body count, 0–4
+ *   4       8     t, float64: ms on the phone's clock, as in the JSON message
+ *   12      132n  per body, 33 landmarks × one uint32: bits 0–9 x·1000, bits 10–19 y·1000,
+ *                 bits 20–29 visibility·1000, bits 30–31 zero
+ *
+ * So 12 + 132 × bodies bytes: 540 for 4 bodies. Each value is 0–1000, the thousandths toPlayerSpace already rounds
+ * to: decoding gives back exactly the numbers the JSON message carries (n / 1000), so both paths feed the host the
+ * same bodies. t is a float64, not a uint32: the app's t is the device's monotonic clock, which passes 2³² ms after
+ * 49.7 days of uptime, and a wrap would break the trackers' time differences; 4 bytes more is nothing. The camera's
+ * aspect is not in it: it travels in hello.
+ *
+ * Only sent when the screen's welcome lists the version in binaryPose (acceptsBinaryPose): an older TV keeps getting
+ * JSON, and a TV takes both forms (a phone that does not know binary sends JSON).
+ */
+export declare const POSE_CODEC_VERSION = 1;
+/** The binary pose versions this build decodes: the screen advertises them in welcome.binaryPose. */
+export declare const POSE_CODEC_VERSIONS: readonly number[];
+/** The size of a binary pose with n bodies. */
+export declare const poseBytes: (bodies: number) => number;
+/** The largest binary pose (4 bodies): a buffer this big holds any pose, for encodePose's out. */
+export declare const POSE_MAX_BYTES: number;
+/** Whether the screen that sent this welcome decodes the binary poses this phone sends. */
+export declare const acceptsBinaryPose: (welcome: Extract<ScreenMessage, {
+	type: "welcome";
+}>) => boolean;
+/**
+ * A pose message in binary (see POSE_CODEC_VERSION). With out (at least POSE_MAX_BYTES, or the pose's size), it is
+ * written there and a view of its first bytes is returned: one buffer per sender, nothing new per frame but that
+ * view. That is safe because RTCDataChannel.send copies the bytes before returning (browsers; react-native-webrtc
+ * base64-encodes them at once): a sender that hands the bytes on later must not reuse out. Throws RangeError on a
+ * message the screen would reject anyway: more than 4 bodies, a body that is not 33 × 3 numbers, a t or a value
+ * not finite. Values outside 0–1 are clamped.
+ */
+export declare function encodePose(msg: {
+	t: number;
+	bodies: readonly (readonly number[])[];
+}, out?: Uint8Array): Uint8Array;
+/**
+ * A binary pose as the message it carries, or null: anything else (not a buffer, too short or long for its body
+ * count, another magic, a version or kind this build doesn't know, more than 4 bodies, t not finite, a value over
+ * 1000 thousandths, the spare bits set) is dropped, like parseControllerMessage drops bad JSON. Never throws.
+ */
+export declare function decodePose(data: unknown): Extract<ControllerMessage, {
+	type: "pose";
+}> | null;
+/**
+ * The product was called Fablee Play: its saved settings (web localStorage, the app's AsyncStorage) used keys
+ * starting `fablee-play.`. They now start `fabi-play.`; the old key of a new one, or null when it had none.
+ */
+export declare const legacyStorageKey: (key: string) => string | null;
+/** The subset of localStorage the migration needs. */
+export interface SyncStore {
+	getItem(key: string): string | null;
+	setItem(key: string, value: string): void;
+	removeItem(key: string): void;
+}
+/** The subset of AsyncStorage the migration needs. */
+export interface AsyncStore {
+	getItem(key: string): Promise<string | null>;
+	setItem(key: string, value: string): Promise<void>;
+	removeItem(key: string): Promise<void>;
+}
+/**
+ * Moves a value saved under the old key to the new one, once: the old value is copied when the new key has none,
+ * then the old key is removed. Storage errors are swallowed (private mode, a WebView without storage): the caller
+ * reads the new key as usual. `oldKey` defaults to legacyStorageKey(newKey).
+ */
+export declare function migrateStorageKey(store: SyncStore | null | undefined, newKey: string, oldKey?: string | null): void;
+/** migrateStorageKey for AsyncStorage. */
+export declare function migrateStorageKeyAsync(store: AsyncStore, newKey: string, oldKey?: string | null): Promise<void>;
+
+
+
+export {};