@fabi-play/avatars 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,76 @@
+Fabi Play Kit License
+Version 1.0 (DRAFT, not yet reviewed by a lawyer)
+
+Copyright (c) 2026 Fabi Play. All rights reserved.
+
+This license applies to the Fabi Play Kit: the packages @fabi-play/protocol, @fabi-play/motion,
+@fabi-play/avatars, @fabi-play/sdk and @fabi-play/engine, in source and built form, as published on npm, served
+from https://cdn.fabiplay.app or found in this repository, including their code, type declarations, documentation,
+avatar artwork and other assets (together, the "Kit").
+
+1. Free of charge, for Fabi Play only
+
+   Fabi Play grants you a worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to
+   use, copy, and modify the Kit, and to distribute it as part of a Permitted Work, solely to make, test, run and
+   distribute Permitted Works.
+
+   A "Permitted Work" is a game, tool, or other software made to run on, be published on, or support the
+   development of games for the Fabi Play platform (https://fabiplay.app), including games submitted to Fabi Play
+   and tools used to build, test or preview them.
+
+2. What is not allowed
+
+   You may not, without Fabi Play's prior written permission:
+
+   a. use the Kit, or any part or modified version of it, in software that is not a Permitted Work, including in
+      any other game platform, product or service;
+   b. distribute the Kit, or a modified version of it, on its own or as a library, SDK, engine or framework for
+      others to build with, other than as part of a Permitted Work (installing it from npm or loading it from
+      https://cdn.fabiplay.app is not a distribution by you);
+   c. sell, rent or sublicense the Kit itself;
+   d. remove or alter this license, copyright notices, or the license banners in the built files;
+   e. use the avatars, the mascot "Fabi", or the name, logos or other trademarks of Fabi Play, except as the Kit
+      does when it runs inside a Permitted Work. This license grants no trademark rights;
+   f. use the Kit to circumvent, interfere with or misrepresent the Fabi Play platform, its safety, privacy or
+      parental controls, or its rules for games.
+
+3. Visible, not open source
+
+   The Kit's code is published so that developers can read it, debug with it and build Permitted Works. Being
+   visible does not make it open source; no rights are granted beyond those stated here.
+
+4. Your works
+
+   You keep all rights in your own code and content. This license does not give Fabi Play any rights in your
+   Permitted Works; publishing a game on Fabi Play is governed by Fabi Play's separate developer terms.
+
+5. Feedback
+
+   If you send Fabi Play suggestions or changes for the Kit, Fabi Play may use them without obligation to you.
+
+6. Termination
+
+   This license ends automatically if you break its terms. If you fix the breach within 30 days of becoming aware
+   of it, the license is reinstated, unless Fabi Play has already told you in writing that it is terminated. On
+   termination you must stop using and distributing the Kit. Permitted Works already distributed to end users in
+   compliance with this license may continue to be used by those end users.
+
+7. No warranty
+
+   THE KIT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. Limitation of liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL FABI PLAY OR ITS CONTRIBUTORS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE KIT OR THE USE OR OTHER DEALINGS IN THE KIT.
+
+9. Changes to this license
+
+   Fabi Play may publish new versions of this license. Each version of the Kit is governed by the license version
+   it is distributed with, unless you choose to accept a later version.
+
+10. Contact
+
+   For permissions beyond this license: https://fabiplay.app

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @fabi-play/avatars
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Thirty-seven 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, and 12 for each band. 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.
+
+All characters are original. None is an existing character or a real person. The people of 9–12 have generic faces,
+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 |
+| 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 |
+| 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, `octopus` Octopus · Polpetto, `ghost` Friendly Ghost · Fantasmino, `shark` Shark · Squalo, `wolf` Wolf · Lupo, `parrot` Parrot · Pappagallo |
+| 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 |
+
+## Install
+
+```sh
+npm install @fabi-play/avatars
+```
+
+ESM only, types included; depends on `@fabi-play/protocol`. Games get the avatars from `@fabi-play/sdk`
+(`play.drawAvatar`) and need not install this package.
+
+## API
+
+```ts
+import { drawAvatar, drawAvatarIcon, avatarIconSvg, AVATARS, avatarById, isAvatarId } from '@fabi-play/avatars'
+
+// On the TV or in a game, every frame (box: where player space 0–1 lands, e.g. cameraBox(...)):
+drawAvatar(ctx, body, player.avatar ?? 'fox', box, { alpha: 0.9 })
+
+// A picker on a canvas:
+drawAvatarIcon(ctx, 'panda', x, y, 96)
+
+// A picker on the phone, without a canvas:
+el.innerHTML = avatarIconSvg('panda', 96)               // web DOM
+<SvgXml xml={avatarIconSvg('panda', 96)} />             // React Native, react-native-svg
+<img src={avatarIconDataUri('panda', 96)} />             // data URI
+```
+
+- `AVATARS: readonly AvatarDef[]` (all 37), `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`), `avatarsFor(ageRange)` (the definitions, in that order), `bandOf(id)` (`'all'` for the
+  mascot, 6–8 for an unknown id). Every definition has its `band` (`AvatarBand`: an age range or `'all'`);
+  `special: true` marks the mascot, so a picker can mark it. `bodyBand(def)` gives the proportions it is drawn with
+  (6–8 for `'all'`).
+- `drawAvatar(ctx, body, def | id, box, { alpha?, mirrored? })`. Unknown ids draw the default avatar. Pass
+  `mirrored` when the body is in camera space rather than player space. It draws nothing when the shoulders are not
+  seen (it returns whether it drew), and it never throws on missing or broken points.
+- `drawAvatarIcon(ctx, def | id, x, y, size)`: a head-and-shoulders portrait in a neutral pose, clipped to its square.
+- `avatarIconSvg(def | id, size, { background?, radius? })`: the same portrait as an SVG document string. Its
+  clip-path id is unique per call (avatar, size and a counter), so many portraits can sit inline in one page.
+  `avatarIconDataUri` returns the same as a data URI.
+- `smoothBody(prev, next, amount = 0.5)`: optional per-player smoothing. Points ease towards the new frame. A point
+  that was seen stays visible until its visibility drops below 0.3, so limbs don't blink. Keep the result per player.
+- Poses for previews and tests: `neutralPose()`, `armsUpPose()`, `starJumpPose()`, `squatPose()`, `wavePose()`,
+  `TEST_POSES`, `poseBody(spec)`.
+- Lower level: `avatarShapes(body, def, box)` returns the shape list, `drawShapes(ctx, shapes)` draws it on a canvas,
+  and `shapesToSvg(shapes)` turns it into SVG. `frameOf(body, box)` gives the rig's torso frame.
+
+## How it is drawn
+
+One source of truth: the rig and the portrait build a small **shape list** (`circle`, `ellipse`, `rect`, `path`,
+`line`, `group` with translate/rotate/scale). Two small backends read it: a canvas backend and an SVG backend.
+Because both read the same list, canvas and SVG pictures match. Paths use only absolute `M L Q C Z`, so the canvas
+backend does not need `Path2D`. The rig builds them as number arrays (`PathData`: a `PATH` command code, then its
+coordinates, rounded to 2 decimals as the SVG prints them), so nothing is turned into a string and parsed back every
+frame; `pathToString` prints one. A head depends only on the avatar and the outline width, so it is built once and
+shared across frames (treat shape lists as read-only). `test/snapshot.json` holds a hash of every avatar's pictures:
+a change that alters them by accident fails the tests (`UPDATE_SNAPSHOT=1` after one meant to).
+
+### Rig rules (`src/rig.ts`)
+
+- **Unit U**: the torso length (shoulder midpoint to hip midpoint). It is at least 1.15 × the shoulder width, so
+  bending forward does not shrink the avatar. Every size is a multiple of U, so avatars scale with distance.
+- **Torso**: a smooth rounded shape along the torso axis (square to the shoulder line when shoulders to hips is under
+  0.25 × the shoulder width: a child bent towards the camera). It runs from just above the shoulders to just below the
+  hips, and is at least 0.68 U wide at the shoulders and 0.8 U wide at the hips. A belly patch sits on top.
+- **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
+  band (`'all'`, the mascot) takes the 6–8 row.
+
+  | band | head radius | head centre above the shoulders | arm / leg thickness | hand radius | torso below the hips | torso min half width (shoulders / hips) |
+  | --- | --- | --- | --- | --- | --- | --- |
+  | 3–5 | 0.75 U | 0.74 head radii | 0.30 / 0.36 U | 0.19 U | 0.26 U | 0.40 / 0.50 U, rounder tummy |
+  | 6–8 | 0.6 U | 0.78 | 0.22 / 0.28 U | 0.15 U | 0.14 U | 0.34 / 0.40 U |
+  | 9–12 | 0.5 U | 0.92 | 0.17 / 0.21 U | 0.125 U | 0.10 U | 0.36 / 0.32 U, slimmer hips |
+
+  In 3–5 an arm raised well above the shoulders is drawn over the big head, which would hide it.
+- **Head**: radius by band (above), centred above the shoulder midpoint along the torso axis. It follows the
+  nose a little (at most 0.35 radii) and tilts with the ear line, or the eye line if the ears are missing. The tilt is
+  clamped to ±0.5 rad from the torso, and a swapped pair is treated as a child facing away.
+- **Tail, wings, backpack, tentacles**: these hang off the hips or the back, in torso coordinates, and are drawn
+  behind the body. The tail goes on the child's right. Portraits leave it out.
+- **Draw order**: back extras, legs, torso, arms, head, then (3–5 only) raised arms.
+- **Degrading**: a point counts as seen at visibility ≥ 0.5. If the elbow or knee is missing, that limb is hidden.
+  If the wrist or ankle is missing, the limb ends at the elbow or knee. If the hips are missing, the torso is one U
+  long and the legs are hidden. If either shoulder is missing, nothing is drawn.
+
+## 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). 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,
+   muzzle, nose, cheeks), a `tail`, `headExtras` and `bodyExtras`. `extraColors` covers stripes, spots, manes and
+   lights.
+2. Make it different from the others by its silhouette (ears, head, tail, extras) **and** its body colour. Use a
+   body colour that reads on both the night background (#1f1813) and a light one. Keep the dark outline.
+3. If a part does not exist yet, add a kind to the union in `src/types.ts` and draw it in `src/head.ts` (head units:
+   radius 1, y down) or in `src/rig.ts` (torso units of U). Don't write per-id special cases.
+4. Run `pnpm -F @fabi-play/avatars preview <dir> --details` and look at the PNGs: the portrait, every pose, and
+   both backgrounds. Then run `pnpm -F @fabi-play/avatars test`.
+
+## Scripts
+
+- `pnpm -F @fabi-play/avatars typecheck` / `test`
+- `pnpm -F @fabi-play/avatars preview [out-dir] [--details]` writes `contact-sheet.html`, grouped by age band. If
+  Chrome is installed, it also renders `contact-sheet.png`: every portrait (SVG and canvas side by side), and every
+  avatar in three poses on night and light backgrounds. `--details` adds `icons.png` and large
+  `detail-<band>-<n>.png` pages with six poses each, including one with missing points (`detail-all-1.png`: the
+mascot, next to the 6–8 fox). The default output is `packages/avatars/preview/`, which git ignores.
+
+## License
+
+Fabi Play Kit License: free to use, for making games and tools for Fabi Play only. The avatars and the mascot Fabi
+are part of the Kit: see [LICENSE](./LICENSE), section 2e.

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+// @fabi-play/avatars: 37 child-friendly avatars: Fabi the fox in every age band and 12 per band, drawn from a body pose, on canvas or as SVG portraits for the pickers. See https://docs.fabiplay.app.
+// Generated by scripts/build-lib.mjs (fabiplay-kit) from the sources: do not edit.
+
+import { AgeRange, Body as Body$1 } from '@fabi-play/protocol';
+
+/**
+ * A tiny shape list, the one source of truth for every avatar picture. The rig and the portrait build a list of
+ * shapes; two small backends draw it: on a 2D canvas (the TV, the games) and as an SVG string (the phones, the
+ * previews). Both read the same numbers, so the canvas and the SVG pictures match.
+ *
+ * Paths use a small subset of SVG path syntax, absolute commands only (M L Q C Z), so the canvas backend can trace
+ * them without Path2D (not available everywhere, e.g. React Native canvases or test mocks). The rig builds them as
+ * PathData, number arrays (no strings built and parsed again every frame); fixed paths may stay strings.
+ */
+/** How an avatar shape is painted (CSS colours). */
+export interface Paint {
+	/** Fill colour; none without it. */
+	fill?: string;
+	/** Outline colour; none without it. */
+	stroke?: string;
+	/** Stroke width, in the units of the shape (scaled by the groups around it). */
+	lw?: number;
+	/** 0–1, multiplied with the alpha around it. */
+	alpha?: number;
+}
+/** One shape of an avatar picture (the rig's output), in canvas units; k says which. */
+export type Shape = (Paint & {
+	k: "circle";
+	x: number;
+	y: number;
+	r: number;
+}) | (Paint & {
+	k: "ellipse";
+	x: number;
+	y: number;
+	rx: number;
+	ry: number;
+	rot?: number;
+})
+/** A rounded rectangle by its centre, rotated by rot radians around it. */
+ | (Paint & {
+	k: "rect";
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+	r: number;
+	rot?: number;
+}) | (Paint & {
+	k: "path";
+	d: string | PathData;
+})
+/** A polyline [x0, y0, x1, y1, …], stroked with round caps and joins. */
+ | (Paint & {
+	k: "line";
+	pts: number[];
+})
+/** Children drawn translated by (x, y), then rotated by rot radians, then scaled by s. */
+ | {
+	k: "group";
+	x: number;
+	y: number;
+	rot?: number;
+	s?: number;
+	alpha?: number;
+	items: Shape[];
+};
+/**
+ * A path as numbers: each command code (PATH.M, …) followed by its coordinates, absolute: M x y, L x y,
+ * Q cx cy x y, C c1x c1y c2x c2y x y, Z. Coordinates are rounded to 2 decimals, as the SVG prints them, so canvas and
+ * SVG pictures match.
+ */
+export type PathData = readonly number[];
+export declare const PATH: {
+	readonly M: 0;
+	readonly L: 1;
+	readonly Q: 2;
+	readonly C: 3;
+	readonly Z: 4;
+};
+/** The part of CanvasRenderingContext2D the backend uses (so tests can pass a mock). */
+export type Ctx2D = Pick<CanvasRenderingContext2D, "save" | "restore" | "translate" | "rotate" | "scale" | "beginPath" | "closePath" | "moveTo" | "lineTo" | "quadraticCurveTo" | "bezierCurveTo" | "arc" | "ellipse" | "fill" | "stroke" | "rect" | "clip" | "globalAlpha" | "fillStyle" | "strokeStyle" | "lineWidth" | "lineCap" | "lineJoin">;
+export declare function drawShapes(ctx: Ctx2D, shapes: readonly Shape[]): void;
+/** PathData as SVG path syntax: "M1 2 L3 4 Q5 6 7 8 Z". */
+export declare function pathToString(d: string | PathData): string;
+/** The coordinates of a path, as x, y pairs in a flat list (control points included). */
+export declare function pathPoints(d: string | PathData): number[];
+export declare function shapesToSvg(shapes: readonly Shape[]): string;
+export interface Pt {
+	x: number;
+	y: number;
+}
+/** A five-pointed star of radius 1. */
+export declare const STAR = "M0 -1 L0.29 -0.4 L0.95 -0.31 L0.47 0.15 L0.59 0.81 L0 0.5 L-0.59 0.81 L-0.47 0.15 L-0.95 -0.31 L-0.29 -0.4 Z";
+/** An avatar's colours (CSS). */
+export interface Palette {
+	/** Head and torso. */
+	body: string;
+	/** Arms and legs. */
+	limbs: string;
+	/** Belly patch, muzzle, inner face. */
+	belly: string;
+	/** Details: inner ears, horns, beaks, tail tips, spikes. */
+	accent: string;
+	/** The outline around every part: dark, so the avatar reads on light and dark backgrounds. */
+	outline: string;
+	/** Hands; defaults to limbs. */
+	hands?: string;
+	/** Feet; defaults to limbs. */
+	feet?: string;
+	/** Solid ears of another colour (panda); by default ears are body-coloured with an accent inside. */
+	ears?: string;
+	/** The face and head when they differ from the torso (people, the lamb's face); defaults to body. */
+	skin?: string;
+	/** Hair (hair, curls, locks). */
+	hair?: string;
+}
+/** The head's outline. */
+export type HeadShape = "round" | "wide" | "tall" | "square" | "bulb" | "bucket";
+/** 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";
+/** 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";
+/** 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";
+/** 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";
+/** 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";
+/** An avatar's face. */
+export interface FaceDef {
+	/** How the eyes are drawn. */
+	eyes: EyeKind;
+	/** Eye colour for big/screen/almond/visor eyes. */
+	eyeColor?: string;
+	/** Eyes higher than usual and bulging over the head (frog). */
+	eyesOnTop?: boolean;
+	/** Ring around the eyes (owl). */
+	eyeRing?: string;
+	/** How the mouth is drawn. */
+	mouth: MouthKind;
+	/** Nose colour; none when missing. */
+	nose?: string;
+	/** The patch around nose and mouth. */
+	muzzle: MuzzleKind;
+	/** Blush colour; none when missing. */
+	cheeks?: string;
+	/** 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). */
+export type AvatarBand = AgeRange | "all";
+/** An avatar, as data: one renderer draws any definition. */
+export interface AvatarDef {
+	/** Stable kebab-case id: stored on the phone and sent around, never renamed. */
+	id: string;
+	/** Its name, in English and Italian, for pickers. */
+	name: {
+		en: string;
+		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.
+	 */
+	band: AvatarBand;
+	/** A special avatar (the mascot): first in every band's list; pickers may mark it. */
+	special?: boolean;
+	/** Its colours. */
+	palette: Palette;
+	/** The head's outline. */
+	head: HeadShape;
+	/** The ears, or what is in their place. */
+	ears: EarKind;
+	/** The face. */
+	face: FaceDef;
+	/** The tail. */
+	tail: TailKind;
+	/** Things on the head (manes, hats, masks). */
+	headExtras: readonly HeadExtra[];
+	/** Things on the body (wings, capes, belts). */
+	bodyExtras: readonly BodyExtra[];
+	/** Colours of the rainbow mane, of the stripes, of the spots: per-avatar extra colours. */
+	extraColors?: readonly string[];
+}
+/** Where player space (0–1) lands on the canvas. */
+export interface Box {
+	/** Left edge, canvas units. */
+	x: number;
+	/** Top edge, canvas units. */
+	y: number;
+	/** Width, canvas units. */
+	w: number;
+	/** Height, canvas units. */
+	h: number;
+}
+export declare const AVATARS: readonly AvatarDef[];
+export type XY = readonly [
+	number,
+	number
+];
+export interface PoseSpec {
+	nose: XY;
+	leftShoulder: XY;
+	rightShoulder: XY;
+	leftElbow: XY;
+	rightElbow: XY;
+	leftWrist: XY;
+	rightWrist: XY;
+	leftHip: XY;
+	rightHip: XY;
+	leftKnee: XY;
+	rightKnee: XY;
+	leftAnkle: XY;
+	rightAnkle: XY;
+	/** Head tilt in radians (positive: clockwise on screen). */
+	tilt?: number;
+}
+/** A body from a pose spec: torso T tall (0–1 of the frame height), shoulders centred at (cx, cy). */
+export declare function poseBody(spec: Partial<PoseSpec>, { cx, cy, T }?: {
+	cx?: number | undefined;
+	cy?: number | undefined;
+	T?: number | undefined;
+}): Body$1;
+/** Standing, arms relaxed: the pose of the portraits. */
+export declare const neutralPose: () => Body$1;
+/** Both arms straight up. */
+export declare const armsUpPose: () => Body$1;
+/** Mid star jump: arms and legs wide, the body up in the air. */
+export declare const starJumpPose: () => Body$1;
+/** A squat: hips down, knees out, arms forward (seen from the front, the hands come in front of the chest). */
+export declare const squatPose: () => Body$1;
+/** Waving with the right hand, head tilted. */
+export declare const wavePose: () => Body$1;
+export declare const TEST_POSES: {
+	readonly neutral: () => Body$1;
+	readonly armsUp: () => Body$1;
+	readonly starJump: () => Body$1;
+	readonly squat: () => Body$1;
+	readonly wave: () => Body$1;
+};
+export type TestPose = keyof typeof TEST_POSES;
+export declare const VISIBLE = 0.5;
+/** Face landmarks (MediaPipe pose) the head tilt is read from. */
+export declare const FACE: {
+	readonly leftEye: 2;
+	readonly rightEye: 5;
+	readonly leftEar: 7;
+	readonly rightEar: 8;
+};
+/**
+ * Body proportions by age band, in torso units U (head, limbs, torso) unless said otherwise. The joints are always
+ * the child's: limbs run through them and the head sits on the shoulders; only sizes change.
+ *
+ *   3–5: a big round head, chubby limbs, a round tummy that reaches low (the legs look short): toddlers.
+ *   6–8: the original proportions.
+ *   9–12: a smaller head, slimmer limbs and hips, a squarer torso: older kids.
+ */
+export interface BandBody {
+	/** Head radius. */
+	head: number;
+	/** How far the head centre sits above the shoulder line, in head radii. */
+	neck: number;
+	/** Limb thickness. */
+	arm: number;
+	leg: number;
+	/** Hand radius. */
+	hand: number;
+	/** Feet size, as a factor. */
+	foot: number;
+	/** The torso: at least this half width at the shoulders and the hips, and this much past the joints. */
+	shoulderMin: number;
+	shoulderPad: number;
+	hipMin: number;
+	hipPad: number;
+	/** How far the torso reaches below the hips. */
+	bottom: number;
+	/** The waist's bulge, as a share of the wider of shoulders and hips. */
+	bulge: number;
+	/** A raised arm is drawn over the head (a big head would hide it). */
+	armsOverHead: boolean;
+}
+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. */
+export declare const bodyBand: (def: Pick<AvatarDef, "band">) => AgeRange;
+/** Head radius in torso units (6–8; see BAND_BODY for the others). */
+export declare const HEAD: number;
+/** The head tilts at most this much (rad) from the shoulders' line. */
+export declare const MAX_TILT = 0.3;
+/**
+ * Tilts under this (rad) are noise, not a child tilting their head: no tilt. Past it the tilt grows from 0, so
+ * there is no jump at the edge.
+ */
+export declare const TILT_DEAD_ZONE = 0.12;
+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. */
+	portrait?: boolean;
+	/** Body proportions (see BAND_BODY); 6–8 by default. avatarShapes takes 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. */
+export interface Frame {
+	S: Pt;
+	r: Pt;
+	d: Pt;
+	U: number;
+	/** Shoulders to hips along d. */
+	L: number;
+	hipsOk: boolean;
+	head: Pt;
+	headR: number;
+	headRot: number;
+	angle: number;
+}
+/** The torso frame and head placement, or null when the shoulders are not seen. */
+export declare function frameOf(body: Body$1, box: Box, opts?: RigOptions): Frame | null;
+/** All the shapes of an avatar for this body, in canvas pixels. Empty when the shoulders are not seen. */
+export declare function avatarShapes(body: Body$1, def: AvatarDef, box: Box, opts?: RigOptions): Shape[];
+export interface InterpolatorOptions {
+	/** A player whose bodies stop for this long (ms of the sender's clock) starts afresh when they come back. */
+	lostMs?: number;
+	/** At most this far past the newest body (ms), when the next one is late. */
+	maxExtrapolateMs?: number;
+}
+export declare class BodyInterpolator {
+	private readonly tracks;
+	/** Page clock minus sender clock, at its smallest (the fastest delivery): NaN before the first body. */
+	private offset;
+	private lastArrival;
+	/** The time between bodies (sender's clock), smoothed. */
+	private interval;
+	private lastT;
+	private readonly lostMs;
+	private readonly maxExtrapolateMs;
+	constructor(o?: InterpolatorOptions);
+	/** The time between bodies the drawing is behind by, in ms. */
+	get delayMs(): number;
+	/**
+	 * A new body for this player, taken at t (the sender's clock), arriving now (this page's clock, by default
+	 * performance.now()). Bodies for several players of one camera frame share t.
+	 */
+	push(player: number, t: number, body: Body$1, arrival?: number): void;
+	/** The player's body to draw at time now (this page's clock); null for a player never pushed or forgotten. */
+	at(player: number, at?: number): Body$1 | null;
+	/** A player gone: their next body starts afresh. */
+	forget(player: number): void;
+	/** Every player gone (a new scene). */
+	clear(): void;
+	private clock;
+}
+/**
+ * The body a share u of the way from a to b (u past 1: beyond b, along the same line). A point seen in both and not
+ * jumping slides; any other takes the nearer body's point, visibility and all.
+ */
+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. */
+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. 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 exactly one band, except those of
+ * band 'all' (the mascot), which are in every band.
+ */
+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). */
+export declare const DEFAULT_AVATAR: AvatarDef;
+export declare const isAvatarId: (v: unknown) => v is AvatarId;
+/** The avatar with this id, or undefined. */
+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: 'all' for the mascot (in every band), 6–8 (the default avatar's) for an unknown id. */
+export declare const bandOf: (id: AvatarId) => AvatarBand;
+export interface DrawOptions {
+	/** 0–1, for the whole avatar. */
+	alpha?: number;
+	/** The body is in camera space (not mirrored like player space): flip it left to right. */
+	mirrored?: boolean;
+}
+/**
+ * Draws the avatar posed like the body. box is where player space (0–1) lands on the canvas, as for the silhouette
+ * (see cameraBox in the screen). Draws nothing when the shoulders are not seen; never throws on missing points.
+ * Returns whether it drew.
+ */
+export declare function drawAvatar(ctx: CanvasRenderingContext2D | Ctx2D, body: Body$1, def: AvatarDef | string, box: Box, opts?: DrawOptions): boolean;
+/** 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[];
+/** Draws the portrait in the square (x, y, size), clipped to it. */
+export declare function drawAvatarIcon(ctx: CanvasRenderingContext2D | Ctx2D, def: AvatarDef | string, x: number, y: number, size: number): void;
+export interface IconSvgOptions {
+	/** A background colour for the square; transparent by default. */
+	background?: string;
+	/** Corner radius of the background, in pixels. */
+	radius?: number;
+}
+/** The portrait as a standalone SVG document (size × size pixels). Use it as markup, an <img> data URI, or SvgXml. */
+export declare function avatarIconSvg(def: AvatarDef | string, size: number, opts?: IconSvgOptions): string;
+/** avatarIconSvg as a data URI, for <img src> or React Native <Image> with SVG support. */
+export declare const avatarIconDataUri: (def: AvatarDef | string, size: number, opts?: IconSvgOptions) => string;
+/**
+ * Smooths a body against the previous frame, so the avatar does not jitter or blink: positions ease towards the new
+ * points (amount 0–1: how much of the new frame to take), and a point seen in the last frame stays visible until
+ * its visibility drops well below the threshold. Keep the result per player and pass it back as prev.
+ *
+ * The face (nose, eyes, ears, mouth: what places and tilts the head) is smoothed much more, and relative to the
+ * shoulders: the head follows the body at once when the child moves, but face-point noise and small nods barely
+ * move it.
+ */
+export declare function smoothBody(prev: Body$1 | null | undefined, next: Body$1, amount?: number): Body$1;
+export interface Bounds {
+	minX: number;
+	minY: number;
+	maxX: number;
+	maxY: number;
+}
+export declare function bounds(shapes: readonly Shape[]): Bounds;
+
+export {};