@fabi-play/sdk 0.3.0 → 0.5.0

package/dist/fabi-play.d.ts

@@ -67,6 +67,20 @@ declare namespace FabiPlay {
 		/** Where the events go: by default the page, with a round cursor (domPointer()). */
 		target?: PointerTarget;
 	}
+	/** The events the remote's cursor makes in the game's page, as a Magic Remote's (a mouse). */
+	export type CursorEventType = "pointermove" | "mousemove" | "pointerdown" | "mousedown" | "pointerup" | "mouseup" | "click" | "pointercancel";
+	/** Where the cursor's events go (connect's options.cursor): by default the page (domCursor()). */
+	export interface CursorTarget {
+		/** The game's viewport in px. */
+		size(): {
+			width: number;
+			height: number;
+		};
+		/** One event at x, y (px); buttons: 1 while OK is held, else 0. */
+		dispatch(type: CursorEventType, x: number, y: number, buttons: number): void;
+	}
+	/** What became of a picture the game asked to save (HostMessage picture-result, Play.savePicture). */
+	export type PictureResult = "sent" | "unavailable" | "too-big" | "error";
 	/**
 	 * 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.
@@ -208,7 +222,18 @@ declare namespace FabiPlay {
 	 */
 	/**
 	 * pointer: only with input 'remote', true when the TV's remote also points (LG's Magic Remote): it reaches the game
-	 * as ordinary pointer and mouse events (hover, click with OK). Absent = false.
+	 * as ordinary pointer and mouse events (hover, click with OK); or, for a game whose manifest says "remoteCursor":
+	 * true, when the screen moves a cursor with the arrows (cursor messages, which the SDK turns into the same pointer
+	 * and mouse events). Absent = false.
+	 */
+	/**
+	 * pictures: a phone that can save pictures is linked now (its hello said pictures), so the game may send picture
+	 * messages; it changes with a capabilities message. Absent = false.
+	 */
+	/**
+	 * orientation: the screen's orientation when the game starts (width ≥ height: 'landscape', see orientationOf);
+	 * only a game whose manifest lists 'portrait' gets 'portrait'. Informational, to choose a layout: lay out from the
+	 * real viewport size all the same. Absent (older hosts) = 'landscape'.
 	 */
 	{
 		type: "init";
@@ -225,6 +250,8 @@ declare namespace FabiPlay {
 		input?: GameInput;
 		turns?: number[];
 		pointer?: boolean;
+		pictures?: boolean;
+		orientation?: Orientation;
 	}
 	/** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
 	 | {
@@ -278,6 +305,36 @@ declare namespace FabiPlay {
 	 | {
 		type: "turn";
 		players: number[];
+	}
+	/**
+	 * What the screen can do for the game changed mid-game: pictures, whether a phone that can save pictures is linked
+	 * now (one joined, or the last one left). init carries the first value.
+	 */
+	 | {
+		type: "capabilities";
+		pictures: boolean;
+	}
+	/**
+	 * The answer to a picture message, with its id (absent if the picture had none): 'sent', the phone has it (saved,
+	 * or saved once the parent allows it); 'unavailable', no phone that saves pictures is linked; 'too-big', over
+	 * MAX_PICTURE_BYTES; 'error', anything else (the link dropped, the phone failed, no answer in time).
+	 */
+	 | {
+		type: "picture-result";
+		id?: number;
+		result: PictureResult;
+	}
+	/**
+	 * Remote mode with "remoteCursor": true: the cursor the arrows move (see KeyCursor), x and y in fractions of the
+	 * game's frame (0–1), down while OK is held. Sent when it moves and when OK goes down or up; the SDK turns it into
+	 * pointer and mouse events in the game's page (pointermove, pointerdown, pointerup, click, …), as a Magic Remote's.
+	 * The screen draws the cursor itself, above the game.
+	 */
+	 | {
+		type: "cursor";
+		x: number;
+		y: number;
+		down: boolean;
 	};
 	/** Why a game is paused (see HostMessage pause). */
 	export type PauseReason = "user" | "distance";
@@ -319,7 +376,20 @@ declare namespace FabiPlay {
 	 | ({
 		type: "stats";
 		renderFps: number;
-	} & GameStats);
+	} & GameStats)
+	/**
+	 * Save a picture on the family's phone (a drawing, the photo of a wall). data: a base64 data URL, data:image/jpeg
+	 * or data:image/png, at most MAX_PICTURE_BYTES, whose bytes really are that type (checkPicture); title: a name for
+	 * it (MAX_PICTURE_TITLE characters); id: the game's own, echoed in picture-result. Anything else is dropped: a game
+	 * can send only an image this way. The screen sends it to the phone over their direct link only, never to a
+	 * server, and answers picture-result.
+	 */
+	 | {
+		type: "picture";
+		data: string;
+		title?: string;
+		id?: number;
+	};
 	/** The movements a game is played with, as its manifest lists them. */
 	export type Movement = "hands" | "jump" | "squat" | "clap" | "freeze" | "lanes" | "shapes";
 	/**
@@ -373,6 +443,14 @@ declare namespace FabiPlay {
 		backdrop?: GameBackdrop[];
 		/** Optional: Fabi explains the game on the TV before calibration (see GameIntro). Absent: straight to calibration. */
 		intro?: GameIntro;
+		/**
+		 * Optional: the game's cover, the card in the catalogue (TV carousel, phone, admin): a path relative to the game's
+		 * address (no scheme, no leading /, no "." or ".." segments, no backslash, up to COVER_MAX_PATH characters, see
+		 * isCoverPath), ending in lowercase .jpg, .jpeg, .png or .webp: cover.jpg. A 16:9 image (COVER_ASPECT, within
+		 * COVER_ASPECT_TOLERANCE), recommended 1280×720 and at most COVER_MAX_BYTES; JPEG is the safest for old TV
+		 * browsers. The review checks the file; absent or broken, the catalogue falls back to another image.
+		 */
+		cover?: string;
 		/** Optional: how it can be played; absent = ['body']. Must include 'body' (Fabi Play is a movement platform); add 'remote' to be offered without a phone. */
 		inputs?: GameInput[];
 		/**
@@ -389,7 +467,27 @@ declare namespace FabiPlay {
 		 * a game drawn on exact spots of the live video).
 		 */
 		framing?: GameFraming;
+		/**
+		 * Optional, only with 'remote' in inputs: true and, in remote mode, the arrows move a free cursor instead of making
+		 * gestures (they speed up when held, see KeyCursor) and OK presses and releases it: the game gets it as pointer and
+		 * mouse events, the same as a Magic Remote's (init.pointer true), so a game written for the pointer works with
+		 * both. Back is still the platform's pause. For games picked or drawn with a pointer (a painting game). Absent or
+		 * false: arrows and OK make gestures.
+		 */
+		remoteCursor?: boolean;
+		/**
+		 * Optional: the screen orientations the game can be played in; absent = ['landscape'] (see gameOrientations).
+		 * Non-empty, without repeats, from ORIENTATIONS. A phone alone («Gioca qui / Play here») is held upright, so it
+		 * offers only games that list 'portrait'; the TV and the tablet are landscape. A game that lists both still lays
+		 * out from its real viewport size; init.orientation says which one it started in.
+		 */
+		orientations?: Orientation[];
 	}
+	/**
+	 * A screen's orientation: 'landscape' when its width is at least its height, else 'portrait' (see orientationOf).
+	 * GameManifest.orientations lists those a game supports; HostMessage init.orientation says the one it starts in.
+	 */
+	export type Orientation = "landscape" | "portrait";
 	/** How the screen frames the camera image for a game: see GameManifest.framing. */
 	export type GameFraming = "auto" | "fixed";
 	/**
@@ -469,6 +567,8 @@ declare namespace FabiPlay {
 	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 savePicture takes: a canvas (any size) or a data URL (data:image/jpeg or data:image/png, base64). */
+	export type PictureSource = HTMLCanvasElement | string;
 	/** What the 'start' event says: who plays and how, as it was at the start (late listeners get the same; see Easy for now). */
 	export interface StartInfo {
 		/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
@@ -477,8 +577,10 @@ declare namespace FabiPlay {
 		players: readonly number[];
 		/** The language to show text in. */
 		locale: Locale;
-		/** 'tv': on a TV, children standing back; 'solo': a tablet in front of one child. */
+		/** 'tv': on a TV, children standing back; 'solo': a tablet or a phone in front of the children. */
 		mode: "tv" | "solo";
+		/** 'landscape' or 'portrait' (a phone held upright): the screen's orientation at the start, see Play.orientation. */
+		orientation: Orientation;
 		/** '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. */
@@ -489,8 +591,12 @@ declare namespace FabiPlay {
 		turns: readonly number[];
 		/** 'body' (the default) or 'remote': played with the TV remote, keys turned into gestures (see Play.input). */
 		input: GameInput;
-		/** With input 'remote', whether the remote also points (LG's Magic Remote; see Play.pointer). */
+		/** With input 'remote', whether the remote also points (LG's Magic Remote, or the arrows as a cursor; see Play.pointer). */
 		pointer: boolean;
+		/** Whether savePicture can reach a phone at the start (see Play.canSavePicture; the capabilities event says when it changes). */
+		canSavePicture: boolean;
+		/** The screen's sound is off: play no sound, and make every cue that sound would give visible instead. */
+		muted: boolean;
 	}
 	/**
 	 * The events of FabiPlay.on, by name, with what each listener gets. Every gesture (jump, land, squat, stand, clap,
@@ -549,6 +655,10 @@ declare namespace FabiPlay {
 		turn: {
 			players: number[];
 		};
+		/** What the screen can do changed: pictures, whether savePicture can reach a phone now (see canSavePicture). */
+		capabilities: {
+			pictures: boolean;
+		};
 	};
 	/** An event name of FabiPlay.on. */
 	export type EasyEvent = keyof EasyEvents;
@@ -565,7 +675,7 @@ declare namespace FabiPlay {
 	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', 'turn' (see EasyEvents). Returns a function that
+		 * 'players', 'pause', 'resume', 'break-start', 'break-end', 'backdrop', 'turn', 'capabilities' (see EasyEvents). Returns a function that
 		 * stops listening.
 		 *
 		 * @example
@@ -606,8 +716,26 @@ declare namespace FabiPlay {
 		readonly turns: readonly number[];
 		/** How this session is played (see Play.input); 'body' before start. */
 		readonly input: GameInput;
-		/** With input 'remote', whether the remote also points (Play.pointer; pointer() is the hand adapter); false before start. */
+		/**
+		 * With input 'remote', whether the remote also points (Play.pointer: a Magic Remote, or the arrows as a cursor with
+		 * "remoteCursor": true; either way plain pointer and mouse events). pointer() is the hand adapter. False before start.
+		 */
 		readonly hasPointer: boolean;
+		/** Whether savePicture can reach a phone now (see Play.canSavePicture); false before start. */
+		readonly canSavePicture: boolean;
+		/**
+		 * Saves a picture on the family's phone: a canvas (scaled to 1920 px at most, JPEG) or a data URL (JPEG or PNG),
+		 * with an optional title. Resolves 'sent', 'unavailable', 'too-big' or 'error' (see Play.savePicture); called before
+		 * start, it waits for it. Only TV → phone over their direct link, never to a server.
+		 *
+		 * @example
+		 * if (FabiPlay.canSavePicture) FabiPlay.savePicture(canvas, { title: 'Il nostro muro' })
+		 */
+		savePicture(source: PictureSource, opts?: {
+			title?: string;
+		}): Promise<PictureResult>;
+		/** The screen's sound is off (see StartInfo.muted); false before start. */
+		readonly muted: boolean;
 		/** 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. */
@@ -675,6 +803,20 @@ declare namespace FabiPlay {
 		turn: Extract<HostMessage, {
 			type: "turn";
 		}>;
+		/**
+		 * What the screen can do for the game changed: pictures, whether savePicture can reach a phone now (see
+		 * Play.canSavePicture). Only when it changes.
+		 */
+		capabilities: Extract<HostMessage, {
+			type: "capabilities";
+		}>;
+		/**
+		 * Remote mode with "remoteCursor": true: the cursor the arrows move (x, y in fractions of the page, down while OK
+		 * is held). Nothing to do with it: the SDK already makes the pointer and mouse events a Magic Remote would.
+		 */
+		cursor: Extract<HostMessage, {
+			type: "cursor";
+		}>;
 	};
 	/**
 	 * The game's side of Fabi Play, from connect(): who plays, their movements, and how the game tells it is ready,
@@ -719,10 +861,43 @@ declare namespace FabiPlay {
 		/**
 		 * Only with input 'remote': the remote also points (LG's Magic Remote), reaching the game as ordinary pointer and
 		 * mouse events (hover, click with OK). Then let what the game has to pick be clicked too (large hit areas, a hover
-		 * highlight). false otherwise, and from hosts that don't say. Not the pointer() adapter, which makes a child's hand
-		 * the mouse.
+		 * highlight). Also true for a game whose manifest says "remoteCursor": true, when the arrows move a cursor: the SDK
+		 * makes the same pointer and mouse events from it (OK held: pointerdown … pointerup, then click), so a game written
+		 * for the pointer works with both. false otherwise, and from hosts that don't say. Not the pointer() adapter, which
+		 * makes a child's hand the mouse.
 		 */
 		readonly pointer: boolean;
+		/**
+		 * Whether savePicture can reach a phone now: true when the screen says a phone that saves pictures is linked (the
+		 * app; the web phone can't). It can change mid-game: listen to 'capabilities'. Hide or grey a "save" button while
+		 * it is false, and never make the children wait on it.
+		 */
+		readonly canSavePicture: boolean;
+		/**
+		 * Saves a picture on the family's phone, in its gallery (a drawing, the photo of a wall). source: a canvas (scaled
+		 * down to MAX_PICTURE_SIDE, 1920 px on its longer side, drawn on white and encoded as JPEG at quality 0.85, lower
+		 * if it would be over 3 MiB) or a data URL (data:image/jpeg or data:image/png, base64, sent as it is). title: a
+		 * name for it (up to 60 characters). Resolves with what became of it: 'sent' (the phone has it), 'unavailable' (no
+		 * phone that saves pictures: canSavePicture is false), 'too-big' (over 3 MiB), 'error' (a canvas that can't be read,
+		 * not an image, the link dropped, no answer in 2 minutes). Never rejects.
+		 *
+		 * Privacy: the picture goes only from the TV to the phone over their direct link (WebRTC, encrypted), never to a
+		 * server, and nothing else can be sent this way. If the phone can't save it (permission denied), Fabi Play tells the
+		 * parent on the phone: don't tell the children.
+		 *
+		 * @example
+		 * if (play.canSavePicture) await play.savePicture(canvas, { title: 'Our wall' })
+		 */
+		savePicture(source: PictureSource, opts?: {
+			title?: string;
+		}): Promise<PictureResult>;
+		/**
+		 * The screen's orientation when the game started: 'landscape' (width ≥ height; the TV, the tablet, and what older
+		 * hosts mean) or 'portrait' (a phone held upright, only for games whose manifest lists it in orientations). Use it
+		 * to choose a layout, but size everything from the real viewport (innerWidth × innerHeight): it is not updated if
+		 * the screen turns.
+		 */
+		readonly orientation: Orientation;
 		/** 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. */
@@ -784,8 +959,8 @@ declare namespace FabiPlay {
 		/** 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', 'turn'
-		 * (see Events). Returns a function that stops listening.
+		 * Listens to the host: 'frame', 'gesture', 'pause', 'resume', 'break-start', 'break-done', 'backdrop', 'turn',
+		 * 'capabilities', 'cursor' (see Events). Returns a function that stops listening.
 		 *
 		 * @example
 		 * const off = play.on('frame', (f) => (players = f.players))
@@ -834,6 +1009,14 @@ declare namespace FabiPlay {
 		 */
 		readonly avatars: Readonly<Record<string, unknown>>;
 	}
+	/** connect()'s options. */
+	export interface ConnectOptions {
+		/**
+		 * Where the remote's cursor events go ("remoteCursor": true): by default the page (domCursor()), null for nowhere
+		 * (the game reads the 'cursor' event itself). Tests pass their own.
+		 */
+		cursor?: CursorTarget | null;
+	}
 }
 
 /**