@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/control-choices.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { ACTIONS } from '../core/actions.js';
+/**
+ * THE FOUR ARROWS, one per direction.
+ *
+ * 🔴 The Dev asked for exactly these: «Por que está escrevendo "↔Up", "↔Down" etc ao invés de simplesmente "↑",
+ * "↓", "←" e "→"? Não escolha poluir a UI.» A chain of `replace` calls over the physical code is a hidden table, and a
+ * hidden table writes what nobody chose — so the table is written out.
+ *
+ * 📌 And there is nothing to translate here: an arrow is the same in pt, en and es, which is exactly why it is a
+ * glyph and not a word. The child who remaps sees the key they have in hand.
+ */
+const GLYPH = {
+    ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→',
+};
+/**
+ * Physical key code → short readable label.
+ *
+ * `Space` is the only one with a word to translate; the arrows are glyphs and the rest are the bare letter or
+ * digit, identical in every language.
+ *
+ * ⚠️ A TABLE AND A LADDER, and not a chain of replacements, which leaks the MACHINE's name whenever a prefix is not
+ * foreseen (`Digit1`, `Numpad5`). What is not recognised still passes through untouched on purpose: `Comma` is ugly
+ * and honest, and inventing a name for it would be guessing.
+ */
+export function keyName(t, code) {
+    const c = String(code);
+    if (GLYPH[c])
+        return GLYPH[c];
+    if (c === 'Space')
+        return t('key.space');
+    if (c.startsWith('Shift'))
+        return 'Shift';
+    if (c.startsWith('Key'))
+        return c.slice(3);
+    if (c.startsWith('Digit'))
+        return c.slice(5);
+    // «Num 5», «Num Add»: the numeric keypad is a different PHYSICAL place, and saying only «5» would make two
+    // distinct keys show the same label in the same list.
+    if (c.startsWith('Numpad'))
+        return `Num ${c.slice(6)}`;
+    return c;
+}
+/**
+ * Which OTHER player already owns `code`, among `schemes` (one entry per player, same order as player index) —
+ * or -1 if free. `mapRef` (the scheme currently being edited) is excluded BY REFERENCE. Built over a Map (code →
+ * owner index) so a scheme with many bound keys does not cost a full re-scan per lookup.
+ */
+export function keyUsedByOther(code, mapRef, schemes) {
+    const owners = new Map();
+    schemes.forEach((m, i) => {
+        if (m === mapRef)
+            return;
+        for (const a of ACTIONS)
+            for (const c of m[a] || [])
+                if (!owners.has(c))
+                    owners.set(c, i);
+    });
+    return owners.get(code) ?? -1;
+}
+/**
+ * Which OTHER action OF THE SAME scheme already has `code` — or `null` if none.
+ *
+ * ⚠️ THE SIBLING `keyUsedByOther` NEEDS, AND ITS ABSENCE IS INVISIBLE IN A ONE-PLAYER GAME (#126). That function
+ * excludes the scheme being edited **by reference**; with a single player, `schemesFor()` returns exactly that
+ * scheme, so its guard scans an empty list and **can never fire**. A child who puts `W` on a new action would keep
+ * `W` on the old one too, and play the whole game with both firing together.
+ *
+ * ⚠️ AND THAT IS THE WORST SHAPE A DEFECT CAN TAKE, as the `input/default-bindings` header says: the two actions fire
+ * together, and the child sees an intermittent double action nobody can reproduce on purpose — on a screen they
+ * opened **because** they could not use the default controls.
+ *
+ * Returns the ACTION and not a boolean, because the announcement has to say which one — saying only that the key is
+ * in use sends the child looking for what the function already knows.
+ */
+export function actionAlreadyBound(code, mapRef, except) {
+    for (const a of ACTIONS) {
+        if (a === except)
+            continue;
+        if ((mapRef[a] || []).includes(code))
+            return a;
+    }
+    return null;
+}

package/dist-pkg/ui/debug-panel.d.ts

@@ -1,67 +1,83 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { JuiceFlags } from '../render/fx.js';
 type Tune = Record<string, number>;
 type Anim = Record<string, number>;
-type Juice = JuiceFlags;
+type Juice = {
+    dust: boolean;
+    sparkle: boolean;
+    squash: boolean;
+    hitstop: boolean;
+    shake: boolean;
+    shimmer: boolean;
+};
 /**
- * UMA FOTO DO PERSONAGEM num quadro — DADOS, e nenhum objeto do PixiJS.
+ * A SNAPSHOT OF THE CHARACTER in one frame — DATA, and no PixiJS object.
  *
- * A raiz de composição, que é o único lugar onde o PixiJS já é conhecido, tira a foto e entrega strings. É a
- * mesma escolha de `RenderizarEm` e `CriarSprite` em render/port: pedir o VERBO cabe onde emprestar o objeto
- * não cabe — e aqui ela paga duas vezes, porque mantém `ui/debug-panel` testável no project `node`.
+ * The composition root, the only place where PixiJS is known, takes the snapshot and hands over strings. It is the
+ * same choice as `RenderInto` and `CreateSprite` in render/port: asking for the VERB fits where lending the object does
+ * not — and here it pays twice, because it keeps `ui/debug-panel` testable in the `node` project.
  */
-export interface AmostraDoPersonagem {
-    /** Identidade da textura DENTRO desta gravação. Não é geometria: os quatro quadros de idle têm a mesma. */
-    texturaId: number;
-    /** O recorte, "x,y LxA". */
-    recorte: string;
-    /** A base da textura, "LxA". */
+export interface CharacterSample {
+    /** Identity of the texture WITHIN this recording. Not geometry: the four idle frames share it. */
+    textureId: number;
+    /** The crop, "x,y WxH". */
+    crop: string;
+    /** The texture base, "WxH". */
     base: string;
-    /** A posição do sprite, "x,y". */
-    posicao: string;
-    /** A escala, "x,y" — o squash & stretch mexe nela. */
-    escala: string;
-    /** Quantos IRMÃOS da câmera estavam desenhando alguma textura do personagem neste quadro. */
-    irmaosDesenhando: number;
-    /** Onde eles estavam, para o caso de haver algum. */
-    posIrmaos: string;
+    /** The sprite position, "x,y". */
+    position: string;
+    /** The scale, "x,y" — squash & stretch moves it. */
+    scale: string;
+    /** How many camera SIBLINGS were drawing a texture of the character in this frame. */
+    siblingsDrawing: number;
+    /** Where they were, in case there is one. */
+    siblingPositions: string;
 }
-/** O que a sonda responde. Três perguntas, porque são elas que separam as causas que sobraram. */
-export interface ResumoDaSonda {
-    quadros: number;
-    texturas: number;
-    maxIrmaos: number;
-    exemploIrmaos: string;
-    /** As texturas cujo recorte é grande demais para um quadro de personagem — sangramento de atlas. */
+/** What the probe answers. Three questions, because they are what separates the remaining causes. */
+export interface ProbeSummary {
+    frames: number;
+    textures: number;
+    maxSiblings: number;
+    siblingExample: string;
+    /** The textures whose crop is too large for a character frame — atlas bleeding. */
     sangramento: string[];
-    escalas: string[];
-    veredito: string;
+    scales: string[];
+    verdict: string;
 }
 /**
- * Reduz a gravação a três perguntas e um veredito.
+ * Reduces the recording to three questions and a verdict.
  *
- * A ORDEM DO VEREDITO É A DECISÃO: irmão desenhando vence sangramento, porque é ele que produz cópias
- * INTEIRAS em posições diferentes — que é exatamente o que foi relatado. E quando as três perguntas vêm
- * limpas o veredito NÃO diz "está tudo bem": ele diz ONDE procurar em seguida. Ausência de prova nas três
- * não é prova de ausência, e encerrar a busca aqui a encerraria no lugar errado.
+ * THE ORDER OF THE VERDICT IS THE DECISION: a sibling drawing beats bleeding, because it is what produces WHOLE copies
+ * at different positions. And when the three questions come back clean the verdict does NOT say "all is well": it says
+ * WHERE to look next. Absence of evidence in the three is not evidence of absence, and ending the search here would end
+ * it in the wrong place.
  */
-export declare function resumirSonda(amostras: readonly AmostraDoPersonagem[]): ResumoDaSonda;
+export declare function summariseProbe(samples: readonly CharacterSample[]): ProbeSummary;
 export interface DebugPanelCtx {
     TUNE: Tune;
     ANIM: Anim;
     JUICE: Juice;
     saveJuice: () => void;
     /**
-     * Uma foto do personagem AGORA, ou `null` se ainda não há personagem na cena.
+     * A snapshot of the character NOW, or `null` if there is no character in the scene yet.
      *
-     * OPCIONAL: um hospedeiro sem personagem (o quiz) não a fornece, e a sonda simplesmente não aparece. O
-     * painel continua sem conhecer o PixiJS.
+     * OPTIONAL: a host with no character (the quiz) does not provide it, and the probe simply does not appear. The
+     * panel still does not know PixiJS.
      */
-    amostrarPersonagem?: () => AmostraDoPersonagem | null;
-    /** Chama `fn` a cada quadro e devolve como cancelar. É o relógio do render, injetado como verbo. */
-    aoQuadro?: (fn: () => void) => () => void;
-    /** Override for tests; defaults to location.search. */
-    search?: string;
+    sampleCharacter?: () => CharacterSample | null;
+    /** Calls `fn` every frame and returns how to cancel. It is the render clock, injected as a verb. */
+    onFrame?: (fn: () => void) => () => void;
+    /**
+     * The page's query string (`location.search`): the panel exists only under `?debug=true`. REQUIRED (ADR-0232 D4): the
+     * host reads its own location, and this module reaches none.
+     */
+    search: string;
+    /** The document the panel is built in and appended to (its `body`). REQUIRED (ADR-0232 D4): never the global one. */
+    doc: Document;
+    /**
+     * Where the probe's RAW recording goes, for whoever wants more than the summary without 180 lines in the panel — the
+     * platformer puts it on `window.__sonda`. REQUIRED (ADR-0232 D4): the module used to write that global itself.
+     */
+    expose: (samples: readonly CharacterSample[]) => void;
 }
 export declare function initDebugPanel(ctx: DebugPanelCtx): HTMLElement | null;
 export {};

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

@@ -1,43 +1,42 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // ui/debug-panel — the ?debug=true live-tuning panel (physics/animation sliders + juice toggles). Leaf UI module.
 // Built via closure DI: receives the LIVE TUNE/ANIM/JUICE objects (mutated in place) + saveJuice from the composition
-// root, so the sliders/checkboxes tune the same state the game reads. Extracted from game.js (modularization Tier 1).
+// root, so the sliders/checkboxes tune the same state the game reads.
 // Returns the panel element (or null when not in ?debug=true) — testable without booting the game.
-/** Um recorte maior que isto não é um quadro de personagem: é um pedaço do atlas. O maior real tem 31x35. */
-const MAIOR_QUADRO = 64;
+/** A crop larger than this is not a character frame: it is a piece of the atlas. The largest real one is 31x35. */
+const MAX_CHARACTER_FRAME_SIDE = 64;
 /**
- * Reduz a gravação a três perguntas e um veredito.
+ * Reduces the recording to three questions and a verdict.
  *
- * A ORDEM DO VEREDITO É A DECISÃO: irmão desenhando vence sangramento, porque é ele que produz cópias
- * INTEIRAS em posições diferentes — que é exatamente o que foi relatado. E quando as três perguntas vêm
- * limpas o veredito NÃO diz "está tudo bem": ele diz ONDE procurar em seguida. Ausência de prova nas três
- * não é prova de ausência, e encerrar a busca aqui a encerraria no lugar errado.
+ * THE ORDER OF THE VERDICT IS THE DECISION: a sibling drawing beats bleeding, because it is what produces WHOLE copies
+ * at different positions. And when the three questions come back clean the verdict does NOT say "all is well": it says
+ * WHERE to look next. Absence of evidence in the three is not evidence of absence, and ending the search here would end
+ * it in the wrong place.
  */
-export function resumirSonda(amostras) {
-    if (!amostras.length) {
-        return { quadros: 0, texturas: 0, maxIrmaos: 0, exemploIrmaos: '', sangramento: [], escalas: [], veredito: 'não gravou nada — o personagem existia?' };
+export function summariseProbe(samples) {
+    if (!samples.length) {
+        return { frames: 0, textures: 0, maxSiblings: 0, siblingExample: '', sangramento: [], scales: [], verdict: 'não gravou nada — o personagem existia?' };
     }
-    const texturas = new Set(amostras.map((a) => a.texturaId)).size;
-    const comIrmaos = amostras.filter((a) => a.irmaosDesenhando > 0);
-    const maxIrmaos = comIrmaos.reduce((m, a) => Math.max(m, a.irmaosDesenhando), 0);
-    const grande = (r) => {
+    const textureCount = new Set(samples.map((a) => a.textureId)).size;
+    const withSiblings = samples.filter((a) => a.siblingsDrawing > 0);
+    const mostSiblings = withSiblings.reduce((m, a) => Math.max(m, a.siblingsDrawing), 0);
+    const isAtlasPiece = (r) => {
         const m = /(\d+)x(\d+)$/.exec(r);
-        return !!m && (+m[1] > MAIOR_QUADRO || +m[2] > MAIOR_QUADRO);
+        return !!m && (+m[1] > MAX_CHARACTER_FRAME_SIDE || +m[2] > MAX_CHARACTER_FRAME_SIDE);
     };
-    const sangramento = [...new Set(amostras.filter((a) => grande(a.recorte)).map((a) => a.recorte + ' (base ' + a.base + ')'))];
-    const escalas = [...new Set(amostras.map((a) => a.escala))].sort();
-    const veredito = maxIrmaos > 0
-        ? 'ALGUÉM DESENHA DUAS VEZES: até ' + maxIrmaos + ' irmão(s) da câmera com a textura do personagem'
+    const sangramento = [...new Set(samples.filter((a) => isAtlasPiece(a.crop)).map((a) => a.crop + ' (base ' + a.base + ')'))];
+    const distinctScales = [...new Set(samples.map((a) => a.scale))].sort();
+    const finding = mostSiblings > 0
+        ? 'ALGUÉM DESENHA DUAS VEZES: até ' + mostSiblings + ' irmão(s) da câmera com a textura do personagem'
         : sangramento.length
             ? 'RECORTE GRANDE DEMAIS: o quadro está pegando pedaço do atlas'
             : 'sprite limpo (uma textura por quadro, sem irmão, recorte de quadro) — procure em composição: filtro, pós-efeito ou câmera';
-    return { quadros: amostras.length, texturas, maxIrmaos, exemploIrmaos: comIrmaos.length ? comIrmaos[0].posIrmaos : '', sangramento, escalas, veredito };
+    return { frames: samples.length, textures: textureCount, maxSiblings: mostSiblings, siblingExample: withSiblings.length ? withSiblings[0].siblingPositions : '', sangramento, scales: distinctScales, verdict: finding };
 }
 export function initDebugPanel(ctx) {
-    const search = ctx.search ?? location.search;
-    if (!/[?&]debug=true/.test(search))
+    if (!/[?&]debug=true/.test(ctx.search))
         return null;
-    const { TUNE, ANIM, JUICE, saveJuice } = ctx;
+    const { TUNE, ANIM, JUICE, saveJuice, doc } = ctx;
     const KNOBS = [
         { h: 'Movimento (valores absolutos)' },
         { label: 'Velocidade de andar', get: () => TUNE.hWalk, set: (v) => (TUNE.hWalk = v), min: 0.5, max: 5, step: 0.1 },
@@ -55,10 +54,10 @@ export function initDebugPanel(ctx) {
         { label: 'Queda máxima', get: () => TUNE.maxFall, set: (v) => (TUNE.maxFall = v), min: 3, max: 14, step: 0.5 },
         { label: 'Queda máxima na água', get: () => TUNE.waterMaxFall, set: (v) => (TUNE.waterMaxFall = v), min: 1, max: 8, step: 0.5 },
         { h: 'Animação (cadência: ticks/quadro)' },
-        { label: 'Andar', get: () => ANIM.walkHold, set: (v) => (ANIM.walkHold = v), min: 1, max: 20, step: 1, cad: true },
-        { label: 'Correr', get: () => ANIM.runHold, set: (v) => (ANIM.runHold = v), min: 1, max: 20, step: 1, cad: true },
-        { label: 'Parado (idle)', get: () => ANIM.idleHold, set: (v) => (ANIM.idleHold = v), min: 2, max: 40, step: 1, cad: true },
-        { label: 'Nado', get: () => ANIM.swimHold, set: (v) => (ANIM.swimHold = v), min: 2, max: 24, step: 1, cad: true },
+        { label: 'Andar', get: () => ANIM.walkHold, set: (v) => (ANIM.walkHold = v), min: 1, max: 20, step: 1, cadence: true },
+        { label: 'Correr', get: () => ANIM.runHold, set: (v) => (ANIM.runHold = v), min: 1, max: 20, step: 1, cadence: true },
+        { label: 'Parado (idle)', get: () => ANIM.idleHold, set: (v) => (ANIM.idleHold = v), min: 2, max: 40, step: 1, cadence: true },
+        { label: 'Nado', get: () => ANIM.swimHold, set: (v) => (ANIM.swimHold = v), min: 2, max: 24, step: 1, cadence: true },
         { h: 'Juice (efeitos de resposta) — toggles independentes' },
         { label: '💨 Poeira (pulo/pouso/corrida)', chk: () => JUICE.dust, set: (v) => { JUICE.dust = v; saveJuice(); } },
         { label: '✨ Brilho ao coletar', chk: () => JUICE.sparkle, set: (v) => { JUICE.sparkle = v; saveJuice(); } },
@@ -66,44 +65,44 @@ export function initDebugPanel(ctx) {
         { label: '⏱️ Hit-stop (impacto)', chk: () => JUICE.hitstop, set: (v) => { JUICE.hitstop = v; saveJuice(); } },
         { label: '📳 Tremor de tela', chk: () => JUICE.shake, set: (v) => { JUICE.shake = v; saveJuice(); } },
         { label: '🌟 Cintilar dos itens', chk: () => JUICE.shimmer, set: (v) => { JUICE.shimmer = v; saveJuice(); } },
-    ]; // Estética CRT saiu daqui: mora no menu Sensibilidade visual (pedido do José).
-    const p = document.createElement('div');
+    ]; // The CRT look is not here: it lives in the visual sensitivity panel (the Dev's request).
+    const p = doc.createElement('div');
     p.id = 'debug-panel';
-    p.hidden = true; // começa oculto; abre pelo botão 🐞 Debug
+    p.hidden = true; // starts hidden; opened by the 🐞 Debug button
     p.setAttribute('role', 'group');
     p.setAttribute('aria-label', 'Painel de depuração');
     p.style.cssText = 'position:fixed;top:8px;right:8px;z-index:200;background:rgba(11,16,32,.97);color:#fff;border:2px solid #ffd23f;border-radius:8px;padding:.6rem .7rem;font:13px/1.4 system-ui,sans-serif;max-width:270px;max-height:86vh;overflow:auto;box-shadow:0 4px 16px rgba(0,0,0,.5)';
     p.innerHTML = '<strong>🔧 ?debug — valores ao vivo</strong>';
     for (const k of KNOBS) {
         if ('h' in k) {
-            const h = document.createElement('div');
+            const h = doc.createElement('div');
             h.textContent = k.h;
             h.style.cssText = 'margin:.7rem 0 .1rem;font-weight:700;color:#ffd23f;border-bottom:1px solid rgba(255,210,63,.4)';
             p.appendChild(h);
             continue;
         }
         if ('chk' in k) {
-            const row = document.createElement('label');
+            const row = doc.createElement('label');
             row.style.cssText = 'display:flex;gap:.4rem;align-items:center;margin-top:.4rem;font-size:12px;cursor:pointer';
-            const inp = document.createElement('input');
+            const inp = doc.createElement('input');
             inp.type = 'checkbox';
             inp.checked = k.chk();
             inp.addEventListener('change', () => k.set(inp.checked));
             row.appendChild(inp);
-            row.appendChild(document.createTextNode(k.label));
+            row.appendChild(doc.createTextNode(k.label));
             p.appendChild(row);
             continue;
         }
-        const row = document.createElement('div');
+        const row = doc.createElement('div');
         row.style.cssText = 'margin-top:.5rem';
-        const lab = document.createElement('label');
+        const lab = doc.createElement('label');
         lab.style.cssText = 'display:block;font-size:12px;margin-bottom:2px';
-        const val = document.createElement('strong');
+        const val = doc.createElement('strong');
         val.style.cssText = 'color:#ffd23f;float:right';
-        const upd = () => { val.textContent = k.cad ? `${k.get()} (${Math.round(60 / k.get())}fps)` : String(k.get()); };
+        const upd = () => { val.textContent = k.cadence ? `${k.get()} (${Math.round(60 / k.get())}fps)` : String(k.get()); };
         lab.textContent = k.label;
         lab.appendChild(val);
-        const inp = document.createElement('input');
+        const inp = doc.createElement('input');
         inp.type = 'range';
         inp.min = String(k.min);
         inp.max = String(k.max);
@@ -117,23 +116,23 @@ export function initDebugPanel(ctx) {
         p.appendChild(row);
         upd();
     }
-    /* ===================== A SONDA DO PERSONAGEM =====================
-       Ela mora AQUI, e não num script para colar no console, porque foi o que o Dev pediu — e ele tem razão
-       pelo motivo de sempre: um instrumento que só existe enquanto alguém lembra de colar não é instrumento, é
-       lembrança. Aqui ele fica ao lado dos outros valores ao vivo, atrás do mesmo `?debug=true`.
+    /* ===================== THE CHARACTER PROBE =====================
+       It lives HERE, and not in a script to paste into the console, because that is what the Dev asked for — an
+       instrument that exists only while someone remembers to paste it is not an instrument, it is a memory. Here it
+       sits beside the other live values, behind the same `?debug=true`.
   
-       Só aparece se o hospedeiro souber tirar a foto: um jogo sem personagem não ganha um botão que não faz
-       nada. */
-    if (ctx.amostrarPersonagem && ctx.aoQuadro) {
-        const amostrar = ctx.amostrarPersonagem, aoQuadro = ctx.aoQuadro;
-        const h = document.createElement('div');
+       It only appears if the host can take the snapshot: a game with no character does not get a button that does
+       nothing. */
+    if (ctx.sampleCharacter && ctx.onFrame) {
+        const sampleCharacter = ctx.sampleCharacter, everyFrame = ctx.onFrame;
+        const h = doc.createElement('div');
         h.textContent = 'Sonda do personagem';
         h.style.cssText = 'margin:.7rem 0 .1rem;font-weight:700;color:#ffd23f;border-bottom:1px solid rgba(255,210,63,.4)';
         p.appendChild(h);
-        const saida = document.createElement('pre');
-        saida.style.cssText = 'margin:.4rem 0 0;font:11px/1.35 ui-monospace,monospace;white-space:pre-wrap;color:#cfe';
-        saida.setAttribute('aria-live', 'polite');
-        const btn = document.createElement('button');
+        const migrated = doc.createElement('pre');
+        migrated.style.cssText = 'margin:.4rem 0 0;font:11px/1.35 ui-monospace,monospace;white-space:pre-wrap;color:#cfe';
+        migrated.setAttribute('aria-live', 'polite');
+        const btn = doc.createElement('button');
         btn.type = 'button';
         btn.textContent = '🥷 Gravar 180 quadros';
         btn.style.cssText = 'margin-top:.4rem;width:100%;min-height:32px;font:inherit;font-weight:700;cursor:pointer;border-radius:6px;border:1px solid #ffd23f;background:#1a2740;color:#fff';
@@ -141,33 +140,33 @@ export function initDebugPanel(ctx) {
             if (btn.disabled)
                 return;
             btn.disabled = true;
-            const amostras = [];
+            const samples = [];
             let n = 0;
-            saida.textContent = 'gravando… PULE agora';
-            const parar = aoQuadro(() => {
-                const a = amostrar();
+            migrated.textContent = 'gravando… PULE agora';
+            const stopSampling = everyFrame(() => {
+                const a = sampleCharacter();
                 if (a)
-                    amostras.push(a);
+                    samples.push(a);
                 if (++n < 180)
                     return;
-                parar();
+                stopSampling();
                 btn.disabled = false;
-                const r = resumirSonda(amostras);
-                saida.textContent = [
-                    'quadros: ' + r.quadros + '  texturas: ' + r.texturas,
-                    'irmãos desenhando: ' + r.maxIrmaos + (r.exemploIrmaos ? ' em ' + r.exemploIrmaos : ''),
+                const r = summariseProbe(samples);
+                migrated.textContent = [
+                    'quadros: ' + r.frames + '  texturas: ' + r.textures,
+                    'irmãos desenhando: ' + r.maxSiblings + (r.siblingExample ? ' em ' + r.siblingExample : ''),
                     'recorte grande: ' + (r.sangramento.length ? r.sangramento.join(' ') : 'nenhum'),
-                    'escalas: ' + r.escalas.join(' '),
+                    'escalas: ' + r.scales.join(' '),
                     '',
-                    '→ ' + r.veredito,
+                    '→ ' + r.verdict,
                 ].join(String.fromCharCode(10));
-                // O BRUTO fica alcançável para quem quiser ir além do resumo — sem poluir o painel com 180 linhas.
-                window.__sonda = amostras;
+                // The RAW recording stays reachable for whoever wants more than the summary — without filling the panel with 180 lines.
+                ctx.expose(samples);
             });
         });
         p.appendChild(btn);
-        p.appendChild(saida);
+        p.appendChild(migrated);
     }
-    document.body.appendChild(p);
+    doc.body.appendChild(p);
     return p;
 }

package/dist-pkg/ui/declared-words.d.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ActionPreset } from '../core/actions.js';
+import type { AccommodationAnswers } from '../core/accommodations.js';
+import type { GameOption } from './game-options.js';
+import type { HowToPlaySlide } from './help-panel.js';
+import type { HudNumber } from './hud-bands.js';
+/** The game's fields that carry declared words — a `Pick` of `CreateGameOptions`, written here so `ui` does not import `boot`. */
+interface DeclaredWords {
+    readonly preset?: ActionPreset;
+    readonly accommodations?: AccommodationAnswers;
+    readonly gameOptions?: readonly GameOption[];
+    readonly howToPlay?: readonly HowToPlaySlide[];
+    readonly hud?: readonly HudNumber[];
+}
+/**
+ * THE DECLARED KEYS THIS GAME'S DICTIONARIES LACK, one line each for `problems` (ADR-0169). `declares` is the root's
+ * translator's (`Translator.declares`): a key in ANY language counts as present, because a key given in one language and not
+ * another is already a line of its own (`Translator.dictionaryGaps`).
+ */
+export declare function missingDeclaredKeys(declared: DeclaredWords, declares: (key: string) => boolean): string[];
+export {};

package/dist-pkg/ui/declared-words.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const ACTION_NAME = 'the child sees this button unnamed: the help, the remap screen, the pad and the scan leave it out';
+const ACTION_SHORT = 'the pad shows the long name squeezed under the glyph';
+const ACTION_HINT = 'the help shows this button without its sentence';
+const ACCOMMODATION_NAME = 'this accommodation has its row left out, and the child who needs it cannot reach it';
+const ACCOMMODATION_SHORT = 'where only a short name fits, the long one is squeezed';
+const ACCOMMODATION_HINT = 'the row explains itself in the engine\'s general words, or not at all';
+const OPTION_NAME = 'this option has its row left out, and the child cannot change it';
+const OPTION_HINT = 'the row shows without its explanation';
+const SLIDE_TEXT = 'this slide is left out of the help';
+const HUD_NAME = 'this number is hidden from the child';
+function presetKeys(preset) {
+    if (!preset)
+        return [];
+    return Object.entries(preset).flatMap(([action, keys]) => (keys ? [
+        { subject: `preset.${action}.labelKey`, key: keys.labelKey, cost: ACTION_NAME, optional: false },
+        { subject: `preset.${action}.shortKey`, key: keys.shortKey, cost: ACTION_SHORT, optional: true },
+        { subject: `preset.${action}.hintKey`, key: keys.hintKey, cost: ACTION_HINT, optional: true },
+    ] : []));
+}
+function accommodationKeys(answers) {
+    if (!answers)
+        return [];
+    return Object.entries(answers).flatMap(([accommodation, keys]) => (keys ? [
+        { subject: `accommodations.${accommodation}.labelKey`, key: keys.labelKey, cost: ACCOMMODATION_NAME, optional: false },
+        { subject: `accommodations.${accommodation}.shortKey`, key: keys.shortKey, cost: ACCOMMODATION_SHORT, optional: true },
+        { subject: `accommodations.${accommodation}.hintKey`, key: keys.hintKey, cost: ACCOMMODATION_HINT, optional: true },
+    ] : []));
+}
+function optionKeys(options) {
+    return (options ?? []).flatMap((o) => [
+        { subject: `gameOptions «${o.id}».labelKey`, key: o.labelKey, cost: OPTION_NAME, optional: false },
+        { subject: `gameOptions «${o.id}».hintKey`, key: o.hintKey, cost: OPTION_HINT, optional: true },
+        ...(o.kind === 'switch' ? [] : o.values.map((v) => ({ subject: `gameOptions «${o.id}».values «${v.value}».labelKey`, key: v.labelKey, cost: OPTION_NAME, optional: false }))),
+    ]);
+}
+function slideKeys(slides) {
+    return (slides ?? []).map((s, i) => ({ subject: `howToPlay[${i}].textKey`, key: s.textKey, cost: SLIDE_TEXT, optional: false }));
+}
+function hudKeys(numbers) {
+    return (numbers ?? []).map((n, i) => ({ subject: `hud[${i}].nameKey`, key: n.nameKey, cost: HUD_NAME, optional: false }));
+}
+/** What is wrong with ONE declared key, or `null`: it must be text, and it must be in the game's dictionaries. */
+function keyProblem(k, declares) {
+    if (k.optional && k.key === undefined)
+        return null;
+    const fix = 'add it to CreateGameOptions.dictionaries, in pt, en and es';
+    if (typeof k.key !== 'string' || !k.key.trim()) {
+        return `${k.subject} is not a key (since ADR-0232 D3 a game declares the KEY of each word, never the word): ${k.cost} — name a key, and ${fix}`;
+    }
+    return declares(k.key) ? null : `${k.subject} «${k.key}» is in none of this game's dictionaries: ${k.cost} — ${fix}`;
+}
+/**
+ * THE DECLARED KEYS THIS GAME'S DICTIONARIES LACK, one line each for `problems` (ADR-0169). `declares` is the root's
+ * translator's (`Translator.declares`): a key in ANY language counts as present, because a key given in one language and not
+ * another is already a line of its own (`Translator.dictionaryGaps`).
+ */
+export function missingDeclaredKeys(declared, declares) {
+    return [
+        ...presetKeys(declared.preset),
+        ...accommodationKeys(declared.accommodations),
+        ...optionKeys(declared.gameOptions),
+        ...slideKeys(declared.howToPlay),
+        ...hudKeys(declared.hud),
+    ].map((k) => keyProblem(k, declares)).filter((line) => line !== null);
+}

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

@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-export declare const $: <T extends Element = HTMLElement>(s: string) => T | null;
-export declare const $$: <T extends Element = HTMLElement>(s: string) => T[];
+import type { Translate } from '../core/i18n.js';
 /**
  * Reflects an on/off state onto a toggle button: the visual class AND `aria-pressed`.
  * Lives here because the two must never drift apart — a button that looks pressed but does not
@@ -8,17 +7,14 @@ export declare const $$: <T extends Element = HTMLElement>(s: string) => T[];
  */
 export declare function toggleBtn(b: Element | null, on: boolean): void;
 /**
- * O TEXTO do botão de alternância: '❚❚ Ligado' / '▶ Desligado'.
+ * The TEXT of a toggle button: 'On' / 'Off' in English.
  *
- * Mora aqui pelo mesmo motivo do `toggleBtn` logo acima — os dois são as duas metades do mesmo gesto, e a
- * nota daquela função diz que elas "não podem se separar". Elas tinham se separado em TREZE cópias, em nove
- * arquivos, e dois deles declaravam um helper que se chamava compartilhado e servia um chamador só
- * (`settings-empathy.toggleLabel` e `settings-motor.onOffLabel`, ambos apagados agora).
- *
- * O custo dessa dispersão não era estético: com o texto em treze lugares, traduzir o jogo exigiria achar os
- * treze, e esquecer um deixaria um botão em português no meio do inglês — sem erro, sem teste vermelho.
+ * It lives here for the same reason as `toggleBtn` just above — the two are halves of one gesture, and must not
+ * drift apart. A text copied into each panel is a text that translating the game has to find everywhere, and the
+ * one copy it misses leaves a button in the wrong language — with no error and no red test.
  */
-export declare function toggleLabel(on: boolean): string;
-/** O `aria-label` da mesma alternância: '{alvo}: ligado'. Separado do rótulo visível porque o leitor de tela
- *  precisa do NOME do alvo junto, e a tela não (o nome já está na linha ao lado do botão). */
-export declare function toggleAria(alvo: string, on: boolean): string;
+export declare function toggleLabel(t: Translate, on: boolean): string;
+/** The `aria-label` of the same toggle: '{alvo}: on' (`{alvo}` is the dictionary's interpolation key). Separate from
+ *  the visible label because a screen reader needs the NAME of the target with it, and the screen does not (the
+ *  name is already on the row beside the button). */
+export declare function toggleAria(t: Translate, target: string, on: boolean): string;