@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/libras-avatar-plan.d.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Where the delivery puts the free player's avatar, clips, manifest and glosses, beside the game's page (`inclusionist-heavy --libras`):
+ * written in the catalogue, whose delivery list keeps these files offline (ADR-0234, phase B3), and re-exported here where the
+ * player and the delivery script already read it.
+ */
+export { LIBRAS_AVATAR_FOLDER } from '../platform/heavy-catalogue.js';
+/** The manifest the delivery writes in that folder: the avatar's file and every clip it carries, with its window. */
+export declare const LIBRAS_AVATAR_MANIFEST = "manifest.json";
+/**
+ * How long two clips overlap, fading one into the other, in seconds. Every clip is at least 1.2 s (📏 the 655 of the delivery:
+ * 1.2–7.1 s, median 2.47 s), and the overlap never exceeds half of either clip, so no clip is swallowed by its neighbours.
+ */
+export declare const CROSS_FADE_S = 0.3;
+/** One clip the delivery carries: its file under the folder, and the stretch of it that is played. */
+export interface ClipWindow {
+    readonly file: string;
+    /** The clip's length in seconds, as exported. */
+    readonly duration: number;
+    /**
+     * Where the sign starts, in seconds — 0 for every clip but one: the export of FALA begins at a stray keyframe 1404 frames
+     * before the sign (46.8 s at 30 fps), which the delivery's pins name, so the player plays from the sign and not from the stray.
+     */
+    readonly from: number;
+    /**
+     * Where the hand is held up, `[up, down]` in seconds of the played window — only for the clips a word is spelled with (a letter
+     * or a digit): a chained letter starts at `up` and hands over at `down`. E's is its whole clip. Absent, the clip plays whole.
+     */
+    readonly held?: readonly [number, number];
+}
+/** The delivery's manifest, read: the avatar's file and the clips by name. */
+export interface AvatarManifest {
+    readonly avatar: string;
+    readonly clips: ReadonlyMap<string, ClipWindow>;
+}
+/**
+ * The manifest the delivery wrote, or `null` for anything else — no file, a fallback page, another format: a delivery that did
+ * not ship the avatar. A clip entry of the wrong shape is left out, not trusted; a `held` of the wrong shape is dropped.
+ */
+export declare function avatarManifestOf(data: unknown): AvatarManifest | null;
+/** How long a clip plays: its window, from `from` to its end. */
+export declare const playedLength: (w: ClipWindow) => number;
+/**
+ * One clip to play: a sign, or a letter of a word being fingerspelled (`spells`, the word; `word`, its place in the gloss — two
+ * letters are of one word, and chained, only when both are the same).
+ */
+export interface SignStep {
+    readonly clip: string;
+    readonly spells?: string;
+    readonly word?: number;
+}
+/** A word the avatar could not sign: no clip of its own, and letters it has no clip for. */
+export interface UnsignedWord {
+    readonly word: string;
+    readonly missing: readonly string[];
+}
+export interface SignPlan {
+    readonly steps: readonly SignStep[];
+    readonly unsigned: readonly UnsignedWord[];
+}
+/**
+ * The clips a gloss is signed with, in order: a token with a clip is its clip; any other is fingerspelled from the letter and
+ * digit clips, as written (capitals, accents stripped, Ç kept); a word with a letter the avatar lacks is left out whole and
+ * listed.
+ */
+export declare function planSigns(gloss: string, carried: (name: string) => boolean): SignPlan;
+/**
+ * What the avatar left out of a text, said for `problems` (the `unsigned` of a `SignResult`): the words, and the letters it
+ * lacks clips for. `undefined` when it left nothing out.
+ */
+export declare function unsignedText(unsigned: readonly UnsignedWord[]): string | undefined;
+/**
+ * Everything a request left out: the words it could neither sign nor spell, and the clips the delivery could not give (`unread`).
+ * `undefined` when it left nothing out.
+ */
+export declare function leftOutText(unsigned: readonly UnsignedWord[], unread: readonly string[]): string | undefined;
+/** Why a request with nothing left to sign was not signed. */
+export declare const nothingSigned: (leftOut: string | undefined) => string;
+/** A clip to put on the stage now: fading in over `fade` seconds from what is there, starting `at` seconds into its window. */
+export interface StartClip {
+    readonly clip: string;
+    readonly fade: number;
+    readonly at: number;
+}
+export interface SignSequencer {
+    /** Replaces whatever was being signed with `steps`; returns the clip to start now (none for no steps). */
+    readonly play: (steps: readonly SignStep[]) => StartClip[];
+    /** Moves the clock `dt` seconds: the clips to start, and whether the last one just reached its end («stopped»). */
+    readonly tick: (dt: number) => {
+        readonly starts: StartClip[];
+        readonly finished: boolean;
+    };
+    /** Drops the queue: nothing more starts, and nothing finishes. */
+    readonly stop: () => void;
+}
+/**
+ * The queue's clock. `lengthOf` is a clip's played length (`playedLength`), `heldOf` where a letter's hand is held up
+ * (`playedSpans`: a spelled word's letters are chained through it; none, and every clip plays whole). Two neighbours overlap by
+ * `fade`, never by more than half of the stretch either plays; the first clip of a queue fades in only when a pose is already on
+ * the stage (a queue that replaced another, or the one held since the last), and appears at once otherwise.
+ */
+export declare function createSignSequencer(lengthOf: (clip: string) => number, fade?: number, heldOf?: (clip: string) => readonly [number, number] | undefined): SignSequencer;

package/dist-pkg/ui/libras-avatar-plan.js

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-avatar-plan — WHAT THE FREE PLAYER SIGNS, IN WHICH ORDER, AND WHEN EACH CLIP STARTS (ADR-0234, route B, phase B2).
+//
+// Route B signs with LAViD-UFPB's own sign sources, exported once to ONE avatar and ONE three.js clip per sign
+// (`scripts/libras-export.mjs`, phase B1). This module is the player's pure half — no three.js, no DOM — so the queue, the
+// timing and the fingerspelling are held in node (`tests/libras-avatar-plan.node.test.js`); `ui/libras-avatar-stage` plays what
+// it decides and `ui/libras-avatar-player` puts it behind the `Interpreter` port.
+//
+// THE GLOSS IS THE DELIVERY'S: its build-time glosses (`ui/libras-glosses`), where a word with no clip is already written as
+// the child reads it on the screen. A token the delivery carries a clip for is signed; any other is FINGERSPELLED letter by
+// letter from the clips named by a single letter or digit — the word as written, capitals, accents stripped but Ç kept, a letter
+// of the manual alphabet with a clip of its own (`provisionalGloss`, the build's own spelling rule).
+// 📌 A word whose letters the avatar does not all carry is LEFT OUT WHOLE, and said: spelling only the letters it has would
+// show the child another word («ENTROU» with only its O is «O»).
+//
+// THE TIMING: each clip plays its window once, and the next one starts `CROSS_FADE_S` before it ends, fading in while the other
+// fades out — almost every exported clip starts and ends in the same pose (arms down), so the overlap joins them without passing
+// through the avatar's rest. 📏 13 of the 655 do not: the letter E holds its raised handshape from its first frame to its last,
+// NÃO_OUVIR keeps the right arm at the avatar's rest, and eleven (CASA and SIM among them) rest their hands lower. The last one
+// plays to its end and its final pose is held: that moment is the player's «stopped».
+//
+// 📌 A SPELLED WORD IS SIGNED WITH THE HAND HELD UP BETWEEN ITS LETTERS (the Dev, interface log 2026-09-26). Each letter's and
+// digit's clip rises from the arms-down pose, holds its handshape and falls back; the delivery's manifest says where it is held
+// (`ClipWindow.held`, measured on the clip: `scripts/libras-export.mjs` `heldWindow`). Inside one spelled word, a letter after the
+// first starts where its hand is up, and a letter before the last hands over where its hand starts down — the cross-fade joins
+// two held handshapes — so the hand rises at the first letter and comes down only after the last. E, still from its first frame
+// to its last, is held for its whole clip and the chain passes through it. A sign keeps its whole clip, a word of one letter is
+// unchanged, and a letter the manifest gives no window plays whole. 📏 On a served delivery «PÕE» went from 4.37 s to 2.86 s and
+// «TRIÂNGULO» from 12.60 s to 5.35 s.
+import { provisionalGloss } from './libras-glosses.js';
+/**
+ * Where the delivery puts the free player's avatar, clips, manifest and glosses, beside the game's page (`inclusionist-heavy --libras`):
+ * written in the catalogue, whose delivery list keeps these files offline (ADR-0234, phase B3), and re-exported here where the
+ * player and the delivery script already read it.
+ */
+export { LIBRAS_AVATAR_FOLDER } from '../platform/heavy-catalogue.js';
+/** The manifest the delivery writes in that folder: the avatar's file and every clip it carries, with its window. */
+export const LIBRAS_AVATAR_MANIFEST = 'manifest.json';
+/**
+ * How long two clips overlap, fading one into the other, in seconds. Every clip is at least 1.2 s (📏 the 655 of the delivery:
+ * 1.2–7.1 s, median 2.47 s), and the overlap never exceeds half of either clip, so no clip is swallowed by its neighbours.
+ */
+export const CROSS_FADE_S = 0.3;
+const isWindow = (w) => {
+    const c = w;
+    return !!c && typeof c.file === 'string' && typeof c.duration === 'number' && c.duration > 0
+        && (c.from === undefined || (typeof c.from === 'number' && c.from >= 0 && c.from < c.duration));
+};
+/** A `held` inside the played window, up before down; anything else is no window, and the clip plays whole. */
+const heldIn = (held, length) => {
+    if (!Array.isArray(held) || held.length !== 2)
+        return undefined;
+    const [up, down] = held;
+    return typeof up === 'number' && typeof down === 'number' && up >= 0 && down > up && down <= length ? [up, down] : undefined;
+};
+/**
+ * The manifest the delivery wrote, or `null` for anything else — no file, a fallback page, another format: a delivery that did
+ * not ship the avatar. A clip entry of the wrong shape is left out, not trusted; a `held` of the wrong shape is dropped.
+ */
+export function avatarManifestOf(data) {
+    const m = data;
+    if (!m || m.format !== 1 || typeof m.avatar !== 'string' || !m.avatar || typeof m.clips !== 'object' || m.clips === null)
+        return null;
+    const clips = new Map();
+    for (const [name, w] of Object.entries(m.clips)) {
+        if (isWindow(w))
+            clips.set(name, windowRead(w));
+    }
+    return { avatar: m.avatar, clips };
+}
+/** A clip entry of the right shape, as the player keeps it: `from` defaulted, `held` only when it is inside the window. */
+function windowRead(w) {
+    const from = w.from ?? 0;
+    const held = heldIn(w.held, w.duration - from);
+    return { file: w.file, duration: w.duration, from, ...(held ? { held } : {}) };
+}
+/** How long a clip plays: its window, from `from` to its end. */
+export const playedLength = (w) => w.duration - w.from;
+/** A gloss token that is not a sign: punctuation (`[PONTO]`) or a template hole the lookup left (`{n}`). */
+const NOT_A_SIGN = /^\[.*\]$|^\{.*\}$/u;
+/**
+ * The clips a gloss is signed with, in order: a token with a clip is its clip; any other is fingerspelled from the letter and
+ * digit clips, as written (capitals, accents stripped, Ç kept); a word with a letter the avatar lacks is left out whole and
+ * listed.
+ */
+export function planSigns(gloss, carried) {
+    const steps = [];
+    const unsigned = [];
+    gloss.split(/\s+/u).forEach((token, word) => {
+        if (!token || NOT_A_SIGN.test(token))
+            return;
+        if (carried(token)) {
+            steps.push({ clip: token });
+            return;
+        }
+        const letters = [...provisionalGloss(token).replace(/\s+/gu, '')];
+        if (!letters.length)
+            return;
+        const missing = [...new Set(letters.filter((c) => !carried(c)))];
+        if (missing.length) {
+            unsigned.push({ word: token, missing });
+            return;
+        }
+        for (const c of letters)
+            steps.push({ clip: c, spells: token, word });
+    });
+    return { steps, unsigned };
+}
+/**
+ * What the avatar left out of a text, said for `problems` (the `unsigned` of a `SignResult`): the words, and the letters it
+ * lacks clips for. `undefined` when it left nothing out.
+ */
+export function unsignedText(unsigned) {
+    if (!unsigned.length)
+        return undefined;
+    const words = [...new Set(unsigned.map((u) => `«${u.word}»`))];
+    const letters = [...new Set(unsigned.flatMap((u) => u.missing))].sort();
+    const one = words.length === 1;
+    return `${words.join(', ')} ${one ? 'lacks a sign of its' : 'lack a sign of their'} own and could not be fingerspelled: `
+        + `the avatar lacks the clips for ${letters.join(', ')}`;
+}
+/**
+ * Everything a request left out: the words it could neither sign nor spell, and the clips the delivery could not give (`unread`).
+ * `undefined` when it left nothing out.
+ */
+export function leftOutText(unsigned, unread) {
+    const parts = [unsignedText(unsigned), unread.length ? `the clips of ${unread.map((n) => `«${n}»`).join(', ')} could not be read from the delivery` : ''];
+    return parts.filter(Boolean).join('; ') || undefined;
+}
+/** Why a request with nothing left to sign was not signed. */
+export const nothingSigned = (leftOut) => `none of the text could be signed: ${leftOut ?? 'it holds not a single word'}`;
+/**
+ * WHAT OF EACH CLIP IS PLAYED: all of it, except inside a spelled word, where two neighbouring letters are CHAINED — the first
+ * ends where its hand starts down, the next starts where its hand is up (`held`). Two steps are chained only when they spell the
+ * same word (`word`) and both have a window; so the first letter keeps its rise, the last its fall, a word of one letter and a
+ * sign are whole.
+ */
+function playedSpans(steps, lengthOf, heldOf) {
+    const oneWord = (a, b) => a.spells !== undefined && a.word !== undefined
+        && b.word === a.word && b.spells === a.spells;
+    const chained = steps.map((s, i) => {
+        const next = steps[i + 1];
+        return !!next && oneWord(s, next) && !!heldOf(s.clip) && !!heldOf(next.clip);
+    });
+    return steps.map((s, i) => [
+        i > 0 && chained[i - 1] ? heldOf(s.clip)[0] : 0,
+        chained[i] ? heldOf(s.clip)[1] : lengthOf(s.clip),
+    ]);
+}
+/**
+ * The queue's clock. `lengthOf` is a clip's played length (`playedLength`), `heldOf` where a letter's hand is held up
+ * (`playedSpans`: a spelled word's letters are chained through it; none, and every clip plays whole). Two neighbours overlap by
+ * `fade`, never by more than half of the stretch either plays; the first clip of a queue fades in only when a pose is already on
+ * the stage (a queue that replaced another, or the one held since the last), and appears at once otherwise.
+ */
+export function createSignSequencer(lengthOf, fade = CROSS_FADE_S, heldOf = () => undefined) {
+    let queue = [];
+    let spans = [];
+    /** The step on the stage now; -1 when none is playing. */
+    let index = -1;
+    /** Seconds into the current step's stretch. */
+    let elapsed = 0;
+    /** Whether a pose is on the stage: after the first clip, the last frame of the last one is held. */
+    let shown = false;
+    const lengthAt = (i) => spans[i][1] - spans[i][0];
+    const overlapAfter = (i) => (i + 1 < queue.length ? Math.min(fade, lengthAt(i) / 2, lengthAt(i + 1) / 2) : 0);
+    return {
+        play: (steps) => {
+            queue = steps;
+            spans = playedSpans(steps, lengthOf, heldOf);
+            elapsed = 0;
+            index = steps.length ? 0 : -1;
+            if (!steps.length)
+                return [];
+            const start = { clip: steps[0].clip, fade: shown ? Math.min(fade, lengthAt(0) / 2) : 0, at: spans[0][0] };
+            shown = true;
+            return [start];
+        },
+        tick: (dt) => {
+            const starts = [];
+            if (index < 0)
+                return { starts, finished: false };
+            elapsed += Math.max(0, dt);
+            for (;;) {
+                const length = lengthAt(index);
+                if (index + 1 < queue.length) {
+                    const handOver = length - overlapAfter(index);
+                    if (elapsed < handOver)
+                        break;
+                    elapsed -= handOver;
+                    index += 1;
+                    starts.push({ clip: queue[index].clip, fade: overlapAfter(index - 1), at: spans[index][0] + elapsed });
+                    continue;
+                }
+                if (elapsed < length)
+                    break;
+                index = -1;
+                queue = [];
+                spans = [];
+                return { starts, finished: true };
+            }
+            return { starts, finished: false };
+        },
+        stop: () => {
+            index = -1;
+            queue = [];
+            spans = [];
+            elapsed = 0;
+        },
+    };
+}

package/dist-pkg/ui/libras-avatar-player.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Interpreter } from './vlibras.js';
+import type { AvatarStage } from './libras-avatar-stage.js';
+/** What the free interpreter is built over. Every port is the host's. */
+export interface LibrasAvatarPorts {
+    /** The host's document: the avatar's canvas is created in it and put in front of the screen. */
+    readonly doc: Document;
+    /** The host's window: it keeps the timers and draws the frames. */
+    readonly win: Pick<Window, 'setTimeout' | 'clearTimeout' | 'requestAnimationFrame' | 'cancelAnimationFrame'> & {
+        readonly devicePixelRatio?: number;
+    };
+    /** The host's `fetch`, for the delivery's manifest, avatar, clips and glosses; `undefined` where it has none. */
+    readonly fetch: ((url: string) => Promise<Response>) | undefined;
+    /** The page's address the delivery's folders are resolved against (`document.baseURI`). */
+    readonly base: string;
+    /** The avatar's accessible name, read when its canvas is made — the page's language at that moment. */
+    readonly title: () => string;
+    /** Where the avatar, the clips, the manifest and the glosses are, under `base`. The delivery's folder unless a test points elsewhere. */
+    readonly avatarFolder?: string;
+    /** How long the avatar may take to load before the request is answered «unavailable». */
+    readonly loadTimeoutMs?: number;
+    /** How long the avatar stays after it stopped signing before it leaves. `LEAVE_AFTER_MS` unless a test says. */
+    readonly leaveAfterMs?: number;
+    /** Builds the stage on the canvas from the avatar's bytes. `ui/libras-avatar-stage`, imported when first needed, unless a test says. */
+    readonly loadStage?: (canvas: HTMLCanvasElement, avatar: ArrayBuffer) => Promise<AvatarStage>;
+}
+/** Builds the free interpreter over the avatar the delivery shipped — or, where it shipped none, «signing unavailable». */
+export declare function createLibrasAvatarInterpreter(ports: LibrasAvatarPorts): Interpreter;

package/dist-pkg/ui/libras-avatar-player.js

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-avatar-player.ts — THE INTERPRETER THAT SIGNS: LAViD-UFPB's signs on a three.js avatar, behind the `Interpreter`
+// port (ADR-0234, route B).
+//
+// 📌 THE ROOT'S OWN (phase B3): `createGame` builds this one when the host lends no interpreter (`EngineHost.interpreter`
+// always wins), over the page's own address.
+//
+// THE RULES, as the Dev set them for the interpreter: the gloss is the delivery's (`glosses.json`, beside the avatar, where a
+// word with no sign is written as the child reads it), and a text it does not cover is its words in capitals, accents stripped,
+// Ç kept; the avatar appears at the bottom right when a request is played, in front of the screen, never taking the keyboard; a
+// new request replaces what is being signed (the players' turns are deaf mode's); the avatar LEAVES the screen `leaveAfterMs` after it stopped signing — hidden, kept
+// loaded for the next press — and a press in those seconds cancels the leaving; `hide()` takes it off at once and `dispose()`
+// releases it. A delivery that did not ship it answers exactly as `NO_INTERPRETER` does («signing unavailable», with the flag
+// that ships it), and a device that cannot draw it (no WebGL) or a load that never ends answers «unavailable» with its own
+// reason (`ui/libras-avatar-load`).
+//
+// WHAT IS ITS OWN: the player is this engine's code, so «stopped» is not a message to wait for — it is the moment the last clip
+// reaches its end (`ui/libras-avatar-plan`'s sequencer), its final pose held; a fingerspelled word is signed with the hand held
+// up between its letters (the sequencer's chaining, the Dev's rule of 2026-09-26). And a word it can neither sign nor fingerspell is
+// left out and SAID: the request still signs the rest, and what it left out comes back in `unsigned`, which deaf mode reports
+// in `problems` (ADR-0169: what works in part is reported).
+//
+// 📌 three.js ARRIVES ONLY HERE, AND LATE: `ui/libras-avatar-stage` is imported dynamically when the avatar is first opened, so
+// a page that never signs never downloads it (ADR-0234 errata; `tests/three-arrives-late.node.test.js`).
+import { loadGlosser, provisionalGloss } from './libras-glosses.js';
+import { createSignSequencer, leftOutText, nothingSigned, planSigns, playedLength, } from './libras-avatar-plan.js';
+import { NOT_SHIPPED, RELEASED, avatarCanvas, avatarPlace, openAvatar, prepareClips, readManifest, } from './libras-avatar-load.js';
+/** A school machine gets many times a fast one's load before it is given up on. */
+const LOAD_TIMEOUT_MS = 60_000;
+/** The Dev's five seconds (interface log, «The interpreter leaves 5 s after the player itself says it stopped»). */
+const LEAVE_AFTER_MS = 5000;
+/** The sharpest the avatar is drawn: above this, a school machine pays for pixels a child a metre away does not see. */
+const MAX_PIXEL_RATIO = 1.5;
+/** The longest step one frame may take: a tab that slept does not jump the signs ahead. */
+const MAX_FRAME_S = 0.1;
+/** The stage the delivery's player draws on, loaded — three.js with it — only when the avatar is first opened. */
+async function stageOf(canvas, avatar) {
+    const { createAvatarStage } = await import('./libras-avatar-stage.js');
+    return createAvatarStage({ canvas, avatar });
+}
+/** Builds the free interpreter over the avatar the delivery shipped — or, where it shipped none, «signing unavailable». */
+export function createLibrasAvatarInterpreter(ports) {
+    // ⚠️ `fetch` is taken OUT of the ports and called bare: the host lends `window.fetch` unbound, and called as `ports.fetch(…)`
+    // it would run with the ports object as `this` — an «Illegal invocation» in the browser, and no avatar.
+    const { doc, win, fetch: fetchFile } = ports;
+    const leaveAfterMs = ports.leaveAfterMs ?? LEAVE_AFTER_MS;
+    let place = null;
+    let shipped = null;
+    let manifest = null;
+    let glosser = null;
+    let canvas = null;
+    let stage = null;
+    let loading = null;
+    let cancelOpening = null;
+    /** Each clip is fetched and prepared once per stage. */
+    const clipLoads = new Map();
+    /** The request being signed now, answered when its last clip reached its end — with what it left out. */
+    let playing = null;
+    let playingLeftOut;
+    /** Moves on every `hide()` and at `dispose()`: a request that waited across one is not played. */
+    let generation = 0;
+    let disposed = false;
+    /** The seconds after the avatar stopped, at whose end it leaves the screen; `null` when none is running. */
+    let leaving = null;
+    let frameId = null;
+    let lastFrame = null;
+    // a spelled word's letters are chained through where each is held up, which the delivery measured (`ClipWindow.held`)
+    const sequencer = createSignSequencer((clip) => {
+        const w = manifest?.clips.get(clip);
+        return w ? playedLength(w) : 0;
+    }, undefined, (clip) => manifest?.clips.get(clip)?.held);
+    const signedWith = (leftOut) => (leftOut ? { signed: true, unsigned: leftOut } : { signed: true });
+    const answerPlaying = (r) => { const answer = playing; playing = null; answer?.(r); };
+    const released = () => ({ signed: false, reason: RELEASED });
+    /** Whether a request that started at `asked` was overtaken by a `hide()` or the root's end while it waited. */
+    const overtaken = (asked) => disposed || asked !== generation;
+    const stayOnScreen = () => {
+        if (leaving !== null)
+            win.clearTimeout(leaving);
+        leaving = null;
+    };
+    const stopDrawing = () => {
+        if (frameId !== null)
+            win.cancelAnimationFrame(frameId);
+        frameId = null;
+        lastFrame = null;
+    };
+    /** The avatar stopped: after `leaveAfterMs` at rest, it leaves — hidden, the stage kept loaded behind it. */
+    const leaveWhenAtRest = () => {
+        stayOnScreen();
+        leaving = win.setTimeout(() => {
+            leaving = null;
+            if (canvas)
+                canvas.hidden = true;
+        }, leaveAfterMs);
+    };
+    const frame = (now) => {
+        frameId = null;
+        if (!stage)
+            return;
+        const dt = lastFrame === null ? 0 : Math.min(MAX_FRAME_S, Math.max(0, (now - lastFrame) / 1000));
+        lastFrame = now;
+        const { starts, finished } = sequencer.tick(dt);
+        for (const s of starts)
+            stage.start(s.clip, s.fade, s.at);
+        stage.advance(dt);
+        if (!finished) {
+            frameId = win.requestAnimationFrame(frame);
+            return;
+        }
+        // «stopped»: the last clip reached its end and its final pose is held — nothing moves, so nothing more is drawn
+        lastFrame = null;
+        answerPlaying(signedWith(playingLeftOut));
+        leaveWhenAtRest();
+    };
+    /** Takes the canvas and the stage away; the next press opens them again. */
+    const release = () => {
+        stopDrawing();
+        cancelOpening?.();
+        cancelOpening = null;
+        stage?.dispose();
+        stage = null;
+        clipLoads.clear();
+        canvas?.remove();
+        canvas = null;
+        loading = null;
+    };
+    /** Opens the canvas and the stage once, and answers when the avatar is ready to sign — or why it cannot. */
+    const load = (at, m) => {
+        if (loading)
+            return loading;
+        const made = avatarCanvas(doc, ports.title());
+        canvas = made;
+        const opening = openAvatar(made, {
+            fetchFile, avatarUrl: new URL(m.avatar, at.folder).href, loadStage: ports.loadStage ?? stageOf,
+            timeoutMs: ports.loadTimeoutMs ?? LOAD_TIMEOUT_MS, win,
+        }, () => canvas === made);
+        cancelOpening = opening.cancel;
+        loading = opening.done.then((r) => {
+            if ('stage' in r) {
+                stage = r.stage;
+                return { signed: true };
+            }
+            if (canvas === made)
+                release(); // the next press tries again, from a fresh canvas
+            return { signed: false, reason: r.reason };
+        });
+        return loading;
+    };
+    /** The delivery's avatar, ready to sign: its place and manifest — or the answer the request gets instead. */
+    const reach = async (asked) => {
+        const at = (place ??= avatarPlace(ports.base, ports.avatarFolder));
+        const m = at ? await (shipped ??= readManifest(fetchFile, at)) : null;
+        if (!at || !m)
+            return { signed: false, reason: NOT_SHIPPED };
+        manifest = m;
+        if (overtaken(asked))
+            return released();
+        const loaded = await load(at, m);
+        return loaded.signed ? { at, m } : loaded;
+    };
+    /** The clips a text is signed with, all prepared, and what was left out — or the answer the request gets instead. */
+    const planFor = async (text, at, m, asked) => {
+        const glossOf = await (glosser ??= loadGlosser(fetchFile, at.glosses));
+        const plan = planSigns(glossOf(text) || provisionalGloss(text), (name) => m.clips.has(name));
+        const unread = stage ? await prepareClips(stage, [...new Set(plan.steps.map((s) => s.clip))], m, at, fetchFile, clipLoads) : [];
+        if (overtaken(asked) || !stage || !canvas)
+            return released();
+        const steps = plan.steps.filter((s) => !unread.includes(s.clip));
+        const leftOut = leftOutText(plan.unsigned, unread);
+        return steps.length ? { steps, leftOut } : { signed: false, reason: nothingSigned(leftOut) };
+    };
+    /** Puts the avatar in front of the screen and signs `steps`; answered when the last one reached its end. */
+    const perform = (on, shown, steps, leftOut) => {
+        // 📌 A new request replaces what is being signed. The turns among players are deaf mode's (`ui/vlibras`, ADR-0234 errata
+        // 2026-09-26): it asks again only for the same player, or for a request that names none. The one replaced is not a
+        // failure: the child asked again.
+        answerPlaying(signedWith(playingLeftOut));
+        shown.hidden = false;
+        const box = shown.getBoundingClientRect();
+        on.resize(box.width, box.height, Math.min(MAX_PIXEL_RATIO, win.devicePixelRatio || 1));
+        for (const s of sequencer.play(steps))
+            on.start(s.clip, s.fade, s.at);
+        lastFrame = null;
+        if (frameId === null)
+            frameId = win.requestAnimationFrame(frame);
+        return new Promise((resolve) => {
+            playing = resolve;
+            playingLeftOut = leftOut;
+        });
+    };
+    return {
+        sign: async (text) => {
+            // nothing to sign is not a failure, and nothing goes to `problems`
+            if (!provisionalGloss(text))
+                return { signed: true };
+            // a press in the seconds at rest keeps the avatar where it is: it is about to sign again
+            stayOnScreen();
+            const asked = generation;
+            const reached = await reach(asked);
+            if ('signed' in reached)
+                return reached;
+            const plan = await planFor(text, reached.at, reached.m, asked);
+            if ('signed' in plan || !stage || !canvas)
+                return 'signed' in plan ? plan : released();
+            return perform(stage, canvas, plan.steps, plan.leftOut);
+        },
+        hide: () => {
+            generation += 1;
+            stayOnScreen();
+            sequencer.stop();
+            stopDrawing();
+            if (canvas)
+                canvas.hidden = true;
+            answerPlaying(released());
+        },
+        dispose: () => {
+            disposed = true;
+            generation += 1;
+            stayOnScreen(); // no timer of this root outlives it
+            sequencer.stop();
+            answerPlaying(released());
+            release();
+        },
+    };
+}

package/dist-pkg/ui/libras-avatar-stage.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type ClipJson } from './libras-avatar-clip.js';
+/** What the player drives. */
+export interface AvatarStage {
+    /** The avatar's three.js root, for a test or a measurement that reads the pose. Nothing in the engine reads it. */
+    readonly scene: object;
+    /** Makes a clip playable, from `from` seconds of it on. */
+    readonly prepare: (name: string, clip: ClipJson, from: number) => void;
+    readonly has: (name: string) => boolean;
+    /** Puts a prepared clip on the stage, fading in over `fade` seconds from what is there, `at` seconds into it. */
+    readonly start: (name: string, fade: number, at: number) => void;
+    /** Moves the clips `dt` seconds and draws. */
+    readonly advance: (dt: number) => void;
+    /** The canvas's size in CSS pixels and the pixel ratio it is drawn at. */
+    readonly resize: (width: number, height: number, pixelRatio: number) => void;
+    /** What the drawing costs, for a measurement: the renderer's own counters. */
+    readonly stats: () => {
+        readonly textures: number;
+        readonly geometries: number;
+        readonly calls: number;
+        readonly triangles: number;
+    };
+    /** Releases the GPU and everything the avatar holds. */
+    readonly dispose: () => void;
+}
+export interface AvatarStageOptions {
+    /** The canvas the avatar is drawn on: the player's, already in its document. */
+    readonly canvas: HTMLCanvasElement;
+    /** The delivery's `avatar.glb`, as bytes. */
+    readonly avatar: ArrayBuffer;
+    readonly textureSize?: number;
+}
+/**
+ * Builds the stage over `canvas`. THROWS where it cannot draw — no WebGL, an avatar three.js cannot read — and the player turns
+ * that into «signing unavailable», with the reason.
+ */
+export declare function createAvatarStage({ canvas, avatar, textureSize }: AvatarStageOptions): Promise<AvatarStage>;