@the-inclusionist/engine 8.0.0 → 10.0.0

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

package/dist-pkg/ui/dom.js

@@ -1,38 +1,4 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/dom.ts — atalhos de seleção do DOM, usados em toda a UI (menus/HUD/pausa/quiz/opções). PURO no import:
-// só define as funções (não toca no DOM → importável em node). $ = querySelector; $$ = querySelectorAll
-// como Array. Genéricos: $<HTMLInputElement>('#x') já tipa o retorno. (Fase 2.27 / Tier 1)
-//
-// DEIXOU DE SER FOLHA no item 14, e de propósito: passou a importar `core/i18n` para que `toggleLabel` (o
-// texto do botão de alternância) more ao lado do `toggleBtn` (a classe e o `aria-pressed`). A propriedade que
-// importa — importável em node, sem I/O no import — continua valendo; o que se perdeu foi a contagem de zero
-// dependências, e o que se ganhou está escrito no comentário de `toggleLabel`.
-import { t } from '../core/i18n.js';
-// O PADRAO E `HTMLElement`, NAO `Element`, e a diferenca aparece em dezessete pontos de chamada: `.hidden`,
-// `.focus()` e `.value` nao existem em `Element`, e sao exatamente o que uma aplicacao faz com o que
-// seleciona. `Element` e o padrao do lib.dom porque `querySelector` tambem serve para SVG e MathML —
-// nenhum seletor deste projeto pega um desses (conferido). Quem precisar de um tipo mais estreito passa
-// o parametro: `$<HTMLSelectElement>('#pad-design')`.
-/**
- * ⚠️ RESOLVIDO POR `globalThis` E NÃO PELO GLOBAL CRU, e a diferença é entre devolver `null` e LANÇAR.
- *
- * `document.querySelector(...)` com `document` inexistente dá `ReferenceError` — não `undefined` —, e a
- * assinatura destas duas funções promete `T | null`. Uma consulta que lança onde promete `null` é um defeito
- * pela própria assinatura, e ele viajava longe: medido em 2026-09-08, o `core/a11y-sr.srAlert` chama o `$`
- * daqui, e o `createGame` chama o `srAlert` ao mostrar o aviso de alcance — logo bootar a engine contra um
- * documento INJECTADO (um iframe, um editor ao lado do jogo, um teste) rebentava o boot inteiro num anúncio.
- *
- * 📌 É o ACHADO 15 do `boot/create-game` outra vez, e sobreviveu pela mesma razão: enquanto toda raiz era um
- * `main.ts` num navegador, o global ERA o documento certo. `globalThis.document` é a mesma coisa onde ele
- * existe, e é `undefined` — em vez de explosão — onde não existe.
- *
- * ⚠️ E ELAS CONTINUAM A OLHAR PARA O GLOBAL, de propósito: quem precisa de consultar OUTRO documento injecta
- * o seu (`create-game` tem um `$` próprio ligado ao `doc` do hospedeiro, e o `ui/pause-icons` tem o
- * `docDaMontagem`). O que este conserto muda não é ONDE se procura — é o que acontece quando não há onde.
- */
-const docGlobal = () => globalThis.document;
-export const $ = (s) => docGlobal()?.querySelector(s) ?? null;
-export const $$ = (s) => [...(docGlobal()?.querySelectorAll(s) ?? [])];
 /**
  * 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
@@ -45,21 +11,18 @@ export function toggleBtn(b, on) {
     b.setAttribute('aria-pressed', String(on));
 }
 /**
- * O TEXTO do botão de alternância: '❚❚ Ligado' / '▶ Desligado'.
- *
- * 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).
+ * The TEXT of a toggle button: 'On' / 'Off' in English.
  *
- * 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 function toggleLabel(on) {
+export function toggleLabel(t, on) {
     return t(on ? 'ui.toggle.on' : 'ui.toggle.off');
 }
-/** 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 function toggleAria(alvo, on) {
-    return t(on ? 'ui.toggle.ariaOn' : 'ui.toggle.ariaOff', { alvo });
+/** 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 function toggleAria(t, target, on) {
+    return t(on ? 'ui.toggle.ariaOn' : 'ui.toggle.ariaOff', { alvo: target });
 }

package/dist-pkg/ui/drawing-problems.d.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Scale } from './layout.js';
+export interface DrawingProblemsCtx {
+    /** `#game-region`, read at EVERY call — see the note at the top of this file. */
+    readonly region: () => HTMLElement | null;
+    /** The accessibility bar, or `null` where the game declined it. Read at every call, for the same reason. */
+    readonly bar: () => Element | null;
+    /** The scale the engine forced, or `null` before the first layout has run. */
+    readonly scale: () => Scale | null;
+    /** `window.getComputedStyle`, absent in a host that has none — then a node is counted rather than guessed about. */
+    readonly computedStyle?: (el: Element) => CSSStyleDeclaration;
+}
+/**
+ * ADR-0163 rule 4, second half: the text and the targets the CARTRIDGE draws under the floor, named — read when `problems` is.
+ * `null` when there is nothing to say, which is what a clean page answers.
+ */
+export declare function drawnBelowTheFloor(ctx: DrawingProblemsCtx): string | null;
+/**
+ * The nodes that PAINT over the accessibility bar's rectangle (ADR-0148 §3).
+ *
+ * 📏 ONLY WHAT PAINTS, and it was measured in `dist/quiz.html`: the quiz was accused at every boot because `#quiz-app` — a
+ * transparent box the size of the region, whose top padding IS the bar's room — intersects the bar's rectangle and draws
+ * nothing there. A node counts when it has text of its own, is a control or a medium, or paints a background.
+ */
+export declare function barIntruderProblems(ctx: DrawingProblemsCtx): string[];

package/dist-pkg/ui/drawing-problems.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/drawing-problems — WHAT A CARTRIDGE DREW THAT THE CHILD PAYS FOR, named (ADR-0163 rule 4, ADR-0148 §3; issue #203).
+//
+// Two questions the engine asks about its own region, and both answer with the sentence a `problems` line needs: text and
+// targets drawn UNDER the floor, and the nodes drawn OVER the accessibility bar. They are one subject — the engine measuring
+// what somebody else drew — and they lived inside `boot/create-game`, which is why this module exists: 📏 that file reached
+// 2185 lines and 330 decision nodes (ADR-0221), and the debt is paid by SUBJECT, never by slicing.
+//
+// ⚠️ THE READERS ARE FUNCTIONS AND NOT VALUES, and that is the whole care in this file. `#game-region`, the bar and the applied
+// scale are all things the root REPLACES: a `mount()` swaps the cartridge and the bar is built after the root is. Taking them
+// as values here would freeze the first answer and report, forever, about a region that is no longer on the page — silently,
+// because a stale element still answers `getBoundingClientRect()`.
+import { barIntruders, belowFloor, minimumTarget } from './layout.js';
+/** The engine's OWN nodes inside the region — their sizes are held by their own gates — and what is not drawn for the eye. */
+const ENGINE_NODES = '#title-icons, .screen-pause, .overlay, #touch-controls, .rodape-da-tela, .pausa-rapida, #incl-parou, .sr-only, .hud-faixa';
+/** What a finger is meant to hit; anything else has no target floor to fail. */
+const TOUCH_TARGET = 'button, a[href], input:not([type="hidden"]), select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])';
+/**
+ * A node named the way a developer finds it: `tag#id.firstClass`.
+ *
+ * 📌 It is NOT exported, and the `exports-without-consumer` gate is what said so: exporting it would publish a name only this
+ * file uses, and an export with no consumer is surface somebody has to maintain with nobody needing it (ADR-0170 §3).
+ */
+function nodeName(el) {
+    return el.tagName.toLowerCase() + (el.id ? `#${el.id}` : '')
+        + (el.className ? `.${String(el.className).trim().split(/\s+/)[0]}` : '');
+}
+/**
+ * ADR-0163 rule 4, second half: the text and the targets the CARTRIDGE draws under the floor, named — read when `problems` is.
+ * `null` when there is nothing to say, which is what a clean page answers.
+ */
+export function drawnBelowTheFloor(ctx) {
+    const region = ctx.region();
+    const scale = ctx.scale();
+    if (!scale || !region || typeof region.querySelectorAll !== 'function' || !ctx.computedStyle)
+        return null;
+    const nodes = [...region.querySelectorAll('*')].map((el) => {
+        const b = el.getBoundingClientRect();
+        const hasText = [...el.childNodes].some((c) => c.nodeType === 3 && (c.textContent ?? '').trim() !== '');
+        return {
+            name: nodeName(el),
+            daEngine: el.closest(ENGINE_NODES) !== null,
+            fontPx: hasText && b.width > 0 && b.height > 0 ? parseFloat(ctx.computedStyle(el).fontSize) : null,
+            target: el.matches(TOUCH_TARGET) ? { w: b.width, h: b.height } : null,
+        };
+    });
+    const { text: smallText, targets: smallTargets } = belowFloor(nodes, scale.k);
+    if (!smallText.length && !smallTargets.length)
+        return null;
+    const k = minimumTarget(scale.k) / 22;
+    const parts = [
+        smallText.length ? `text under ${8 * k} px (${smallText.slice(0, 4).join(', ')})` : '',
+        smallTargets.length ? `targets under ${22 * k} px (${smallTargets.slice(0, 4).join(', ')})` : '',
+    ].filter(Boolean);
+    return `the cartridge draws ${parts.join(' and ')} in #game-region: a child with low vision or unsteady hands cannot `
+        + 'read or hit them — text and targets start at 16 and 44 px at 640×360 and grow with the scale (ADR-0163): size them '
+        + 'from `--ui-fs` and `--alvo-min`';
+}
+/**
+ * The nodes that PAINT over the accessibility bar's rectangle (ADR-0148 §3).
+ *
+ * 📏 ONLY WHAT PAINTS, and it was measured in `dist/quiz.html`: the quiz was accused at every boot because `#quiz-app` — a
+ * transparent box the size of the region, whose top padding IS the bar's room — intersects the bar's rectangle and draws
+ * nothing there. A node counts when it has text of its own, is a control or a medium, or paints a background.
+ */
+export function barIntruderProblems(ctx) {
+    const region = ctx.region();
+    const bar = ctx.bar();
+    if (!bar || !region || typeof bar.getBoundingClientRect !== 'function')
+        return [];
+    const boxOf = (el) => {
+        const b = el.getBoundingClientRect();
+        return { x: b.x, y: b.y, w: b.width, h: b.height };
+    };
+    const paints = (el) => {
+        if ([...el.childNodes].some((c) => c.nodeType === 3 && (c.textContent ?? '').trim() !== ''))
+            return true;
+        if (/^(img|canvas|svg|video|input|button|select|textarea)$/i.test(el.tagName))
+            return true;
+        if (!ctx.computedStyle)
+            return true; // no way to tell: count it, as before
+        const cs = ctx.computedStyle(el);
+        return (cs.backgroundColor !== '' && cs.backgroundColor !== 'transparent' && cs.backgroundColor !== 'rgba(0, 0, 0, 0)')
+            || (cs.backgroundImage !== '' && cs.backgroundImage !== 'none');
+    };
+    const nodes = [...region.querySelectorAll('*')].filter((el) => paints(el)).map((el) => ({
+        name: nodeName(el),
+        box: boxOf(el),
+        // the engine's HUD bands are placed by the ENGINE: if one reaches the bar, that is the engine's defect and not the game's
+        isBar: el === bar || bar.contains(el) || el.closest('.hud-faixa') !== null,
+    }));
+    return barIntruders(boxOf(bar), nodes);
+}