@fabi-play/sdk 0.4.0 → 0.7.0

package/README.md

@@ -45,6 +45,63 @@ From the CDN, pinned to an exact version with its Subresource Integrity hash (li
 | `fabi-play.d.ts` | types for script-tag games (`FabiPlay.PlayerFrame`, …) |
 | `fabi-play.schema.json` | the JSON Schema of `fabi-play.json` |
 
+## The cover
+
+The game's card in the catalogue (the TV's carousel, the phone, the admin) is its cover, an image you draw. Put it
+with the game's files and name it in `fabi-play.json`:
+
+```json
+"cover": "cover.jpg"
+```
+
+- **16:9**, 1280×720 recommended, at most 150 KB (`COVER_MAX_BYTES`). `.jpg`, `.jpeg`, `.png` or `.webp`; JPG
+  (quality about 80) is the safest on old TV browsers.
+- **A path relative to the game's address**, like `entry`: no scheme, no leading `/`, no `\`, no `.` or `..`
+  segments, extension in lowercase, up to 128 characters.
+- **Optional.** Fabi Play's review checks the file (it exists, it is an image, its size, its shape: 16:9 within 2%,
+  `COVER_ASPECT`, `COVER_ASPECT_TOLERANCE`) and warns about a problem; without a working cover the catalogue shows
+  another picture of the game.
+
+## Portrait (a phone held upright)
+
+A phone alone («Gioca qui / Play here») is held upright, close to the child (about one step away, upper body in
+view), and offers only games that say they can be played in portrait:
+
+```json
+"orientations": ["landscape", "portrait"]
+```
+
+- **Optional**, `["landscape"]` by default; non-empty, no repeats, from `"landscape"` and `"portrait"`.
+- `play.orientation` (and the `start` event's `orientation`) says the one the game started in: `'portrait'` or
+  `'landscape'` (also what older hosts mean). Use it to choose a layout, but size everything from the real viewport
+  (`innerWidth` × `innerHeight`).
+- On a phone the child is close and often seen from the head to the knees: don't rely on the feet being visible.
+- **Aim with `play.aim`, not with `toScreen(wrist)`.** On a phone the camera image (`play.view`) is drawn small at the
+  bottom of the screen, and raised hands even leave it, so a wrist through `toScreen` never reaches the top.
+  `play.aim(player, side)` (`side` `'left'` or `'right'`; a player id or a frame) is where a hand aims, in fractions
+  of the page: in portrait the arms' reach around the shoulders stretched to the whole screen (arms straight up near
+  the top, y ≈ 0.15; arms out to the sides near the edges; the wrist on the shoulder line at y ≈ 0.53; hands by the
+  hips near the bottom, y ≈ 0.87), held for 300 ms when the camera loses the wrist; in landscape exactly
+  `toScreen(wrist)` on the avatar's hand (or the real one over the video), as before. So one line works on every
+  screen: **use `aim` for what the hand touches, catches or presses; `toScreen(wrist)` only to draw on the body**.
+  The script tag has `FabiPlay.aim(player, side)` and the `hands` event's `aim: { left, right }`; with
+  `@fabi-play/engine`, `engine.hands()`, `engine.touched()` and `engine.handMarkers()` already aim, nothing to change.
+
+  ```js
+  const p = play.aim(1, 'right')
+  if (p && near(star, p.x * innerWidth, p.y * innerHeight)) pop(star)
+  ```
+
+- **Safe area.** A phone's notch, rounded corners and home bar cover parts of the page, and the game's frame can't
+  read `env(safe-area-inset-*)`. `play.safeArea` (`FabiPlay.safeArea`, the `start` event's `safeArea`) says how much,
+  in fractions of the page: `{ top, bottom, left, right }`, top and bottom of its height, left and right of its
+  width, each from 0 to 0.25; zeros on a TV, a tablet and from older hosts. Keep buttons, scores and targets out of
+  it, and still paint your background under it:
+
+  ```js
+  hud.style.top = `${play.safeArea.top * innerHeight}px`
+  ```
+
 ## Fabi explains your game (intro)
 
 Before calibration, Fabi (the mascot) can explain your game on the TV in a few steps: a speech bubble over an image
@@ -84,7 +141,8 @@ of the game, or a move shown with the children's own avatars, which they can als
 
 `play.view` is where the camera image lies on your page, so each child's avatar and hands are where the child stands.
 Draw anything that belongs to a child at `play.toScreen(point)` (a wrist, the head, the avatar's box), never at your
-own mapping of player space.
+own mapping of player space. For what a hand touches, use `play.aim(player, side)`: the same as `toScreen(wrist)` on
+a TV or a tablet, and on a phone held upright the hand stretched to the whole screen (see Portrait).
 
 The view is not fixed. By default the screen frames the children: when they stand far from the camera it zooms in on
 them, up to 1.8×, so every child's avatar is about the same size and reaches the same things, near or far. It decides

package/dist/avatars.d.ts

@@ -142,7 +142,7 @@ export interface FaceDef {
 	/** Eyebrows of this colour (people): a little attitude. */
 	brows?: string;
 }
-/** The age band an avatar is for, or 'all': offered in every band (Fabi the fox, the app's mascot). */
+/** The age band an avatar is for, or 'all': of no band (Fabi the fox, the app's mascot: the host, in no picker). */
 export type AvatarBand = AgeRange | "all";
 /** An avatar, as data: one renderer draws any definition. */
 export interface AvatarDef {
@@ -155,7 +155,7 @@ export interface AvatarDef {
 	};
 	/**
 	 * The age band the avatar is for, its home: its style and its body proportions (see BAND_BODY in rig.ts). 'all': in
-	 * every band's list, drawn with the 6–8 proportions. See alsoIn for an avatar offered in other bands too.
+	 * no band's list (the mascot), drawn with the 6–8 proportions. See alsoIn for an avatar offered in other bands too.
 	 */
 	band: AvatarBand;
 	/**
@@ -164,7 +164,7 @@ export interface AvatarDef {
 	 * (outline), bandOf, and its proportions when the band shown is not known. Not for 'all' (the mascot).
 	 */
 	alsoIn?: readonly AgeRange[];
-	/** A special avatar (the mascot): first in every band's list; pickers may mark it. */
+	/** A special avatar (the mascot): the host, not a player; in no band's list (AVATAR_BANDS). */
 	special?: boolean;
 	/** Its colours. */
 	palette: Palette;

package/dist/avatars.js

@@ -6,7 +6,7 @@ import {
   drawShapes,
   frameOf,
   iconShapes
-} from "./chunks/chunk-QUFAT4K5.js";
+} from "./chunks/chunk-WS2JRQ53.js";
 export {
   BAND_BODY,
   DEFAULT_AVATAR,

package/dist/chunks/{chunk-QUFAT4K5.js → chunk-WS2JRQ53.js}

@@ -70,6 +70,73 @@ function parseView(v) {
   return isNumber(x) && isNumber(y) && isNumber(w) && isNumber(h) && w > 0 && h > 0 ? { x, y, w, h } : void 0;
 }
 var toScreen = (view, p) => view ? { x: view.x + p.x * view.w, y: view.y + p.y * view.h } : { x: p.x, y: p.y };
+var AIM_VISIBLE = 0.5;
+var HAND_SPACE = { left: 1.6, top: 1.6, w: 3.2, h: 3 };
+var TORSO_PER_SHOULDER_WIDTH = 1.2;
+function aimPoint(who, side, opts = {}) {
+  const body = Array.isArray(who) ? who : who.body;
+  if (!Array.isArray(body)) return null;
+  const w = side === "left" ? P.leftWrist : P.rightWrist;
+  const at = (i) => isNumber(body[i * 3]) && isNumber(body[i * 3 + 1]) && (body[i * 3 + 2] ?? 0) >= AIM_VISIBLE ? i : -1;
+  if (at(w) < 0) return null;
+  const wx = body[w * 3];
+  const wy = body[w * 3 + 1];
+  if (opts.orientation !== "portrait") return toScreen(opts.view, { x: wx, y: wy });
+  if (at(P.leftShoulder) < 0 || at(P.rightShoulder) < 0) return null;
+  const ls = P.leftShoulder * 3;
+  const rs = P.rightShoulder * 3;
+  const sx = (body[ls] + body[rs]) / 2;
+  const sy = (body[ls + 1] + body[rs + 1]) / 2;
+  const lh = P.leftHip * 3;
+  const rh = P.rightHip * 3;
+  const hx = (body[lh] + body[rh]) / 2;
+  const hy = (body[lh + 1] + body[rh + 1]) / 2;
+  let torso = isNumber(hx) && isNumber(hy) ? Math.hypot(hx - sx, hy - sy) : 0;
+  if (at(P.leftHip) < 0 || at(P.rightHip) < 0) torso = Math.max(torso, TORSO_PER_SHOULDER_WIDTH * Math.hypot(body[ls] - body[rs], body[ls + 1] - body[rs + 1]));
+  torso = Math.max(torso, 0.01);
+  return {
+    x: clamp01((wx - sx + HAND_SPACE.left * torso) / (HAND_SPACE.w * torso)),
+    y: clamp01((wy - sy + HAND_SPACE.top * torso) / (HAND_SPACE.h * torso))
+  };
+}
+var AIM_HOLD_MS = 300;
+var AimHold = class {
+  constructor(holdMs = AIM_HOLD_MS) {
+    __publicField(this, "holdMs", holdMs);
+    __publicField(this, "last", /* @__PURE__ */ new Map());
+  }
+  /** A number for a player's hand. */
+  static key(player, side) {
+    return player * 2 + (side === "right" ? 1 : 0);
+  }
+  /** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+  at(key, p, t) {
+    const l = this.last.get(key);
+    if (p) {
+      if (l) {
+        l.x = p.x;
+        l.y = p.y;
+        l.t = t;
+      } else this.last.set(key, { x: p.x, y: p.y, t });
+      return p;
+    }
+    if (!l) return null;
+    if (t - l.t <= this.holdMs) return { x: l.x, y: l.y };
+    this.last.delete(key);
+    return null;
+  }
+  /** Forgets every hand. */
+  clear() {
+    this.last.clear();
+  }
+};
+var MAX_SAFE_INSET = 0.25;
+var NO_SAFE_AREA = Object.freeze({ top: 0, bottom: 0, left: 0, right: 0 });
+function parseSafeArea(v) {
+  if (!isObject(v)) return void 0;
+  const f2 = (n) => isNumber(n) ? Math.min(Math.max(n, 0), MAX_SAFE_INSET) : 0;
+  return { top: f2(v.top), bottom: f2(v.bottom), left: f2(v.left), right: f2(v.right) };
+}
 var DEVICE_TIERS = ["high", "medium", "low"];
 function parseDeviceHint(v) {
   if (!isObject(v)) return void 0;
@@ -103,8 +170,10 @@ function parseTurnOrder(v) {
   if (!Array.isArray(v) || v.length < 1 || v.length > MAX_PLAYERS || !v.every(isPlayerId) || new Set(v).size !== v.length) return void 0;
   return [...v];
 }
+var COVER_ASPECT = 16 / 9;
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var clamp01 = (n) => Math.min(Math.max(n, 0), 1);
 var POSE_HEADER = 12;
 var POSE_BODY_BYTES = LANDMARKS * 4;
 var poseBytes = (bodies) => POSE_HEADER + bodies * POSE_BODY_BYTES;
@@ -2384,6 +2453,10 @@ export {
   wire,
   parseView,
   toScreen,
+  aimPoint,
+  AimHold,
+  NO_SAFE_AREA,
+  parseSafeArea,
   parseDeviceHint,
   parseGameStats,
   parseCursor,

package/dist/fabi-play.d.ts

@@ -178,6 +178,20 @@ declare namespace FabiPlay {
 		/** 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";
 	/**
@@ -230,6 +244,15 @@ declare namespace FabiPlay {
 	 * 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;
@@ -246,6 +269,8 @@ declare namespace FabiPlay {
 		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). */
 	 | {
@@ -437,6 +462,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[];
 		/**
@@ -461,7 +494,19 @@ declare namespace FabiPlay {
 		 * 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";
 	/**
@@ -551,8 +596,12 @@ 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;
+		/** 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. */
@@ -581,11 +630,20 @@ declare namespace FabiPlay {
 	} & {
 		/** 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: {
@@ -640,7 +698,7 @@ declare namespace FabiPlay {
 	 *
 	 * @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)
 	 */
@@ -708,6 +766,10 @@ declare namespace FabiPlay {
 		}): 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. */
@@ -719,6 +781,13 @@ declare namespace FabiPlay {
 		 * 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.
@@ -863,6 +932,20 @@ declare namespace FabiPlay {
 		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. */
@@ -885,6 +968,20 @@ declare namespace FabiPlay {
 		 * 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