@fabi-play/sdk 0.3.0 → 0.5.0

package/README.md

@@ -45,6 +45,38 @@ 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.
+
 ## 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
@@ -127,6 +159,25 @@ opts in with `inputs` in `fabi-play.json`:
   `"remote"` must work with the arrow keys alone and, where it has things to pick (bubbles, answers, buttons), let a
   pointer click them as well: pointer events, large hit areas, a hover highlight. Fabi Play's own menus, pickers
   and turn screen are clickable too.
+- **The arrows as a free cursor (`"remoteCursor": true`).** A game picked or drawn with a pointer (a painting
+  game) can ask for the arrows to move a cursor instead of making gestures, with `"remoteCursor": true` in
+  `fabi-play.json` (only next to `"remote"` in `inputs`):
+
+  ```json
+  "inputs": ["body", "remote"], "remoteCursor": true
+  ```
+
+  Then, in remote mode, the screen draws a cursor above the game and moves it with the arrows: slowly at first, for
+  precision, faster the longer an arrow is held, stopping at the edges. OK presses it: held, it stays pressed until
+  released (OK held = paint); a quick OK is a click. Back is still Fabi Play's pause. The game gets it exactly like
+  a Magic Remote: `play.pointer` / `FabiPlay.hasPointer` is `true`, and the SDK makes ordinary pointer and mouse
+  events in the page at the cursor (`pointermove`/`mousemove`, `pointerover`/`pointerout`, `pointerdown`/`mousedown`
+  while OK goes down, `pointerup`/`mouseup` then `click` when it comes up; `pointerType` `'mouse'`; at a pause, a
+  break or a turn a held OK is let go with `pointercancel` and `mouseup`, no click). So a game written for the
+  Magic Remote's pointer works with the arrows unchanged, and the other way round. The arrows make no gestures
+  then: no lanes, no jump, no squat. `play.on('cursor', ({ x, y, down }) => …)` gives the raw position (fractions of
+  the page) if you want it, but the events are enough. Old TV browsers without `PointerEvent` get the mouse events
+  only: listen to both, or to mouse events.
 - **One remote is one child; several children take turns, a round each, if the game follows the contract.**
   Turns are not free: the game must follow the steps below, and say so in `fabi-play.json` with
   `"turns": true` (only next to `"remote"` in `inputs`): `"inputs": ["body", "remote"], "turns": true`. A game
@@ -159,6 +210,39 @@ opts in with `inputs` in `fabi-play.json`:
 - **Games aimed with the hands** (`movements: ["hands"]`, the `pointer()` adapter) should not list `"remote"`
   unless they offer a remote-friendly selection: a child with a remote has no hand cursor.
 
+## Saving a picture on the phone
+
+A game can save a picture on the family's phone, in its gallery: the drawing at the end, the photo of a wall before
+it is cleared.
+
+```js
+if (play.canSavePicture) {
+  const result = await play.savePicture(canvas, { title: 'Il nostro muro' })
+  // 'sent' | 'unavailable' | 'too-big' | 'error'
+}
+play.on('capabilities', ({ pictures }) => showSaveButton(pictures))
+```
+
+With the script tag: `FabiPlay.savePicture(canvas, { title })`, `FabiPlay.canSavePicture`,
+`FabiPlay.on('capabilities', ({ pictures }) => …)`, and `canSavePicture` in the `start` event.
+
+- **`canSavePicture`** is `true` when the screen says a phone that can save pictures is linked (the Fabi Play app;
+  the web phone can't, and nor can TV-only remote sessions). It can change mid-game (a phone joins, the last one
+  leaves): the `capabilities` event says so. `false` before the start and from older screens.
+- **`savePicture(source, { title })`** takes a canvas or a data URL. A canvas is scaled down to 1920 px on its
+  longer side, drawn on white (JPEG has no transparency) and encoded as JPEG at quality 0.85 (lower, then smaller,
+  if it would be over 3 MiB). A data URL must be `data:image/jpeg;base64,…` or `data:image/png;base64,…`, at most
+  3 MiB, and is sent as it is. `title` (optional, up to 60 characters) names the file. A canvas tainted by another
+  site's image can't be read: draw only your own images on it.
+- **It resolves, never rejects**, with `'sent'` (the phone has it), `'unavailable'` (`canSavePicture` is false),
+  `'too-big'` (over 3 MiB) or `'error'` (not an image, a canvas that can't be read, the link dropped, no answer in
+  2 minutes). Never make the children wait on it: show the picture "flying into the phone" and go on.
+- **If the phone can't save it** (the parent denied the permission), Fabi Play tells the parent on the phone; the
+  game is told `'sent'` or `'error'`, and should not tell the children.
+- **Privacy.** The picture goes only from the TV to the phone, over the direct link they already share (WebRTC,
+  encrypted), never through or to a server, and no copy is kept anywhere else. Only a JPEG or PNG image can travel
+  this way (the screen checks the data URL and its bytes): a game can send nothing else to the phone.
+
 Docs: https://docs.fabiplay.app.
 
 ## License

package/dist/avatars.d.ts

@@ -106,21 +106,21 @@ export interface Palette {
 	hair?: string;
 }
 /** The head's outline. */
-export type HeadShape = "round" | "wide" | "tall" | "square" | "bulb" | "bucket";
+export type HeadShape = "round" | "wide" | "tall" | "square" | "bulb" | "bucket" | "snout-long";
 /** The ears (or what is in their place: horns, antennae, a fin). */
-export type EarKind = "none" | "pointy" | "round" | "big-round" | "long" | "side" | "tufts" | "antenna" | "antennae" | "horns" | "unicorn" | "floppy" | "droopy" | "fin" | "human";
+export type EarKind = "none" | "pointy" | "round" | "big-round" | "long" | "side" | "tufts" | "antenna" | "antennae" | "horns" | "unicorn" | "floppy" | "droopy" | "fin" | "human" | "pixie";
 /** How the eyes are drawn. */
 export type EyeKind = "dot" | "big" | "mask" | "screen" | "almond" | "visor" | "calm" | "slit" | "goggle" | "bead";
 /** How the mouth (or beak) is drawn. */
-export type MouthKind = "none" | "smile" | "open" | "cat" | "beak" | "teeth" | "grill" | "tiny" | "smirk" | "bill" | "hook" | "jaws";
+export type MouthKind = "none" | "smile" | "open" | "cat" | "beak" | "teeth" | "grill" | "tiny" | "smirk" | "bill" | "hook" | "jaws" | "toothy";
 /** The patch around the nose and mouth. */
 export type MuzzleKind = "none" | "oval" | "heart" | "monkey" | "disc" | "cheeks" | "band";
 /** The tail, behind the body. */
-export type TailKind = "none" | "fluffy" | "brush" | "pom" | "long" | "curl" | "tuft" | "striped" | "spiky" | "arrow" | "fish" | "plume";
+export type TailKind = "none" | "fluffy" | "brush" | "pom" | "long" | "curl" | "tuft" | "striped" | "spiky" | "arrow" | "fish" | "plume" | "thick";
 /** Things on the head. */
-export type HeadExtra = "mane" | "rainbow-mane" | "stripes" | "spikes" | "spots" | "curl" | "helmet" | "bolts" | "whiskers" | "tuft" | "brows" | "eggshell" | "wool" | "eye-spot" | "crest" | "forehead" | "gills" | "ruff" | "hair" | "curls" | "locks" | "ninja-hood" | "cap" | "safari-hat" | "wizard-hat" | "plume" | "stripe" | "bandana" | "eye-patch" | "dive-mask" | "domino";
+export type HeadExtra = "mane" | "rainbow-mane" | "stripes" | "spikes" | "spots" | "curl" | "helmet" | "bolts" | "whiskers" | "tuft" | "brows" | "eggshell" | "wool" | "eye-spot" | "crest" | "forehead" | "gills" | "ruff" | "hair" | "curls" | "locks" | "ninja-hood" | "cap" | "safari-hat" | "wizard-hat" | "plume" | "stripe" | "bandana" | "eye-patch" | "dive-mask" | "domino" | "bun" | "flower-crown";
 /** Things on the body. */
-export type BodyExtra = "wings" | "backpack" | "sheet" | "tentacles" | "panel" | "badge" | "joints" | "feathers" | "flippers" | "boots" | "scarf" | "spots" | "wool" | "robe" | "cape" | "fins" | "tank" | "straps" | "belt" | "stripes" | "pauldrons" | "emblem" | "pocket" | "racing-stripe" | "star";
+export type BodyExtra = "wings" | "backpack" | "sheet" | "tentacles" | "panel" | "badge" | "joints" | "feathers" | "flippers" | "boots" | "scarf" | "spots" | "wool" | "robe" | "cape" | "fins" | "tank" | "straps" | "belt" | "stripes" | "pauldrons" | "emblem" | "pocket" | "racing-stripe" | "star" | "tiny-arms" | "strong-legs" | "wings-fairy" | "wand" | "petals";
 /** An avatar's face. */
 export interface FaceDef {
 	/** How the eyes are drawn. */
@@ -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 {
@@ -154,11 +154,17 @@ export interface AvatarDef {
 		it: string;
 	};
 	/**
-	 * The age band the avatar is for: its style and its body proportions (see BAND_BODY in rig.ts). 'all': in every
-	 * band's list, drawn with the 6–8 proportions.
+	 * The age band the avatar is for, its home: its style and its body proportions (see BAND_BODY in rig.ts). 'all': in
+	 * no band's list (the mascot), drawn with the 6–8 proportions. See alsoIn for an avatar offered in other bands too.
 	 */
 	band: AvatarBand;
-	/** A special avatar (the mascot): first in every band's list; pickers may mark it. */
+	/**
+	 * Other age bands the avatar is also offered in (listed in their AVATAR_BANDS too), besides its own band. Shown in
+	 * one of them, it is drawn with that band's proportions (bodyBand(def, band)); its band stays its home: its style
+	 * (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): the host, not a player; in no band's list (AVATAR_BANDS). */
 	special?: boolean;
 	/** Its colours. */
 	palette: Palette;
@@ -223,9 +229,12 @@ export interface BandBody {
 export declare const BAND_BODY: Record<AgeRange, BandBody>;
 export interface RigOptions {
 	mirrored?: boolean;
-	/** Portraits leave the tail out: in a head-and-shoulders crop it would only peek in as a stray shape. */
+	/** Portraits leave the tail and the wand out: in a head-and-shoulders crop they would only peek in as stray shapes. */
 	portrait?: boolean;
-	/** Body proportions (see BAND_BODY); 6–8 by default. avatarShapes takes the avatar's own band. */
+	/**
+	 * Body proportions (see BAND_BODY); 6–8 by default. For avatarShapes, the band the avatar is shown in: it follows
+	 * it only for an avatar offered there too (alsoIn, see bodyBand); otherwise the avatar's own band.
+	 */
 	band?: AgeRange;
 }
 /** The torso frame: origin between the shoulders, r to the right, d down along the torso; lengths in pixels. */
@@ -250,7 +259,10 @@ export declare function avatarShapes(body: Body, def: AvatarDef, box: Box, opts?
 export declare const DEFAULT_AVATAR: AvatarDef;
 /** The avatar with this id, or undefined. */
 export declare const avatarById: (id: string) => AvatarDef | undefined;
-/** The portrait: head and shoulders of the neutral pose, framed in a size × size square at (0, 0). */
-export declare function iconShapes(def: AvatarDef | string, size: number): Shape[];
+/**
+ * The portrait: head and shoulders of the neutral pose, framed in a size × size square at (0, 0). band: the band the
+ * picker shows (see DrawOptions.band).
+ */
+export declare function iconShapes(def: AvatarDef | string, size: number, band?: AgeRange): Shape[];
 
 export {};

package/dist/avatars.js

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