@fabi-play/avatars 0.4.0 → 0.7.0

package/README.md

@@ -1,7 +1,8 @@
 # @fabi-play/avatars
 
-Thirty-nine original, child-friendly avatars, drawn from a body pose: Fabi the fox (the fox of the app icon, the
-mascot), offered in every age band, 12 for each band, and the T-rex and the fairy. The lion, the T-rex and the fairy
+Thirty-nine original, child-friendly avatars, drawn from a body pose: 12 for each age band, the T-rex and the fairy,
+and Fabi the fox (the fox of the app icon, the mascot). Fabi is the host, not a player: no band offers it to the
+children, but the TV and games draw it like any other avatar. The lion, the T-rex and the fairy
 are offered to both 3–5 and 6–8. The TV shows them in place
 of the plain silhouette when the phone's video is not on screen. Each child picks one on the phone, among the avatars
 of their age band. The phone stores only the avatar's id; any valid id is accepted everywhere, whatever the band.
@@ -11,7 +12,7 @@ varied skin tones and gender-neutral looks, and are told apart by their gear.
 
 | Band | Style | id · en · it (the first four are the slot defaults) |
 | --- | --- | --- |
-| all | the app icon's fox: first in every band's list, `special: true`, drawn with the 6–8 proportions; never a slot default | `mascot` Fabi · Fabi |
+| all | the app icon's fox, the host: in no band's list (pickers don't offer it), `special: true`, drawn with the 6–8 proportions; never a slot default; a child saved with it keeps it | `mascot` Fabi · Fabi |
 | 3–5 | cuddly baby animals: big round heads, chubby limbs, soft colours, a soft brown outline | `bunny` Bunny · Coniglietto, `bear` Bear · Orsetto, `panda` Panda · Panda, `penguin` Penguin · Pinguino, `koala` Koala · Koala, `frog` Frog · Ranocchio, `cat` Cat · Gattino, `owl` Owl · Gufetto, `chick` Chick · Pulcino, `puppy` Puppy · Cucciolo, `lamb` Lamb · Agnellino, `duckling` Duckling · Anatroccolo; then, also offered here (home 6–8): `lion`, `trex`, `fairy` |
 | 6–8 | animals and adventure | `fox` Fox · Volpe, `lion` Lion · Leoncino, `dragon` Little Dragon · Draghetto, `unicorn` Unicorn · Unicorno, `tiger` Tiger · Tigrotto, `monkey` Monkey · Scimmietta, `dinosaur` Dinosaur · Dinosauro, `trex` T-Rex · T-Rex, `octopus` Octopus · Polpetto, `ghost` Friendly Ghost · Fantasmino, `shark` Shark · Squalo, `wolf` Wolf · Lupo, `parrot` Parrot · Pappagallo, `fairy` Fairy · Fatina |
 | 9–12 | older kids: smaller heads, slimmer longer limbs, gear, cooler colours, no blush, a cool outline | `robot` Robot · Robot, `astronaut` Astronaut · Astronauta, `ninja` Ninja · Ninja, `skater` Skater · Skater, `alien` Alien · Alieno, `explorer` Explorer · Giramondo, `wizard` Wizard · Mago, `knight` Knight · Cavaliere, `racer` Racer · Pilota, `pirate` Pirate · Pirata, `diver` Diver · Sub, `hero` Hero · Supereroe |
@@ -43,13 +44,14 @@ el.innerHTML = avatarIconSvg('panda', 96)               // web DOM
 ```
 
 - `AVATARS: readonly AvatarDef[]` (all 39), `AVATAR_IDS`, `DEFAULT_AVATAR` (the fox), `avatarById(id)`, `isAvatarId(x)`.
-- `AVATAR_BANDS: Record<AgeRange, readonly AvatarId[]>` (picker order: the mascot, `MASCOT_ID`, first, then the
-  band's own 12, whose first four are the slot defaults, see `defaultAvatarFor(slot, ageRange?)` in
-  `@fabi-play/protocol`, then the avatars also offered there; the lists are not all the same length: 16, 15, 13),
+- `AVATAR_BANDS: Record<AgeRange, readonly AvatarId[]>` (picker order: the band's own 12, whose first four are the
+  slot defaults, see `defaultAvatarFor(slot, ageRange?)` in `@fabi-play/protocol`, then the avatars also offered
+  there; the lists are not all the same length: 15, 14, 12). The mascot (`MASCOT_ID`) is in none: Fabi is the host,
+  not a player. It stays in `AVATARS`, `isAvatarId('mascot')` is true and `drawAvatar` draws it,
   `avatarsFor(ageRange)` (the definitions, in that order), `bandOf(id)` (the home band: `'all'` for the mascot, 6–8
-  for an unknown id), `bandsOf(id)` (every band whose list offers it). Every definition has its `band`
+  for an unknown id), `bandsOf(id)` (every band whose list offers it: none for the mascot). Every definition has its `band`
   (`AvatarBand`: an age range or `'all'`) and, if it is offered elsewhere too, `alsoIn` (see "Avatars of two bands"
-  below); `special: true` marks the mascot, so a picker can mark it. `bodyBand(def, shown?)` gives the proportions
+  below); `special: true` marks the mascot. `bodyBand(def, shown?)` gives the proportions
   it is drawn with (6–8 for `'all'`).
 - `drawAvatar(ctx, body, def | id, box, { alpha?, mirrored?, band? })`. Unknown ids draw the default avatar. `band`:
   the child's age band, when the caller knows it (see "Avatars of two bands"). Pass
@@ -106,7 +108,7 @@ a change that alters them by accident fails the tests (`UPDATE_SNAPSHOT=1` after
 - **Limbs**: thick round strokes from shoulder to elbow to wrist (0.22 U) and from hip to knee to ankle (0.28 U),
   each with an outline. Arms start just below the shoulder. Legs start inside the torso, so nothing looks detached.
   Hands are round caps. Feet are ovals, flippers or boots.
-- **Proportions by band** (`BAND_BODY`): the joints are always the child's, only sizes change. An avatar of every
+- **Proportions by band** (`BAND_BODY`): the joints are always the child's, only sizes change. An avatar of no
   band (`'all'`, the mascot) takes the 6–8 row. An avatar of two bands takes the row of the band shown (above).
 
   | band | head radius | head centre above the shoulders | arm / leg thickness | hand radius | torso below the hips | torso min half width (shoulders / hips) |
@@ -134,7 +136,7 @@ a change that alters them by accident fails the tests (`UPDATE_SNAPSHOT=1` after
 ## Adding an avatar
 
 1. Add an entry to `AVATARS` in `src/defs.ts` and its id to its band in `AVATAR_BANDS` (`src/index.ts`) (an avatar
-   of band `'all'` goes in every band, after the mascot; one offered in another band too lists it in `alsoIn` and goes
+   of band `'all'` goes in no band (only the mascot, the host, is one); one offered in another band too lists it in `alsoIn` and goes
    in that band's list as well, after the band's own). Choose a new
    kebab-case `id` and never rename it later, because phones store it. Fill in `name.en`, `name.it` and `band`. Pick a `palette` with `body`, `limbs`, `belly`, `accent` and
    `outline`, plus optional `hands`, `feet` and `ears`. Then choose a `head` shape, `ears`, the `face` (eyes, mouth,

package/dist/index.d.ts

@@ -152,7 +152,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 {
@@ -165,7 +165,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;
 	/**
@@ -174,7 +174,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;
@@ -292,7 +292,7 @@ export interface BandBody {
 }
 export declare const BAND_BODY: Record<AgeRange, BandBody>;
 /**
- * The proportions an avatar is drawn with: its band's, 6–8's for an avatar of every band ('all') or anything else.
+ * The proportions an avatar is drawn with: its band's, 6–8's for the mascot ('all') or anything else.
  * shown: the band it is shown in (the child's, the picker's), when known; an avatar offered in more than one band
  * (alsoIn) takes the proportions of the one shown, any other keeps its own (the mascot always 6–8's).
  */
@@ -375,14 +375,17 @@ export declare class BodyInterpolator {
 export declare function blend(a: Body$1, b: Body$1, u: number): Body$1;
 export declare const AVATAR_IDS: readonly string[];
 export type AvatarId = string;
-/** Fabi the fox, the app's mascot: an avatar of every band ('all'), first in each band's list. */
+/**
+ * Fabi the fox, the app's mascot ('all': no band of its own). Fabi is the host, not a player: in no band's list
+ * (AVATAR_BANDS), so pickers never offer it, but it is a valid avatar (isAvatarId, avatarById, drawAvatar) for the TV
+ * and for games, and a child saved with it before keeps it.
+ */
 export declare const MASCOT_ID: AvatarId;
 /**
- * The avatars of each age band, in the order the pickers show them: the mascot first (special: pickers may mark
- * it), then the band's own 12, then (3–5) the ones also offered there. The first four of the band's own are the
- * defaults of the four player slots (defaultAvatarFor in @fabi-play/protocol), not the mascot. Every avatar is in
- * its own band and in those of its alsoIn; those of band 'all' (the mascot) are in every band. The lists are not
- * all the same length.
+ * The avatars of each age band, in the order the pickers show them: the band's own 12, then (3–5) the ones also
+ * offered there. The first four are the defaults of the four player slots (defaultAvatarFor in @fabi-play/protocol).
+ * Every avatar is in its own band and in those of its alsoIn; those of band 'all' (the mascot, MASCOT_ID) are in
+ * none: Fabi hosts, the children play. The lists are not all the same length.
  */
 export declare const AVATAR_BANDS: Readonly<Record<AgeRange, readonly AvatarId[]>>;
 /** The avatar of a child who has not picked one yet: the fox (6–8's first). */
@@ -393,12 +396,15 @@ export declare const avatarById: (id: string) => AvatarDef | undefined;
 /** The avatars of an age band, in picker order (6–8 for anything that is not an age band). */
 export declare function avatarsFor(ageRange: AgeRange): readonly AvatarDef[];
 /**
- * The age band of an avatar, its home: 'all' for the mascot (in every band), 6–8 (the default avatar's) for an
+ * The age band of an avatar, its home: 'all' for the mascot (in no band's list), 6–8 (the default avatar's) for an
  * unknown id. An avatar offered in more than one band has one home band (its style, its proportions when the band
  * shown is not known); bandsOf gives every band it is offered in.
  */
 export declare const bandOf: (id: AvatarId) => AvatarBand;
-/** Every age band whose list (AVATAR_BANDS) offers the avatar, youngest first; the default avatar's for an unknown id. */
+/**
+ * Every age band whose list (AVATAR_BANDS) offers the avatar, youngest first; the default avatar's for an unknown id;
+ * none for the mascot (offered in no band).
+ */
 export declare const bandsOf: (id: AvatarId) => readonly AgeRange[];
 export interface DrawOptions {
 	/** 0–1, for the whole avatar. */

package/dist/index.js

@@ -2248,9 +2248,9 @@ function blend(a, b, u) {
 var AVATAR_IDS = AVATARS.map((a) => a.id);
 var MASCOT_ID = "mascot";
 var AVATAR_BANDS = {
-  "3-5": [MASCOT_ID, "bunny", "bear", "panda", "penguin", "koala", "frog", "cat", "owl", "chick", "puppy", "lamb", "duckling", "lion", "trex", "fairy"],
-  "6-8": [MASCOT_ID, "fox", "lion", "dragon", "unicorn", "tiger", "monkey", "dinosaur", "trex", "octopus", "ghost", "shark", "wolf", "parrot", "fairy"],
-  "9-12": [MASCOT_ID, "robot", "astronaut", "ninja", "skater", "alien", "explorer", "wizard", "knight", "racer", "pirate", "diver", "hero"]
+  "3-5": ["bunny", "bear", "panda", "penguin", "koala", "frog", "cat", "owl", "chick", "puppy", "lamb", "duckling", "lion", "trex", "fairy"],
+  "6-8": ["fox", "lion", "dragon", "unicorn", "tiger", "monkey", "dinosaur", "trex", "octopus", "ghost", "shark", "wolf", "parrot", "fairy"],
+  "9-12": ["robot", "astronaut", "ninja", "skater", "alien", "explorer", "wizard", "knight", "racer", "pirate", "diver", "hero"]
 };
 var BY_ID = new Map(AVATARS.map((a) => [a.id, a]));
 var DEFAULT_AVATAR = BY_ID.get("fox");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/avatars",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "39 child-friendly avatars: Fabi the fox in every age band, 12 per band, a T-rex and a fairy, drawn from a body pose, on canvas or as SVG portraits for the pickers.",
   "keywords": [
     "fabi-play",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@fabi-play/protocol": "^0.4.0"
+    "@fabi-play/protocol": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "24.10.1",