@the-inclusionist/engine 9.0.0 → 11.0.0

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);
+    }
+}

package/dist-pkg/ui/locale-flags.d.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The locales the button cycles, in the Dev's order. */
+export declare const LOCALE_CYCLE: readonly ["pt", "en", "es"];
+export type CycleLocale = (typeof LOCALE_CYCLE)[number];
+/** The next locale of the cycle; a locale outside it starts the cycle again. */
+export declare const nextLocale: (current: string) => CycleLocale;
+/** Each language in its own words, with the place its flag stands for. */
+export declare const LANGUAGE_NAME: {
+    readonly [L in CycleLocale]: string;
+};
+/** Brazil, the United States and Mexico, simplified to icon size. */
+export declare const FLAG_SVG: {
+    readonly [L in CycleLocale]: string;
+};
+/** The flag of a locale, or Brazil's for one outside the cycle (the engine's base language). */
+export declare const flagOf: (locale: string) => string;

package/dist-pkg/ui/locale-flags.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/locale-flags — THE LANGUAGE BUTTON'S THREE FLAGS (the Dev, 2026-09-16: «três bandeiras que se intercalam cada vez que o botão é
+// apertado: Brasil, Estados Unidos e México. Cada bandeira indica a localização para qual o app está configurado»).
+//
+// The flags are DRAWN, not emoji: 📏 measured in Chromium on Windows, 🇧🇷 🇺🇸 🇲🇽 render as the letters BR, US and MX (zero coloured pixels,
+// against 716 for 🧑) — a school's Windows machine would show the child two letters where a flag was promised. Simplified to their shapes
+// and colours at icon size. Each language is named in itself, so a child who does not read the current language still finds their own.
+/** The locales the button cycles, in the Dev's order. */
+export const LOCALE_CYCLE = ['pt', 'en', 'es'];
+/** The next locale of the cycle; a locale outside it starts the cycle again. */
+export const nextLocale = (current) => {
+    const i = LOCALE_CYCLE.indexOf(current);
+    return LOCALE_CYCLE[(i + 1) % LOCALE_CYCLE.length];
+};
+/** Each language in its own words, with the place its flag stands for. */
+export const LANGUAGE_NAME = {
+    pt: 'Português (Brasil)', en: 'English (United States)', es: 'Español (México)',
+};
+const svg = (inner) => `<svg class="pi-flag" viewBox="0 0 30 20" width="1.4em" height="0.93em" aria-hidden="true" focusable="false">${inner}</svg>`;
+/** Brazil, the United States and Mexico, simplified to icon size. */
+export const FLAG_SVG = {
+    pt: svg('<rect width="30" height="20" fill="#009c3b"/><polygon points="15,2.2 27.4,10 15,17.8 2.6,10" fill="#ffdf00"/><circle cx="15" cy="10" r="4.4" fill="#002776"/>'),
+    en: svg('<rect width="30" height="20" fill="#b22234"/>'
+        + [1, 3, 5, 7, 9, 11].map((r) => `<rect y="${(r * 20) / 13}" width="30" height="${20 / 13}" fill="#fff"/>`).join('')
+        + '<rect width="12" height="10.77" fill="#3c3b6e"/>'
+        + [[2, 2], [6, 2], [10, 2], [4, 5.4], [8, 5.4], [2, 8.8], [6, 8.8], [10, 8.8]].map(([x, y]) => `<circle cx="${x}" cy="${y}" r=".7" fill="#fff"/>`).join('')),
+    es: svg('<rect width="10" height="20" fill="#006847"/><rect x="10" width="10" height="20" fill="#fff"/><rect x="20" width="10" height="20" fill="#ce1126"/><circle cx="15" cy="10" r="2.6" fill="#8b5a2b"/>'),
+};
+/** The flag of a locale, or Brazil's for one outside the cycle (the engine's base language). */
+export const flagOf = (locale) => FLAG_SVG[LOCALE_CYCLE.includes(locale) ? locale : 'pt'];

package/dist-pkg/ui/loop-crash.d.ts

@@ -1,23 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** O id da caixa do aviso. Estável porque a folha de estilo e o teste a procuram. */
-export declare const AVISO_DE_QUEDA_ID = "incl-parou";
-export interface AvisoDeQuedaCtx {
-    /** `querySelector` do documento deste jogo. Injetado: a engine recebe o dela, `main.ts` passa o `$` global. */
-    procurar: (sel: string) => HTMLElement | null;
-    /** `document.createElement` — a caixa do aviso é um elemento de verdade, não um pseudo-elemento. */
-    criar: (tag: string) => HTMLElement;
-    /** A narração falada, quando o jogo tiver uma. Ausente = o aviso escrito basta. */
-    narrar?: (texto: string) => void;
+import type { Translate } from '../core/i18n.js';
+export interface CrashNoticeCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** `querySelector` of this game's document. Injected: the engine receives its own. */
+    find: (sel: string) => HTMLElement | null;
+    /** `document.createElement` — the notice box is a real element, not a pseudo-element. */
+    create: (tag: string) => HTMLElement;
+    /** The spoken narration, when the game has one. Absent = the written notice is enough. */
+    narrate?: (text: string) => void;
 }
 /**
- * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ * Builds the handler for `startLoop(ticker, frame, maxDt, { speed, onFailure })`.
  *
- * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
- * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
- * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
- * viu a tela parar.
+ * THE ORDER OF THE CHANNELS IS DELIBERATE: the console FIRST, because whoever debugs must not lose the error if the DOM
+ * is broken — and a broken DOM is one plausible reason the frame threw. Then the screen reader, which has no other clue
+ * at all. The visible one last, because whoever sees it has already seen the screen stop.
  *
- * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
- * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ * Each channel is isolated from the next: if narration throws, the written notice has already gone out. A notice that
+ * fails halfway must deliver the other half — the same rule `startLoop` applies to this very callback.
  */
-export declare function criarAvisoDeQueda(ctx: AvisoDeQuedaCtx): (erro: unknown) => void;
+export declare function createCrashNotice(ctx: CrashNoticeCtx): (failure: unknown) => void;

package/dist-pkg/ui/loop-crash.js

@@ -1,79 +1,50 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/loop-crash.ts — O ANÚNCIO DE QUE O LAÇO PAROU. A outra metade do ADR-0054.
-//
-// `core/loop.startLoop` já PARA quando um quadro lança, e já chama `aoFalhar`. O que faltava era alguém que
-// passasse um `aoFalhar` — e a `confirmation` do ADR-0054 diz isso por escrito: *"a raiz de composição ainda
-// não liga o `aoFalhar`, então hoje o laço para em silêncio... enquanto isto não existir este registro é só
-// metade verdadeiro."*
-//
-// ⚠️ E A METADE QUE FALTAVA É A QUE IMPORTA. Tela congelada é sintoma VISUAL. No modo cego, um jogo parado e
-// um jogo pensando produzem a mesma coisa: silêncio. A criança fica a esperar por um jogo que já morreu, sem
-// nada que lhe diga para recarregar — e o único aviso que existia era um erro no console, que ela não lê.
-//
-// ⚠️ POR QUE UM MÓDULO E NÃO UMA LINHA DENTRO DE `createGame`. Porque o jogo de plataforma NÃO PASSA POR
-// `createGame` — `main.ts` monta a engine à mão, e é ele quem chama `startLoop`. Uma solução que vivesse só
-// na raiz de composição da engine deixaria de fora exatamente o jogo que existe. As duas raízes importam
-// daqui.
-//
-// ⚠️ E NÃO USA `srAlert` DE `core/a11y-sr`, o que é uma escolha e não um esquecimento:
-//
-//   · `srAlert` limpa, espera um `requestAnimationFrame` e só então escreve. Essa dança existe para forçar o
-//     leitor a REANUNCIAR texto repetido; uma queda é anunciada uma vez e nunca se repete, então não compra
-//     nada aqui — e faz o aviso depender de um quadro futuro, no instante em que os quadros pararam.
-//   · `srAlert` busca no documento GLOBAL. Quem recebe o documento por injeção (a engine, um teste, um
-//     segundo jogo na mesma página) perderia o aviso. O anúncio de que tudo parou é o último lugar que
-//     deveria depender de uma busca global.
-import { t } from '../core/i18n.js';
-/** O id da caixa do aviso. Estável porque a folha de estilo e o teste a procuram. */
-export const AVISO_DE_QUEDA_ID = 'incl-parou';
+/** The id of the notice box. Stable because the stylesheet and the test look for it. */
+const CRASH_NOTICE_ID = 'incl-parou';
 /**
- * Monta o `aoFalhar` para entrar em `startLoop(ticker, quadro, maxDt, { aoFalhar })`.
+ * Builds the handler for `startLoop(ticker, frame, maxDt, { speed, onFailure })`.
  *
- * A ORDEM DOS CANAIS É DELIBERADA e vale escrever: o console PRIMEIRO, porque quem depura não pode perder o
- * erro se o DOM estiver quebrado — e um DOM quebrado é um dos motivos plausíveis para o quadro ter lançado.
- * Depois o leitor de tela, que é quem não tem outra pista nenhuma. O visível por último, porque quem o vê já
- * viu a tela parar.
+ * THE ORDER OF THE CHANNELS IS DELIBERATE: the console FIRST, because whoever debugs must not lose the error if the DOM
+ * is broken — and a broken DOM is one plausible reason the frame threw. Then the screen reader, which has no other clue
+ * at all. The visible one last, because whoever sees it has already seen the screen stop.
  *
- * Cada canal é isolado do seguinte: se a narração lançar, o aviso escrito já saiu. Um aviso que falha pela
- * metade tem de entregar a outra metade — é a mesma regra que o `startLoop` aplica a este próprio callback.
+ * Each channel is isolated from the next: if narration throws, the written notice has already gone out. A notice that
+ * fails halfway must deliver the other half — the same rule `startLoop` applies to this very callback.
  */
-export function criarAvisoDeQueda(ctx) {
-    return (erro) => {
+export function createCrashNotice(ctx) {
+    const { t } = ctx;
+    return (failure) => {
         try {
-            console.error('[inclusionist] the frame threw; the loop stopped.', erro);
+            console.error('[inclusionist] the frame threw; the loop stopped.', failure);
         }
         catch { /* noop */ }
         const msg = t('sr.laco.parou');
-        // O leitor de tela: assertivo, porque interromper é justamente o ponto.
-        const alerta = ctx.procurar('#sr-alert');
-        if (alerta)
-            alerta.textContent = msg;
+        // The screen reader: assertive, because interrupting is exactly the point.
+        const alert = ctx.find('#sr-alert');
+        if (alert)
+            alert.textContent = msg;
         try {
-            ctx.narrar?.(msg);
+            ctx.narrate?.(msg);
         }
-        catch { /* noop: a narração falhou; o aviso escrito já saiu */ }
-        // O VISÍVEL, e é um ELEMENTO DE VERDADE — não um pseudo-elemento.
+        catch { /* noop: narration failed; the written notice has already gone out */ }
+        // THE VISIBLE ONE, and it is a REAL ELEMENT — not a pseudo-element, for two reasons:
         //
-        // ⚠️ ERA `::after` COM `content: attr(data-incl-parou)`, E NUNCA TERIA APARECIDO. Medido no arranque real
-        // em 2026-09-06: `.game-region.crt-scan-1::after` é o efeito de scanline do CRT, ligado por padrão, e um
-        // elemento tem UM `::after` só — as duas regras não se empilham, a do CRT vem depois e vence. O
-        // `::before` está igualmente tomado, pela vinheta. O aviso disputava um lugar já ocupado.
+        // ⚠️ the region's `::after` and `::before` are already taken by the CRT scanlines and the vignette, and an element
+        // has ONE of each — a notice there competes for an occupied place and loses;
         //
-        // ⚠️ E O PSEUDO-ELEMENTO ERA ERRADO POR UMA SEGUNDA RAZÃO, que a primeira escondia: texto de `content`
-        // não entra de forma confiável na árvore de acessibilidade. O aviso de que o jogo morreu é exatamente o
-        // que não pode depender disso.
+        // ⚠️ and `content` text does not reliably enter the accessibility tree. The notice that the game died is exactly
+        // what cannot depend on that.
         //
-        // O raciocínio que continua de pé é o da TRADUÇÃO: a frase vem de `t()` e entra por `textContent`, então
-        // ela chega traduzida e escapada. O que muda é o recipiente.
-        const regiao = ctx.procurar('#game-region');
-        if (!regiao)
+        // The sentence comes from `t()` and goes in through `textContent`, so it arrives translated and escaped.
+        const region = ctx.find('#game-region');
+        if (!region)
             return;
-        const anterior = ctx.procurar('#' + AVISO_DE_QUEDA_ID);
-        const caixa = anterior ?? ctx.criar('div');
-        caixa.id = AVISO_DE_QUEDA_ID;
-        caixa.setAttribute('role', 'alert');
-        caixa.textContent = msg;
-        if (!anterior)
-            regiao.appendChild(caixa);
+        const previous = ctx.find('#' + CRASH_NOTICE_ID);
+        const notice = previous ?? ctx.create('div');
+        notice.id = CRASH_NOTICE_ID;
+        notice.setAttribute('role', 'alert');
+        notice.textContent = msg;
+        if (!previous)
+            region.appendChild(notice);
     };
 }