@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/help-panel.js

@@ -31,7 +31,7 @@ import { ACTIONS } from '../core/actions.js';
  * on-screen legend. A help screen ordered by whatever order the game happened to write its object in would
  * teach a different order from every other surface.
  *
- * @param preset  what this game declares — positions, words, hints.
+ * @param preset  this game's positions and their words, RESOLVED now in the page's language (`core/actions.wordsOf`).
  * @param keysOf  the codes bound to a position FOR THIS SEAT. `kbFor(seat)[action]`, so a child who remapped
  *                sees her own key. `null`/empty means the keyboard does not reach it.
  * @param keyName code → readable label (`ui/settings-controls.keyName`), injected so this half stays pure.
@@ -57,6 +57,16 @@ export function helpRows(preset, keysOf, keyName) {
 }
 /** What the slide says where the keyboard reaches nothing. A KEY, not a sentence — the caller translates it. */
 export const NO_KEY = 'help.noKey';
+/**
+ * The cartridge's slides, their texts resolved NOW through `word` (`Translator.word`). A slide whose text the game's
+ * dictionaries lack is left out — never shown as its key — and `problems` names it (`ui/declared-words`).
+ */
+export function playSlidesOf(slides, word) {
+    return slides.flatMap((s) => {
+        const text = word(s.textKey);
+        return text ? [{ text, ...(s.figure ? { figure: s.figure } : {}) }] : [];
+    });
+}
 /** Why a `howToPlay` declaration is malformed; empty when well formed. Absent is well formed: the help shows the buttons alone. */
 export function howToPlayProblems(slides) {
     if (slides === undefined)
@@ -70,14 +80,14 @@ export function howToPlayProblems(slides) {
             out.push(`${at} must be a slide`);
             return;
         }
-        if (typeof s.text !== 'function')
-            out.push(`${at}.text must be a function returning the slide's text, in the page's language`);
+        if (typeof s.textKey !== 'string' || !s.textKey.trim())
+            out.push(`${at}.textKey must name the slide's text by a key of the game's dictionary`);
         if (s.figure !== undefined && typeof s.figure !== 'function')
             out.push(`${at}.figure must be a function drawing on the surface it is given`);
     });
     return out;
 }
-const isFromGame = (s) => typeof s.text === 'function';
+const isFromGame = (s) => typeof s.text === 'string';
 /**
  * Draws the shown slide's figure, and keeps drawing it while the slide show is in the document and the same slide is shown.
  * Returns a stop. A figure that throws is a cartridge defect: it stops drawing and the text stays.
@@ -208,7 +218,7 @@ function showPlaySlide(p, r) {
     p.figure.hidden = !r.figure;
     p.keyCap.hidden = true;
     p.word.hidden = true;
-    const phrase = r.text();
+    const phrase = r.text;
     p.text.textContent = phrase;
     p.text.hidden = false;
     return joinParts([phrase]);

package/dist-pkg/ui/hud-bands.d.ts

@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Speakable } from '../core/contract.js';
-import type { Translate } from '../core/i18n.js';
+import type { Translator } from '../core/i18n.js';
 export type HudBand = 'identity' | 'mission' | 'power' | 'learning';
 /**
  * A skill's bar, as `educational/segment-bar.barOf` returns it — the same field names and values, so its `Bar` passes
@@ -12,8 +11,8 @@ export interface HudBar {
 }
 export type HudNumber = {
     readonly band: 'identity' | 'mission' | 'power';
-    /** What is counted, in the interface language («points», «balls»). */
-    readonly name: Speakable;
+    /** The key of what is counted («points», «balls») in the game's dictionary. */
+    readonly nameKey: string;
     /** A count, or how many of how many, for seat `seat`. Read on every animation frame while mounted: keep it cheap. */
     readonly value: (seat: number) => number | {
         readonly have: number;
@@ -21,25 +20,43 @@ export type HudNumber = {
     };
 } | {
     readonly band: 'learning';
-    /** The skill, in the interface language. */
-    readonly name: Speakable;
+    /** The key of the skill's name in the game's dictionary. */
+    readonly nameKey: string;
     readonly value: (seat: number) => HudBar;
 };
+/** What the HUD asks of the root's translator: the engine's frames, and the game's declared words. */
+type HudTranslator = Pick<Translator, 't' | 'word'>;
 /** Why a `hud` declaration is malformed; empty when it is well formed. Absent is well formed: no HUD is mounted. */
 export declare function hudNumbersProblems(numbers: unknown): string[];
+/** The HUD row's cells the bands go into (`ui/hud-row`, ADR-0239). */
+export interface HudRowSlots {
+    readonly learning: HTMLElement;
+    readonly score: HTMLElement;
+}
 export interface HudBandsMounted {
-    /** The top-left column: identity, then mission. */
+    /** The mission, at the top centre under the quick bar (the name is from when it sat top left). */
     readonly left: HTMLElement;
-    /** The top-right column: power (under the clock, when #94 builds it). */
+    /** The power in use, above the score. */
     readonly right: HTMLElement;
+    /** The identity numbers — the score — in five digits (ADR-0238). */
+    readonly points: HTMLElement;
     readonly learning: HTMLElement;
     /** Rewrites what changed; `true` when a text at the top did, so the caller measures the room again. */
     refresh(): boolean;
     remove(): void;
 }
 /**
- * Mounts the two top columns and the footer bars in the game region, one element per declared number, and fills them. A
- * column with no number is hidden. The learning band goes in BEFORE the screen footer when one exists, so the explanation band, drawn later on the
- * same layer, covers it.
+ * A count as FIVE DIGITS WITH LEADING ZEROS, clamped to 0…99999 (ADR-0238): 12 is «00012». `shown` is the number those digits
+ * say, which is what a listener hears — the same number a sighted child sees, never the zeros.
+ */
+export declare function fiveDigits(count: number): {
+    readonly digits: string;
+    readonly shown: number;
+};
+/**
+ * Mounts the bands, one element per declared number, and fills them: the mission in the game region, the rest in the HUD
+ * row's cells (`row`). A place with no number is hidden. Without a row every band goes in the region itself — the learning
+ * band BEFORE the screen footer when one exists, so the explanation band, drawn later on the same layer, covers it.
  */
-export declare function mountHudBands(t: Translate, doc: Document, region: HTMLElement, numbers: readonly HudNumber[], seat?: number): HudBandsMounted;
+export declare function mountHudBands(tr: HudTranslator, doc: Document, region: HTMLElement, numbers: readonly HudNumber[], seat?: number, row?: HudRowSlots): HudBandsMounted;
+export {};

package/dist-pkg/ui/hud-bands.js

@@ -13,8 +13,8 @@ export function hudNumbersProblems(numbers) {
     numbers.forEach((n, i) => {
         if (!n || !HUD_BANDS.includes(n.band))
             out.push(`hud[${i}].band must be one of ${HUD_BANDS.join(', ')}`);
-        if (!n || typeof n.name?.text !== 'string' || !n.name.text.trim())
-            out.push(`hud[${i}].name.text must say what is counted`);
+        if (!n || typeof n.nameKey !== 'string' || !n.nameKey.trim())
+            out.push(`hud[${i}].nameKey must name what is counted by a key of the game's dictionary`);
         if (!n || typeof n.value !== 'function')
             out.push(`hud[${i}].value must be a function of the seat`);
     });
@@ -23,12 +23,29 @@ export function hudNumbersProblems(numbers) {
         out.push(`hud declares ${bars} learning bars: at most ${MAX_BARS}, one per skill the adult enabled (ADR-0049 §5)`);
     return out;
 }
-/** What the child reads, or hears on the bar: the frame in the dictionary, the name through a parameter (pillar 3). */
-function numberText(t, n, seat) {
+/** The highest count five digits hold; a larger score is shown as this (ADR-0238). */
+const MAX_POINTS = 99_999;
+/**
+ * A count as FIVE DIGITS WITH LEADING ZEROS, clamped to 0…99999 (ADR-0238): 12 is «00012». `shown` is the number those digits
+ * say, which is what a listener hears — the same number a sighted child sees, never the zeros.
+ */
+export function fiveDigits(count) {
+    const shown = Math.min(MAX_POINTS, Math.max(0, Math.floor(count) || 0));
+    return { digits: String(shown).padStart(5, '0'), shown };
+}
+/**
+ * What the child reads, and — for the points — what a listener hears instead (`label`): the frame in the dictionary, the name
+ * — resolved from the game's key at this refresh (ADR-0232 D3) — through a parameter (pillar 3). A count of objectives keeps
+ * its «3 of 10» wherever it is declared.
+ */
+function lineFace(t, name, n, seat) {
     const v = n.value(seat);
-    return typeof v === 'number'
-        ? t('hud.numero', { nome: n.name.text, valor: String(v) })
-        : t('hud.contador', { have: String(v.have), need: String(v.need), nome: n.name.text });
+    if (typeof v !== 'number')
+        return { text: t('hud.contador', { have: String(v.have), need: String(v.need), nome: name }), label: null };
+    if (n.band !== 'identity')
+        return { text: t('hud.numero', { nome: name, valor: String(v) }), label: null };
+    const { digits, shown } = fiveDigits(v);
+    return { text: digits, label: t('hud.points', { count: String(shown), name }) };
 }
 function barLabel(t, name, bar) {
     const count = (c) => String(bar.segmentos.filter((s) => s === c).length);
@@ -36,11 +53,12 @@ function barLabel(t, name, bar) {
     return bar.cor === 'roxa' ? `${base}. ${t('hud.barra.sobe')}` : bar.cor === 'laranja' ? `${base}. ${t('hud.barra.desce')}` : base;
 }
 /**
- * Mounts the two top columns and the footer bars in the game region, one element per declared number, and fills them. A
- * column with no number is hidden. The learning band goes in BEFORE the screen footer when one exists, so the explanation band, drawn later on the
- * same layer, covers it.
+ * Mounts the bands, one element per declared number, and fills them: the mission in the game region, the rest in the HUD
+ * row's cells (`row`). A place with no number is hidden. Without a row every band goes in the region itself — the learning
+ * band BEFORE the screen footer when one exists, so the explanation band, drawn later on the same layer, covers it.
  */
-export function mountHudBands(t, doc, region, numbers, seat = 0) {
+export function mountHudBands(tr, doc, region, numbers, seat = 0, row) {
+    const { t } = tr;
     const band = (cls, count) => {
         const el = doc.createElement('div');
         el.className = `hud-faixa ${cls}`;
@@ -49,17 +67,17 @@ export function mountHudBands(t, doc, region, numbers, seat = 0) {
     };
     const texts = numbers.filter((n) => n.band !== 'learning');
     const bars = numbers.filter((n) => n.band === 'learning');
-    // the identity lines first and the mission under them, whatever order the game declared them in
-    const leftTexts = [...texts.filter((n) => n.band === 'identity'), ...texts.filter((n) => n.band === 'mission')];
-    const rightTexts = texts.filter((n) => n.band === 'power');
-    const left = band('hud-esquerda', leftTexts.length);
-    const right = band('hud-direita', rightTexts.length);
+    const ofBand = (b) => texts.filter((n) => n.band === b);
+    const left = band('hud-esquerda', ofBand('mission').length);
+    const right = band('hud-direita', ofBand('power').length);
+    const points = band('hud-points', ofBand('identity').length);
     const learning = band('hud-aprendizagem', bars.length);
-    const lines = [...leftTexts, ...rightTexts].map((n) => {
+    const place = { identity: points, mission: left, power: right };
+    const lines = texts.map((n) => {
         const p = doc.createElement('p');
         p.className = 'hud-numero';
         p.dataset.band = n.band;
-        (n.band === 'power' ? right : left).appendChild(p);
+        place[n.band].appendChild(p);
         return [n, p];
     });
     const bardivs = bars.map((n) => {
@@ -72,21 +90,40 @@ export function mountHudBands(t, doc, region, numbers, seat = 0) {
         return [n, div];
     });
     region.appendChild(left);
-    region.appendChild(right);
-    region.insertBefore(learning, [...region.children].find((c) => c.classList.contains('rodape-da-tela')) ?? null);
+    // the power ABOVE the score (ADR-0239 point 3): the order of the two in their cell is the order on screen
+    (row?.score ?? region).append(right, points);
+    if (row)
+        row.learning.appendChild(learning);
+    else
+        region.insertBefore(learning, [...region.children].find((c) => c.classList.contains('rodape-da-tela')) ?? null);
     function refresh() {
         let changed = false;
         for (const [n, p] of lines) {
-            const text = numberText(t, n, seat);
-            if (p.textContent !== text) {
-                p.textContent = text;
+            // a name the game's dictionaries lack hides its line — never its key on screen (`problems` names it)
+            const name = tr.word(n.nameKey);
+            if (p.hidden !== !name) {
+                p.hidden = !name;
                 changed = true;
             }
+            const face = name ? lineFace(t, name, n, seat) : { text: '', label: null };
+            if (p.textContent !== face.text) {
+                p.textContent = face.text;
+                changed = true;
+            }
+            // the points are an image of a number for a listener: the name says «12 points», never «zero zero zero one two»
+            if (face.label !== null && p.getAttribute('aria-label') !== face.label) {
+                p.setAttribute('role', 'img');
+                p.setAttribute('aria-label', face.label);
+            }
         }
         for (const [n, div] of bardivs) {
+            const name = tr.word(n.nameKey);
+            div.hidden = !name;
+            if (!name)
+                continue;
             const bar = n.value(seat);
             const shown = bar.segmentos.slice(-SEGMENTS);
-            const label = barLabel(t, n.name.text, { segmentos: shown, cor: bar.cor }); // in the key: a language change rewrites it
+            const label = barLabel(t, name, { segmentos: shown, cor: bar.cor }); // in the key: a language change rewrites it
             const key = `${bar.cor}:${shown.join(',')}:${label}`;
             if (div.dataset.estado === key)
                 continue;
@@ -101,8 +138,9 @@ export function mountHudBands(t, doc, region, numbers, seat = 0) {
     return {
         left,
         right,
+        points,
         learning,
         refresh,
-        remove: () => { left.remove(); right.remove(); learning.remove(); },
+        remove: () => { left.remove(); points.remove(); right.remove(); learning.remove(); },
     };
 }

package/dist-pkg/ui/hud-row.d.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The row's cells, each a place something else fills: the bands (`ui/hud-bands`), the clock (`ui/session-clock`), the map. */
+export interface HudRow {
+    readonly row: HTMLElement;
+    /** Bottom left: the learning bars. */
+    readonly learning: HTMLElement;
+    /** Bottom centre: the session clock. */
+    readonly clock: HTMLElement;
+    /** Between the centre and the right: the power above the score. */
+    readonly score: HTMLElement;
+    /** Bottom right: where a game mounts its own map. Empty, it is not drawn (ADR-0239 point 4). */
+    readonly map: HTMLElement;
+}
+/**
+ * Builds the row in `region`, BEFORE the screen footer when one exists, so the explanation band — drawn later on the same
+ * layer — covers it. `null` where the region takes no children.
+ */
+export declare function mountHudRow(doc: Document, region: HTMLElement | null): HudRow | null;
+/** What `reserveBottomBand` measures. The pad is the on-screen controller (`#touch-controls`), when the page has one. */
+export interface BottomBandCtx {
+    readonly region: HTMLElement | null;
+    readonly row: HTMLElement | null;
+    readonly pad: HTMLElement | null;
+}
+/**
+ * THE ROW FOLLOWS THE PAD AT ONCE (ADR-0239 §6): `measure` runs again whenever the on-screen pad under `host` shows, hides or is
+ * rebuilt, by whichever door — a touch, a key, a menu opening or closing (ADR-0166), a new cartridge. A resize and the session
+ * clock's tick are not enough: between them the row stood behind the pad for up to a second, and the explanation band that
+ * stands where the row stands lay over the pad's START pill. A mutation observer answers before the next frame is drawn.
+ * Returns what stops it; nothing is watched where the host has no observer.
+ */
+export declare function followThePad(host: Node | null, Observer: typeof MutationObserver | undefined, measure: () => void): () => void;
+/** Measures the bottom and writes `--hud-row-bottom` and `--hud-row-h` on the region (see the header). */
+export declare function reserveBottomBand(ctx: BottomBandCtx): void;

package/dist-pkg/ui/hud-row.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/hud-row — THE HUD IS ONE ROW AT THE BOTTOM of the game region (ADR-0239; issue #94), and this module builds the row's
+// cells and measures the room it takes.
+//
+// Left to right: the learning bars · the session clock, in the centre · the score, with the power above it · the game's map.
+// The mission is not here: it sits at the top centre, just under the quick bar (ADR-0239 erratum; `ui/top-band`).
+//
+// WHO SITS OVER WHOM at the bottom (ADR-0239 point 6), written as two variables on the region that the stylesheet reads:
+//   · `--hud-row-bottom` — how far above the region's lower edge the row stands: 0, or the height of the on-screen pad's
+//     lower parts while the pad shows, so the row sits ABOVE the pad;
+//   · `--hud-row-h` — the row's own height, so the sound caption and the button legend sit above it, and a game's workspace
+//     ends above it: `--rodape-h` is these two and nothing else, because the caption and the legend are momentary and
+//     overlay the workspace while they show (ADR-0239 erratum).
+// The explanation band covers the row while a menu is open: that is the stylesheet's alone.
+//
+// ⚠️ IT RECEIVES THE NODES and reaches no global (ADR-0232), like `ui/top-band`.
+/**
+ * Builds the row in `region`, BEFORE the screen footer when one exists, so the explanation band — drawn later on the same
+ * layer — covers it. `null` where the region takes no children.
+ */
+export function mountHudRow(doc, region) {
+    if (!region || typeof region.insertBefore !== 'function')
+        return null;
+    const cell = (cls) => { const el = doc.createElement('div'); el.className = cls; return el; };
+    const row = cell('hud-row');
+    const learning = cell('hud-row-cell hud-row-learning');
+    const clock = cell('hud-row-cell hud-row-clock');
+    const end = cell('hud-row-cell hud-row-end');
+    const score = cell('hud-score');
+    const map = cell('hud-map');
+    end.appendChild(score);
+    end.appendChild(map);
+    for (const c of [learning, clock, end])
+        row.appendChild(c);
+    // `children` may be missing in a host double; then there is no footer to go before
+    region.insertBefore(row, Array.from(region.children ?? []).find((c) => c.classList.contains('rodape-da-tela')) ?? null);
+    return { row, learning, clock, score, map };
+}
+/** A pad part counts when it stands on the region's lower edge — within this many pixels of it. */
+const ON_THE_EDGE_PX = 24;
+/** How high the pad's lower parts reach above the region's lower edge while the pad shows; 0 when it is hidden or absent. */
+function padReach(pad, regionBottom) {
+    if (!pad || pad.hidden)
+        return 0;
+    let reach = 0;
+    for (const part of [...pad.children]) {
+        const b = part.getBoundingClientRect();
+        if (b.height > 0 && regionBottom - b.bottom <= ON_THE_EDGE_PX)
+            reach = Math.max(reach, regionBottom - b.top);
+    }
+    return reach;
+}
+/** The pad, or a part of it, in a mutation: its `hidden` changed, its parts were rebuilt, or it came or went. */
+function aboutThePad(r) {
+    return [r.target, ...Array.from(r.addedNodes), ...Array.from(r.removedNodes)].some((n) => !!n.closest?.('#touch-controls'));
+}
+/**
+ * THE ROW FOLLOWS THE PAD AT ONCE (ADR-0239 §6): `measure` runs again whenever the on-screen pad under `host` shows, hides or is
+ * rebuilt, by whichever door — a touch, a key, a menu opening or closing (ADR-0166), a new cartridge. A resize and the session
+ * clock's tick are not enough: between them the row stood behind the pad for up to a second, and the explanation band that
+ * stands where the row stands lay over the pad's START pill. A mutation observer answers before the next frame is drawn.
+ * Returns what stops it; nothing is watched where the host has no observer.
+ */
+export function followThePad(host, Observer, measure) {
+    if (!host || typeof Observer !== 'function')
+        return () => { };
+    const observer = new Observer((records) => { if (records.some(aboutThePad))
+        measure(); });
+    observer.observe(host, { attributes: true, attributeFilter: ['hidden'], childList: true, subtree: true });
+    return () => observer.disconnect();
+}
+/** Measures the bottom and writes `--hud-row-bottom` and `--hud-row-h` on the region (see the header). */
+export function reserveBottomBand(ctx) {
+    const { region, row } = ctx;
+    if (!region || !row || typeof region.getBoundingClientRect !== 'function')
+        return;
+    const lift = Math.ceil(padReach(ctx.pad, region.getBoundingClientRect().bottom));
+    region.style.setProperty('--hud-row-bottom', `${lift}px`);
+    region.style.setProperty('--hud-row-h', `${Math.ceil(row.getBoundingClientRect().height)}px`);
+}

package/dist-pkg/ui/hud.d.ts

@@ -3,15 +3,12 @@ import type { PlayerView } from '../core/entity.js';
 import type { Objective } from '../core/contract.js';
 import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
 /** Only the player fields the HUD reads. Structural on purpose: the real `players[]` is `unknown[]` in core/state. */
 /** What the HUD reads from the PLAYER: the active power and whether they quit. Progress comes from the `Objective`,
  *  not from here. */
 export type HudPlayer = PlayerView<'activePower' | 'quit'>;
 /** Screen grid: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (the 3rd screen is centred on the bottom row). */
 export { screenGrid } from '../core/screens.js';
-export type { ScreenGrid } from '../core/screens.js';
 /** Screen `i`'s rectangle in CSS percentages, ready for `style.left/top/width/height`. */
 export interface ScreenRect {
     L: string;

package/dist-pkg/ui/layout.js

@@ -4,8 +4,8 @@
 // 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.
 //
-// IT RESERVES NO SPACE FOR THE INTERPRETER: the Dev decided the interpreter appears IN FRONT of the screen while audio
-// plays, and disappears (see ui/vlibras), so the layout does not shift the game for it.
+// 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';
 /**
  * THE TOUCH TARGET FLOOR, in CSS px, for a CSS scale factor `k` (ADR-0163).
@@ -93,6 +93,9 @@ export function applyScale(region, e) {
     // 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');
 }
 /**
  * Builds a stage scaler over the document and window it is handed. It keeps nothing between calls: every `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[]>;