@fabi-play/sdk 0.0.0-stage → 0.2.0

package/dist/fabi-play.d.ts

@@ -0,0 +1,714 @@
+// fabi-play.js: the Fabi Play SDK as a script tag. It sets window.FabiPlay; these are its types.
+// Generated by scripts/types.mjs from the sources: do not edit.
+//
+// Use it next to fabi-play.js, in a script (not a module) or a // @ts-check JavaScript file:
+//   /// <reference path="fabi-play.d.ts" />
+// or list it in tsconfig.json / jsconfig.json "include" (or "files"). The types are FabiPlay.Point, FabiPlay.PlayerFrame, …
+
+/** The Fabi Play SDK's types, for script-tag games: FabiPlay.PlayerFrame, FabiPlay.Point, FabiPlay.Gesture, … */
+declare namespace FabiPlay {
+	/** Anything with Play's on(): a Play, or a stand-in in tests. */
+	export type On = Pick<Play, "on">;
+	/** What the child does, as the keyboard adapter names it. */
+	export type Action = "jump" | "squat" | "left" | "right" | "clap" | "arms-up";
+	/** Action → key code (KeyboardEvent.code: Space, Enter, ArrowUp, KeyW, Digit1…). */
+	export type KeyMap = Partial<Record<Action, string>>;
+	/** The fields of a KeyboardEvent for one key. */
+	export interface KeyInfo {
+		/** KeyboardEvent.key: ' ', 'Enter', 'ArrowLeft', 'a'… */
+		key: string;
+		/** KeyboardEvent.code: 'Space', 'Enter', 'ArrowLeft', 'KeyA'… */
+		code: string;
+		/** Legacy, still read by many games. */
+		keyCode: number;
+	}
+	/** Where the keyboard adapter sends its key events. */
+	export interface KeyTarget {
+		/** Sends a keydown or keyup. */
+		dispatch(type: "keydown" | "keyup", key: KeyInfo): void;
+	}
+	/** Options of keyboard(). */
+	export interface KeyboardOptions {
+		/** Whose movements (default 1); another player can get other keys (e.g. WASD). */
+		player?: number;
+		/** Where the keys go: by default the page (domKeys()). */
+		target?: KeyTarget;
+		/** The timer for taps and releases (tests). */
+		setTimeout?: (fn: () => void, ms: number) => unknown;
+	}
+	/** Where the pointer adapter sends its moves and clicks. */
+	export interface PointerTarget {
+		/** Screen size in px. */
+		size(): {
+			width: number;
+			height: number;
+		};
+		/** The hand moved to x, y (px). */
+		move(x: number, y: number): void;
+		/** The hand stayed still long enough at x, y (px): a click. */
+		click(x: number, y: number): void;
+		/** Draws the hand: progress 0–1 while it stays still, to show the click coming. */
+		cursor(x: number, y: number, progress: number): void;
+	}
+	/** Options of pointer(). */
+	export interface PointerOptions {
+		/** Whose hand (default 1). */
+		player?: number;
+		/** Which hand drives the pointer; "any" picks the higher one (the one the child is raising). */
+		hand?: "left" | "right" | "any";
+		/** How long the hand must stay still to click. */
+		dwellMs?: number;
+		/** How still: a share of the screen's diagonal. */
+		radius?: number;
+		/** Where the events go: by default the page, with a round cursor (domPointer()). */
+		target?: PointerTarget;
+	}
+	/**
+	 * 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[];
+	/** 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";
+	/** 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";
+	};
+	/**
+	 * 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";
+	/**
+	 * 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;
+	}
+	/** Quality tiers for drawing, best first: what @fabi-play/engine calls engine.tier.name. */
+	export type DeviceTier = "high" | "medium" | "low";
+	/**
+	 * 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;
+	}
+	/**
+	 * 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;
+	}
+	/** 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";
+	/** 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">;
+	/** 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";
+	/** 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[];
+	}
+	/** Where player space (0–1) lands on the canvas. */
+	export interface Box {
+		/** Left edge, canvas units. */
+		x: number;
+		/** Top edge, canvas units. */
+		y: number;
+		/** Width, canvas units. */
+		w: number;
+		/** Height, canvas units. */
+		h: number;
+	}
+	/** Where player space (0–1, the body points) lands on the canvas, in the canvas's drawing units. */
+	export type AvatarBox = Box;
+	/** Options of drawAvatar (and, smooth and interpolate, of smoothedBody). */
+	export interface DrawAvatarOptions {
+		/** 0–1, for the whole avatar. */
+		alpha?: number;
+		/**
+		 * Smoothing, per player (needs a player id: a frame, or a body with a player number): true (default, 0.5), a
+		 * number 0–1 (how much of each new frame to take; 1 is none), or false. The avatar then doesn't jitter, and limbs
+		 * the camera loses for a moment don't blink. It advances once per new body, however often you draw.
+		 */
+		smooth?: boolean | number;
+		/**
+		 * true (default): the body for this animation frame, interpolated between the camera's last two (needs a frame,
+		 * or a player id), so the avatar moves at the display's rate. false: the newest body as it came (smoothed).
+		 */
+		interpolate?: boolean;
+	}
+	/**
+	 * Draws an avatar; returns the body it was posed with (smoothed unless smooth: false, interpolated for this
+	 * animation frame unless interpolate: false), or null if it drew nothing.
+	 */
+	export type DrawAvatar = (ctx: CanvasRenderingContext2D, who: PlayerFrame | Body, player?: number | string, box?: AvatarBox | null, options?: DrawAvatarOptions) => Body | null;
+	/** A frame's body smoothed (and interpolated) for its player, or a player id's last one; null if none. */
+	export type SmoothedBody = (who: PlayerFrame | number, options?: Pick<DrawAvatarOptions, "smooth" | "interpolate">) => Body | null;
+	/** What the 'start' event says: who plays and how. */
+	export interface StartInfo {
+		/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
+		ageRange: AgeRange;
+		/** The ids of the players (1, 2, …). */
+		players: number[];
+		/** The language to show text in. */
+		locale: Locale;
+		/** 'tv': on a TV, children standing back; 'solo': a tablet in front of one child. */
+		mode: "tv" | "solo";
+		/** 'video': mirror mode, paint no opaque background; 'none': paint your own. See the backdrop event. */
+		backdrop: Backdrop;
+		/** Where the camera image is (with 'video', the video; with 'none', where the avatars stand), see toScreen; null if unknown. */
+		view: BackdropView | null;
+		/** What the screen knows about the device (a starting tier, the display's rate), or null: see Play.device. */
+		device: DeviceHint | null;
+	}
+	/**
+	 * The events of FabiPlay.on, by name, with what each listener gets. Every gesture (jump, land, squat, stand, clap,
+	 * freeze, move, lane-left, lane-center, lane-right) is an event of its own, with the player who made it.
+	 */
+	export type EasyEvents = {
+		[G in Gesture]: {
+			player: number;
+		};
+	} & {
+		/** The screen started the game (late listeners still get it). */
+		start: StartInfo;
+		/** Every frame, the hands of each player, as screen shares (0–1). */
+		hands: {
+			player: number;
+			left: Point | null;
+			right: Point | null;
+		};
+		/** When a player's shape changes (arms up, wide, …). */
+		shape: {
+			player: number;
+			shape: Shape | null;
+		};
+		/** Every frame, every player: bodies for drawAvatar and your own hit-tests. */
+		players: {
+			players: PlayerFrame[];
+		};
+		/**
+		 * The game is paused: stop the clock until resume. reason 'user': a grown-up (or a child's crossed arms);
+		 * 'distance': a child is too close to the screen (it resumes by itself once they step back). Fabi Play draws the
+		 * pause either way.
+		 */
+		pause: {
+			reason: PauseReason;
+		};
+		/** Go on after a pause. */
+		resume: Record<string, never>;
+		/** Fabi Play shows an ad: mute and stop the clock (the script tag mutes audio and video for you). */
+		"break-start": Record<string, never>;
+		/** Go on; shown says whether an ad was shown. */
+		"break-end": {
+			shown: boolean;
+		};
+		/**
+		 * The backdrop changed mid-game, 'video' (no opaque background) or 'none' (your own background again), or the
+		 * camera image moved on the screen (view).
+		 */
+		backdrop: {
+			backdrop: Backdrop;
+			view: BackdropView | null;
+		};
+	};
+	/** An event name of FabiPlay.on. */
+	export type EasyEvent = keyof EasyEvents;
+	/**
+	 * The simple API: window.FabiPlay from the script tag (fabi-play.js), or easy(connect()) with the npm package.
+	 * Everything can be called before the screen starts the game: it waits for it.
+	 *
+	 * @example
+	 * FabiPlay.on('jump', ({ player }) => hop(player))
+	 * FabiPlay.on('hands', ({ player, right }) => right && aim(player, FabiPlay.toScreen(right)))
+	 * await FabiPlay.break('level')
+	 * FabiPlay.end(120)
+	 */
+	export interface Easy {
+		/**
+		 * Listens to an event: a gesture by its name ('jump', 'clap', 'lane-left', …), 'start', 'hands', 'shape',
+		 * 'players', 'pause', 'resume', 'break-start', 'break-end', 'backdrop' (see EasyEvents). Returns a function that
+		 * stops listening.
+		 *
+		 * @example
+		 * const off = FabiPlay.on('clap', ({ player }) => fire(player))
+		 */
+		on<K extends EasyEvent>(event: K, listener: (data: EasyEvents[K]) => void): () => void;
+		/** Say the game is loaded; done for you on page load unless the script tag says data-ready="manual". */
+		ready(): void;
+		/** The score so far, for the screen to show; player 1 unless said. */
+		score(score: number, player?: number): void;
+		/** The game stopped by itself ('level' or 'gameover', never its pause menu): Fabi Play may show an ad. Resolves when it can go on. */
+		break(reason?: BreakReason): Promise<boolean>;
+		/** The end: a score, or one per player. Stars from 0 to 3, 2 if not given. */
+		end(score: number | {
+			player: number;
+			score: number;
+			stars?: 0 | 1 | 2 | 3;
+		}[]): void;
+		/**
+		 * Presses keys for movements, for a game played with the keyboard (see keyboard()): by default Space while in the
+		 * air, ArrowDown while crouched, arrows for side steps, Enter on a clap. The script tag's data-keys does the same.
+		 *
+		 * @example
+		 * FabiPlay.keys({ jump: 'Space', left: 'ArrowLeft', right: 'ArrowRight' })
+		 */
+		keys(map?: KeyMap, options?: Omit<KeyboardOptions, "target">): void;
+		/**
+		 * The child's hand as the mouse, for a game played with the pointer (see pointer()): it moves the pointer and
+		 * clicks by staying still on a spot. The script tag's data-pointer does the same.
+		 */
+		pointer(options?: Omit<PointerOptions, "target">): void;
+		/** Where the camera image is, with any backdrop; null if the host didn't say, and before start. */
+		readonly view: BackdropView | null;
+		/** What the screen knows about the device (see Play.device); null if it said nothing, and before start. */
+		readonly device: DeviceHint | null;
+		/** For engines, debug only: how the game draws now (see Play.reportStats). Dropped before start. */
+		reportStats(stats: GameStats): void;
+		/**
+		 * A body point (player space, 0–1, as in players[i].body) on the screen, in fractions: where the child is, in the
+		 * video or on their avatar. Draw hands and effects at toScreen(wrist), in every mode. Unchanged without a view.
+		 */
+		toScreen(p: Point): Point;
+		/**
+		 * The avatar id a player picked on the phone, by player id or from a frame (players[i]); the slot's default
+		 * (fox, lion, dragon, unicorn: the 6–8 band's, as no age is known here) until the first frame says otherwise.
+		 */
+		avatarOf(player: number | PlayerFrame): string;
+		/**
+		 * Draws a player's avatar posed like them, smoothed per player: drawAvatar(ctx, players[i]). Optional: player (a
+		 * player id, or an avatar id), box (where player space 0–1 lands on the canvas; default the view, where the child
+		 * stands, else the whole canvas), { alpha, smooth }. Draw avatars only when backdrop is not 'video'. Returns the
+		 * smoothed body it drew (or null): put the hands on it, so they stay in the avatar's hands.
+		 */
+		drawAvatar: DrawAvatar;
+		/**
+		 * A player's body smoothed as drawAvatar draws it (from a frame: smooths it, shared with drawAvatar; from a player
+		 * id: the last one, or null). Use it for hit-tests and glows in avatar mode, so they follow the avatar's hands.
+		 */
+		smoothedBody: SmoothedBody;
+	}
+	/** The events of Play.on, by name: each listener gets the host's message of that type. */
+	export type Events = {
+		/** Every camera frame (about 30 a second): each player's body, hands, shape, lane and avatar. */
+		frame: Extract<HostMessage, {
+			type: "frame";
+		}>;
+		/** A player made a movement: jump, land, squat, stand, clap, freeze, move, lane-left/center/right. */
+		gesture: Extract<HostMessage, {
+			type: "gesture";
+		}>;
+		/** The game is paused (reason: 'user', or 'distance' when a child is too close): stop the clock until resume. */
+		pause: Extract<HostMessage, {
+			type: "pause";
+		}>;
+		/** Go on after a pause. */
+		resume: Extract<HostMessage, {
+			type: "resume";
+		}>;
+		/** Fabi Play is showing a break: mute, stop the clock, until break-done. */
+		"break-start": Extract<HostMessage, {
+			type: "break-start";
+		}>;
+		/** The break is over (shown: whether an ad was shown): unmute and go on. */
+		"break-done": Extract<HostMessage, {
+			type: "break-done";
+		}>;
+		/** What is behind the game changed, or where its video is: see Play.backdrop and Play.view. */
+		backdrop: Extract<HostMessage, {
+			type: "backdrop";
+		}>;
+	};
+	/**
+	 * The game's side of Fabi Play, from connect(): who plays, their movements, and how the game tells it is ready,
+	 * the scores and the end.
+	 *
+	 * @example
+	 * const play = await connect()
+	 * play.on('gesture', (g) => g.gesture === 'jump' && hop(g.player))
+	 * play.ready()
+	 */
+	export interface Play {
+		/** The language to show text in. */
+		readonly locale: Locale;
+		/** 'tv': on a TV or Chromecast, children standing back; 'solo': a tablet in front of one child. */
+		readonly mode: "tv" | "solo";
+		/** The ids of the players in this game (1, 2, …), as frames and gestures name them. */
+		readonly players: number[];
+		/** The screen's sound is off: start the game muted. */
+		readonly muted: boolean;
+		/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
+		readonly ageRange: AgeRange;
+		/**
+		 * What is behind the game, now: 'video' (mirror mode: the players' camera video fills the screen under the
+		 * game; paint no opaque background, only what is on top) or 'none' (paint your own background). Only games whose
+		 * manifest says "backdrop": ["video"] ever get 'video'; it can change mid-game.
+		 */
+		readonly backdrop: Backdrop;
+		/**
+		 * Where the whole camera image is, in fractions of the game's viewport, with any backdrop. The screen decides it:
+		 * with 'video' where the video is drawn, with 'none' where the avatars stand. null if the host didn't say (older
+		 * hosts). Use toScreen rather than reading it, and don't compute your own.
+		 */
+		readonly view: BackdropView | null;
+		/**
+		 * A body point (player space, 0–1, as in frame.players[i].body) on the game's viewport, in fractions: where the
+		 * child is, in the video or on the avatar. Draw hands and effects on the children at toScreen(wrist), in every
+		 * mode. Unchanged without a view.
+		 */
+		toScreen(p: Point): Point;
+		/**
+		 * The avatar id a player picked on the phone (fox, lion, robot, …), by player id or from a frame. Each
+		 * frame carries it; before the first frame, from an older host, or for an id this SDK doesn't know: the slot's
+		 * default (fox, lion, dragon, unicorn for players 1–4: the 6–8 band's).
+		 */
+		avatarOf(player: number | PlayerFrame): string;
+		/**
+		 * Draws a player's avatar posed like their body, smoothed per player. who: a frame (its body and avatar) or a
+		 * body; player: a player id (whose avatar, and whose smoothing) or an avatar id. box: where player space (0–1)
+		 * lands on the canvas, in its drawing units; by default the view (where the child stands), else the whole canvas.
+		 * Draw avatars only when backdrop is not 'video': in mirror mode the children are on screen themselves. Draws
+		 * nothing when the shoulders aren't seen. Returns the body it posed the avatar with (smoothed), or null if it drew nothing: put hands
+		 * and effects on that body's points, so they stay in the avatar's hands. Call it every animation frame: the body
+		 * is interpolated for that frame between the camera's last two (about one camera interval, 33 ms, behind the
+		 * newest), so the avatar moves at the display's rate, not the camera's ({ interpolate: false } for the newest).
+		 */
+		drawAvatar: DrawAvatar;
+		/**
+		 * A player's body smoothed as drawAvatar draws it, for hit-tests and effects in avatar mode: from a frame, it
+		 * smooths that frame's body (once per new body, shared with drawAvatar); from a player id, the last smoothed body,
+		 * or null. Options: { smooth, interpolate } as in drawAvatar: by default the same interpolated body drawAvatar
+		 * draws in this animation frame, so hit-tests catch where the child sees the avatar's hand.
+		 */
+		smoothedBody: SmoothedBody;
+		/**
+		 * What the screen knows about the device (DeviceHint): a starting quality tier and the display's rate, Hz. null
+		 * if it said nothing (older hosts, a plain browser). A hint for engines: start at this tier instead of measuring
+		 * the device again (@fabi-play/engine does it by itself), and still lower it if frames are slow.
+		 */
+		readonly device: DeviceHint | null;
+		/**
+		 * For engines, debug only: how the game draws now (fps, renderer, tier). The SDK adds the last one to its stats
+		 * messages when a debug host (the simulator) asked for them, and drops it otherwise. @fabi-play/engine calls it
+		 * by itself about once a second.
+		 */
+		reportStats(stats: GameStats): void;
+		/** Called when backdrop or view changes; returns a function that stops listening. */
+		onBackdrop(listener: (backdrop: Backdrop, view: BackdropView | null) => void): () => void;
+		/**
+		 * Listens to the host: 'frame', 'gesture', 'pause', 'resume', 'break-start', 'break-done', 'backdrop' (see
+		 * Events). Returns a function that stops listening.
+		 *
+		 * @example
+		 * const off = play.on('frame', (f) => (players = f.players))
+		 */
+		on<K extends keyof Events>(event: K, listener: (m: Events[K]) => void): () => void;
+		/** Assets loaded, the game can start: the screen hides its loader. Call it within 10 seconds of the page loading. */
+		ready(): void;
+		/** A player's score so far, for the screen to show. */
+		score(player: number, score: number): void;
+		/**
+		 * The game has stopped by itself: a level is over or the game is over (never its pause menu). Fabi Play may show
+		 * an ad there, if its rules allow (break-start, then break-done); resolves when the game can go on, true if an
+		 * ad was shown. Never call it in the middle of play.
+		 */
+		break(reason?: BreakReason): Promise<boolean>;
+		/**
+		 * The game is over: each player's score and stars (0–3). The screen shows the results and takes over.
+		 *
+		 * @example
+		 * play.end([{ player: 1, score: 120, stars: 3 }])
+		 */
+		end(scores: {
+			player: number;
+			score: number;
+			stars: 0 | 1 | 2 | 3;
+		}[]): void;
+	}
+	/** How the SDK reaches the host; in a page, the parent window. Tests pass their own. */
+	export interface Channel {
+		/** Sends a message to the host. */
+		post(message: Wire<GameMessage>): void;
+		/** Receives everything that arrives; the SDK picks out the host's messages. */
+		listen(listener: (data: unknown) => void): void;
+	}
+	/**
+	 * window.FabiPlay, as fabi-play.js sets it: the simple API (Easy), plus the avatars' rig it carries for the engine.
+	 * For a script-tag game written in TypeScript: `declare const FabiPlay: FabiPlayGlobal` (or reference
+	 * dist/fabi-play.d.ts, which declares it).
+	 */
+	export interface FabiPlayGlobal extends Easy {
+		/**
+		 * The avatars' rig and data fabi-play.js carries (for drawAvatar), handed over to fabi-play-engine.lite.js or a
+		 * bundler alias so the engine doesn't ship them twice. Not a game API: draw avatars with drawAvatar. Typed in
+		 * `@fabi-play/sdk/avatars`.
+		 */
+		readonly avatars: Readonly<Record<string, unknown>>;
+	}
+}
+
+/**
+ * The Fabi Play SDK, set by fabi-play.js: listen to movements by name, draw avatars, say when the game is ready,
+ * the scores and the end. Everything can be called before the screen starts the game.
+ *
+ * @example
+ * FabiPlay.on('jump', ({ player }) => hop(player))
+ * FabiPlay.on('players', ({ players }) => (frames = players))
+ * FabiPlay.end(120)
+ */
+declare const FabiPlay: FabiPlay.FabiPlayGlobal
+
+interface Window {
+	/** The Fabi Play SDK, set by fabi-play.js (see the global FabiPlay). */
+	readonly FabiPlay: FabiPlay.FabiPlayGlobal
+}