@the-inclusionist/engine 10.0.0 → 11.0.0

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>;

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

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-avatar-stage — THE FREE PLAYER'S STAGE: three.js, the avatar and its clips (ADR-0234, route B, phase B2).
+//
+// 📌 THE ONLY MODULE THAT NAMES three.js, and it is reached only by the dynamic `import()` in `ui/libras-avatar-player`, at the
+// first sign in deaf mode (ADR-0234 errata): a child who never turns deaf mode on never downloads three.js. three.js 0.186.1,
+// MIT, a runtime `dependency` pinned to that exact version; the types are `three-subset.d.ts`, beside this file.
+//
+// WHAT IT DOES: parses the delivery's `avatar.glb` (GLTFLoader, from the bytes the player fetched — no loader fetches anything),
+// frames the signing space, and plays clips on one `AnimationMixer`, each once, its last frame held. Two things the export
+// hands over are answered here and not hidden:
+//   · the face: a morph track names the head's node, which three.js loads as a group of two meshes — `bindFaceTracks` writes
+//     it once for each mesh that carries the targets;
+//   · the bones a clip does not move: the export dropped the tracks at the avatar's rest, so a clip that follows one that moved
+//     them must bring them back. The mixer does it: a property no running clip drives is blended back to the value it had when
+//     it was first bound — the avatar's rest, since nothing else ever poses it — and an action whose fade-out ended is stopped,
+//     which restores it outright (`tests/libras-avatar.browser.test.js` holds it).
+//
+// 🔴 TEXTURES ARE DECODED HERE, NOT BY THE LOADER'S OWN IMAGE LOADER: three.js reads an embedded image by `fetch`ing a `blob:`
+// URL, which the delivery's `connect-src 'self'` refuses. `createImageBitmap` over the bytes fetches nothing, and it is also
+// where the avatar's 2048² textures are brought down to `TEXTURE_SIZE` — the interpreter is a few hundred pixels tall.
+import { AnimationClip, AnimationMixer, Box3, DirectionalLight, HemisphereLight, LoopOnce, PerspectiveCamera, Scene, Vector3, WebGLRenderer, } from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { bindFaceTracks, clipFrom } from './libras-avatar-clip.js';
+/**
+ * The longest side a texture keeps, in pixels. 📏 The export's head and body textures are 2048² each: 16 MiB of pixels apiece
+ * once decoded, 21 with mipmaps; at 1024² a quarter of that. The avatar is drawn a few hundred pixels tall.
+ */
+const TEXTURE_SIZE = 1024;
+const isMesh = (o) => o.isMesh === true;
+/** The loader's texture step, replaced: the embedded image decoded from its bytes (no `blob:` fetch), then brought down to `size`. */
+function decodedTextures(size) {
+    return (parser) => ({
+        name: 'incl_decoded_textures',
+        loadTexture: (textureIndex) => {
+            const texture = parser.json.textures?.[textureIndex];
+            const source = texture?.source;
+            const image = source === undefined ? undefined : parser.json.images?.[source];
+            if (source === undefined || image?.bufferView === undefined)
+                return null; // not embedded: the loader's own path
+            return parser.getDependency('bufferView', image.bufferView).then(async (bytes) => {
+                const blob = new Blob([bytes], { type: image.mimeType ?? 'image/png' });
+                let bitmap = await createImageBitmap(blob, { premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
+                const scale = Math.min(1, size / Math.max(bitmap.width, bitmap.height));
+                if (scale < 1) {
+                    const full = bitmap;
+                    bitmap = await createImageBitmap(full, {
+                        premultiplyAlpha: 'none', colorSpaceConversion: 'none', resizeQuality: 'high',
+                        resizeWidth: Math.max(1, Math.round(full.width * scale)), resizeHeight: Math.max(1, Math.round(full.height * scale)),
+                    });
+                    full.close();
+                }
+                const decoded = bitmap;
+                return parser.loadTextureImage(textureIndex, source, {
+                    isImageBitmapLoader: true,
+                    load: (_url, onLoad) => { onLoad(decoded); },
+                });
+            });
+        },
+    });
+}
+/**
+ * The meshes a morph track on each node must reach: for a node that is not itself a mesh with morph targets but holds meshes
+ * that have them (the head, loaded as a group of two), their uuids — three.js binds a track by uuid as well as by name.
+ */
+function faceMeshes(root) {
+    const out = new Map();
+    root.traverse((node) => {
+        if (isMesh(node) && node.morphTargetDictionary)
+            return;
+        const meshes = node.children.filter((c) => isMesh(c) && !!c.morphTargetDictionary).map((c) => c.uuid);
+        if (meshes.length && node.name)
+            out.set(node.name, meshes);
+    });
+    return out;
+}
+/**
+ * The signing space, framed on the head (the mesh with morph targets): from just above it to below the waist, where Libras signs
+ * are made. 📏 Tuned on the export's avatar (screenshot of 2026-09-25): its head mesh runs from the hair's base to the neck, and
+ * 1.45 of its heights below it is a little under the belt — the face about a quarter of the frame's height.
+ */
+function frame(root, camera) {
+    root.updateMatrixWorld(true);
+    const face = new Box3();
+    root.traverse((node) => { if (isMesh(node) && node.morphTargetDictionary)
+        face.expandByObject(node); });
+    const box = face.isEmpty() ? new Box3().setFromObject(root) : face;
+    const center = box.getCenter(new Vector3());
+    const head = box.getSize(new Vector3()).y || 1;
+    const top = box.max.y + 0.15 * head;
+    const bottom = box.min.y - 1.45 * head;
+    const middle = (top + bottom) / 2;
+    const tall = top - bottom;
+    const fov = 30;
+    const distance = (tall / 2) / Math.tan((fov / 2) * Math.PI / 180);
+    camera.position.set(center.x, middle, box.max.z + distance);
+    camera.lookAt(center.x, middle, center.z);
+    camera.updateProjectionMatrix();
+}
+/**
+ * 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 async function createAvatarStage({ canvas, avatar, textureSize = TEXTURE_SIZE }) {
+    const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: true, powerPreference: 'low-power' });
+    renderer.setClearColor(0x000000, 0);
+    let root;
+    try {
+        const loader = new GLTFLoader().register(decodedTextures(textureSize));
+        root = (await loader.parseAsync(avatar, '')).scene;
+    }
+    catch (failure) {
+        renderer.dispose();
+        renderer.forceContextLoss();
+        throw failure;
+    }
+    const scene = new Scene();
+    const camera = new PerspectiveCamera(30, 1, 0.05, 200);
+    const sky = new HemisphereLight(0xffffff, 0x8a8a9a, 2.2);
+    const key = new DirectionalLight(0xffffff, 1.6);
+    key.position.set(2, 6, 10);
+    scene.add(root, sky, key);
+    frame(root, camera);
+    const mixer = new AnimationMixer(root);
+    const meshesOf = faceMeshes(root);
+    /** Each clip twice: the same sign signed twice in a row fades into its own copy, not into itself. */
+    const clips = new Map();
+    let current = null;
+    /** Actions fading out or held: stopped once their weight reaches nothing, which returns what they drove to rest. */
+    const leaving = new Set();
+    const draw = () => { renderer.render(scene, camera); };
+    return {
+        scene: root,
+        prepare: (name, json, from) => {
+            const bound = bindFaceTracks(clipFrom(json, from), (node) => meshesOf.get(node) ?? null);
+            // 🔴 `AnimationClip.parse` copies the JSON's `uuid`, and the export writes none: every parsed clip has the SAME uuid
+            // (`undefined`), and the mixer keys its actions by uuid — so every clip played as the first one ever asked for. A clone
+            // is built by the constructor, which gives it a uuid of its own.
+            const clip = AnimationClip.parse(bound).clone();
+            clip.name = name;
+            clips.set(name, [clip, clip.clone()]);
+        },
+        has: (name) => clips.has(name),
+        start: (name, fade, at) => {
+            const pair = clips.get(name);
+            if (!pair)
+                return;
+            const clip = current?.getClip() === pair[0] ? pair[1] : pair[0];
+            const action = mixer.clipAction(clip);
+            leaving.delete(action);
+            action.reset();
+            action.setLoop(LoopOnce, 1);
+            action.clampWhenFinished = true;
+            action.time = at;
+            action.play();
+            if (current) {
+                if (fade > 0) {
+                    action.crossFadeFrom(current, fade, false);
+                    leaving.add(current);
+                }
+                else
+                    current.stop();
+            }
+            current = action;
+        },
+        advance: (dt) => {
+            mixer.update(dt);
+            for (const action of leaving) {
+                if (!action.enabled) {
+                    action.stop();
+                    leaving.delete(action);
+                }
+            }
+            draw();
+        },
+        resize: (width, height, pixelRatio) => {
+            renderer.setPixelRatio(pixelRatio);
+            renderer.setSize(Math.max(1, Math.round(width)), Math.max(1, Math.round(height)), false);
+            camera.aspect = width > 0 && height > 0 ? width / height : 1;
+            camera.updateProjectionMatrix();
+            draw();
+        },
+        stats: () => ({
+            textures: renderer.info.memory.textures, geometries: renderer.info.memory.geometries,
+            calls: renderer.info.render.calls, triangles: renderer.info.render.triangles,
+        }),
+        dispose: () => {
+            mixer.stopAllAction();
+            mixer.uncacheRoot(root);
+            root.traverse((node) => {
+                if (!isMesh(node))
+                    return;
+                node.geometry.dispose();
+                for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+                    for (const value of Object.values(material)) {
+                        const texture = value;
+                        if (texture?.isTexture) {
+                            texture.dispose?.();
+                            texture.image?.close?.();
+                        }
+                    }
+                    material.dispose();
+                }
+            });
+            renderer.dispose();
+            renderer.forceContextLoss();
+        },
+    };
+}

package/dist-pkg/ui/libras-glosses.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The file the delivery writes beside the avatar (`LIBRAS_AVATAR_FOLDER`), read by the interpreter. */
+export declare const LIBRAS_GLOSSES_FILE = "glosses.json";
+/** The file's shape. `glosses` holds `[text, gloss]` pairs; a text with `{name}` holes is a template, its gloss has them too. */
+export interface GlossFile {
+    readonly format: 1;
+    /** What made the glosses, e.g. `vlibras-translator 1.3.3 (rules) · pt_core_news_md 3.8.0`. For whoever reads the file. */
+    readonly made: string;
+    readonly glosses: readonly (readonly [text: string, gloss: string])[];
+}
+/** The text a player is handed for a text on screen. */
+export type Glosser = (text: string) => string;
+/**
+ * The text as the player is handed it where no gloss is known: its words in capitals, accents stripped but Ç kept, anything
+ * that is not a letter or a digit a separator. Not a gloss — see the header. The marks are stripped from each run of text
+ * with no Ç in it: Ç is the only letter with a mark that the manual alphabet signs as itself.
+ */
+export declare function provisionalGloss(text: string): string;
+/**
+ * The glosser over a delivered file: known texts and templates first, today's rule for what neither covers. A file that is not
+ * the delivery's (`null`, a fallback page, another format) glosses nothing, and every text gets today's rule.
+ */
+export declare function glosserOf(data: unknown): Glosser;
+/**
+ * The glosser of the delivery the page came from: `glosses.json` read through `fetchFile`, or — no fetch, no file, not the
+ * delivery's — today's rule for every text. Never rejects: a missing file costs the glosses, not the signing.
+ */
+export declare function loadGlosser(fetchFile: ((url: string) => Promise<Response>) | undefined, url: string): Promise<Glosser>;

package/dist-pkg/ui/libras-glosses.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/libras-glosses — WHAT THE INTERPRETER HANDS THE PLAYER: the Libras gloss of the text the sonar found (ADR-0234, plan
+// item 5b).
+//
+// The player signs a GLOSS — Libras word order, in sign names — and the sonar finds Portuguese. Translating needs spaCy's full
+// Portuguese parser, which does not run in a browser, and it does not have to: the text a child can be shown is AUTHORED, so the
+// delivery glosses it once, at build time, with LAViD's rule-based `vlibras-translator` (`scripts/libras-glosses.mjs`, run by
+// `inclusionist-heavy --libras`), and writes `glosses.json` beside the avatar. At run time nothing is translated: the text is
+// LOOKED UP here.
+//
+// WHAT IS IN THE FILE: the engine's own Portuguese dictionary, and the game's when its delivery names it (`--libras-texts`).
+// A string with `{param}` holes is kept as a TEMPLATE, glossed with its holes in place (`JOGADOR {n} ENTRAR [EXCLAMAÇÃO]`),
+// because the value arrives only at run time: here the value is looked up in turn, and a value with no gloss of its own — a
+// number, a name — is handed over by today's rule below, which the player fingerspells letter by letter.
+//
+// HOW A SCREEN IS LOOKED UP: the sonar reads the screen as sentences (`ui/screen-text`, one per line, joined), so the text is
+// cut at sentence ends and, from the first sentence on, the LONGEST run of sentences that is a known text or matches a template
+// is taken — a dictionary string may itself hold two sentences, or a colon the reader cut at. A sentence nothing matches falls
+// back to today's rule, alone; the rest of the screen keeps its glosses.
+//
+// 📌 TODAY'S RULE (`provisionalGloss`), which stays the fallback: the words in capitals with the accents stripped, anything that
+// is not a letter or a digit a separator. Not a gloss — the player fingerspells it — and the accents go because the player has
+// no clip for an accented letter (the avatar's alphabet is A–Z and Ç, `scripts/libras-avatar.json`). Ç IS KEPT: it is a letter of
+// the Libras manual alphabet, with its own handshape and movement, and the avatar carries its clip. The build spells with the same
+// rule (`scripts/libras-glosses.mjs` `spelledWord`, ADR-0234 erratum «A WORD WITH NO SIGN IS SPELLED AS IT IS WRITTEN»).
+//
+// It reaches no global: the file comes through the fetch the interpreter was given (ADR-0232).
+/** The file the delivery writes beside the avatar (`LIBRAS_AVATAR_FOLDER`), read by the interpreter. */
+export const LIBRAS_GLOSSES_FILE = 'glosses.json';
+/**
+ * The text as the player is handed it where no gloss is known: its words in capitals, accents stripped but Ç kept, anything
+ * that is not a letter or a digit a separator. Not a gloss — see the header. The marks are stripped from each run of text
+ * with no Ç in it: Ç is the only letter with a mark that the manual alphabet signs as itself.
+ */
+export function provisionalGloss(text) {
+    return text.normalize('NFC').replace(/[^Çç]+/gu, (run) => run.normalize('NFD').replace(/\p{M}+/gu, '')).toUpperCase()
+        .split(/[^\p{L}\p{N}]+/u).filter(Boolean).join(' ');
+}
+/** Where the sonar's text is cut: after a sentence's end, before the next. */
+const SENTENCE_END = /(?<=[.!?…:;])\s+/u;
+/** A hole of a template (`split` and `replace` read the capture; `HAS_HOLE` only asks). */
+const HOLE = /\{([^{}\s]+)\}/gu;
+const HAS_HOLE = /\{[^{}\s]+\}/u;
+const NUMBERED_HOLE = /\{\d+\}/gu;
+/**
+ * What a hole matches: any run of characters that does not cross a sentence's end — a template that starts or ends with a hole
+ * would otherwise swallow the sentences around it when a longer run is tried.
+ */
+const VALUE = String.raw `((?:(?![.!?…:;]\s).)+?)`;
+/** What the edges of a text may carry that does not change it: punctuation, an icon, a space. */
+const EDGES = /^[^\p{L}\p{N}{}]+|[^\p{L}\p{N}{}]+$/gu;
+/** The same text, however the screen wrote it: one space, no punctuation or icon at the edges, lower case. */
+function keyOf(text) {
+    return text.normalize('NFC').replace(/\s+/gu, ' ').replace(EDGES, '').toLocaleLowerCase('pt-BR');
+}
+const sentencesOf = (text) => text.split(SENTENCE_END).filter((s) => s.trim() !== '');
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** A template's text as a pattern over keys: its fixed parts as keys are, each hole a `VALUE`. */
+function templateOf(text, gloss) {
+    const names = [];
+    const parts = text.split(HOLE); // even indices are fixed text, odd ones hole names
+    for (let i = 1; i < parts.length; i += 2)
+        names.push(parts[i]);
+    // each hole becomes `{0}`, `{1}`…: braces survive `keyOf`, and a name's capitals would not
+    const marked = parts.map((p, i) => (i % 2 ? `{${(i - 1) / 2}}` : p)).join('');
+    const key = keyOf(marked);
+    const fixed = key.replace(NUMBERED_HOLE, '');
+    if (!/[\p{L}\p{N}]/u.test(fixed))
+        return null; // all holes: it would match anything
+    const source = key.split(NUMBERED_HOLE).map(escapeRegExp).join(VALUE);
+    return { pattern: new RegExp(`^${source}$`, 'u'), names, gloss, fixed: fixed.length };
+}
+/** Is this a file the delivery wrote? Anything else is read as no file at all. */
+function isGlossFile(data) {
+    const file = data;
+    return !!file && file.format === 1 && Array.isArray(file.glosses)
+        && file.glosses.every((g) => Array.isArray(g) && typeof g[0] === 'string' && typeof g[1] === 'string');
+}
+/**
+ * The glosser over a delivered file: known texts and templates first, today's rule for what neither covers. A file that is not
+ * the delivery's (`null`, a fallback page, another format) glosses nothing, and every text gets today's rule.
+ */
+export function glosserOf(data) {
+    const exact = new Map();
+    const templates = [];
+    let longest = 1;
+    if (isGlossFile(data)) {
+        for (const [text, gloss] of data.glosses) {
+            if (!gloss.trim())
+                continue;
+            if (HAS_HOLE.test(text)) {
+                const template = templateOf(text, gloss);
+                if (template)
+                    templates.push(template);
+            }
+            else {
+                const key = keyOf(text);
+                if (key && !exact.has(key))
+                    exact.set(key, gloss);
+            }
+            longest = Math.max(longest, sentencesOf(text).length);
+        }
+        templates.sort((a, b) => b.fixed - a.fixed);
+    }
+    /** A value put into a template's hole: its own gloss when it is a known text, else today's rule. */
+    const valueGloss = (value) => exact.get(keyOf(value)) ?? provisionalGloss(value);
+    const lookUp = (piece) => {
+        const key = keyOf(piece);
+        if (!key)
+            return null;
+        const known = exact.get(key);
+        if (known !== undefined)
+            return known;
+        for (const t of templates) {
+            const m = t.pattern.exec(key);
+            if (!m)
+                continue;
+            const values = new Map(t.names.map((name, i) => [name, valueGloss(m[i + 1])]));
+            return t.gloss.replace(HOLE, (_, name) => values.get(name) ?? '').replace(/\s+/gu, ' ').trim();
+        }
+        return null;
+    };
+    return (text) => {
+        const sentences = sentencesOf(text);
+        const out = [];
+        for (let i = 0; i < sentences.length;) {
+            let taken = 0;
+            for (let span = Math.min(longest, sentences.length - i); span >= 1 && !taken; span--) {
+                const gloss = lookUp(sentences.slice(i, i + span).join(' '));
+                if (gloss !== null) {
+                    if (gloss)
+                        out.push(gloss);
+                    taken = span;
+                }
+            }
+            if (!taken) {
+                const spelled = provisionalGloss(sentences[i]);
+                if (spelled)
+                    out.push(spelled);
+                taken = 1;
+            }
+            i += taken;
+        }
+        return out.join(' ');
+    };
+}
+/**
+ * The glosser of the delivery the page came from: `glosses.json` read through `fetchFile`, or — no fetch, no file, not the
+ * delivery's — today's rule for every text. Never rejects: a missing file costs the glosses, not the signing.
+ */
+export async function loadGlosser(fetchFile, url) {
+    if (!fetchFile)
+        return glosserOf(null);
+    try {
+        const resp = await fetchFile(url);
+        return glosserOf(resp.ok ? await resp.json() : null);
+    }
+    catch {
+        return glosserOf(null);
+    }
+}