@fabi-play/protocol 0.5.0 → 0.7.0

package/README.md

@@ -66,6 +66,18 @@ and offers only games that list `'portrait'`; the TV and the tablet are landscap
 game starts in with `init.orientation` (`orientationOf(width, height)`: width ≥ height is `'landscape'`); absent from
 older hosts, it means `'landscape'`. It is informational: a game lays out from its real viewport size.
 
+**Aiming.** `aimPoint(body | frame, side, { orientation, view })` is the one rule for where a hand aims on the
+screen (what it touches), in fractions: in landscape `toScreen(view, wrist)`; in portrait, where the camera image is
+small at the bottom of a phone, the wrist stretched around the shoulders to the whole screen (`HAND_SPACE`, the
+stretch of `PlayerFrame.leftHand`, clamped to 0–1; with the hips unseen the torso is at least
+`TORSO_PER_SHOULDER_WIDTH` shoulder widths). null when the wrist (in portrait, the shoulders too) isn't seen
+(`AIM_VISIBLE`). `AimHold` keeps a lost hand where it was for `AIM_HOLD_MS` (300). The SDK's `play.aim` and the
+engine's `hands()` apply it.
+
+**Safe area.** `init.safeArea` (optional) is what a phone's notch, rounded corners and home bar cover, in fractions
+of the game's viewport: `{ top, bottom, left, right }` (`SafeArea`). `parseSafeArea` clamps each side to 0–0.25
+(`MAX_SAFE_INSET`), 0 when missing; `NO_SAFE_AREA` is all zeros, what hosts that don't send it mean.
+
 ## The carousel on two screens
 
 The phone can show the TV's carousel of games, and both move together. While the grown-up swipes, the phone sends

package/dist/index.d.ts

@@ -611,6 +611,87 @@ export interface BackdropView {
 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;
+/** A hand: the child's own left or right. */
+export type HandSide = "left" | "right";
+/** aimPoint's options: the screen's orientation (absent = 'landscape') and the view (see BackdropView). */
+export interface AimOptions {
+	orientation?: Orientation;
+	view?: BackdropView | null;
+}
+/** A body point counts for aiming when the camera sees it this well (as the avatars and the engine do). */
+export declare const AIM_VISIBLE = 0.5;
+/**
+ * The space the arms reach, around the shoulders, in torsos (shoulders to hips): HAND_SPACE.left and .top from the
+ * shoulders' midpoint, HAND_SPACE.w × HAND_SPACE.h wide and high. It is stretched to the whole screen: the space of
+ * PlayerFrame.leftHand and rightHand (@fabi-play/motion's hands() and handSpace()), and of aimPoint in portrait.
+ */
+export declare const HAND_SPACE: {
+	readonly left: 1.6;
+	readonly top: 1.6;
+	readonly w: 3.2;
+	readonly h: 3;
+};
+/**
+ * The torso when the hips are not seen (a phone close by, hips out of the image, where their points are guesses
+ * clamped to its edge): at least this many shoulder widths, so the stretch does not blow up.
+ */
+export declare const TORSO_PER_SHOULDER_WIDTH = 1.2;
+/**
+ * Where a hand aims on the game's viewport, in fractions (0–1): what the hand touches, picks, catches. One rule for
+ * every game, by orientation:
+ *
+ * - 'landscape' (a TV, a tablet; the default): on the body, toScreen(view, wrist), where the child sees their hand
+ *   (in the video, or the avatar's when body is the smoothed body the avatar is drawn with). Not clamped.
+ * - 'portrait' (a phone held upright): the camera image is small (the view sits at the bottom) and raised hands leave
+ *   it, so the wrist is stretched instead (HAND_SPACE, as PlayerFrame.leftHand): the space the arms reach around the
+ *   shoulders becomes the whole screen, clamped to 0–1. Arms straight up land near the top (y ≈ 0.15), arms out to
+ *   the sides at the edges (x ≈ 0.02 and 0.98), the wrist on the shoulder line at y ≈ 0.53, hands down by the hips
+ *   near the bottom (y ≈ 0.87). The view does not matter. When the hips are not seen the torso is at least
+ *   TORSO_PER_SHOULDER_WIDTH shoulder widths.
+ *
+ * null when the camera doesn't see the wrist well enough (AIM_VISIBLE), and in portrait the shoulders too. Pure:
+ * AimHold keeps a hand that is lost for a moment. Draw on the body with toScreen(wrist); aim with this.
+ */
+export declare function aimPoint(who: Body | Pick<PlayerFrame, "body">, side: HandSide, opts?: AimOptions): Point | null;
+/** How long AimHold keeps a lost hand where it last was, ms: a wrist the camera misses for a few frames. */
+export declare const AIM_HOLD_MS = 300;
+/**
+ * Keeps each hand's aim through short losses: a hand the camera misses for up to holdMs stays where it last was,
+ * so it does not blink out and back (and a touch is not lost and made again). Past that it is gone (null). One per
+ * game; a key per hand, e.g. AimHold.key(player, side).
+ */
+export declare class AimHold {
+	readonly holdMs: number;
+	private readonly last;
+	constructor(holdMs?: number);
+	/** A number for a player's hand. */
+	static key(player: number, side: HandSide): number;
+	/** The aim to use at time t (ms) for the hand key, given what aimPoint said now (p, or null if lost). */
+	at(key: number, p: Point | null, t: number): Point | null;
+	/** Forgets every hand. */
+	clear(): void;
+}
+/**
+ * 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;
+}
+/** The largest inset parseSafeArea keeps, a fraction of the viewport. */
+export declare const MAX_SAFE_INSET = 0.25;
+/** No inset: what a game gets from hosts that don't send one. */
+export declare const NO_SAFE_AREA: Readonly<SafeArea>;
+/**
+ * A safe area, or undefined if it is not an object: each of top, bottom, left, right a finite number clamped to
+ * 0–MAX_SAFE_INSET, 0 if missing or not a number. Extra fields are dropped.
+ */
+export declare function parseSafeArea(v: unknown): SafeArea | undefined;
 /** 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[];
@@ -673,6 +754,10 @@ export type HostMessage =
  * 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;
@@ -690,6 +775,7 @@ export type HostMessage =
 	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). */
  | {

package/dist/index.js

@@ -406,6 +406,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: clamp012((wx - sx + HAND_SPACE.left * torso) / (HAND_SPACE.w * torso)),
+    y: clamp012((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 f = (n) => isNumber(n) ? Math.min(Math.max(n, 0), MAX_SAFE_INSET) : 0;
+  return { top: f(v.top), bottom: f(v.bottom), left: f(v.left), right: f(v.right) };
+}
 var DEVICE_TIERS = ["high", "medium", "low"];
 function parseDeviceHint(v) {
   if (!isObject(v)) return void 0;
@@ -565,6 +632,7 @@ var voiceUrl = (base, key, voice = FABI_VOICE) => `${base.replace(/\/+$/, "")}/v
 var gamesFor = (games, range, players = 1) => games.filter((g) => g.ageRanges.includes(range) && players >= g.players.min && players <= g.players.max);
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var clamp012 = (n) => Math.min(Math.max(n, 0), 1);
 var SEGMENT = "[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*";
 var isGamePath = (v, ext) => typeof v === "string" && v.length <= 200 && new RegExp(`^(?:${SEGMENT}/)*${SEGMENT}\\.(?:${ext})$`).test(v);
 var isGameId = (v) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v) && v.length <= 60;
@@ -800,6 +868,9 @@ async function migrateStorageKeyAsync(store, newKey, oldKey = legacyStorageKey(n
 }
 export {
   AGE_RANGES,
+  AIM_HOLD_MS,
+  AIM_VISIBLE,
+  AimHold,
   BREAK_REASONS,
   COVER_ASPECT,
   COVER_ASPECT_TOLERANCE,
@@ -814,6 +885,7 @@ export {
   GAME_BACKDROPS,
   GAME_FRAMINGS,
   GAME_INPUTS,
+  HAND_SPACE,
   INTRO_MAX_CHARS,
   INTRO_MAX_STEPS,
   INTRO_MOVES,
@@ -824,8 +896,10 @@ export {
   MAX_PICTURE_SIDE,
   MAX_PICTURE_TITLE,
   MAX_PLAYERS,
+  MAX_SAFE_INSET,
   MIRROR_ENABLED,
   MOVEMENTS,
+  NO_SAFE_AREA,
   NS,
   ORIENTATIONS,
   P,
@@ -845,9 +919,11 @@ export {
   SCREEN_SIZES,
   SCREEN_SIZE_KEY,
   TOO_CLOSE_KEY,
+  TORSO_PER_SHOULDER_WIDTH,
   VIDEO_BLOCKS,
   VIDEO_STATES,
   acceptsBinaryPose,
+  aimPoint,
   checkPicture,
   chunkPicture,
   decodePose,
@@ -882,6 +958,7 @@ export {
   parsePictureMessage,
   parsePictureResult,
   parsePictureTitle,
+  parseSafeArea,
   parseScreenMessage,
   parseTurnOrder,
   parseTurnPlayers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/protocol",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Messages between the phone, the screen and the games, with their checks.",
   "keywords": [
     "fabi-play",