@fabi-play/engine 0.0.0-stage → 0.1.0

package/dist/fabi-play-engine.d.ts

@@ -0,0 +1,2338 @@
+// fabi-play-engine.js: the Fabi Play engine as a script tag. It sets window.FabiEngine; these are its types.
+// Generated by scripts/types.mjs from the sources: do not edit.
+//
+// Use it next to the script, with fabi-play.d.ts (the SDK, window.FabiPlay), in a script or a // @ts-check file:
+//   /// <reference path="fabi-play.d.ts" />
+//   /// <reference path="fabi-play-engine.d.ts" />
+// or list both in tsconfig.json / jsconfig.json "include". The types are FabiEngine.Engine, FabiEngine.Sprite, …
+/**
+ * The Fabi Play engine, set by fabi-play-engine.js or fabi-play-engine.lite.js (load it after fabi-play.js).
+ *
+ * @example
+ * FabiEngine.createEngine({ play: FabiPlay }).then((engine) => {
+ *   engine.stage.add(engine.avatars())
+ *   engine.start()
+ *   FabiPlay.ready()
+ * })
+ */
+declare namespace FabiEngine {
+	/**
+	 * One body: for each landmark x, y (0–1, y downwards) and visibility (0–1), so 33 × 3 numbers.
+	 * In "player space": mirrored like a mirror, whatever camera took it, so a child moving to their left moves left.
+	 */
+	export type Body = number[];
+	/**
+	 * Age ranges: each has its own games. Only the range is kept, never a birth date: it is all the catalogue and the
+	 * games need (simpler rules and no losing for the little ones, scores and challenges for the older ones).
+	 */
+	export type AgeRange = "3-5" | "6-8" | "9-12";
+	/** A pose the whole body holds: arms up, arms wide, arms in a V, a star (arms and legs apart), arms down. */
+	export type BodyShape = "arms-up" | "arms-wide" | "arms-v" | "star" | "arms-down";
+	/** A point: in player space (0–1 of the camera image, y downwards) or, after toScreen, in fractions of the screen. */
+	export interface Point {
+		/** 0 left, 1 right. */
+		x: number;
+		/** 0 top, 1 bottom. */
+		y: number;
+	}
+	/** One player in a frame the game gets: the body, its hands as pointers, its shape, its avatar. */
+	export interface PlayerFrame {
+		/** The player, from 1. */
+		id: number;
+		/** The 33 landmarks, in player space (see Body; P names the indices). */
+		body: Body;
+		/**
+		 * The left hand as a pointer, in fractions of the screen (0–1): the wrist, with the space the arms reach around the
+		 * shoulders stretched to the whole screen and clamped to it, so a child reaches every corner without walking. Not
+		 * where the wrist is on screen: draw on the body with toScreen(wrist). null when the camera doesn't see the wrist (or the child holds Fabi Play's crossed arms).
+		 */
+		leftHand: Point | null;
+		/** The right hand as a pointer, as leftHand. */
+		rightHand: Point | null;
+		/** The pose held right now, if any. */
+		shape: BodyShape | null;
+		/** Which lane the child stands in: -1 left, 0 centre, 1 right. */
+		lane: -1 | 0 | 1;
+		/**
+		 * The avatar of player id (slot id − 1): the one the child picked on the phone, or the slot's default
+		 * (defaultAvatarFor). It rides on every frame, so a game never misses a change and needs no extra message. Hosts
+		 * before avatars don't send it; the SDK's avatarOf falls back to the slot's default then, and for ids it does not
+		 * know.
+		 */
+		avatar?: string;
+	}
+	/**
+	 * What is behind the game's frame: 'video', the phone's camera video (mirror mode; the game paints no opaque
+	 * background), or 'none', the screen's plain background (the game paints its own).
+	 */
+	export type Backdrop = "video" | "none";
+	/**
+	 * Where the whole camera image is, in fractions of the game's viewport (0–1; it may reach past the edges when the
+	 * image is cropped to fill the screen), with any backdrop, so avatars and hands are where the children stand (a
+	 * "virtual mirror"). The screen decides it: with 'video', where the video is drawn (cover or contain); with 'none',
+	 * the whole image contained at 92% of the viewport's height, bottom-aligned. Games don't compute it: they just use
+	 * it. Body points are in player space (0–1 of the camera image, already mirrored like the video), so a point p is on
+	 * screen at (x + p.x·w, y + p.y·h): see toScreen.
+	 */
+	export interface BackdropView {
+		/** Left edge, a fraction of the viewport's width. */
+		x: number;
+		/** Top edge, a fraction of the viewport's height. */
+		y: number;
+		/** Width, a fraction of the viewport's width. */
+		w: number;
+		/** Height, a fraction of the viewport's height. */
+		h: number;
+	}
+	/**
+	 * Small pure helpers: 2D affine matrices, colours, easing. No DOM here, so they run in Node tests.
+	 */
+	/** An affine transform [a, b, c, d, e, f]: x' = a·x + c·y + e, y' = b·x + d·y + f (Canvas 2D's order). */
+	export type Mat = Float64Array;
+	/** A colour as 0xRRGGBB (alpha separate), or a CSS string. */
+	export type ColorLike = number | string;
+	/**
+	 * A CSS colour as [0xRRGGBB, alpha 0–1]: #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), rgba() and a few names. Anything
+	 * else is resolved by a canvas when there is one (cached), else white.
+	 */
+	export function parseColor(c: ColorLike): [
+		number,
+		number
+	];
+	/**
+	 * A tint and an alpha as the GPU wants them: premultiplied RGBA in one 32-bit word (little-endian byte order R, G,
+	 * B, A, as an UNSIGNED_BYTE vec4 attribute reads it). additive: alpha 0, so ONE / ONE_MINUS_SRC_ALPHA blending adds.
+	 */
+	export function packColor(rgb: number, alpha: number, additive?: boolean): number;
+	/** An easing function: progress 0–1 in, eased progress out (0 at 0, 1 at 1). */
+	export type Ease = (t: number) => number;
+	/**
+	 * The easings by name, for engine.tween: linear, quadIn, quadOut (the default), quadInOut, cubicOut, sineInOut,
+	 * backOut (overshoots a little), elasticOut, bounceOut.
+	 *
+	 * @example
+	 * engine.tween(star, { y: 0 }, 0.6, 'bounceOut')
+	 */
+	export const EASE: {
+		linear: (t: number) => number;
+		quadIn: (t: number) => number;
+		quadOut: (t: number) => number;
+		quadInOut: (t: number) => number;
+		cubicOut: (t: number) => number;
+		sineInOut: (t: number) => number;
+		backOut: (t: number) => number;
+		elasticOut: (t: number) => number;
+		bounceOut: (t: number) => number;
+	};
+	/** The name of an easing in EASE. */
+	export type EaseName = keyof typeof EASE;
+	/** A seedable random number generator (mulberry32), for tests and replays. */
+	export function rng(seed: number): () => number;
+	/**
+	 * A filter on a node (node.filters): made by tint(), brightness(), blur(), shader() and the other factories. Its
+	 * parameters are plain fields, changed (or tweened) any time without allocating.
+	 */
+	export interface Filter {
+		/** Off: skipped, as if not in the list (cheaper than taking it out and back). */
+		enabled: boolean;
+		/** @internal F_COLOR, F_BLUR, F_SHADOW or F_SHADER. */
+		readonly kind: number;
+		/** @internal Colour filters: the 4×5 matrix (row-major, offsets 0–1) into out. */
+		toMatrix?(out: Float32Array): void;
+		/**
+		 * @internal Canvas 2D: the CSS filter function (lengths in backing pixels), or null when CSS can't say it. svg: the
+		 * runtime's SVG colour-matrix filters, url(#…) for a matrix (null without a document).
+		 */
+		css?(scale: number, maxBlur: number, svg?: (m: ArrayLike<number>) => string | null): string | null;
+		/**
+		 * @internal Canvas 2D: writes the parameters its plan depends on into out from i (at most 20); the index after them.
+		 * Canvas 2D keys plans by these values, so a list rebuilt with the same values reuses its plan.
+		 */
+		params?(out: Float64Array, i: number): number;
+		/** @internal Canvas 2D: applies itself in place to a canvas holding only the node, in the region x, y, w, h (pixels). */
+		paint2d?(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number): void;
+		/** @internal How far it reaches past the node's pixels, stage units. */
+		pad?(maxBlur: number): number;
+	}
+	/** Which backend draws: engine.renderer.kind ('webgpu' is reserved for later). */
+	export type RendererKind = "webgpu" | "webgl2" | "webgl1" | "canvas2d";
+	/** What a texture is made from: a canvas (baked shapes, text, atlas pages) or a decoded image. */
+	export type TextureSource = HTMLCanvasElement | HTMLImageElement | ImageBitmap | OffscreenCanvas;
+	/** A texture on a renderer. */
+	export interface Texture {
+		/** Unique per texture, for batching. */
+		readonly id: number;
+		/** Pixels. */
+		readonly width: number;
+		/** Pixels. */
+		readonly height: number;
+		/** Kept to upload again after a context loss, and for Canvas 2D's drawImage. */
+		source: TextureSource;
+	}
+	/** A region of a texture, in its pixels. */
+	export interface Region {
+		/** Left, pixels. */
+		x: number;
+		/** Top, pixels. */
+		y: number;
+		/** Width, pixels. */
+		w: number;
+		/** Height, pixels. */
+		h: number;
+	}
+	/** How a node's pixels mix with what is under them: 'normal', or 'add' (light adds up: glows, sparks). */
+	export type Blend = "normal" | "add";
+	/** What a frame cost the renderer. */
+	export interface FrameStats {
+		/** Draw calls (GL) in the frame. */
+		drawCalls: number;
+		/** Quads drawn in the frame. */
+		quads: number;
+		/** Filters skipped in the frame: not supported by this renderer (shaders on Canvas 2D, …), or not compiling. */
+		filtersSkipped: number;
+	}
+	/** What a renderer can do with filters. */
+	export interface FilterSupport {
+		/** Colour filters, blur and drop shadows: always on GL; on Canvas 2D where ctx.filter works (tint works anyway). */
+		readonly filters: boolean;
+		/** Custom shaders (shader()): WebGL only. */
+		readonly shaders: boolean;
+	}
+	/**
+	 * engine.renderer: the backend that draws (WebGL2, WebGL1 or Canvas 2D). Games read kind for logs; the scene graph
+	 * and the avatars draw with the rest.
+	 */
+	export interface Renderer {
+		/** 'webgl2', 'webgl1' or 'canvas2d'. */
+		readonly kind: RendererKind;
+		/** The canvas drawn in (after a switch to Canvas 2D, a fresh one in the old one's place). */
+		readonly canvas: HTMLCanvasElement;
+		/** The largest texture side it takes, pixels. */
+		readonly maxTextureSize: number;
+		/** GL: instancing and vertex array objects in use; for logs. */
+		readonly features: Record<string, boolean | number | string>;
+		/** What it can do with filters. */
+		readonly support: FilterSupport;
+		/** The largest blur, stage units (the engine sets the tier's; 0: blurs off, drop shadows hard). */
+		maxBlur: number;
+		/** Game time, seconds (the engine sets it every frame): a custom shader's uTime. */
+		time: number;
+		/** The backing store, in pixels. */
+		resize(width: number, height: number): void;
+		/** A texture of source (uploaded now). */
+		createTexture(source: TextureSource): Texture;
+		/** source drawn into texture at (x, y): the whole texture by default. */
+		updateTexture(texture: Texture, source?: TextureSource, x?: number, y?: number): void;
+		/** Frees a texture. */
+		destroyTexture(texture: Texture): void;
+		/** Starts a frame: clear (0xRRGGBB and alpha; alpha 0 for a transparent stage), scale: pixels per stage unit. */
+		begin(clear: number, clearAlpha: number, scale: number): void;
+		/** Draws region r of t over the local rectangle (0, 0)–(w, h), transformed by m (stage units). */
+		quad(t: Texture, r: Region, m: Mat, w: number, h: number, tint: number, alpha: number, blend: Blend): void;
+		/**
+		 * @internal quad with w, h and alpha in QUAD (0, 1, 2): the scene's hot path, numbers passed through an array
+		 * (as arguments they would be boxed on every call).
+		 */
+		quadQ(t: Texture, r: Region, m: Mat, tint: number, blend: Blend): void;
+		/**
+		 * @internal A nine-slice drawn as one picture, alpha in QUAD[2]: frame region r of t cut by cols and rows (each
+		 * [start, size, texture start, texture size] × 3, stage units then pixels of r), the box at (0, 0) of m. Optional:
+		 * Canvas 2D antialiases every drawImage's edges under a rotation, so pieces drawn one by one would show hairline
+		 * seams where they meet. False: not done (axis-aligned, or no such method), draw the pieces with quadQ.
+		 */
+		nineQ?(t: Texture, r: Region, cols: ArrayLike<number>, rows: ArrayLike<number>, m: Mat, tint: number, blend: Blend): boolean;
+		/** A filled ellipse centred at (cx, cy), radii rx, ry, rotated by rot radians; color 0xRRGGBB. */
+		ellipse(cx: number, cy: number, rx: number, ry: number, rot: number, color: number, alpha: number): void;
+		/** A filled polygon: pts x0, y0, x1, y1, … (n points). */
+		polygon(pts: ArrayLike<number>, n: number, color: number, alpha: number): void;
+		/** A polyline of width w, round joins and caps; closed joins the last point to the first. */
+		stroke(pts: ArrayLike<number>, n: number, w: number, color: number, alpha: number, closed: boolean): void;
+		/**
+		 * Clips what follows to an axis-aligned rectangle of the stage (stage units, snapped to whole backing pixels), until
+		 * the next clip or unclip. It holds inside layers and for their composites. GL clips quads on the CPU where they
+		 * stay axis-aligned and uses the scissor only for the others, so a clip rarely breaks the batch.
+		 */
+		clip(x: number, y: number, w: number, h: number): void;
+		/** Turns the clip off. */
+		unclip(): void;
+		/**
+		 * Draws what follows, until endLayer, into an offscreen layer the size of the canvas (cleared), then composites
+		 * the layer at alpha: a faint avatar is see-through as a whole, without its overlapping parts showing through each
+		 * other. Layers nest up to MAX_LAYERS deep; past that, a layer is drawn straight through (and its mask and filters
+		 * ignored).
+		 *
+		 * @returns false when it is drawn straight through (too deep, or no layer could be made): then draw what follows at
+		 * the alpha yourself, endLayer's alpha does not apply.
+		 */
+		beginLayer(): boolean;
+		/**
+		 * Inside a layer: what follows, until endLayer, is drawn into a mask instead. At endLayer the layer keeps its
+		 * pixels only where the mask is opaque (times the mask's alpha), then is composited.
+		 */
+		beginMask(): void;
+		/**
+		 * Composites the layer begun by beginLayer at alpha (masked first, if beginMask was called), through filters if
+		 * given (the enabled ones, in order). Only the area drawn into the layer is composited (plus what filters reach).
+		 */
+		endLayer(alpha: number, filters?: readonly Filter[] | null): void;
+		/** Ends the frame (flushes the batch); what it cost. */
+		end(): FrameStats;
+		/** The context was lost (stop drawing) or restored (textures already uploaded again). */
+		onLost(listener: () => void): void;
+		/** Called when the context comes back, textures already uploaded again. */
+		onRestored(listener: () => void): void;
+		/** The GL context is lost right now: nothing is drawn. */
+		readonly lost: boolean;
+		/** Information for logs and the tier cache key (GPU string where allowed). */
+		readonly info: Record<string, unknown>;
+		/** Frees the context and every texture. */
+		destroy(): void;
+	}
+	/** How deep layers nest (a masked group inside a masked group…); a mask counts as one. */
+	export const MAX_LAYERS = 4;
+	/** A rectangle in an atlas page, pixels. */
+	export interface Rect {
+		/** Left, pixels. */
+		x: number;
+		/** Top, pixels. */
+		y: number;
+		/** Width, pixels. */
+		w: number;
+		/** Height, pixels. */
+		h: number;
+	}
+	/**
+	 * Shelf packing: rows ("shelves") of the height of their first item, filled left to right. Freed rectangles go to a
+	 * free list and are reused by items that fit them without wasting more than half. Pure: tested in Node.
+	 */
+	export class ShelfPacker {
+		/** The page's width, pixels. */
+		readonly width: number;
+		/** The page's height, pixels. */
+		readonly height: number;
+		/** Pixels kept free around each item (no bleeding when sampled). */
+		readonly padding: number;
+		private shelves;
+		private free;
+		private bottom;
+		/** A page of width × height pixels, with padding pixels kept around each item. */
+		constructor(
+		/** The page's width, pixels. */
+		width: number, 
+		/** The page's height, pixels. */
+		height: number, 
+		/** Pixels kept free around each item (no bleeding when sampled). */
+		padding?: number);
+		/** A place for a w × h item (padding added around it), or null if the page is full. */
+		alloc(w: number, h: number): Rect | null;
+		/** Gives a rectangle from alloc back. */
+		release(r: Rect): void;
+		/** Share of the page's height used by shelves. */
+		get fill(): number;
+		/** Empties the page. */
+		reset(): void;
+		private inner;
+	}
+	/** A texture as the engine holds it: its pixels (kept for context loss and renderer swaps) and the renderer's copy. */
+	export interface Surface {
+		/** The pixels. */
+		source: HTMLCanvasElement | HTMLImageElement | ImageBitmap;
+		/** The renderer's texture of it, made on first draw (null until then, and after a renderer swap). */
+		texture: Texture | null;
+		/** Regions baked since the last upload: [scratch canvas, x, y]. */
+		pending: [
+			HTMLCanvasElement,
+			number,
+			number
+		][];
+	}
+	/** A frame: a region of a surface, in its pixels. scale: source pixels per stage unit (baked at the backing resolution). */
+	export interface Frame extends Region {
+		/** The surface (atlas page or image) it is a region of. */
+		surface: Surface;
+		/** Pixels per stage unit it was baked at: the frame is drawn w / scale × h / scale stage units by default. */
+		scale: number;
+		/** The atlas generation it belongs to: frames of an older one were wiped. 0: not in the atlas (an image). */
+		gen: number;
+		/** Where the frame's origin sits inside it, in stage units (the centre of a shape, the baseline of a text). */
+		ox: number;
+		/** Vertical position of the origin inside the frame, stage units. */
+		oy: number;
+		/** Paint around the content (outline, glow), stage units: the content box is the frame minus this on every side. */
+		margin: number;
+		/** A trimmed frame of a loaded atlas: the untrimmed width, pixels (the region sits at tx, ty inside it). */
+		sw?: number;
+		/** The untrimmed height, pixels. */
+		sh?: number;
+		/** Where the trimmed region starts inside the untrimmed frame, pixels. */
+		tx?: number;
+		/** Where the trimmed region starts inside the untrimmed frame, pixels (down). */
+		ty?: number;
+		/**
+		 * Nine-slice insets, pixels, [top, right, bottom, left] (CSS order): a loaded atlas's `scale9Borders`. Sprites of
+		 * the frame are nine-sliced by default.
+		 */
+		slice?: Insets;
+	}
+	/** Nine-slice insets: [top, right, bottom, left], pixels of the frame (CSS order). */
+	export type Insets = readonly [
+		top: number,
+		right: number,
+		bottom: number,
+		left: number
+	];
+	/** Pages of baked art. bake() draws into a scratch canvas, copies it into a page and queues the upload. */
+	export class Atlas {
+		/** A page's side, pixels. */
+		readonly pageSize: number;
+		/** Pages kept before the atlas is wiped. */
+		readonly maxPages: number;
+		/** The pages, each a canvas with its packer. */
+		readonly pages: {
+			surface: Surface;
+			packer: ShelfPacker;
+			ctx: CanvasRenderingContext2D;
+		}[];
+		/** The generation: bumped when the atlas is wiped (frames of an older one are baked again). */
+		gen: number;
+		/** Called when a page is added (the engine keeps track of surfaces). */
+		onPage: (s: Surface) => void;
+		/** Called when a page is dropped by a wipe: free its GPU texture (renderer.destroyTexture). */
+		onDrop: (s: Surface) => void;
+		/** Pages of pageSize × pageSize pixels, at most maxPages before a wipe. */
+		constructor(
+		/** A page's side, pixels. */
+		pageSize?: number, 
+		/** Pages kept before the atlas is wiped. */
+		maxPages?: number);
+		/** Whether a frame is still in the atlas (not wiped by a reset). */
+		valid(f: Frame | null | undefined): f is Frame;
+		/**
+		 * A w × h region (pixels) drawn by draw(ctx) with (0, 0) at its top-left: a frame of it. A new page is made while
+		 * there are fewer than maxPages, or for an item bigger than a page (a page of its own, its size). When every page
+		 * is full the atlas is wiped (gen changes, every frame is baked again on its next use): the first maxPages pages of
+		 * the usual size are kept, emptied, the others dropped, and the item goes on the first page.
+		 */
+		bake(w: number, h: number, draw: (ctx: CanvasRenderingContext2D) => void, scale?: number, ox?: number, oy?: number, margin?: number): Frame;
+		/** An image or canvas put into the atlas as it is. */
+		add(source: CanvasImageSource & {
+			width: number;
+			height: number;
+		}, scale?: number, ox?: number, oy?: number): Frame;
+		/** Gives a frame's place back (texts that changed size). */
+		release(f: Frame): void;
+		/**
+		 * Bakes again into the same place, if the new size fits in it (texts that change): the frame, updated, or null
+		 * (bake a new one).
+		 */
+		rebake(f: Frame, w: number, h: number, draw: (ctx: CanvasRenderingContext2D) => void, maxW?: number, maxH?: number): Frame | null;
+		private put;
+		private newPage;
+		/**
+		 * Every page emptied: frames of the old generation are baked again when used. Pages past maxPages, and pages made
+		 * bigger for one big item, are dropped (onDrop frees their textures).
+		 */
+		wipe(): void;
+	}
+	/**
+	 * How a text looks (engine.text(string, style)). Texts are baked once into the atlas, and again only when the string
+	 * or the style changes.
+	 *
+	 * @example
+	 * engine.text('0', { x: 40, y: 40, size: 48, align: 'left', outline: true })
+	 */
+	export interface TextStyle {
+		/** Font size, stage units. */
+		size?: number;
+		/** CSS font family list. */
+		font?: string;
+		/** CSS font weight (default 700). */
+		weight?: number | string;
+		/** CSS colour (default cream, #FBEFE3). */
+		color?: string;
+		/** 'left': x is the start; 'center' (default); 'right': x is the end. y is always the middle of the line. */
+		align?: "left" | "center" | "right";
+		/** A dark outline (true: the default halo colour) of this width (stage units). */
+		outline?: boolean | string;
+		/** The outline's width, stage units. */
+		outlineWidth?: number;
+		/** A soft shadow (true: the default halo colour), blur in stage units. */
+		shadow?: boolean | string;
+		/** The shadow's blur radius, stage units. */
+		shadowBlur?: number;
+		/**
+		 * Draw with a bitmap font (its name, from engine.load or engine.bitmapFont, or the font): no bake per string, for
+		 * texts that change often. size scales the font; the look (colour, outline) is the font's, and tint multiplies it.
+		 */
+		bitmapFont?: string | BitmapFont;
+	}
+	/** The font texts use by default: Fredoka if the page loaded it, then rounded fallbacks. */
+	export const DEFAULT_FONT = "Fredoka, Nunito, \"Varela Round\", system-ui, sans-serif";
+	/** The dark halo that makes text read over a real room or a light avatar. */
+	export const HALO = "rgba(10,16,30,0.75)";
+	/**
+	 * A line of text, baked into the atlas: cheap to move, scale and fade; changing text or style bakes it again (fine
+	 * for a score, not every frame). With a bitmap font nothing is baked: it may change every frame.
+	 *
+	 * @example
+	 * const score = stage.add(engine.text('0', { x: 40, y: 40, size: 48, align: 'left', outline: true }))
+	 * score.text = String(points)
+	 */
+	export class Text extends Sprite {
+		private _text;
+		private _style;
+		/** The string or style changed since the last bake. */
+		private dirty;
+		/** What the current frame was baked with. */
+		private bakedScale;
+		private bakedFontGen;
+		private bakedEffects;
+		/** The slot's capacity, pixels, so a longer string may still fit. */
+		private capW;
+		private capH;
+		/** Use engine.text(text, style). */
+		constructor(kernel: Kernel, text: string, style?: TextStyle & NodeProps);
+		/** The string shown: setting another bakes the text again (at the next draw); a bitmap text bakes nothing. */
+		get text(): string;
+		set text(v: string);
+		/** The style it is drawn with; setting one merges it into the current one and bakes again. */
+		get style(): TextStyle;
+		/** A new style (merged with the current one). */
+		set style(s: TextStyle);
+		/** The bitmap font it is drawn with, or null (a baked text). Sets the anchor from align while it is automatic. */
+		private bitmap;
+		/** The content width, stage units: the text's own. */
+		get naturalWidth(): number;
+		/** The content height, stage units: the line's. */
+		get naturalHeight(): number;
+		protected frameNow(): Frame | null;
+		/** Draws the text (the engine calls it): its baked frame, or its glyphs. */
+		draw(ctx: DrawContext, alpha: number, tint: number): void;
+		/** Removes the text and gives its place in the atlas back. */
+		destroy(): void;
+		private bake;
+		/** bake's slow path, apart: its closure's context would otherwise be made on every call, even the cheap ones. */
+		private rebake;
+	}
+	/** A glyph of a bitmap font: its frame and where it goes, in the font's units (stage units at its size). */
+	export interface Glyph {
+		/** The glyph's picture. */
+		frame: Frame;
+		/** From the pen to the picture's left edge. */
+		x: number;
+		/** From the line's top to the picture's top. */
+		y: number;
+		/** The picture's width. */
+		w: number;
+		/** The picture's height. */
+		h: number;
+		/** How far the pen moves after it. */
+		advance: number;
+	}
+	/** A BMFont file, parsed: sizes in its pixels. */
+	export interface BMFontData {
+		/** The size it was made at (info size). */
+		size: number;
+		/** Distance between lines. */
+		lineHeight: number;
+		/** From the line's top to the baseline. */
+		base: number;
+		/** Page image files, by page id. */
+		pages: string[];
+		/** The glyphs: where each is on its page and how it sits on the line. */
+		chars: {
+			id: number;
+			x: number;
+			y: number;
+			width: number;
+			height: number;
+			xoffset: number;
+			yoffset: number;
+			xadvance: number;
+			page: number;
+		}[];
+		/** Pairs moved closer (negative) or apart. */
+		kernings: {
+			first: number;
+			second: number;
+			amount: number;
+		}[];
+	}
+	/**
+	 * A BMFont description: text .fnt (`char id=48 x=0 …` lines), XML .fnt (`<char id="48" … />`), or JSON (a string
+	 * or an object: `{ info, common, pages, chars, kernings }`).
+	 */
+	export function parseBMFont(src: string | object): BMFontData;
+	/** The look of a generated bitmap font (as engine.text's style), and the characters to bake up front. */
+	export interface BitmapFontOptions extends Pick<TextStyle, "size" | "font" | "weight" | "color" | "outline" | "outlineWidth" | "shadow" | "shadowBlur"> {
+		/** Characters baked now (default the digits); any other is baked the first time it is drawn. */
+		chars?: string;
+	}
+	/** What a generated font needs from the engine, read at each draw. */
+	export interface GlyphHost {
+		readonly atlas: Atlas;
+		readonly pixelScale: number;
+		readonly fontGen: number;
+		readonly effects: boolean;
+	}
+	/**
+	 * A bitmap font: glyphs by code point, kerning pairs, its size and line height (stage units at size). Made by
+	 * engine.load (a BMFont) or engine.bitmapFont; texts use it with { bitmapFont: name }.
+	 */
+	export class BitmapFont {
+		/** A generated font's baker (null: a BMFont, glyphs given up front). */
+		private readonly baker;
+		/** A generated font's engine side (bake again when its resolution, fonts, effects or atlas change). */
+		private readonly host;
+		/** The size its units are at: a text of this size draws the glyphs 1:1. */
+		readonly size: number;
+		/** The line's height, font units. */
+		readonly lineHeight: number;
+		/** From the line's top to the baseline, font units. */
+		readonly base: number;
+		private readonly ascii;
+		private readonly more;
+		private readonly kern;
+		private bScale;
+		private bFontGen;
+		private bEffects;
+		private bGen;
+		/** Use engine.bitmapFont or engine.load. */
+		constructor(size: number, lineHeight: number, base: number, 
+		/** A generated font's baker (null: a BMFont, glyphs given up front). */
+		baker?: ((code: number) => Glyph | null) | null, 
+		/** A generated font's engine side (bake again when its resolution, fonts, effects or atlas change). */
+		host?: GlyphHost | null);
+		/** Sets a glyph (BMFont loading). */
+		set(code: number, g: Glyph | null): void;
+		/** Sets a kerning pair, font units. */
+		setKerning(first: number, second: number, amount: number): void;
+		/** Before a draw: a generated font whose resolution, tier, web font or atlas changed forgets its glyphs. */
+		prepare(): void;
+		/** The glyph of a code point (baked now if the font is generated), or null. */
+		glyph(code: number): Glyph | null;
+		/** Kerning between two code points, font units (0 for most pairs). */
+		kerning(a: number, b: number): number;
+		/** A string's width, font units. */
+		measure(text: string): number;
+		/**
+		 * Lays text out: its width, font units. With ctx, also draws it in the space of m, the line's top-left at (x0, y0),
+		 * font units scaled by kx, ky: one quad per glyph, nothing allocated (code points read in place).
+		 */
+		run(text: string, ctx?: DrawContext, m?: Mat, x0?: number, y0?: number, kx?: number, ky?: number, tint?: number, alpha?: number, blend?: Blend): number;
+	}
+	/** How a shape is painted: fill, outline, shadow or glow. Colours are CSS. */
+	export interface Paint {
+		/** The fill colour; none without it. */
+		fill?: string;
+		/** The outline colour; none without it. */
+		stroke?: string;
+		/** Outline width, stage units. */
+		lw?: number;
+		/** The outline under the fill (only its outer half shows), as when a path is stroked before it is filled. */
+		outlineBelow?: boolean;
+		/** A soft shadow or glow around the shape: colour and blur radius (stage units), optional offset. */
+		shadow?: {
+			color: string;
+			blur: number;
+			x?: number;
+			y?: number;
+		};
+	}
+	/**
+	 * A shape for engine.shape and engine.particles: its type and size (stage units) and its paint.
+	 *
+	 * @example
+	 * engine.shape({ type: 'circle', r: 30, fill: '#8CC9A0', stroke: '#fff', lw: 4 })
+	 * engine.shape({ type: 'roundRect', w: 300, h: 80, r: 24, fill: 'rgba(15,24,42,0.6)' })
+	 * engine.shape({ type: 'star', r: 40, fill: '#FBD46A', shadow: { color: '#FBD46A', blur: 12 } })
+	 */
+	export type ShapeSpec = Paint & (
+	/** A disc of radius r. */
+	{
+		type: "circle";
+		r: number;
+	}
+	/** An ellipse of radii rx, ry. */
+	 | {
+		type: "ellipse";
+		rx: number;
+		ry: number;
+	}
+	/** w × h with corner radius r; drawn nine-sliced: set the node's width and height freely. */
+	 | {
+		type: "roundRect";
+		w: number;
+		h: number;
+		r: number;
+	}
+	/** A star of radius r: points (5), inner radius as a share of r (0.5). */
+	 | {
+		type: "star";
+		r: number;
+		points?: number;
+		inner?: number;
+	}
+	/** A circle's outline of radius r (stroke and lw). */
+	 | {
+		type: "ring";
+		r: number;
+	}
+	/** A horizontal capsule `length` long and lw thick (stroke colour, or fill). */
+	 | {
+		type: "line";
+		length: number;
+	}
+	/** An SVG path (any syntax Path2D takes) in a size × size box, drawn centred; scaled to `r` (half the box) if given. */
+	 | {
+		type: "path";
+		d: string;
+		size: number;
+		r?: number;
+	});
+	/** A shape baked into the atlas. */
+	export interface BakedShape {
+		/** Where it is in the atlas. */
+		frame: Frame;
+		/** Nine-slice border, in frame pixels (rounded rectangles), else 0. */
+		slice: number;
+		/** Local width, stage units. */
+		w: number;
+		/** Local height, stage units. */
+		h: number;
+	}
+	/** Options of engine.timeline(). */
+	export interface TimelineOptions {
+		/** Plays after the first: 2 plays three times in all; -1 forever (until stop). Default 0. */
+		repeat?: number;
+		/** Every other play runs backwards (with repeat). */
+		yoyo?: boolean;
+		/** Seconds before it starts. */
+		delay?: number;
+		/** Made paused: call resume() to start it. */
+		paused?: boolean;
+		/** Called when the last play ends (not on stop). */
+		onComplete?: () => void;
+	}
+	/**
+	 * Where a step goes: seconds from the start, or a string: 'label', 'label+=0.2', 'label-=0.2', '+=0.5' / '-=0.5'
+	 * (from the current end), '<' (where the previous step started), '<+=0.1', '>' (the end, the default).
+	 */
+	export type Position = number | string;
+	/** Options of a timeline step: a tween's, and where it goes. */
+	export interface StepOptions extends TweenOptions {
+		/** Where it starts (see Position); delay is added to it. Default: the end of the timeline so far. */
+		at?: Position;
+	}
+	/**
+	 * A timeline (engine.timeline()): chain to, set, call, label and wait to build it; it starts on the next frame
+	 * unless made paused. Await it (or then) for its end; stop() ends it early (where it is).
+	 */
+	export class Timeline implements PromiseLike<void> {
+		private readonly steps;
+		private readonly labels;
+		private end;
+		private prevStart;
+		private elapsed;
+		private iter;
+		private last;
+		private delayLeft;
+		private _paused;
+		private done;
+		private rewinding;
+		private readonly promise;
+		private resolve;
+		/** Plays after the first (-1: forever). */
+		repeat: number;
+		/** Every other play backwards. */
+		yoyo: boolean;
+		/** Called when the last play ends. */
+		onComplete?: () => void;
+		/** Use engine.timeline(opts). */
+		constructor(o?: TimelineOptions);
+		/** One play's length, seconds. */
+		get duration(): number;
+		/** Where the playhead is in the current play, seconds. */
+		get time(): number;
+		/** Paused by pause() (or made paused). */
+		get paused(): boolean;
+		/** It ended (all its plays, or stop()). */
+		get finished(): boolean;
+		/** Where a position is, seconds. */
+		private at;
+		private add;
+		/**
+		 * Eases target's numeric fields to `to` over `seconds` (as engine.tween), after the previous step or `at`.
+		 *
+		 * @example
+		 * engine.timeline().to(a, { x: 600 }, 0.5).to(b, { alpha: 0 }, 0.3, { at: '<' })
+		 */
+		to<T extends object>(target: T, to: Partial<Record<keyof T, number>>, seconds: number, ease?: Ease | EaseName | StepOptions): this;
+		/** Sets fields at once, when the playhead gets there. */
+		set<T extends object>(target: T, values: Partial<Record<keyof T, number>>, at?: Position): this;
+		/** Calls fn when the playhead passes this point (either way: a yoyo calls it going back too). */
+		call(fn: () => void, at?: Position): this;
+		/** Names a point (default: the end so far), for `at: 'name'` and seek('name'). */
+		label(name: string, at?: Position): this;
+		/** A pause of `seconds` at the end: the next step starts after it. */
+		wait(seconds: number): this;
+		/** Stops the clock where it is (game pauses stop it anyway). */
+		pause(): this;
+		/** Starts or goes on after pause() or { paused: true }. */
+		resume(): this;
+		/** Ends it now, fields where they are; the promise resolves. */
+		stop(): void;
+		/** Moves the playhead to a time or a label of the current play, writing the fields there. */
+		seek(pos: Position): this;
+		then<A = void, B = never>(ok?: ((v: void) => A | PromiseLike<A>) | null, fail?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+		/** Advances by dt seconds of game time (the engine's tweens call it). */
+		update(dt: number): void;
+		private complete;
+		/** Writes every step at playhead t: forwards in start order, backwards in reverse (see the file's comment). */
+		private render;
+		private apply;
+	}
+	/** Options of engine.tween. */
+	export interface TweenOptions {
+		/** An EASE name ('quadOut' by default, 'backOut', 'linear', …) or a function of 0–1. */
+		ease?: Ease | EaseName;
+		/** Seconds before it starts; the start values are read then. */
+		delay?: number;
+		/** Called every step with the eased progress, 0–1. */
+		onUpdate?: (k: number) => void;
+	}
+	/** A promise that resolves when the tween ends (or is stopped), with stop(). */
+	export type TweenHandle = Promise<void> & {
+		stop(): void;
+	};
+	/** The engine's tweens (engine.tween): advanced on game time, so they stop on pause and breaks. */
+	export class Tweens {
+		private readonly list;
+		private timelines;
+		/** A timeline played on the same clock (see Timeline). */
+		timeline(opts?: TimelineOptions): Timeline;
+		/** Eases target's numeric fields to `to` over `seconds`. */
+		tween<T extends object>(target: T, to: Partial<Record<keyof T, number>>, seconds: number, ease?: Ease | EaseName | TweenOptions): TweenHandle;
+		/** Stops every tween of target (they resolve where they are). */
+		stopAll(target: object): void;
+		/** Tweens running. */
+		get size(): number;
+		/** Advances every tween by dt seconds. */
+		update(dt: number): void;
+		private step;
+		private finish;
+		/** Stops every tween (they resolve where they are). */
+		clear(): void;
+	}
+	/** What nodes need from the engine (the engine makes it; a game never does). */
+	export interface Kernel {
+		/** Where frames, baked shapes and texts live. */
+		readonly atlas: Atlas;
+		/** Backing-store pixels per stage unit (texts and shapes are baked at it). */
+		readonly pixelScale: number;
+		/** Bumped when web fonts finish loading: texts bake again. */
+		readonly fontGen: number;
+		/** The tier's effects (glows, soft shadows): shapes and texts bake without their shadow when false. */
+		readonly effects: boolean;
+		/** The engine's tweens (a destroyed node's stop). */
+		readonly tweens: Tweens;
+		/** A loaded or baked frame by name. */
+		frame(name: string): Frame;
+		/** A shape baked into the atlas. */
+		shape(spec: ShapeSpec): BakedShape;
+		/** A bitmap font by name (loaded, or made with engine.bitmapFont). */
+		bitmapFont(name: string): BitmapFont;
+	}
+	/** A frame being drawn: what Node.draw gets (for custom nodes). */
+	export interface DrawContext {
+		/** The renderer to draw with. */
+		readonly r: Renderer;
+		/** The engine's side of the nodes. */
+		readonly kernel: Kernel;
+		/** A surface's texture on this renderer. */
+		tex(s: Surface): Texture;
+	}
+	/**
+	 * Fields to set on a node when making it (or with node.set): position, rotation, scale, look. Stage units.
+	 *
+	 * @example
+	 * engine.sprite('star', { x: 640, y: 360, scale: 2, anchor: 0.5, alpha: 0.8 })
+	 */
+	export interface NodeProps {
+		/** Position in the parent, stage units (y downwards). */
+		x?: number;
+		/** Position in the parent, stage units (y downwards). */
+		y?: number;
+		/** Radians, clockwise. */
+		rotation?: number;
+		/** Both scales at once. */
+		scale?: number;
+		/** Horizontal scale (negative: mirrored). */
+		scaleX?: number;
+		/** Vertical scale. */
+		scaleY?: number;
+		/** 0–1, multiplied down the tree. */
+		alpha?: number;
+		/** Hidden nodes and their children are not drawn. */
+		visible?: boolean;
+		/** A colour multiplied with the pixels (white: none), as 0xRRGGBB or CSS. */
+		tint?: ColorLike;
+		/** 'add' for glows and sparks. */
+		blend?: Blend;
+		/** Drawing order among siblings: higher on top (equal: order of adding). */
+		z?: number;
+		/** Anchor, 0–1 of the size: 0 top-left, 0.5 the middle. A number sets both. */
+		anchor?: number | {
+			x: number;
+			y: number;
+		};
+		/** Local width, stage units (sprites and shapes: stretched to it). */
+		width?: number;
+		/** Local height, stage units. */
+		height?: number;
+		/** Hit tests use a circle of this radius (local units) around the origin instead of the rectangle. */
+		hitRadius?: number;
+		/** Clips the node and its children to this rectangle, in the node's own units (null: no clip). */
+		clip?: ClipRect | null;
+		/** Shows the node and its children only where this node is opaque (null: no mask). See Node.mask. */
+		mask?: Node | null;
+		/** Filters, in order (null: none). See Node.filters. */
+		filters?: Filter[] | null;
+	}
+	/** A clip rectangle, in a node's own units. */
+	export interface ClipRect {
+		/** Left, local units. */
+		x: number;
+		/** Top, local units. */
+		y: number;
+		/** Width, local units. */
+		width: number;
+		/** Height, local units. */
+		height: number;
+	}
+	/**
+	 * The base of everything on the stage: a transform, a look and a place in a group. Make nodes with the engine
+	 * (engine.sprite, shape, text, group, particles), add them to the stage or a group, then change their fields every
+	 * frame.
+	 *
+	 * A node is a handle on a slot of the node store (src/store.ts): x, y, rotation, scale, alpha, visible, tint and its
+	 * world matrix live there. After destroy() the handle is stale: its writes reach no other node, and its reads give
+	 * its last values until its slot goes to a new node, then a fresh node's (hidden).
+	 */
+	export class Node {
+		protected readonly kernel: Kernel;
+		/**
+		 * @internal Slot index in the node store: the accessors read slot _i and write slot _i || SINK, unchecked. Once the
+		 * slot is another node's, a destroyed handle's _i is 0 (the neutral slot) and its _g -1 (store.ts, alloc).
+		 */
+		_i: number;
+		/** @internal The slot's generation when it was given to this node. */
+		_g: number;
+		/** The world view, and the slot and store epoch it was made for. */
+		private _wv;
+		private _wi;
+		private _we;
+		/** Position in the parent, stage units. */
+		get x(): number;
+		set x(v: number);
+		/** Position in the parent, stage units (y downwards). */
+		get y(): number;
+		set y(v: number);
+		/** Radians, clockwise. */
+		get rotation(): number;
+		set rotation(v: number);
+		/** Horizontal scale (negative: mirrored). */
+		get scaleX(): number;
+		set scaleX(v: number);
+		/** Vertical scale. */
+		get scaleY(): number;
+		set scaleY(v: number);
+		/** 0–1, multiplied down the tree. */
+		get alpha(): number;
+		set alpha(v: number);
+		/** Hidden nodes and their children are not drawn. Hit tests (engine.touched, engine.hits) still see them. */
+		get visible(): boolean;
+		set visible(v: boolean);
+		/** Set by destroy(): the node is gone (its handle is stale). */
+		get destroyed(): boolean;
+		/**
+		 * The transform to the stage, as of the last draw (or updateWorld): a view on the node store, written in place.
+		 * Read it when you need it: a view kept across frames stops following the node once the store grows (new arrays).
+		 */
+		get world(): Mat;
+		/** 'add' for glows and sparks; 'normal' otherwise. */
+		blend: Blend;
+		private _data;
+		/** Free for the game: speed, state, anything (made on first use). */
+		get data(): Record<string, any>;
+		set data(v: Record<string, any>);
+		/** The group the node is in, or null. */
+		parent: Group | null;
+		/** Hit tests use a circle of this radius (local units) around the origin instead of the rectangle; null: the rectangle. */
+		hitRadius: number | null;
+		/**
+		 * Clips the node and its children to this rectangle, in the node's own units (x, y, width, height). While no
+		 * rotation is above it, the renderer clips on whole pixels without breaking the batch; rotated, it is drawn as a
+		 * mask. Clips nest (they intersect). Hit tests ignore it.
+		 *
+		 * @example
+		 * list.clip = { x: 0, y: 0, width: 400, height: 300 }   // a scrolling list: move its children, not the clip
+		 */
+		clip: ClipRect | null;
+		/**
+		 * Shows the node and its children only where this node is opaque, times its alpha: a circle, a star, a text, any
+		 * node. The mask is placed as a child of the masked node would be, and is not drawn otherwise (keep it out of the
+		 * stage). The masked node is drawn into a layer: about two full-canvas composites per mask, so use a few.
+		 *
+		 * @example
+		 * photo.mask = engine.shape({ type: 'circle', r: 80, fill: '#fff' })
+		 */
+		mask: Node | null;
+		/**
+		 * Filters the node and its children go through, in order: tint, brightness, contrast, saturate, grayscale, sepia,
+		 * hueRotate, invert, colorMatrix, blur, dropShadow (the same on WebGL and Canvas 2D), shader (WebGL only). The node
+		 * is drawn into a layer and composited through them (the filters inside a clip and under a mask). Change their
+		 * fields freely (`flash.amount = 0.5`, tweens); null or [] for none.
+		 *
+		 * @example
+		 * import { blur, dropShadow } from '@fabi-play/engine'
+		 * card.filters = [dropShadow(0, 8, 6, 'rgba(0,0,0,0.35)')]
+		 * background.filters = [blur(6)]
+		 */
+		filters: Filter[] | null;
+		private _z;
+		/** Horizontal anchor, 0–1 of the width: 0 left, 0.5 the middle. */
+		anchorX: number;
+		/** Vertical anchor, 0–1 of the height: 0 top, 0.5 the middle. */
+		anchorY: number;
+		/** @internal The node pool that made it (nodePool), if any. */
+		_pool: {
+			forget(n: Node): void;
+		} | null;
+		/** @internal Released to its pool, waiting for get(). */
+		_free: boolean;
+		/** @internal Registered to give its slots back if dropped without destroy() (store.ts, track). */
+		_reg: boolean;
+		/** Nodes are made by the engine (engine.sprite, engine.group, …); a custom node subclass passes the kernel on. */
+		constructor(kernel: Kernel);
+		/** Both scales: reads scaleX, sets scaleX and scaleY. */
+		get scale(): number;
+		set scale(v: number);
+		/** Drawing order among siblings: higher on top (equal: order of adding). */
+		get z(): number;
+		set z(v: number);
+		/** A colour multiplied with the node's pixels (white: none), as 0xRRGGBB or CSS. */
+		get tint(): number;
+		set tint(v: ColorLike);
+		/** Sets anchorX and anchorY: a number for both, or { x, y }. 0 top-left, 0.5 the middle. */
+		set anchor(v: number | {
+			x: number;
+			y: number;
+		});
+		/** Local size, for hit tests and anchors; groups have none. */
+		get width(): number;
+		set width(_: number);
+		/** Local height, for hit tests and anchors; groups have none. */
+		get height(): number;
+		set height(_: number);
+		/** Sets many fields at once. */
+		set(props: NodeProps): this;
+		/** Removes the node: invisible at once (its parent null), out of its group's children at the end of the frame. Its tweens stop. */
+		destroy(): void;
+		/** world, computed now from the parents (for hit tests between draws). */
+		updateWorld(): Mat;
+		/** Draws the node; world is already composed. */
+		draw(_ctx: DrawContext, _alpha: number, _tint: number): void;
+	}
+	/**
+	 * A node holding others: they move, rotate, scale, fade and tint with it.
+	 *
+	 * @example
+	 * const stars = stage.add(engine.group())
+	 * stars.add(engine.shape({ type: 'star', r: 40, fill: '#FBD46A' }, { x: 100 }))
+	 * for (const star of stars.children) star.y += 150 * dt
+	 */
+	export class Group extends Node {
+		/** The nodes in it, in drawing order (one shared empty array until the first add). Safe to destroy() them while iterating. */
+		readonly children: Node[];
+		/** @internal */ sortDirty: boolean;
+		/** @internal: a child was destroyed. */ dead: boolean;
+		constructor(kernel: Kernel);
+		/** Adds nodes (moving them from another group); returns the first, so `const s = stage.add(engine.sprite(…))`. */
+		add<T extends Node>(node: T, ...more: Node[]): T;
+		private adopt;
+		/** Takes a node out of the group (without destroying it). */
+		remove(node: Node): void;
+		private detach;
+		/** Destroys every child. */
+		clear(): void;
+		/** Destroys the group and every child. */
+		destroy(): void;
+		/** @internal Drops destroyed children (end of frame). */
+		sweep(): void;
+		/**
+		 * Draws the children, in order of z, each placed (its world composed, store.ts place) right before it is drawn,
+		 * when it or a parent moved. The outermost draw begins a pass; a group in no group drawn inside it (a mask) has
+		 * been placed anew by its caller, so everything under it is composed.
+		 */
+		draw(ctx: DrawContext, alpha: number, tint: number): void;
+		private drawChildren;
+	}
+	/** NodeProps, and the frame to show. */
+	export interface SpriteProps extends NodeProps {
+		/** An atlas frame, or the name of a loaded or baked one. */
+		frame?: Frame | string;
+		/**
+		 * Nine-slice insets in frame pixels: one number for all sides, or [top, right, bottom, left]. The corners keep
+		 * their size when the sprite is resized, the edges and the middle stretch. Default: the frame's own (an atlas's
+		 * scale9Borders), else none.
+		 */
+		slice?: number | Insets;
+	}
+	/**
+	 * A picture: an atlas frame or an image, or a baked shape or text (subclasses). Its local size is width × height
+	 * (the frame's own by default), placed by its anchor.
+	 *
+	 * @example
+	 * // A panel from a loaded image, nine-sliced: 24-pixel corners, any size.
+	 * const panel = stage.add(engine.sprite('ui/panel', { slice: 24, width: 420, height: 160 }))
+	 */
+	export class Sprite extends Node {
+		protected _frame: Frame | null;
+		protected _w: number | null;
+		protected _h: number | null;
+		/**
+		 * Nine-slice insets in frame pixels (0: none, or the frame's own): one number for all sides, or [top, right,
+		 * bottom, left]. The corners keep their size when the sprite is resized.
+		 */
+		slice: number | Insets;
+		/** True until an anchor is set: then the frame's own origin (a shape's centre, a text's alignment) is used. */
+		protected autoAnchor: boolean;
+		/** Use engine.sprite(frame, props). */
+		constructor(kernel: Kernel, frame?: Frame | string | null, props?: SpriteProps);
+		/** What it shows: set a frame or the name of a loaded or baked one (an animation swaps it every few frames). */
+		get frame(): Frame | null;
+		set frame(f: Frame | string | null);
+		/** The name the frame came from: baked frames are looked up again after the atlas was wiped. */
+		private frameName;
+		/** Sets anchorX and anchorY (until then the frame's own origin is used). */
+		set anchor(v: number | {
+			x: number;
+			y: number;
+		});
+		/** The content size the frame has, stage units (without its margin; untrimmed). */
+		get naturalWidth(): number;
+		/** The content height the frame has, stage units (without its margin; untrimmed). */
+		get naturalHeight(): number;
+		/** Local width, stage units: the frame's own (naturalWidth) until set; setting it stretches the sprite. */
+		get width(): number;
+		set width(v: number);
+		/** Local height, stage units: the frame's own (naturalHeight) until set; setting it stretches the sprite. */
+		get height(): number;
+		set height(v: number);
+		/**
+		 * frameQ[0], [1] = width and height, drawing frame f: what the getters say, written to an array instead of returned
+		 * (a number returned through a getter on several classes is boxed on every call).
+		 */
+		protected sizeQ(f: Frame): void;
+		/** The frame to draw now (subclasses bake it on demand). */
+		protected frameNow(): Frame | null;
+		protected useFrameAnchor(): void;
+		/** Draws the frame (the engine calls it). */
+		draw(ctx: DrawContext, alpha: number, tint: number): void;
+	}
+	/**
+	 * A shape baked once into the atlas (see ShapeSpec); changing spec bakes again (do it rarely, not every frame). A
+	 * roundRect resizes freely with width and height (panels, progress bars).
+	 *
+	 * @example
+	 * const star = stage.add(engine.shape({ type: 'star', r: 40, fill: '#FBD46A', stroke: '#fff', lw: 4 }, { x: 200, y: 100 }))
+	 */
+	export class Shape extends Sprite {
+		private _spec;
+		private baked;
+		private bakedEffects;
+		/** Use engine.shape(spec, props). */
+		constructor(kernel: Kernel, spec: ShapeSpec, props?: NodeProps);
+		/** What it is: setting it bakes the shape again. */
+		get spec(): ShapeSpec;
+		set spec(s: ShapeSpec);
+		private bake;
+		protected frameNow(): Frame;
+		protected sizeQ(): void;
+		/** Local width, stage units: the shape's own until set (a roundRect is redrawn to it, others stretched). */
+		get width(): number;
+		set width(v: number);
+		/** Local height, stage units: the shape's own until set. */
+		get height(): number;
+		set height(v: number);
+	}
+	/** How an emitter behaves (engine.particles(frame, opts)), for all its particles. */
+	export interface ParticleOptions {
+		/** Most particles alive at once (the pool; fixed). Scale it with tier.scale. */
+		max?: number;
+		/** 'add' for glowing sparks. */
+		blend?: Blend;
+		/** Stage units per second², down. */
+		gravity?: number;
+		/** Velocity kept per second (0–1): 1 none lost. */
+		drag?: number;
+	}
+	/** How the particles of one burst start: speed, life, direction, size, spin and look. */
+	export interface BurstOptions {
+		/** Speed range, stage units per second. */
+		speed?: number | [
+			number,
+			number
+		];
+		/** Life range, seconds. */
+		life?: number | [
+			number,
+			number
+		];
+		/** Direction (rad) and spread around it; full circle by default. */
+		angle?: number;
+		/** Radians around angle; without it, the full circle. */
+		spread?: number;
+		/** Scale at birth and at death. */
+		scale?: number | [
+			number,
+			number
+		];
+		/** Spin range, rad per second. */
+		spin?: number;
+		/** Their colour (multiplied with the frame's pixels), e.g. the player's colour. */
+		tint?: ColorLike;
+		/** Alpha at birth; they fade out over their life. */
+		alpha?: number;
+	}
+	/**
+	 * A pooled emitter: particles live in fixed typed arrays (no allocation while playing), move with their speed,
+	 * gravity and drag, fade out and shrink or grow. Drawn as one quad each, from one frame.
+	 */
+	export class Particles extends Node {
+		/** The pool's size: most particles alive at once. */
+		readonly max: number;
+		private readonly f;
+		private readonly tints;
+		private count;
+		/** Stage units per second², down. */
+		gravity: number;
+		/** Velocity kept per second (0–1): 1 none lost. */
+		drag: number;
+		/** The frame every particle shows (or its name). */
+		frameRef: Frame | string;
+		/** The random source for bursts (a seeded rng in tests and replays). */
+		random: () => number;
+		private static readonly W;
+		/** Use engine.particles(frame, opts). */
+		constructor(kernel: Kernel, frame: Frame | string, opts?: ParticleOptions);
+		/** Particles alive. */
+		get alive(): number;
+		/**
+		 * n particles at (x, y) (local units); past the pool's size the oldest are reused.
+		 *
+		 * @example
+		 * sparks.burst(star.x, star.y, engine.tier.scale(24), { tint: hand.color, speed: [100, 300] })
+		 */
+		burst(x: number, y: number, n: number, o?: BurstOptions): void;
+		/** Advances every particle (the engine calls it, on game time). */
+		update(dt: number): void;
+		/** Removes every particle at once. */
+		clear(): void;
+		/** Draws the particles (the engine calls it). */
+		draw(ctx: DrawContext, alpha: number, tint: number): void;
+	}
+	/** An animation's frames (frames, or loaded or baked frame names) and, if it has them, each frame's seconds. */
+	export interface AnimationDef {
+		/** The frames, in order. */
+		frames: readonly (Frame | string)[];
+		/** Seconds per frame (Aseprite's durations); without them, 1 / fps each. */
+		durations?: readonly number[];
+	}
+	/**
+	 * How an animated sprite plays (engine.animation(frames, props)): a sprite's props and these.
+	 *
+	 * @example
+	 * engine.animation('hero/run', { fps: 12, x: 200, y: 500, anchor: 0.5 })
+	 */
+	export interface AnimationProps extends SpriteProps {
+		/** Frames per second (default 12); ignored for frames with their own durations, unless set. */
+		fps?: number;
+		/** Start again after the last frame (default true); false: stop on it and call onComplete. */
+		loop?: boolean;
+		/** Starts playing at once (default true). */
+		playing?: boolean;
+		/** Time scale: 2 plays twice as fast, -1 backwards. Default 1. */
+		speed?: number;
+		/** Called when a non-looping animation reaches its last frame. */
+		onComplete?: () => void;
+	}
+	/**
+	 * A sprite showing the frames of an animation one after the other, on game time.
+	 *
+	 * @example
+	 * const hero = stage.add(engine.animation('hero/run', { fps: 12, x: 200, y: 500, anchor: 0.5 }))
+	 * hero.gotoFrame(0)
+	 * const jump = stage.add(engine.animation('hero/jump', { loop: false, onComplete: () => jump.destroy() }))
+	 */
+	export class AnimatedSprite extends Sprite {
+		/** The frames, in order. */
+		readonly frames: readonly (Frame | string)[];
+		/** Seconds per frame, when the animation has its own (else 1 / fps). */
+		durations: readonly number[] | null;
+		/** Frames per second, when there are no durations. */
+		fps: number;
+		/** Start again after the last frame. */
+		loop: boolean;
+		/** Time scale: 2 twice as fast, -1 backwards. */
+		speed: number;
+		/** Called when a non-looping animation reaches its end. */
+		onComplete: (() => void) | null;
+		private _playing;
+		private index;
+		/** Seconds into the current frame. */
+		private t;
+		/** Use engine.animation(frames, props). */
+		constructor(kernel: Kernel, def: AnimationDef, props?: AnimationProps);
+		/** The frame shown, from 0. */
+		get frameIndex(): number;
+		/** How many frames. */
+		get frameCount(): number;
+		/** Playing (not stopped, not at the end of a non-looping run). */
+		get playing(): boolean;
+		/** Plays from where it is (from the start again if a non-looping run had ended). */
+		play(): this;
+		/** Stops on the current frame. */
+		stop(): this;
+		/** Shows frame i (from 0; wrapped into range), keeping the playing state. */
+		gotoFrame(i: number): this;
+		/** Shows frame i and plays from it. */
+		gotoAndPlay(i: number): this;
+		/** Shows frame i and stops on it. */
+		gotoAndStop(i: number): this;
+		private show;
+		private secondsOf;
+		/** Advances by dt seconds of game time (the engine calls it). */
+		update(dt: number): void;
+	}
+	/** A hand on the stage (engine.hands(), engine.touched()): whose, which, where. */
+	export interface Hand {
+		/** The player, from 1. */
+		player: number;
+		/** Which hand (the child's own left or right). */
+		side: "left" | "right";
+		/** Stage units. */
+		x: number;
+		/** Stage units. */
+		y: number;
+		/** The player's colour (CSS). */
+		color: string;
+	}
+	/** The wrists of a body seen well enough, in player space. */
+	export function wrists(body: Body): {
+		side: "left" | "right";
+		x: number;
+		y: number;
+	}[];
+	/** A player's colour (CSS), as the TV draws them: player 1 orange, 2 blue, 3 green, 4 lilac, then again. */
+	export const playerColor: (player: number) => "#EE6A43" | "#6FA0E0" | "#8CC9A0" | "#C49BE0";
+	/**
+	 * Every player's hands in stage units: wrists of bodyOf(frame) (null: the frame's own body), through toScreen
+	 * (player space to screen fractions), times the stage size.
+	 */
+	export function handsOf(frames: readonly PlayerFrame[], toScreen: (p: Point) => Point, width: number, height: number, bodyOf?: (f: PlayerFrame) => Body | null): Hand[];
+	/** What a node offers to hit tests: its world transform, size and anchor, or a radius. */
+	export interface Hittable {
+		/** The node's transform to the stage. */
+		readonly world: Mat;
+		/** Local size (stage units, before the world transform) and anchor (0–1): the rectangle's corner is at -anchor × size. */
+		readonly width: number;
+		/** Local height, stage units. */
+		readonly height: number;
+		/** Horizontal anchor, 0–1 of the width. */
+		readonly anchorX: number;
+		/** Vertical anchor, 0–1 of the height. */
+		readonly anchorY: number;
+		/** Set: a circle of this radius (local units) around the node's origin instead of the rectangle. */
+		hitRadius?: number | null;
+	}
+	/**
+	 * Whether the point (stage units) touches the node: in its local space, inside the rectangle (or circle) grown by
+	 * pad stage units. Rotation and scale are taken into account.
+	 */
+	export function hits(node: Hittable, x: number, y: number, pad?: number): boolean;
+	/** The first hand touching the node (of one player, or anyone's), or null. */
+	export function touching(node: Hittable, hands: readonly Hand[], player?: number, pad?: number): Hand | null;
+	/** Options of the WebGL backends. */
+	export interface GLOptions {
+		/** Refuse a context the browser says is much slower than usual (software rendering). Default true. */
+		failIfMajorPerformanceCaveat?: boolean;
+		/** Turn off instancing / VAOs (tests, comparisons). */
+		instancing?: boolean;
+		/** Turn off vertex array objects (tests, comparisons). */
+		vao?: boolean;
+	}
+	/** A renderer to ask for: a kind, 'webgl' (2, else 1) or 'auto' (WebGL2, WebGL1, then Canvas 2D). */
+	export type RendererChoice = RendererKind | "auto" | "webgl";
+	/** Options to choose and set up a renderer. */
+	export interface DetectOptions extends GLOptions {
+		/** Force one ('webgl': 2, else 1). 'auto' (default): the order above. A forced one that fails falls back too. */
+		renderer?: RendererChoice;
+	}
+	/** The order to try, for a choice. */
+	export function rendererOrder(choice?: RendererChoice): RendererKind[];
+	/** A renderer on canvas (or a fresh canvas that replaced it in the page: use renderer.canvas from now on). */
+	export function createRenderer(canvas: HTMLCanvasElement, opts?: DetectOptions): Renderer;
+	/**
+	 * Sound, as small as it can be: Web Audio, decoded buffers by name, and simple tones for games without sound files.
+	 * Silent while the host says muted, during pauses and breaks (the engine suspends it), and until the page may play
+	 * audio (resumed on the first event the page receives).
+	 */
+	export interface PlayOptions {
+		/** 0–1 (default 1). */
+		volume?: number;
+		/** Playback rate (pitch): 1 normal. */
+		rate?: number;
+		/** Start again at the end, until stop() (default false). */
+		loop?: boolean;
+	}
+	/** Options of sound.tone(). */
+	export interface ToneOptions {
+		/** 0–1 (default 0.12). */
+		volume?: number;
+		/** The waveform (default 'sine'). */
+		type?: OscillatorType;
+		/** Glide to this frequency over the tone. */
+		to?: number;
+	}
+	/**
+	 * engine.sound: Web Audio, loaded by name with engine.load, quiet while the host pauses, shows a break or is muted.
+	 *
+	 * @example
+	 * await engine.load({ pop: 'sounds/pop.mp3' })
+	 * engine.sound.play('pop', { volume: 0.8 })
+	 * engine.sound.tone(880, 0.15)
+	 */
+	export class Sound {
+		private ctx;
+		private master;
+		private readonly buffers;
+		private held;
+		/** Muted by the host (the TV's sound is off): set by the engine. */
+		muted: boolean;
+		/** Master volume, 0–1. */
+		volume: number;
+		/** The engine makes it (engine.sound); browsers unlock its audio on the first touch, key or click. */
+		constructor();
+		/** The audio context, made on first use (null without Web Audio). */
+		context(): AudioContext | null;
+		/** Decodes a sound file (mp3, aac, ogg, wav) under a name. */
+		load(name: string, url: string): Promise<void>;
+		/** Whether a sound of that name is loaded. */
+		has(name: string): boolean;
+		/** Plays a loaded sound; returns stop(). */
+		play(name: string, o?: PlayOptions): () => void;
+		/** A short tone (a "ding"): frequency Hz, seconds, fading out. */
+		tone(freq: number, seconds?: number, o?: ToneOptions): void;
+		private get audible();
+		/** Pauses and breaks: everything stops until release(). */
+		hold(): void;
+		/** Sound again after hold(). */
+		release(): void;
+		/** Closes the audio context. */
+		destroy(): void;
+	}
+	/** The quality tiers, best first. */
+	export type TierName = "high" | "medium" | "low";
+	/**
+	 * engine.tier: how much the device can draw. Games read name, and scale counts with scale(n); the engine applies
+	 * the rest (resolution, effects).
+	 *
+	 * @example
+	 * const sparks = engine.particles(frame, { max: engine.tier.scale(200) })
+	 */
+	export interface Tier {
+		/** 'high', 'medium' or 'low'. */
+		readonly name: TierName;
+		/** Most backing-store pixels per stage unit (the stage is 720 units high): 1.5, 1, 0.75. */
+		readonly resolution: number;
+		/** Particles and other counts: × 1, × 0.5, × 0.2. */
+		readonly particles: number;
+		/** Additive glows and extra layers (high only). */
+		readonly effects: boolean;
+		/** The largest blur (blur(), dropShadow()) radius, stage units: 32, 16, 0 (off: shadows hard). */
+		readonly maxBlur: number;
+		/** n scaled for this tier (at least 1 if n ≥ 1). */
+		scale(n: number): number;
+	}
+	/** Every tier, best first. */
+	export const TIERS: TierName[];
+	/** The tier of that name. */
+	export function tier(name: TierName): Tier;
+	/** What the engine's short probe measured, for pickTier. */
+	export interface ProbeResult {
+		/** Intervals between animation frames while drawing, ms (warm-up already dropped). */
+		intervals: number[];
+		/** CPU time of each probe frame (drawing; on Canvas 2D, rasterising too), ms. */
+		cpu: number[];
+		/**
+		 * The display's frame interval, ms, measured on idle frames before drawing (displayInterval). Without it, it is
+		 * guessed from the drawing intervals, which a slow device misreads as a slower display.
+		 */
+		refresh?: number;
+	}
+	/**
+	 * The tier for a renderer and a probe, against the display's frame (probe.refresh). "Fits": within the frame +25%.
+	 *  - GL: high when the 90th percentile fits and the drawing takes under half a frame; medium when the median fits;
+	 *    else low.
+	 *  - Canvas 2D: never high (no cheap glows). Medium only when the 90th percentile fits and drawing plus rasterising
+	 *    take under a quarter of a frame (the probe is a light scene; a game draws more); else low.
+	 */
+	export function pickTier(kind: RendererKind, probe: ProbeResult): TierName;
+	/** What the screen says about the device (init.device, DeviceHint in @fabi-play/protocol): play.device. */
+	export interface TierHint {
+		tier?: string;
+		hz?: number;
+	}
+	/** The stage's height in stage units, on every screen: its width follows the viewport (1280 at 16:9). */
+	export const STAGE_HEIGHT = 720;
+	/**
+	 * What the engine needs of the SDK: the Play object of connect() or the script tag's FabiPlay (Easy). Both have
+	 * on, toScreen, smoothedBody and avatarOf; the engine listens to both kinds of events ('frame' and 'players',
+	 * 'break-done' and 'break-end').
+	 */
+	export interface PlayLike {
+		/** Listens to the host's events; returns a function that stops listening. */
+		on(event: string, listener: (m: any) => void): () => void;
+		/** A body point on the screen, in fractions (see the SDK's toScreen). */
+		toScreen(p: Point): Point;
+		/** A player's body smoothed and interpolated as the SDK draws avatars. */
+		smoothedBody?(who: PlayerFrame | number, options?: {
+			smooth?: boolean | number;
+			interpolate?: boolean;
+		}): Body | null;
+		/** The avatar id a player picked. */
+		avatarOf?(player: number | PlayerFrame): string;
+		/** What is behind the game now: 'video' (mirror mode) or 'none'. */
+		readonly backdrop?: Backdrop;
+		/** Where the camera image is on the screen, in fractions; null if unknown. */
+		readonly view?: BackdropView | null;
+		/** The screen's sound is off. */
+		readonly muted?: boolean;
+		/** What the screen knows about the device (init.device): a starting tier and the display's rate. */
+		readonly device?: TierHint | null;
+		/** Debug: how the game draws now, for the simulator's status line (the SDK sends it only when asked). */
+		reportStats?(stats: {
+			fps?: number;
+			renderer?: string;
+			tier?: TierName;
+		}): void;
+	}
+	/**
+	 * Options of createEngine: all optional.
+	 *
+	 * @example
+	 * const engine = await createEngine({ play, background: '#132040', maxPixelRatio: 1.5 })
+	 */
+	export interface EngineOptions {
+		/** The SDK's play object (connect()) or window.FabiPlay. Without it there are no hands or avatars. */
+		play?: PlayLike | null;
+		/** The canvas to draw in; by default one is made to fill the page. */
+		canvas?: HTMLCanvasElement;
+		/** Force a renderer ('canvas2d', 'webgl1', 'webgl2'); also ?renderer= in the address. */
+		renderer?: RendererChoice;
+		/**
+		 * Force a tier; also ?tier= in the address (never lowered during play). Else the screen's hint (play.device), no
+		 * higher than this game's cached tier; else the cached probe, or a new one.
+		 */
+		tier?: TierName;
+		/** Refuse slow (software) WebGL; default true. */
+		failIfMajorPerformanceCaveat?: boolean;
+		/** Probe the device when there is no cached tier (default true; false: medium). */
+		probe?: boolean;
+		/** Device pixel ratio cap (default 2). */
+		maxPixelRatio?: number;
+		/** The stage's colour when there is no video behind it; transparent by default (the page shows through). */
+		background?: ColorLike;
+		/** Engine version of instancing etc. (tests). */
+		instancing?: boolean;
+	}
+	/** engine.stage: the root group, 720 units high, as wide as the viewport's aspect. */
+	export interface Stage extends Group {
+		/** Stage units: width follows the viewport's aspect, height is always 720. */
+		readonly width: number;
+		/** Always 720 (STAGE_HEIGHT). */
+		readonly height: number;
+		/** The 16:9 area in the middle, for what must be seen on any screen. */
+		readonly safe: {
+			x: number;
+			y: number;
+			w: number;
+			h: number;
+		};
+	}
+	/**
+	 * engine.supports: what node.filters can do on this renderer and tier.
+	 *
+	 * @example
+	 * flag.filters = engine.supports.shaders ? [wave] : [brightness(1.1)]
+	 */
+	export interface Supports {
+		/** Colour filters, blur and drop shadows draw (WebGL; Canvas 2D with ctx.filter). tint() draws everywhere. */
+		readonly filters: boolean;
+		/** blur() and soft drop shadows draw: filters, and the tier's maxBlur above 0 (not on the low tier). */
+		readonly blur: boolean;
+		/** shader() filters draw: WebGL only. */
+		readonly shaders: boolean;
+		/** The largest blur radius on the current tier, stage units (bigger ones are drawn at it; 0: off). */
+		readonly maxBlur: number;
+		/** The limits of each tier (the tier can drop during play). */
+		readonly tiers: Readonly<Record<TierName, {
+			readonly maxBlur: number;
+		}>>;
+	}
+	/** engine.stats: what the last second cost (for a debug overlay). */
+	export interface EngineStats extends FrameStats {
+		/** Frames drawn in the last second. */
+		fps: number;
+		/** CPU time of a frame (update + draw), ms, averaged over the last second. */
+		cpuMs: number;
+	}
+	/**
+	 * The engine, from createEngine: a stage to add nodes to, factories for them, the players' hands and avatars, a
+	 * loop on game time that follows the host (pause, breaks, mirror mode).
+	 *
+	 * @example
+	 * const engine = await createEngine({ play })
+	 * const star = engine.stage.add(engine.shape({ type: 'star', r: 40, fill: '#FBD46A' }, { x: 640, y: 100 }))
+	 * engine.onFrame((dt) => {
+	 *   star.y += 120 * dt
+	 *   if (engine.touched(star)) star.destroy()
+	 * })
+	 * engine.start()
+	 */
+	export interface Engine {
+		/** The root group: add nodes here. 720 units high; width follows the viewport's aspect. */
+		readonly stage: Stage;
+		/** The quality tier: read tier.name, scale counts with tier.scale(n). */
+		readonly tier: Tier;
+		/** The backend that draws (renderer.kind: 'webgl2', 'webgl1' or 'canvas2d'). */
+		readonly renderer: Renderer;
+		/** The canvas drawn in (after a switch to Canvas 2D on context loss, a fresh one in its place). */
+		readonly canvas: HTMLCanvasElement;
+		/** Backing-store pixels per stage unit. */
+		readonly pixelScale: number;
+		/** What is behind the game now: 'video' (mirror mode: the stage is transparent, avatars hidden) or 'none'. */
+		readonly backdrop: Backdrop;
+		/** Where the camera image is on the screen, in fractions; null if the host didn't say. */
+		readonly view: BackdropView | null;
+		/** Paused by the host (pause, break) or by pause(): game time, tweens, particles and sound are stopped. */
+		readonly paused: boolean;
+		/** Sounds and tones, quiet while paused or muted. */
+		readonly sound: Sound;
+		/** What the last second cost: fps, CPU time, draw calls. */
+		readonly stats: EngineStats;
+		/** Game time, seconds (stops on pause). */
+		readonly time: number;
+		/** What filters can do here (renderer and tier): pick another look where a filter is not supported. */
+		readonly supports: Supports;
+		/**
+		 * A sprite of a frame (or a loaded or baked frame's name). Add it to the stage or a group to see it.
+		 *
+		 * @example
+		 * const fox = engine.stage.add(engine.sprite('fox', { x: 640, y: 500, anchor: 0.5 }))
+		 */
+		sprite(frame: Frame | string, props?: SpriteProps): Sprite;
+		/** A shape, baked once (see ShapeSpec). */
+		shape(spec: ShapeSpec, props?: NodeProps): Shape;
+		/** A text, baked once and again when it changes. */
+		text(text: string, style?: TextStyle & NodeProps): Text;
+		/** An empty group, to move, fade or clear nodes together. */
+		group(props?: NodeProps): Group;
+		/**
+		 * A pooled particle emitter of one frame (or a shape, baked); burst() it.
+		 *
+		 * @example
+		 * const sparks = stage.add(engine.particles({ type: 'circle', r: 6, fill: '#fff' }, { max: engine.tier.scale(200), gravity: 400 }))
+		 * sparks.burst(x, y, 24)
+		 */
+		particles(frame: Frame | string | ShapeSpec, opts?: ParticleOptions & NodeProps): Particles;
+		/**
+		 * Eases numeric fields of target (a node, or any object) to `to` over `seconds`, on game time. Resolves at the
+		 * end (or when stopped, or when the node is destroyed).
+		 *
+		 * @example
+		 * await engine.tween(star, { scale: 1.6, alpha: 0 }, 0.25)
+		 * star.destroy()
+		 */
+		tween<T extends object>(target: T, to: Partial<Record<keyof T, number>>, seconds: number, ease?: Ease | EaseName | TweenOptions): TweenHandle;
+		/**
+		 * A timeline: tweens in sequence (each after the previous) or together (`at`), with labels, calls, waits, repeat
+		 * and yoyo, on game time (frozen on pause and breaks). It starts on the next frame; await it for its end.
+		 *
+		 * @example
+		 * await engine.timeline()
+		 *   .to(title, { alpha: 1, scale: 1 }, 0.4, 'backOut')
+		 *   .label('cheer')
+		 *   .to(score, { y: 300 }, 0.5, { at: 'cheer' })
+		 *   .call(() => engine.sound.play('ding'), 'cheer+=0.2')
+		 */
+		timeline(opts?: TimelineOptions): Timeline;
+		/**
+		 * An animated sprite: an animation of a loaded atlas (its `animations` or Aseprite `frameTags`, as 'atlas/name'),
+		 * every frame whose name starts with a prefix ('atlas/run_'), or a list of frames. Plays on game time.
+		 *
+		 * @example
+		 * const hero = engine.stage.add(engine.animation('hero/run', { fps: 12, x: 200, y: 500, anchor: 0.5 }))
+		 */
+		animation(frames: string | readonly (Frame | string)[], props?: AnimationProps): AnimatedSprite;
+		/**
+		 * A bitmap font for engine.text({ bitmapFont: name }): made now from a web font (each glyph baked into the atlas
+		 * on first use, with engine.text's look), or from a BMFont's data and page images. With only a name: the font
+		 * loaded or made before.
+		 *
+		 * @example
+		 * engine.bitmapFont('score', { size: 48, color: '#FBEFE3', outline: true, chars: '0123456789' })
+		 * const label = stage.add(engine.text('0', { bitmapFont: 'score', x: 40, y: 40, align: 'left' }))
+		 * engine.onFrame(() => (label.text = String(points)))  // nothing baked per value
+		 */
+		bitmapFont(name: string, source?: BitmapFontOptions | {
+			data: string | object;
+			pages: readonly (HTMLImageElement | HTMLCanvasElement | ImageBitmap)[];
+		}): BitmapFont;
+		/** A frame drawn by you with Canvas 2D (stage units; the context is scaled), baked once, by name. */
+		bake(name: string, width: number, height: number, draw: (ctx: CanvasRenderingContext2D) => void, origin?: {
+			x: number;
+			y: number;
+		}): Frame;
+		/** A loaded or baked frame by name. */
+		frame(name: string): Frame;
+		/**
+		 * Loads images, atlases (.json + image: TexturePacker or Aseprite, with trimming, scale9Borders and animations),
+		 * bitmap fonts (.fnt, or a BMFont .json, + page images), sounds and fonts, by name.
+		 */
+		load(assets: Record<string, string>): Promise<void>;
+		/** This frame's hands (of one player, or everyone's), stage units: in the avatar's hands, or on the real ones. */
+		hands(player?: number): Hand[];
+		/** The first hand (of one player, or anyone's) touching the node, or null. padding: stage units. */
+		touched(node: Node, player?: number, opts?: {
+			padding?: number;
+		}): Hand | null;
+		/** Whether a point (stage units) is on the node. */
+		hits(node: Node, x: number, y: number, padding?: number): boolean;
+		/**
+		 * A node drawing every player's avatar where they stand (nothing over the video). tags: a name tag above each head,
+		 * in the player's colour: a function giving each player's tag (null: none), or true for the player numbers.
+		 *
+		 * @example
+		 * stage.add(engine.avatars({ tags: (player) => teamNames[player] ?? null }))
+		 */
+		avatars(opts?: AvatarsOptions): AvatarsNode;
+		/**
+		 * A node drawing a ring on every hand, in the players' colours. Over the video (look 'auto', the default) the ring
+		 * gets the video look: a dark outline and halo under it, so it reads over a bright room.
+		 */
+		handMarkers(opts?: HandMarkersOptions): Node;
+		/** The live player frames (newest from the host; empty if none for a second). */
+		players(): readonly PlayerFrame[];
+		/** Every animation frame while not paused: dt seconds (at most 0.1), game time. Returns a function that stops it. */
+		onFrame(fn: (dt: number, time: number) => void): () => void;
+		/** Every animation frame, paused or not, before drawing. */
+		onRender(fn: (dt: number) => void): () => void;
+		/** Called when the backdrop or the view changes (not at start: read engine.backdrop). Returns a function that stops it. */
+		onBackdrop(fn: (backdrop: Backdrop, view: BackdropView | null) => void): () => void;
+		/** An HTML layer over the canvas for a HUD or menus (made on first use). Its --unit is one stage unit in CSS px. */
+		readonly hud: HTMLElement;
+		/** A random number between min (0) and max (1). */
+		random(min?: number, max?: number): number;
+		/** Starts the loop: call it once the scene is set up. */
+		start(): void;
+		/** Pauses the game (its own pause menu): game time, tweens, particles and sound stop. The host's pauses are followed by themselves. */
+		pause(): void;
+		/** Resumes after pause() (the host's pauses still hold). */
+		resume(): void;
+		/** Stops the loop and frees the renderer, sounds and listeners. */
+		destroy(): void;
+	}
+	/** Options of engine.avatars. */
+	export interface AvatarsOptions {
+		/** 0–1 for every avatar (below 1 each is composited as one layer). */
+		alpha?: number;
+		/** Name tags: a player's tag (null or '' for none), or true for the player numbers. Default none. */
+		tags?: boolean | ((player: number) => string | null | undefined);
+		/** The tags' height, stage units (default 34). */
+		tagHeight?: number;
+		/** The tags' CSS font family (default Nunito). */
+		tagFont?: string;
+	}
+	/** Options of engine.handMarkers. */
+	export interface HandMarkersOptions {
+		/** The ring's radius, stage units (default 36). */
+		radius?: number;
+		/** 'auto' (default): the video look over the video, the plain one over the sky; or always one of them. */
+		look?: "auto" | "sky" | "video";
+	}
+	/** The avatars of every player, drawn with the engine's renderer. Its own transform is ignored: they stand where the children stand. */
+	export class AvatarsNode extends Node {
+		private readonly paintAll;
+		/** Use engine.avatars(). */
+		constructor(kernel: Kernel, paintAll: (ctx: DrawContext, alpha: number) => void);
+		/** Draws the avatars (the engine calls it). */
+		draw(ctx: DrawContext, alpha: number): void;
+	}
+	/**
+	 * Makes the engine: picks the renderer (WebGL2, WebGL1, Canvas 2D) and the quality tier (a short probe, cached per
+	 * device), makes the stage, and follows the host through play (pause, breaks, backdrop, hands, avatars). Resolves
+	 * in under a second; then set up the scene and call start().
+	 *
+	 * @example
+	 * import { connect } from '@fabi-play/sdk'
+	 * import { createEngine } from '@fabi-play/engine'
+	 *
+	 * const play = await connect()
+	 * const engine = await createEngine({ play })
+	 * engine.stage.add(engine.avatars())
+	 * engine.start()
+	 * play.ready()
+	 */
+	export function createEngine(opts?: EngineOptions): Promise<Engine>;
+	/**
+	 * 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 AvatarPaint {
+		/** 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 AvatarShape = (AvatarPaint & {
+		k: "circle";
+		x: number;
+		y: number;
+		r: number;
+	}) | (AvatarPaint & {
+		k: "ellipse";
+		x: number;
+		y: number;
+		rx: number;
+		ry: number;
+		rot?: number;
+	})
+	/** A rounded rectangle by its centre, rotated by rot radians around it. */
+	 | (AvatarPaint & {
+		k: "rect";
+		x: number;
+		y: number;
+		w: number;
+		h: number;
+		r: number;
+		rot?: number;
+	}) | (AvatarPaint & {
+		k: "path";
+		d: string | PathData;
+	})
+	/** A polyline [x0, y0, x1, y1, …], stroked with round caps and joins. */
+	 | (AvatarPaint & {
+		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: AvatarShape[];
+	};
+	/**
+	 * 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[];
+	/** 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 AvatarBox {
+		/** Left edge, canvas units. */
+		x: number;
+		/** Top edge, canvas units. */
+		y: number;
+		/** Width, canvas units. */
+		w: number;
+		/** Height, canvas units. */
+		h: number;
+	}
+	/** Bounds of a shape list, in its units (outlines included): for the bake canvas. */
+	export function shapeBounds(shapes: readonly AvatarShape[], m?: Mat | null): {
+		minX: number;
+		minY: number;
+		maxX: number;
+		maxY: number;
+	};
+	/** What an AvatarPainter drew: for comparisons and logs. */
+	export interface PaintStats {
+		/** Groups drawn as baked sprites. */
+		baked: number;
+		/** Groups drawn as vectors. */
+		vector: number;
+	}
+	/**
+	 * Turns avatar shape lists into renderer calls, baking rigid groups (heads) into an atlas. Nothing is allocated per
+	 * frame once the heads are baked: a matrix stack by group depth, scratch point buffers, colours parsed once.
+	 */
+	export class AvatarPainter {
+		private readonly atlas;
+		private readonly seen;
+		private readonly baked;
+		private readonly m;
+		/** Group transforms by depth, and one for a rounded rectangle's own. */
+		private readonly stack;
+		private readonly local;
+		private pts;
+		/** Counts since it was made. */
+		readonly stats: PaintStats;
+		/** Bake heads (true) or draw everything as vectors (comparisons). */
+		bakeGroups: boolean;
+		/** Coarse head bakes (the low tier): see bakeBucket. */
+		private coarse;
+		private gen;
+		/** The bakes of this generation, to free them when the tier changes. */
+		private readonly live;
+		/** A painter baking into atlas. */
+		constructor(atlas: Atlas);
+		/**
+		 * Follows the quality tier: on 'low' the heads are baked coarser (steps of 2, at most 256 pixels per unit), on the
+		 * others finer. A change frees the heads baked so far; they bake again, at the new sizes, on their next draw.
+		 */
+		setTier(tier: "high" | "medium" | "low"): void;
+		/**
+		 * Draws one avatar posed like body in box (stage units). pixelScale: backing pixels per unit (bake sizes, curve
+		 * flattening). Returns whether it drew (false: shoulders not seen). Below alpha 1 the avatar is drawn into an
+		 * offscreen layer and composited at that alpha, so it is faint as a whole: its outlines and overlapping parts
+		 * don't show through each other.
+		 */
+		draw(r: Renderer, tex: (s: Surface) => Texture, body: Body, avatar: AvatarDef | string, box: AvatarBox, alpha: number, pixelScale: number): boolean;
+		/** Paints a shape list under the transform m (a similarity: translate, rotate, uniform scale) with an alpha. */
+		paint(r: Renderer, tex: (s: Surface) => Texture, shapes: readonly AvatarShape[], m: Mat | null, alpha: number, pixelScale: number, depth?: number): void;
+		/** A shape list baked at k pixels per unit (bucketed), or null if it would be too big. */
+		private bake;
+	}
+	/** One player for AvatarRenderer.draw: a body, an avatar, an optional name tag. */
+	export interface AvatarPlayer {
+		/** The body, in player space (PlayerFrame.body). */
+		body: Body;
+		/** An avatar id (fox, lion, robot, …; unknown ids: the default avatar). */
+		avatar?: string;
+		/** Who it is, for smoothing and interpolation (by default the place in the array, from 1). */
+		id?: number;
+		/**
+		 * Who it is, when the caller has a stable identity that is not a small number (a tracker's person id, a name):
+		 * smoothing and interpolation follow it, whatever the place in the array. Takes precedence over id.
+		 */
+		key?: string | number;
+		/** A name tag above the head, in a pill of this colour (the player's colour). */
+		name?: string;
+		/** The tag's colour (CSS; the player's colour). */
+		color?: string;
+		/**
+		 * 0–1 for the whole avatar and its tag (extra people are drawn faint). Below 1 the avatar is composited as one
+		 * layer: faint, without its outlines and overlapping parts showing through each other.
+		 */
+		alpha?: number;
+	}
+	/** Options of createAvatarRenderer. */
+	export interface AvatarRendererOptions extends DetectOptions {
+		/**
+		 * The drawing units: a fixed size (as a 2D canvas's width and height, e.g. the TV's 1280 × 720 stage), stretched
+		 * by CSS; the backing store is that times pixelRatio (1 by default). Without it: CSS pixels, times
+		 * devicePixelRatio (at most 2).
+		 */
+		units?: {
+			width: number;
+			height: number;
+		};
+		/** Backing-store pixels per drawing unit (default: 1 with units, else devicePixelRatio, at most 2). */
+		pixelRatio?: number;
+		/** As the SDK's drawAvatar: smoothing per player (0.5), or false (bodies already smoothed by the caller). */
+		smooth?: boolean | number;
+		/** Bodies interpolated at the display's rate (true, default), or drawn as given. */
+		interpolate?: boolean;
+		/** Name tags: their height in drawing units (34 on the 1280 × 720 stage) and font family. */
+		tagHeight?: number;
+		/** The tags' CSS font family (default Nunito). */
+		tagFont?: string;
+	}
+	/** createAvatarRenderer's result: avatars drawn on a canvas of their own. */
+	export interface AvatarRenderer {
+		/** The renderer in use: a GL one is replaced by Canvas 2D (on a fresh canvas) after 3 s of context loss. */
+		readonly renderer: Renderer;
+		/** Its kind: 'webgl2', 'webgl1' or 'canvas2d'. */
+		readonly kind: RendererKind;
+		/** The GL context is lost right now (nothing is drawn until it comes back, or Canvas 2D takes over). */
+		readonly lost: boolean;
+		/** The canvas drawn in: after a switch to Canvas 2D a fresh one, in the old one's place in the page. */
+		readonly canvas: HTMLCanvasElement;
+		/**
+		 * Clears the canvas and draws each player's avatar, posed like their body (smoothed and interpolated per player
+		 * unless the options say not), with its name tag. box: where player space (0–1) lands, in drawing units. Call it
+		 * every animation frame.
+		 */
+		draw(players: readonly AvatarPlayer[], box: AvatarBox): void;
+		/** An empty canvas (nothing to draw this frame). */
+		clear(): void;
+		/** Forget the players' previous bodies (a new scene). */
+		reset(): void;
+		/** Frees the renderer and its textures. */
+		destroy(): void;
+	}
+	/**
+	 * The avatars on a canvas of their own, with the engine's renderer (WebGL2, WebGL1 or Canvas 2D, chosen as the
+	 * engine chooses), its own atlas and the SDK's smoothing and interpolation. For pages that are not engine games:
+	 * the TV's calibration, the simulator's preview. Throws only if the page has neither WebGL nor Canvas 2D.
+	 */
+	export function createAvatarRenderer(canvas: HTMLCanvasElement, opts?: AvatarRendererOptions): AvatarRenderer;
+	/**
+	 * An avatar's portrait (head and shoulders, neutral pose) as a canvas of size × size CSS pixels at pixelRatio,
+	 * drawn once from the same shapes as the avatars and cached: for DOM places such as the TV's gesture rings.
+	 */
+	export function avatarPortrait(avatar: string, size: number, pixelRatio?: number): HTMLCanvasElement;
+	/** A colour filter with one parameter, `amount`. */
+	export interface AmountFilter extends Filter {
+		/** Its strength (see the factory). Tween it freely. */
+		amount: number;
+	}
+	/** hueRotate's filter: `angle` in degrees (`amount` is the same number). */
+	export interface HueRotateFilter extends AmountFilter {
+		/** Degrees. */
+		angle: number;
+	}
+	/** tint's filter: the colour and how far towards it (0 none, 1 all of it). */
+	export interface TintFilter extends AmountFilter {
+		/** The colour mixed in, as 0xRRGGBB or CSS (reads as 0xRRGGBB). */
+		get color(): number;
+		set color(v: ColorLike);
+	}
+	/** colorMatrix's filter: 20 numbers, row-major (R, G, B, A rows; r, g, b, a, offset columns; offsets 0–1). */
+	export interface ColorMatrixFilter extends Filter {
+		/** The matrix: change its numbers in place, or set a new one. */
+		values: number[] | Float32Array;
+	}
+	/** blur's filter: `radius`, stage units. */
+	export interface BlurFilter extends Filter {
+		/** The Gaussian's standard deviation, stage units (as CSS blur()); it reaches about three times as far. */
+		radius: number;
+	}
+	/** dropShadow's filter: offset, blur and colour, all changeable. */
+	export interface DropShadowFilter extends Filter {
+		/** Offset right, stage units. */
+		dx: number;
+		/** Offset down, stage units. */
+		dy: number;
+		/** The shadow's blur, σ in stage units (as blur()). */
+		blur: number;
+		/** 0xRRGGBB, or CSS with alpha ('rgba(0,0,0,0.5)'); reads as 0xRRGGBB. */
+		get color(): number;
+		set color(v: ColorLike);
+		/** The colour's alpha, 0–1. */
+		opacity: number;
+	}
+	/** shader()'s options. */
+	export interface ShaderOptions {
+		/**
+		 * A GLSL ES 1.00 fragment shader: declare your own uniforms and write main(). The engine declares, before it:
+		 *
+		 *   uniform sampler2D uTexture;  // the node drawn so far (premultiplied alpha)
+		 *   varying vec2 vUv;            // where this pixel is in uTexture, 0–1, (0, 0) bottom-left
+		 *   uniform vec2 uResolution;    // uTexture's size, pixels
+		 *   uniform float uTime;         // engine.time, seconds (stops on pause)
+		 *   uniform vec4 uRect;          // the node's area in uTexture (x0, y0, x1, y1), 0–1
+		 *
+		 * Write a premultiplied colour to gl_FragColor; the engine applies the node's alpha after it.
+		 */
+		fragment: string;
+		/** Your uniforms (float, vec2–vec4) by name: numbers or arrays of 2–4. Change them in place any time. */
+		uniforms?: Record<string, number | number[]>;
+		/** How far the effect reaches past the node's pixels, stage units (a ripple that moves pixels out). Default 0. */
+		padding?: number;
+	}
+	/** shader()'s filter. */
+	export interface ShaderFilter extends Filter {
+		/** The uniforms: set numbers (`f.uniforms.uAmount = 0.5`) or change arrays in place (`f.uniforms.uCenter[0] = x`). */
+		readonly uniforms: Record<string, number | Float32Array>;
+		/** Stage units the effect reaches past the node's pixels. */
+		padding: number;
+	}
+	/**
+	 * Mixes the node's colours towards `color` by `amount` (0 none, 1 a flat silhouette of that colour): a hit flash,
+	 * a frozen look. Unlike node.tint (a multiply), it can make dark pixels light.
+	 *
+	 * @example
+	 * const flash = tint('#ffffff', 0); enemy.filters = [flash]
+	 * engine.tween(flash, { amount: 1 }, 0.06).then(() => engine.tween(flash, { amount: 0 }, 0.2))
+	 */
+	export const tint: (color: ColorLike, amount?: number) => TintFilter;
+	/** Brightness: 1 unchanged, 0 black, above 1 brighter (CSS brightness()). */
+	export const brightness: (v: number) => AmountFilter;
+	/** Contrast: 1 unchanged, 0 flat grey, above 1 more (CSS contrast()). */
+	export const contrast: (v: number) => AmountFilter;
+	/** Saturation: 1 unchanged, 0 grey, above 1 more vivid (CSS saturate()). */
+	export const saturate: (v: number) => AmountFilter;
+	/** Grey: amount 0–1 (CSS grayscale()). */
+	export const grayscale: (amount?: number) => AmountFilter;
+	/** Old-photo brown: amount 0–1 (CSS sepia()). */
+	export const sepia: (amount?: number) => AmountFilter;
+	/** Turns hues around the colour wheel by `deg` degrees (CSS hue-rotate()). */
+	export const hueRotate: (deg: number) => HueRotateFilter;
+	/** Negative: amount 0–1 (CSS invert()). */
+	export const invert: (amount?: number) => AmountFilter;
+	/**
+	 * Any colour matrix: 20 numbers, 4 rows (R, G, B, A) of 5 (times r, g, b, a, plus an offset 0–1), on unpremultiplied
+	 * colours (SVG feColorMatrix). On Canvas 2D it needs ctx.filter with url() (Chrome, Firefox); elsewhere it is skipped.
+	 */
+	export const colorMatrix: (m: ArrayLike<number>) => ColorMatrixFilter;
+	/**
+	 * A Gaussian blur of `radius` stage units (the standard deviation, as CSS blur()). Capped per tier
+	 * (engine.supports.maxBlur): off on the low tier. Each blurred node costs two to six passes over its area.
+	 */
+	export const blur: (radius: number) => BlurFilter;
+	/**
+	 * A shadow of the node's shape: offset (dx, dy), blurred by `blur` (σ, stage units; capped like blur(), hard on the
+	 * low tier), in `color` (with its alpha: 'rgba(0,0,0,0.4)').
+	 */
+	export const dropShadow: (dx: number, dy: number, blur: number, color?: ColorLike) => DropShadowFilter;
+	/**
+	 * A custom fragment shader as a filter: **WebGL only**. On Canvas 2D it is skipped (the node is drawn without it,
+	 * engine.stats.filtersSkipped counts it, the console says so once): check engine.supports.shaders and pick another
+	 * look there. Compiled once per distinct source. With a WebGL engine running, a shader that does not compile throws
+	 * here with the compiler's log; otherwise the error is logged once at its first use and the filter skipped.
+	 *
+	 * @example
+	 * const wave = shader({
+	 *   fragment: `uniform float uAmp;
+	 *     void main() { gl_FragColor = texture2D(uTexture, vUv + vec2(sin(vUv.y * 40.0 + uTime * 4.0) * uAmp, 0.0)); }`,
+	 *   uniforms: { uAmp: 0.004 },
+	 *   padding: 8,
+	 * })
+	 * flag.filters = [wave]
+	 */
+	export function shader(o: ShaderOptions): ShaderFilter;
+	/** nodePool's options. */
+	export interface NodePoolOptions<T extends Node> {
+		/** Most free nodes kept; released ones past it are destroyed. Default: no limit. */
+		max?: number;
+		/** Called on a node as it is released, after the engine reset it: reset what the engine does not (data, children). */
+		reset?: (node: T) => void;
+	}
+	/** What a pool counts. */
+	export interface NodePoolStats {
+		/** Nodes given out by get and not released (nor destroyed). */
+		live: number;
+		/** Released nodes waiting for get. */
+		free: number;
+		/** Nodes the factory made, in all. */
+		created: number;
+	}
+	/**
+	 * Nodes made by a factory once and used again: get() gives a free one (or makes one), release() takes it back. From
+	 * nodePool(factory, options).
+	 *
+	 * @example
+	 * const labels = nodePool(() => engine.text('', { size: 32, outline: true }), { max: 20 })
+	 * const l = hud.add(labels.get({ x, y, text: '+10' }))
+	 * engine.tween(l, { y: y - 60, alpha: 0 }, 0.8).then(() => labels.release(l))
+	 */
+	export class NodePool<T extends Node> {
+		private readonly factory;
+		private readonly opts;
+		/** live, free and created: kept up to date (one object, read it any time). */
+		readonly stats: NodePoolStats;
+		private readonly free;
+		/** Every node it made and still has (live or free), with its state as made. */
+		private readonly states;
+		private dead;
+		/** Use nodePool(factory, options). */
+		constructor(factory: () => T, opts?: NodePoolOptions<T>);
+		/**
+		 * A node: a free one, back to how the factory made it, or a new one; then props are applied (any node field, and a
+		 * text's `text`). It is not added anywhere: add it to a group.
+		 *
+		 * What is reset: position, rotation, scale, alpha, visible, blend, tint, z, anchor, hitRadius, clip, mask, filters
+		 * (the same objects the factory set, not copies); a sprite's frame, size and slice; a shape's spec; a text's string
+		 * and style; an animation's fps, loop, speed, onComplete and playing, rewound to its first frame. Not reset: `data`,
+		 * a group's children, and nodes' own fields in your subclasses: reset those in options.reset.
+		 */
+		get(props?: NodeProps & {
+			text?: string;
+		}): T;
+		/**
+		 * Takes a node back: out of its group, hidden, its tweens stopped (they resolve), its animation stopped, reset; not
+		 * destroyed. Keep no reference to it: the next get() gives it to someone else. Past `max` free nodes, it is
+		 * destroyed instead. Releasing a node twice, or one of another pool, does nothing (and says so once).
+		 */
+		release(node: T): void;
+		/** @internal A node of this pool was destroyed: it leaves the pool. */
+		forget(node: Node): void;
+		/** Destroys the free nodes (the ones in use stay). */
+		clear(): void;
+		/** Destroys every node it made, in use or free; get() can't be called after. */
+		destroy(): void;
+	}
+	/**
+	 * A pool of nodes made by factory and used again: get() a node (a free one, reset to how the factory made it, or a new
+	 * one), release() it instead of destroying it. Worth it only when spawning many nodes a second; creating and
+	 * destroying nodes is fine otherwise.
+	 *
+	 * @example
+	 * import { nodePool } from '@fabi-play/engine'
+	 * const coins = nodePool(() => engine.shape({ type: 'circle', r: 16, fill: '#FBD46A' }), { max: 40 })
+	 * const coin = layer.add(coins.get({ x: 200, y: -20 }))
+	 * engine.tween(coin, { y: 740 }, 2, 'linear').then(() => coins.release(coin))
+	 */
+	export const nodePool: <T extends Node>(factory: () => T, options?: NodePoolOptions<T>) => NodePool<T>;
+	/** How tags look: their height in drawing units (34 on the 1280 × 720 stage) and font family. */
+	export interface TagOptions {
+		/** The tag's height, drawing units (default 34). */
+		tagHeight?: number;
+		/** The tags' CSS font family (default Nunito). */
+		tagFont?: string;
+	}
+	/** Name tags baked into an atlas, and drawn above heads. */
+	export class NameTags {
+		private readonly atlas;
+		/** Baked tags by name, colour and resolution (nested maps: no key string built per lookup). */
+		private readonly tags;
+		private count;
+		private readonly m;
+		private measure;
+		/** The tag's height, drawing units. */
+		readonly height: number;
+		private readonly font;
+		/** Tags baked into atlas. */
+		constructor(atlas: Atlas, o?: TagOptions);
+		/** Forgets every tag (bake them again: the web font arrived). */
+		drop(): void;
+		/** The name in a pill of the colour, baked once per name, colour and resolution (ratio: pixels per unit). */
+		get(name: string, color: string, ratio: number): Frame;
+		/** get's slow path, apart (its closure's context would be made on every get otherwise). */
+		private bake;
+		/**
+		 * Draws a player's tag above the head of body as drawn in box (def's band proportions), inside a width × height
+		 * area (drawing units). ratio: pixels per unit.
+		 */
+		draw(r: Renderer, tex: (s: Surface) => Texture, body: Body, def: AvatarDef, box: AvatarBox, name: string, color: string, alpha: number, ratio: number, width: number, height: number): void;
+	}
+}
+
+interface Window {
+	/** The Fabi Play engine, set by fabi-play-engine.js (see the global FabiEngine). */
+	readonly FabiEngine: typeof FabiEngine
+}