@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/layout.js

@@ -1,117 +1,135 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/layout.ts — ESCALA do jogo (Estágio 4, Tier 1). Trava o #game-region num múltiplo inteiro de PIXELS REAIS
-// de 320×180 (por jogador) e reescala as vars de UI escopadas ao canvas. Deps: ui/dom ($), core/screens,
-// render/crt (crtScanVars). A contagem de jogadores entra por `initLayout`. fpsTick/configureRender seguem no main.js.
+// ui/layout.ts — the game's SCALE. Locks #game-region to a whole multiple of REAL PIXELS of 320×180 (per player) and
+// rescales the UI variables scoped to the canvas. Deps: core/screens. The pure arithmetic (`stageScale`, `applyScale`,
+// the target floor, the reporters' rules) is exported as functions; `createLayout` is the shell that measures a
+// document it is HANDED and calls `afterScale` (the root's CRT re-anchoring its scanlines) — ADR-0232 D4, issue #207.
 //
-// JÁ NÃO RESERVA ESPAÇO PARA O INTÉRPRETE. Reservava 380px à direita quando o painel do VLibras "abria", e o
-// jogo deslocava para a esquerda — decisão revista pelo Dev: o intérprete deve aparecer NA FRENTE da tela
-// enquanto um áudio toca, e sumir. E a reserva estava sendo aplicada O TEMPO TODO, porque o detector de
-// "aberto" lia um div vazio (ver o cabeçalho de ui/vlibras): o canvas vivia em `left: -136`, fora da tela,
-// com ou sem modo pessoa surda. O acoplamento vlibras↔layout desaparece junto.
-import { $ } from './dom.js';
+// IT RESERVES NO SPACE FOR THE INTERPRETER: in deaf mode the interpreter appears IN FRONT of the screen when the sonar
+// calls it (ADR-0234, see ui/vlibras), so the layout does not shift the game for it.
 import { screenBaseSize } from '../core/screens.js';
-import { crtScanVars } from '../render/crt.js';
 /**
- * A RÉGUA DO ALVO DE TOQUE, INDEXADA PELA ALTURA DO VIEWPORT (ADR-0095, decisão do Dev).
+ * THE TOUCH TARGET FLOOR, in CSS px, for a CSS scale factor `k` (ADR-0163).
  *
- * ⚠️ O ALVO DEIXOU DE SER UM NÚMERO E PASSOU A SER UMA FUNÇÃO DA TELA, e o motivo é um custo que o gate de
- * `pausa-44px` já tinha MEDIDO e deixado por resolver: a 640×360 o cartão de pausa não cabe e a lista ROLA.
- * Remedido em 06/09, porque o cartão mudou desde então: 391 px de conteúdo para 349 visíveis, ou seja 42 px
- * de excesso (o comentário antigo dizia 413/353). Um alvo de 44 px que exige rolagem para ser alcançado
- * pode custar mais dedo do que um de 24 px que está à vista.
- *
- * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ * 🔴 IT WAS A RULER BY VIEWPORT HEIGHT (ADR-0095: 24 px under 540, 34 under 720, 44 above), because a 640×360 pause
+ * card with 44 px items scrolled. ADR-0163 made the resolution the engine's — never under 640×360 — and the Dev set the
+ * target — «44px é o correto, eu errei quando disse 42px» — so the floor is 44 px at the minimum (k = 2) and
+ * grows with the scale, like the text; there is no smaller screen left to shrink for.
+ */
+export function minimumTarget(k) {
+    return 22 * (Number.isFinite(k) && k > 2 ? k : 2);
+}
+/**
+ * WHAT A CARTRIDGE DRAWS UNDER THE FLOOR (ADR-0163 rule 4): text under 8·k px (16 at 640×360) and targets whose SMALLER
+ * side is under 22·k px (44 at 640×360). The engine's own nodes are not the cartridge's to answer for, and a node with no
+ * area is not drawn. Half a pixel of slack absorbs subpixel layout.
+ */
+export function belowFloor(nodes, k) {
+    const ratio = minimumTarget(k) / 22;
+    const smallText = [];
+    const smallTargets = [];
+    for (const n of nodes) {
+        if (n.daEngine)
+            continue;
+        if (n.fontPx !== null && n.fontPx > 0 && n.fontPx < 8 * ratio - 0.5)
+            smallText.push(n.name);
+        if (n.target && n.target.w > 0 && n.target.h > 0 && Math.min(n.target.w, n.target.h) < minimumTarget(k) - 0.5)
+            smallTargets.push(n.name);
+    }
+    return { text: smallText, targets: smallTargets };
+}
+export function barIntruders(barBox, nodes) {
+    // A bar with no area reserves nothing — and accusing against a zero rectangle would accuse everyone.
+    if (!barBox || barBox.w <= 0 || barBox.h <= 0)
+        return [];
+    // ⚠️ THE ZERO-AREA GUARD DOES WORK: the strict inequalities exclude a node that is DEGENERATE AT THE BOUNDARY, not one
+    // in general — a zero-width stripe crossing the bar passes all four comparisons. 📌 Containers of zero height or width
+    // are common in generated markup, and accusing them would be pure noise — which is how a consumer learns to ignore
+    // the line.
+    return nodes
+        .filter((n) => !n.isBar && n.box.w > 0 && n.box.h > 0)
+        .filter((n) => n.box.x < barBox.x + barBox.w && barBox.x < n.box.x + n.box.w
+        && n.box.y < barBox.y + barBox.h && barBox.y < n.box.y + n.box.h)
+        .map((n) => n.name);
+}
+/**
+ * THE SHELL THAT GIVES THE AVAILABLE SPACE — by id OR by class, and both forms count the same.
  *
- *     altura ≥ 720   44 px   WCAG 2.2 · 2.5.5 Target Size (Enhanced) — AAA
- *     altura ≥ 540   34 px   o degrau do meio
- *     altura <  540  24 px   WCAG 2.2 · 2.5.8 Target Size (Minimum)  — AA
+ * ⚠️ BY ID ONLY, a host with `<div class="stage-wrap">` (the quiz) got no scale at all: `layout()` returned early and
+ * nothing reported anything — a silent `return` is indistinguishable from "there was nothing to do".
  *
- * ⚠️ ISTO É «MARCAR HONESTAMENTE ONDE SÓ DÁ AA», que é regra escrita do projeto — e não uma renúncia
- * silenciosa. O que se perde em 360 está registrado com número no ADR-0095: a 96 px/pol, 24 CSS px são
- * 6,4 mm, abaixo do alvo de polegar de 9,6 mm que o painel de toque deste jogo cita. É por isso que o
- * ESPAÇAMENTO entre alvos passa a ser o que protege o dedo onde o tamanho não pode — a mesma saída que a
- * própria 2.5.8 dá na sua exceção de spacing.
+ * The consumer is not wrong to use the class: a document can have several screens, and an id is unique. Accepting both
+ * is what makes the engine consumable by whoever did not copy its markup.
  */
-export const REGUA_DE_ALVO = Object.freeze([
-    { altura: 720, alvo: 44 },
-    { altura: 540, alvo: 34 },
-    { altura: 0, alvo: 24 },
-]);
+function findStageWrap(doc) {
+    return doc.querySelector('#stage-wrap') ?? doc.querySelector('.stage-wrap');
+}
 /**
- * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ * ADR-0001 AS A PURE FUNCTION — so the engine can apply it to every cartridge (ADR-0163) and a test can pin it.
  *
- * ⚠️ NUNCA DEVOLVE MENOS DE 24: abaixo disso não é «AA num aparelho pequeno», é furar o piso da WCAG. Uma
- * tela mais baixa que 360 não compra o direito de encolher mais — compra o direito de mostrar menos itens.
+ * Integer multiple of 320×180 (per the screen grid) in REAL pixels; up to 5 logical px of crop per side when that buys one
+ * more step (the `−10`: `base·kDev − avail·dpr ≤ 10·kDev`). Never under 2 CSS px per logical pixel — 640×360 CSS, text 16 px,
+ * targets 44 px: where the whole multiple gives less (a fractional display scale on the minimum window) the scale is exactly
+ * 2 CSS px, whole in real pixels or not, because WCAG 2.2 AA decides (ADR-0179).
  */
-export function alvoMinimoDeToque(alturaCss) {
-    const h = Number.isFinite(alturaCss) ? alturaCss : 0;
-    for (const degrau of REGUA_DE_ALVO)
-        if (h >= degrau.altura)
-            return degrau.alvo;
-    return 24;
+export function stageScale(availW, availH, dpr, baseW, baseH) {
+    const MIN_K = 2;
+    const integerK = Math.floor(Math.min(availW * dpr / (baseW - 10), availH * dpr / (baseH - 10)));
+    const kDev = integerK / dpr >= MIN_K ? integerK : MIN_K * dpr;
+    const k = kDev / dpr;
+    return { kDev, k, width: baseW * k, height: baseH * k };
 }
-// A CONTAGEM DE JOGADORES entra por injeção desde 2026-08-26. Era `numPlayers`, um `let` de `core/state`
-// importado como binding vivo — e um `let` de módulo é compartilhado por qualquer segundo jogo que a
-// mesma página carregue (D13 do `demos`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
-// possui; o `let` que sobra guarda a função, não o número.
-let _numJogadores = () => 1;
-/** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
-export function initLayout(deps) { _numJogadores = deps.numJogadores; }
 /**
- * A CASCA QUE DÁ O ESPAÇO DISPONÍVEL — por id OU por classe, e as duas formas valem o mesmo.
- *
- * ⚠️ ERA SÓ `#stage-wrap`, E ISSO DEIXOU A ENGINE SEM ESCALA NO PRÓPRIO HOST. O `app/index.html` do jogo
- * trazia `<div id="stage-wrap">`; quando o cartucho saiu (issue #111) sobrou o `app/quiz.html`, que tem
- * `<div class="stage-wrap">`. A procura por id falhava, `layout()` fazia early-return, e **nada reportava
- * nada**: um `return` silencioso é indistinguível de «não havia o que fazer». O comentário do próprio
- * `quiz.html` dizia «mesmo id que ui/layout escala» — quem o escreveu acreditava que corria.
+ * Writes a scale onto the game region: its size, and the UI variables that grow with it.
  *
- * O consumidor não erra ao usar a classe: um documento pode ter várias telas, e um id é único. Aceitar as
- * duas é o que torna a engine consumível por quem não copiou o markup dela.
+ * ⚠️ HOST-INJECTED (the region is passed in): `createGame` serves documents that
+ * are not the global one — the fault the root's finding 15 names about reaching `document` from under the injection.
  */
-function cascaDoPalco() {
-    return $('#stage-wrap') ?? $('.stage-wrap');
+export function applyScale(region, e) {
+    region.style.width = e.width + 'px';
+    region.style.height = e.height + 'px';
+    region.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * e.k * 0.052)) + 'px');
+    region.style.setProperty('--ui-fs', (8 * e.k) + 'px'); // LOGICAL base 8px × k (16px at k=2)
+    // One ruler (plan phase 5b): `--tap` is the name three sibling games read, `--alvo-min` the engine's (ADR-0163); both come
+    // from `minimumTarget`, so a display scale that gives k under 2 (Windows 110%) no longer drops `--tap` under 44 px.
+    region.style.setProperty('--tap', minimumTarget(e.k) + 'px');
+    region.style.setProperty('--alvo-min', minimumTarget(e.k) + 'px'); // 44 px at 640×360, growing with k (ADR-0163)
+    // THE EDGE MARGIN (interface log 2026-09-26): 4 logical px between the region's edge and every text and button but the quick
+    // bar's — 8 px at 640×360, growing with k like the text. The stylesheet reads it; the quick bar keeps the edge (ADR-0180).
+    region.style.setProperty('--margem-borda', (4 * e.k) + 'px');
 }
-export function layout() {
-    const wrap = cascaDoPalco();
-    if (!wrap)
-        return;
-    wrap.style.paddingRight = '0px';
-    const availW = wrap.clientWidth || 320;
-    const availH = wrap.clientHeight || 180;
-    // E11: a grade de telas define a base (1=320×180, 2=640×180, 3-4=640×360)
-    const n = _numJogadores();
-    // (`screenGrid(n)` SAIU em 2026-08-26: `cols`/`rows` eram desestruturados e nunca lidos — a escala sai de
-    //  `screenBaseSize`, logo abaixo. Era uma chamada paga a cada `layout()` por nada. `noUnusedLocals` achou.)
-    const { w: baseW, h: baseH } = screenBaseSize(n);
-    // Piso k=2: CADA viewport tem no mínimo 640×360. Assim 2×2 = 1280×720 cabe num Chromebook do governo (1366×768).
-    const MIN_K = 2;
-    // ADR-001 (CORRIGIDO 2026-07-04): ESCALA travada em PIXELS REAIS INTEIROS. Cada pixel de arte = kDev pixels
-    // FÍSICOS (inteiro) → scanlines SEMPRE regulares e arte uniforme em QUALQUER dpr. Tolera ≤5px lógicos de corte
-    // por lado (o −10): base·kDev − avail·dpr ≤ 10·kDev ⇒ kDev ≤ avail·dpr/(base−10). (José escolheu inteiro-REAL.)
-    const dpr = window.devicePixelRatio || 1;
-    const kDev = Math.max(Math.round(MIN_K * dpr), Math.floor(Math.min(availW * dpr / (baseW - 10), availH * dpr / (baseH - 10))));
-    const k = kDev / dpr; // fator LÓGICO/CSS (kDev = fator em pixels REAIS, inteiro)
-    // ESCALA das vars de UI é ESCOPADA ao #game-region: só a UI DENTRO do canvas (menus/HUD/pausa/quiz) escala com o
-    // k. Fora do canvas (barra de topo, painel de debug) herda o :root → texto SEMPRE 16px, toque 44px (José).
-    const gr = $('#game-region');
-    if (gr) {
-        gr.style.width = (baseW * k) + 'px';
-        gr.style.height = (baseH * k) + 'px';
-        gr.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * k * 0.052)) + 'px');
-        gr.style.setProperty('--ui-fs', (8 * k) + 'px'); // base LÓGICA 8px × k (16px em k=2)
-        gr.style.setProperty('--tap', (22 * k) + 'px'); // toque 22px × k (44px em k=2, piso WCAG)
-        // ⚠️ O PISO DA RÉGUA (ADR-0095), e ele é OUTRA COISA que o `--tap`. O `--tap` é o tamanho PREFERIDO e
-        // cresce com a escala do canvas; `--alvo-min` é o CHÃO por altura de tela — 24 px abaixo de 540, 34 a
-        // partir de 540, 44 a partir de 720. Um botão isolado usa o preferido; um item de LISTA, que tem de
-        // caber inteiro na tela, usa o chão.
-        //
-        // ⚠️ A ALTURA É A DO ESPAÇO DISPONÍVEL, e não a da sub-tela de um jogador: o dedo toca o aparelho, não
-        // o viewport lógico. Em quatro telas divididas cada uma tem 180 px de alto, e encolher o alvo por causa
-        // disso seria ler o número errado — o aparelho continua o mesmo.
-        gr.style.setProperty('--alvo-min', alvoMinimoDeToque(availH) + 'px');
+/**
+ * Builds a stage scaler over the document and window it is handed. It keeps nothing between calls: every `layout()`
+ * measures again, reads the player count again, and writes onto the region.
+ */
+export function createLayout(ctx) {
+    function layout() {
+        const wrap = findStageWrap(ctx.doc);
+        if (!wrap)
+            return;
+        wrap.style.paddingRight = '0px';
+        const availW = wrap.clientWidth || 320;
+        const availH = wrap.clientHeight || 180;
+        // The screen grid sets the base (1=320×180, 2=640×180, 3-4=640×360).
+        const n = ctx.numPlayers();
+        const { w: baseW, h: baseH } = screenBaseSize(n);
+        // Floor k=2: EACH viewport is at least 640×360, so 2×2 = 1280×720 fits a government Chromebook (1366×768).
+        // ADR-0001: SCALE locked to WHOLE REAL PIXELS. Each art pixel = kDev PHYSICAL pixels (whole) → scanlines ALWAYS regular
+        // and uniform art at ANY dpr. Tolerates ≤5 logical px of crop per side (the −10): base·kDev − avail·dpr ≤ 10·kDev ⇒
+        // kDev ≤ avail·dpr/(base−10). (The Dev chose whole REAL pixels.) The arithmetic lives in `stageScale` (ADR-0163), so the
+        // engine applies it to every cartridge.
+        const dpr = ctx.win.devicePixelRatio || 1;
+        const ratio = stageScale(availW, availH, dpr, baseW, baseH);
+        const { kDev, k } = ratio;
+        // The UI variables' SCALE is SCOPED to #game-region: only the UI INSIDE the canvas (menus/HUD/pause/quiz) scales with
+        // k. Outside the canvas (top bar, debug panel) it inherits :root → text ALWAYS 16px, touch 44px (the Dev).
+        const gr = ctx.doc.querySelector('#game-region');
+        if (gr) {
+            // `--tap` is the PREFERRED size (22·k) and `--alvo-min` the FLOOR (22·k, 44 px at 640×360 — ADR-0163), written in `applyScale`.
+            applyScale(gr, ratio);
+        }
+        ctx.afterScale(); // scanlines realign when the scale k changes
+        if (ctx.debug?.())
+            console.info(`[escala] kDev=${kDev}× px REAIS (canvas físico ${baseW * kDev}×${baseH * kDev} = múltiplo INTEIRO de ${baseW}×${baseH}); CSS ${Math.round(baseW * k)}×${Math.round(baseH * k)} (k=${k.toFixed(3)}, dpr=${dpr})`);
     }
-    crtScanVars(); // scanlines re-alinham quando a escala k muda
-    if (/[?&]debug=true/.test(location.search))
-        console.info(`[escala] kDev=${kDev}× px REAIS (canvas físico ${baseW * kDev}×${baseH * kDev} = múltiplo INTEIRO de ${baseW}×${baseH}); CSS ${Math.round(baseW * k)}×${Math.round(baseH * k)} (k=${k.toFixed(3)}, dpr=${dpr})`);
+    return { layout };
 }

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

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** One track of a three.js AnimationClip JSON, as the export writes it. */
+export interface TrackJson {
+    readonly name: string;
+    readonly type: string;
+    readonly times: readonly number[];
+    readonly values: readonly number[];
+    readonly interpolation?: number;
+}
+/** A three.js AnimationClip JSON (`AnimationClip.parse`), as the export writes it. */
+export interface ClipJson {
+    readonly name: string;
+    readonly duration: number;
+    readonly tracks: readonly TrackJson[];
+}
+/** A track's value at `time`, as three.js interpolates it: held before the first key and after the last. */
+export declare function valueAt(track: TrackJson, time: number): number[];
+/**
+ * The clip from `from` seconds on, its times shifted to start at zero: each track keeps its value AT `from` as its first key,
+ * then its later keys. A track whose keys all lie before `from` holds its last value. `from` of zero is the clip itself.
+ */
+export declare function clipFrom(clip: ClipJson, from: number): ClipJson;
+/**
+ * The face's tracks, bound to every mesh that carries the morph targets. The export names a morph track after the head's NODE
+ * (`cabecaModifAlisson.morphTargetInfluences[Sorriso]`), and three.js loads a node whose mesh has two primitives as a GROUP of
+ * two meshes, each with its own copy of the targets — a track on the group moves neither. `meshesOf(node)` answers the meshes
+ * a track on that node must reach (by the names three.js binds, e.g. their uuids), or `null` where the node is itself the mesh;
+ * the track is written once for each.
+ */
+export declare function bindFaceTracks(clip: ClipJson, meshesOf: (node: string) => readonly string[] | null): ClipJson;

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

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-avatar-clip — A SIGN CLIP, BEFORE three.js READS IT (ADR-0234, route B, phase B2). Pure: no three.js, no DOM.
+//
+// The B1 export hands each sign over as three.js AnimationClip JSON (`scripts/libras-export.mjs`), and two things about it are
+// answered here, on the JSON, where node can hold them (`tests/libras-avatar-plan.node.test.js`): a clip whose sign starts
+// later than the clip does — FALA, whose export starts at a stray keyframe — is played from its sign (`clipFrom`), and the
+// face's tracks, named after the head's node, are written for each mesh three.js loads the head as (`bindFaceTracks`).
+// `ui/libras-avatar-stage` parses what comes out.
+/** three.js `InterpolateDiscrete`: the export marks a STEP track with it. */
+const DISCRETE = 2300;
+function slerp(a, b, u) {
+    let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+    const bb = dot < 0 ? b.map((x) => -x) : [...b];
+    dot = Math.abs(dot);
+    if (dot > 0.9995) {
+        const q = a.map((x, c) => x + (bb[c] - x) * u);
+        const l = Math.hypot(...q);
+        return q.map((x) => x / l);
+    }
+    const th = Math.acos(dot);
+    const s = Math.sin(th);
+    return a.map((x, c) => (Math.sin((1 - u) * th) * x + Math.sin(u * th) * bb[c]) / s);
+}
+/** A track's value at `time`, as three.js interpolates it: held before the first key and after the last. */
+export function valueAt(track, time) {
+    const { times, values } = track;
+    const width = values.length / times.length;
+    const key = (i) => values.slice(i * width, i * width + width);
+    const last = times.length - 1;
+    if (time <= times[0] || last === 0)
+        return key(0);
+    if (time >= times[last])
+        return key(last);
+    let i = 0;
+    while (times[i + 1] <= time)
+        i += 1;
+    if (time === times[i] || track.interpolation === DISCRETE)
+        return key(i);
+    const u = (time - times[i]) / (times[i + 1] - times[i]);
+    const a = key(i);
+    const b = key(i + 1);
+    return track.type === 'quaternion' ? slerp(a, b, u) : a.map((x, c) => x + (b[c] - x) * u);
+}
+/**
+ * The clip from `from` seconds on, its times shifted to start at zero: each track keeps its value AT `from` as its first key,
+ * then its later keys. A track whose keys all lie before `from` holds its last value. `from` of zero is the clip itself.
+ */
+export function clipFrom(clip, from) {
+    if (!(from > 0))
+        return clip;
+    const tracks = clip.tracks.map((t) => {
+        const times = [0];
+        const values = [...valueAt(t, from)];
+        const width = t.values.length / t.times.length;
+        t.times.forEach((time, i) => {
+            if (time <= from)
+                return;
+            times.push(time - from);
+            values.push(...t.values.slice(i * width, i * width + width));
+        });
+        return { ...t, times, values };
+    });
+    return { name: clip.name, duration: Math.max(0, clip.duration - from), tracks };
+}
+const MORPH_TRACK = /^(.+)\.morphTargetInfluences\[(.+)\]$/u;
+/**
+ * The face's tracks, bound to every mesh that carries the morph targets. The export names a morph track after the head's NODE
+ * (`cabecaModifAlisson.morphTargetInfluences[Sorriso]`), and three.js loads a node whose mesh has two primitives as a GROUP of
+ * two meshes, each with its own copy of the targets — a track on the group moves neither. `meshesOf(node)` answers the meshes
+ * a track on that node must reach (by the names three.js binds, e.g. their uuids), or `null` where the node is itself the mesh;
+ * the track is written once for each.
+ */
+export function bindFaceTracks(clip, meshesOf) {
+    const tracks = [];
+    for (const t of clip.tracks) {
+        const m = MORPH_TRACK.exec(t.name);
+        const meshes = m ? meshesOf(m[1]) : null;
+        if (!m || !meshes) {
+            tracks.push(t);
+            continue;
+        }
+        for (const mesh of meshes)
+            tracks.push({ ...t, name: `${mesh}.morphTargetInfluences[${m[2]}]` });
+    }
+    return { ...clip, tracks };
+}

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

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type AvatarManifest } from './libras-avatar-plan.js';
+import type { AvatarStage } from './libras-avatar-stage.js';
+/** The host's `fetch`, lent unbound — and called bare, never as a method of what carries it. */
+export type FetchFile = ((url: string) => Promise<Response>) | undefined;
+/**
+ * Why a delivery with no avatar cannot sign, and the fix (ADR-0169): the reason `NO_INTERPRETER` gives, word for word — the
+ * root's interpreter answers a delivery built without `--libras` exactly as a root with no player would.
+ */
+export declare const NOT_SHIPPED = "a Libras player is not installed in this delivery \u2014 build it with `inclusionist-heavy <folder> --libras`";
+/** Why a request that waited across a `hide()` or the root's end was not signed. */
+export declare const RELEASED = "the interpreter was taken off the screen before it signed";
+/** Where the delivery's files are: the avatar's folder, its manifest, and the glosses `--libras` writes beside them. */
+export interface AvatarPlace {
+    readonly folder: string;
+    readonly manifest: string;
+    readonly glosses: string;
+}
+/** The addresses under `base`, or `null` where it resolves nothing — a host whose document has no address finds no avatar. */
+export declare function avatarPlace(base: string, folder?: string): AvatarPlace | null;
+/** The delivery's manifest, or `null` for a delivery that did not ship the avatar. */
+export declare const readManifest: (fetchFile: FetchFile, place: AvatarPlace) => Promise<AvatarManifest | null>;
+/** The canvas the avatar is drawn on: the bottom right, in front of the screen, watched and never operated. */
+export declare function avatarCanvas(doc: Document, title: string): HTMLCanvasElement;
+export interface AvatarOpening {
+    readonly fetchFile: FetchFile;
+    /** The avatar's address, from the manifest. */
+    readonly avatarUrl: string;
+    readonly loadStage: (canvas: HTMLCanvasElement, avatar: ArrayBuffer) => Promise<AvatarStage>;
+    readonly timeoutMs: number;
+    readonly win: Pick<Window, 'setTimeout' | 'clearTimeout'>;
+}
+/** A stage, or why there is none. */
+export type Opened = {
+    readonly stage: AvatarStage;
+} | {
+    readonly reason: string;
+};
+/**
+ * Builds the stage on `canvas` from the delivery's avatar: the stage, or why not — an avatar the delivery cannot give, a device
+ * that cannot draw it, a load past `timeoutMs`. `wanted()` is asked when the stage arrives: false, and it is released at once.
+ * `cancel()` answers «released» now and clears the timer, so nothing of a released root outlives it.
+ */
+export declare function openAvatar(canvas: HTMLCanvasElement, o: AvatarOpening, wanted: () => boolean): {
+    readonly done: Promise<Opened>;
+    readonly cancel: () => void;
+};
+/**
+ * Makes each clip of `names` playable on `stage`, fetching the ones it has not got — once each, remembered in `ready` — and
+ * answers the names whose file could not be read or prepared.
+ */
+export declare function prepareClips(stage: AvatarStage, names: readonly string[], manifest: AvatarManifest, place: AvatarPlace, fetchFile: FetchFile, ready: Map<string, Promise<boolean>>): Promise<string[]>;

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

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-avatar-load — WHAT THE DELIVERY SHIPPED FOR THE FREE PLAYER, AND OPENING IT (ADR-0234, route B, phase B2).
+//
+// The half of `ui/libras-avatar-player` that talks to the delivery: where its files are, whether it shipped the avatar at all
+// (its manifest, which only `inclusionist-heavy --libras` writes), the canvas the avatar is drawn on, the stage built on it from
+// the avatar's bytes — within a time, or not at all — and the clips, each fetched and prepared once. Every answer is a value,
+// never a throw: a delivery without the avatar, a device without WebGL and a clip that cannot be read are reasons, which the
+// player hands to deaf mode and deaf mode to `problems` (ADR-0169).
+import { LIBRAS_GLOSSES_FILE } from './libras-glosses.js';
+import { LIBRAS_NOT_INSTALLED } from './vlibras.js';
+import { LIBRAS_AVATAR_FOLDER, LIBRAS_AVATAR_MANIFEST, avatarManifestOf } from './libras-avatar-plan.js';
+/**
+ * Why a delivery with no avatar cannot sign, and the fix (ADR-0169): the reason `NO_INTERPRETER` gives, word for word — the
+ * root's interpreter answers a delivery built without `--libras` exactly as a root with no player would.
+ */
+export const NOT_SHIPPED = LIBRAS_NOT_INSTALLED;
+/** Why a request that waited across a `hide()` or the root's end was not signed. */
+export const RELEASED = 'the interpreter was taken off the screen before it signed';
+/** The addresses under `base`, or `null` where it resolves nothing — a host whose document has no address finds no avatar. */
+export function avatarPlace(base, folder = LIBRAS_AVATAR_FOLDER) {
+    try {
+        const at = new URL(folder, base);
+        return { folder: at.href, manifest: new URL(LIBRAS_AVATAR_MANIFEST, at).href, glosses: new URL(LIBRAS_GLOSSES_FILE, at).href };
+    }
+    catch {
+        return null;
+    }
+}
+/** A JSON file of the delivery, or `null` — no fetch, no file, not JSON. */
+async function readJson(fetchFile, url) {
+    if (!fetchFile)
+        return null;
+    try {
+        const resp = await fetchFile(url);
+        return resp.ok ? await resp.json() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The delivery's manifest, or `null` for a delivery that did not ship the avatar. */
+export const readManifest = async (fetchFile, place) => avatarManifestOf(await readJson(fetchFile, place.manifest));
+/** The canvas the avatar is drawn on: the bottom right, in front of the screen, watched and never operated. */
+export function avatarCanvas(doc, title) {
+    const canvas = doc.createElement('canvas');
+    canvas.setAttribute('role', 'img');
+    canvas.setAttribute('aria-label', title);
+    canvas.tabIndex = -1; // the keyboard stays with the game
+    canvas.hidden = true;
+    Object.assign(canvas.style, {
+        position: 'fixed', right: '0', bottom: '0', width: 'max(25vw, 200px)', height: 'max(50vh, 200px)', border: '0',
+        background: 'transparent', pointerEvents: 'none', zIndex: '2147483000',
+    });
+    doc.body.append(canvas);
+    return canvas;
+}
+const reasonOf = (failure) => (failure instanceof Error ? failure.message : String(failure));
+async function build(canvas, o, wanted) {
+    const { fetchFile } = o; // called bare, as `FetchFile` says
+    if (!fetchFile)
+        return { reason: NOT_SHIPPED };
+    try {
+        const resp = await fetchFile(o.avatarUrl);
+        if (!resp.ok) {
+            return { reason: `the Libras avatar could not be read from the delivery (HTTP ${resp.status}) — build it again with `
+                    + '`inclusionist-heavy <folder> --libras`' };
+        }
+        const stage = await o.loadStage(canvas, await resp.arrayBuffer());
+        if (!wanted()) {
+            stage.dispose();
+            return { reason: RELEASED };
+        } // given up on or released meanwhile: nothing is kept
+        return { stage };
+    }
+    catch (failure) {
+        return { reason: `the Libras avatar cannot be drawn here: ${reasonOf(failure)}` };
+    }
+}
+/**
+ * Builds the stage on `canvas` from the delivery's avatar: the stage, or why not — an avatar the delivery cannot give, a device
+ * that cannot draw it, a load past `timeoutMs`. `wanted()` is asked when the stage arrives: false, and it is released at once.
+ * `cancel()` answers «released» now and clears the timer, so nothing of a released root outlives it.
+ */
+export function openAvatar(canvas, o, wanted) {
+    let answer = () => { };
+    const stopped = new Promise((resolve) => { answer = resolve; });
+    const timer = o.win.setTimeout(() => {
+        answer({ reason: `the Libras avatar did not load within ${Math.round(o.timeoutMs / 1000)} s` });
+    }, o.timeoutMs);
+    const done = Promise.race([build(canvas, o, wanted), stopped]).then((r) => { o.win.clearTimeout(timer); return r; });
+    return { done, cancel: () => { o.win.clearTimeout(timer); answer({ reason: RELEASED }); } };
+}
+const isClipJson = (data) => {
+    const c = data;
+    return !!c && typeof c.duration === 'number' && Array.isArray(c.tracks);
+};
+/**
+ * A clip's address under the avatar's folder, SPELLED AS A URL SPELLS ITS NAME — which is the address the delivery's list keeps it
+ * under offline (`libras/offline-avatar.json`, ADR-0234 phase B3). Escaping the name first (`&` as `%26`, as `encodeURIComponent`
+ * does) asks another address, which the server answers online and the checked cache never holds: PRIMEIRO&ORDINAL and
+ * SEGUNDO&ORDINAL went unsigned offline. 📌 No clip name carries `%`, `#`, `?` or `\`, which a URL reads as something other than
+ * a name — `tests/libras-avatar-delivery.node.test.js` holds that over the pins.
+ */
+const clipAddress = (file, folder) => new URL(file, folder).href;
+/**
+ * Makes each clip of `names` playable on `stage`, fetching the ones it has not got — once each, remembered in `ready` — and
+ * answers the names whose file could not be read or prepared.
+ */
+export async function prepareClips(stage, names, manifest, place, fetchFile, ready) {
+    const one = async (name) => {
+        const w = manifest.clips.get(name);
+        if (!w)
+            return false;
+        const json = await readJson(fetchFile, clipAddress(w.file, place.folder));
+        if (!isClipJson(json))
+            return false;
+        try {
+            stage.prepare(name, json, w.from);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const read = await Promise.all(names.map((name) => {
+        let loading = ready.get(name);
+        if (!loading) {
+            loading = one(name);
+            ready.set(name, loading);
+        }
+        return loading;
+    }));
+    return names.filter((_, i) => !read[i]);
+}