@fabi-play/sdk 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -213,6 +213,20 @@ export interface BackdropView {
 	/** Height, a fraction of the viewport's height. */
 	h: number;
 }
+/** A hand: the child's own left or right. */
+export type HandSide = "left" | "right";
+/**
+ * The parts of the game's viewport a phone's notch, rounded corners or home bar may cover, in fractions of the
+ * viewport (top and bottom of its height, left and right of its width; each 0–0.25). The game's frame cannot read
+ * env(safe-area-inset-*), so the screen sends it (init.safeArea): keep buttons, scores and targets out of it, and
+ * still paint the background under it. Zeros where nothing is covered (a TV, a tablet, older hosts).
+ */
+export interface SafeArea {
+	top: number;
+	bottom: number;
+	left: number;
+	right: number;
+}
 /** Quality tiers for drawing, best first: what @fabi-play/engine calls engine.tier.name. */
 export type DeviceTier = "high" | "medium" | "low";
 /**
@@ -265,6 +279,15 @@ export type HostMessage =
  * 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'.
+ */
+/**
+ * safeArea: what a phone's notch, rounded corners and home bar cover, in fractions of the viewport (see SafeArea;
+ * parseSafeArea clamps each side to 0–0.25). Absent (a TV, a tablet, older hosts) = nothing covered.
+ */
 {
 	type: "init";
 	v: number;
@@ -281,6 +304,8 @@ export type HostMessage =
 	turns?: number[];
 	pointer?: boolean;
 	pictures?: boolean;
+	orientation?: Orientation;
+	safeArea?: SafeArea;
 }
 /** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
@@ -472,6 +497,14 @@ export interface GameManifest {
 	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[];
 	/**
@@ -496,7 +529,19 @@ export interface GameManifest {
 	 * 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";
 /**
@@ -650,8 +695,12 @@ export interface StartInfo {
 	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;
+	/** What a phone's notch and home bar cover, fractions of the viewport (zeros if nothing): see Play.safeArea. */
+	safeArea: Readonly<SafeArea>;
 	/** '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. */
@@ -680,11 +729,20 @@ export type EasyEvents = {
 } & {
 	/** The screen started the game (late listeners still get it). */
 	start: StartInfo;
-	/** Every frame, the hands of each player, as screen shares (0–1). */
+	/**
+	 * Every frame, the hands of each player, in fractions of the screen (0–1). aim: where each hand aims, for what it
+	 * touches (see Easy.aim: the hand on the body in landscape, stretched to the whole screen in portrait). left and
+	 * right: the hands as pointers, the arms' reach stretched to the whole screen in every orientation
+	 * (PlayerFrame.leftHand and rightHand). null: not seen.
+	 */
 	hands: {
 		player: number;
 		left: Point | null;
 		right: Point | null;
+		aim: {
+			left: Point | null;
+			right: Point | null;
+		};
 	};
 	/** When a player's shape changes (arms up, wide, …). */
 	shape: {
@@ -739,7 +797,7 @@ export type EasyEvent = keyof EasyEvents;
  *
  * @example
  * FabiPlay.on('jump', ({ player }) => hop(player))
- * FabiPlay.on('hands', ({ player, right }) => right && aim(player, FabiPlay.toScreen(right)))
+ * FabiPlay.on('hands', ({ player, aim }) => aim.right && touch(player, aim.right))
  * await FabiPlay.break('level')
  * FabiPlay.end(120)
  */
@@ -807,6 +865,10 @@ export interface Easy {
 	}): Promise<PictureResult>;
 	/** The screen's sound is off (see StartInfo.muted); false before start. */
 	readonly muted: boolean;
+	/** The screen's orientation at the start (see Play.orientation); 'landscape' before start. */
+	readonly orientation: Orientation;
+	/** What a phone's notch and home bar cover, fractions of the viewport (see Play.safeArea); zeros before start. */
+	readonly safeArea: Readonly<SafeArea>;
 	/** 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. */
@@ -818,6 +880,13 @@ export interface Easy {
 	 * video or on their avatar. Draw hands and effects at toScreen(wrist), in every mode. Unchanged without a view.
 	 */
 	toScreen(p: Point): Point;
+	/**
+	 * Where a player's hand aims on the screen, in fractions (0–1), by player id or from a frame: use it for what the
+	 * hand touches; toScreen(wrist) only to draw on the body. On a TV or a tablet the hand on the body (the avatar's,
+	 * or the real one over the video); on a phone held upright the wrist stretched to the whole screen, so raised
+	 * hands reach the top. See Play.aim. null when not seen, and before start.
+	 */
+	aim(player: number | PlayerFrame, side: HandSide): Point | null;
 	/**
 	 * 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.
@@ -970,6 +1039,20 @@ export interface Play {
 	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;
+	/**
+	 * What a phone's notch, rounded corners and home bar cover, in fractions of the viewport: top and bottom of its
+	 * height, left and right of its width, each 0–0.25. The game's frame can't read env(safe-area-inset-*), so the
+	 * screen says it. Keep buttons, scores and targets out of it (e.g. a top bar from safeArea.top × innerHeight down);
+	 * still paint the background under it. Zeros (frozen) on a TV, a tablet, and from hosts that don't say.
+	 */
+	readonly safeArea: Readonly<SafeArea>;
 	/** 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. */
@@ -992,6 +1075,20 @@ export interface Play {
 	 * mode. Unchanged without a view.
 	 */
 	toScreen(p: Point): Point;
+	/**
+	 * Where a player's hand aims on the game's viewport, in fractions (0–1), by player id (their newest frame) or from
+	 * a frame: use it for what the hand touches, catches, presses; toScreen(wrist) only to draw on the body. One rule
+	 * for every game, the protocol's aimPoint: in landscape (a TV, a tablet) the wrist through toScreen, on the
+	 * avatar's hand (its smoothed body) or, over the video, on the real one; in portrait (a phone held upright, where
+	 * the camera image is small at the bottom and raised hands leave it) the wrist stretched around the shoulders to
+	 * the whole screen (as PlayerFrame.leftHand), so arms straight up reach the top (y ≈ 0.15) and arms out the edges,
+	 * held 300 ms when the camera loses the wrist. null when the hand isn't seen.
+	 *
+	 * @example
+	 * const p = play.aim(1, 'right')
+	 * if (p && hit(star, p.x * innerWidth, p.y * innerHeight)) pop(star)
+	 */
+	aim(player: number | PlayerFrame, side: HandSide): Point | null;
 	/**
 	 * 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

package/dist/index.js

@@ -1,10 +1,13 @@
 import {
+  AimHold,
   BodyInterpolator,
   MAX_PICTURE_SIDE,
+  NO_SAFE_AREA,
   NS,
   PICTURE_JPEG_QUALITY,
   PROTOCOL_VERSION,
   __publicField,
+  aimPoint,
   checkPicture,
   defaultAvatarFor,
   drawAvatar,
@@ -14,13 +17,14 @@ import {
   parseGameStats,
   parsePictureResult,
   parsePictureTitle,
+  parseSafeArea,
   parseTurnOrder,
   parseTurnPlayers,
   parseView,
   smoothBody,
   toScreen,
   wire
-} from "./chunks/chunk-QUFAT4K5.js";
+} from "./chunks/chunk-WS2JRQ53.js";
 
 // src/adapters.ts
 function muteDuringBreaks(play, win = window) {
@@ -405,7 +409,7 @@ function easy(connecting) {
     p.on("frame", (f) => {
       emit("players", { players: f.players });
       for (const pl of f.players) {
-        emit("hands", { player: pl.id, left: pl.leftHand, right: pl.rightHand });
+        emit("hands", { player: pl.id, left: pl.leftHand, right: pl.rightHand, aim: { left: p.aim(pl, "left"), right: p.aim(pl, "right") } });
         if (shapes.get(pl.id) !== pl.shape) {
           shapes.set(pl.id, pl.shape);
           emit("shape", { player: pl.id, shape: pl.shape });
@@ -455,6 +459,12 @@ function easy(connecting) {
     get muted() {
       return play?.muted ?? false;
     },
+    get orientation() {
+      return play?.orientation ?? "landscape";
+    },
+    get safeArea() {
+      return play?.safeArea ?? NO_SAFE_AREA;
+    },
     get view() {
       return play?.view ?? null;
     },
@@ -463,13 +473,14 @@ function easy(connecting) {
     },
     reportStats: (s) => play?.reportStats(s),
     toScreen: (p) => play ? play.toScreen(p) : toScreen(null, p),
+    aim: (player, side) => play ? play.aim(player, side) : null,
     avatarOf: (player) => play ? play.avatarOf(player) : early.of(player),
     drawAvatar: (...args) => play ? play.drawAvatar(...args) : drawEarly(...args),
     smoothedBody: (...args) => play ? play.smoothedBody(...args) : early.smoothedBody(...args)
   };
 }
 var none = Object.freeze([]);
-var startInfo = (p) => ({ ageRange: p.ageRange, players: p.players, locale: p.locale, mode: p.mode, backdrop: p.backdrop, view: p.view, device: p.device, turns: p.turns, input: p.input, pointer: p.pointer, canSavePicture: p.canSavePicture, muted: p.muted });
+var startInfo = (p) => ({ ageRange: p.ageRange, players: p.players, locale: p.locale, mode: p.mode, orientation: p.orientation, safeArea: p.safeArea, backdrop: p.backdrop, view: p.view, device: p.device, turns: p.turns, input: p.input, pointer: p.pointer, canSavePicture: p.canSavePicture, muted: p.muted });
 var playingNow = (p) => p.input === "remote" ? p.players[0] ?? 1 : 1;
 function endOf(p, score, last) {
   const now = playingNow(p);
@@ -536,6 +547,9 @@ function connect(channel = windowChannel(), options = {}) {
     let started = false;
     let backdrop = "none";
     let view = null;
+    let orientation = "landscape";
+    let latest = [];
+    const hold = new AimHold();
     let input = "body";
     let players = Object.freeze([]);
     let turns = players;
@@ -568,6 +582,9 @@ function connect(channel = windowChannel(), options = {}) {
         backdrop = m.backdrop === "video" ? "video" : "none";
         view = parseView(m.view) ?? null;
         const device = parseDeviceHint(m.device) ?? null;
+        orientation = m.orientation === "portrait" ? "portrait" : "landscape";
+        const safe = parseSafeArea(m.safeArea);
+        const safeArea = safe ? Object.freeze(safe) : NO_SAFE_AREA;
         input = m.input === "remote" ? "remote" : "body";
         const pointer2 = input === "remote" && m.pointer === true;
         pictures = m.pictures === true;
@@ -594,6 +611,8 @@ function connect(channel = windowChannel(), options = {}) {
           input,
           pointer: pointer2,
           muted: m.muted,
+          orientation,
+          safeArea,
           ageRange: m.ageRange ?? "6-8",
           get backdrop() {
             return backdrop;
@@ -606,6 +625,14 @@ function connect(channel = windowChannel(), options = {}) {
             reported = parseGameStats(s);
           },
           toScreen: (p) => toScreen(view, p),
+          aim(player, side) {
+            const id = typeof player === "number" ? player : player?.id;
+            const frame = typeof player === "number" ? latest.find((f) => f.id === player) : player;
+            const portrait = orientation === "portrait";
+            const body = frame ? (backdrop !== "video" || portrait ? smoothedBody(frame) : null) ?? frame.body : null;
+            const p = body ? aimPoint(body, side, { orientation, view }) : null;
+            return portrait && typeof id === "number" ? hold.at(AimHold.key(id, side), p, performance.now()) : p;
+          },
           avatarOf: (player) => avatars.of(player),
           drawAvatar: drawAvatar2,
           smoothedBody,
@@ -651,7 +678,10 @@ function connect(channel = windowChannel(), options = {}) {
       } else if (!started) return;
       else {
         let message = m;
-        if (m.type === "frame" && Array.isArray(m.players)) avatars.note(m.players, m.t);
+        if (m.type === "frame" && Array.isArray(m.players)) {
+          avatars.note(m.players, m.t);
+          latest = m.players;
+        }
         if (m.type === "backdrop") {
           if (m.backdrop !== "video" && m.backdrop !== "none") return;
           const next = parseView(m.view) ?? null;

package/dist/integrity.json

@@ -1,12 +1,12 @@
 {
   "package": "@fabi-play/sdk",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "algorithm": "sha384",
   "files": {
-    "fabi-play.js": "sha384-FpM2nE3/MMqC7jUzUTJ59Ta5f3YALEWS3Flkfn78AD9ixTlV8ZjSvp3Rb8nOP39f",
-    "fabi-play.umd.js": "sha384-nCwjRGf7UUDl+mFo8l4up0/7CKKB16grQRbiUBoxQ9A7CHuS9h59Tb7YJ77m/BLp",
-    "fabi-play.umd.min.js": "sha384-840JxTr5Fpmt8bCYAL6W0D6CYYt4On8g9NZmLFGfgWTpPvsNi5TtdCrPmRZAGjqK",
-    "fabi-play.d.ts": "sha384-nU69EaldqZNzlZNMNpHZmhMtN8GV2ZEzlFdy/CvZVv0IxyFuceHeXDrPX48EZuJc",
-    "fabi-play.schema.json": "sha384-/rtU1nyXCiEON87rFJIceNrFD8CL8rgIM38N/FEDp4GTPY9aWs4WjkE8YAEYQqI6"
+    "fabi-play.js": "sha384-oFpkf9B1CsUDL+XlGXShlfHQ3DTLlgS44lky9VxfWnBeqvmNphqu65gEPayVBIfG",
+    "fabi-play.umd.js": "sha384-tK0C5xmAYcSgn3f6b5GwRW4FSvlYaL/mU66pq59HL7PxleXQ8pq5dlscRP2eBBnS",
+    "fabi-play.umd.min.js": "sha384-jm4xGGWJgLcbQz0V1il8tK2X6XAIn8DWbSJwMk9qW5ow7f1wnJlMuthrBJ4wPmOl",
+    "fabi-play.d.ts": "sha384-ck4BadH6pHuM4CSneqAG70DIGprN0PUMf+DPfGM9D1XUKcnMuQrgqm5d1K3Lmvo4",
+    "fabi-play.schema.json": "sha384-MzT9DYjL6d80Ff+4iZQFbrQVpg7q02ok5Bzkb2UKshUStaFZocty+JxuzLHXXheR"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/sdk",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "What a game imports: players, movements and the end of the game, from inside its sandboxed frame.",
   "keywords": [
     "fabi-play",
@@ -36,8 +36,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@fabi-play/avatars": "^0.4.0",
-    "@fabi-play/protocol": "^0.4.0",
+    "@fabi-play/avatars": "^0.7.0",
+    "@fabi-play/protocol": "^0.7.0",
     "dts-bundle-generator": "9.5.1",
     "esbuild": "0.28.2",
     "tsx": "4.23.15",