@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/hud.js

@@ -1,41 +1,32 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/hud.ts — HUD POR TELA + a infraestrutura de TELAS do jogo (Estágio 4). Duas responsabilidades coladas
-// desde sempre no game.js: (a) a GRADE de `.player-screen` dentro de `#game-hud` — um contêiner por jogador,
-// posicionado em %, que hospeda o HUD, o selo "jogo abandonado", o selo "aperte um botão para entrar"
-// (`.vp-wait`), o menu de pausa daquele jogador e (em MP) o overlay de quiz dele; e (b) o CONTEÚDO do HUD —
-// o OBJETIVO do jogador e o poder ativo — reescrito a cada frame por updateGameHud().
+// ui/hud.ts — PER-SCREEN HUD + the game's SCREEN infrastructure. Two responsibilities: (a) the GRID of
+// `.player-screen` inside `#game-hud` — one container per player, positioned in %, hosting the HUD, the quit badge, the
+// press-a-button-to-join badge (`.vp-wait`), that player's pause menu and (in multiplayer) their quiz overlay; and (b)
+// the HUD's CONTENT — the player's OBJECTIVE and active power — rewritten every frame by updateGameHud().
 //
-// ========================= O CONTADOR DEIXOU DE SER DE MOEDA (item 19) =========================
-// O passo 4 do ADR-0027 matou a DEPENDÊNCIA (`vphudHtml(coinTarget = COIN_TARGET)` virou parâmetro
-// obrigatório); o que sobrou era VOCABULÁRIO — o ícone cravado no markup, a classe `vphud-coins`, o campo
-// `coins` do view-model. Nome não é seguido pelo compilador e não impede um pacote de se separar, e por isso
-// a dívida era menor. Não era nula: ela dizia, em toda tela, que este HUD é de um jogo de plataforma.
+// ========================= THE COUNTER IS NOT A COIN COUNTER =========================
+// The counter receives an `Objective` — field 5 of `core/contract` — and the icon comes in by injection, so the HUD
+// shows what the game declared without knowing whether it is a coin, a word or a sum. And `Objective.name` gives the
+// counter an ACCESSIBLE NAME: without it a blind child would hear "3 / 10", two numbers with no noun — the engine did
+// not know the name of what is collected. Now the game declares it.
 //
-// Agora o contador recebe um `Objective` — campo 5 de `core/contract` — e o ícone entra por injeção. E a
-// mudança compra mais do que um nome: com `Objective.name` o contador GANHOU NOME ACESSÍVEL. Até aqui a
-// criança cega ouvia o contador como "3 / 10", dois números sem substantivo — não havia o que falar porque a
-// engine não sabia o nome do que se junta. Agora sabe, porque o jogo declara.
+// The HUD is OVERLAID DOM (not pixelated: it stays in high definition over the 320×180 canvas) — which is why it lives
+// here and not in render. The pause menu is NOT this module's: `buildScreenPause(i)` comes in by injection, and this
+// module only attaches the result to the right screen and hands the finished panels back through `onScreensBuilt`.
 //
-// O HUD é DOM SOBREPOSTO (não pixela: fica em alta definição sobre o canvas 320×180) — por isso vive aqui e
-// não no render. O menu de pausa NÃO é deste módulo: `buildScreenPause(i)` entra por injeção e este módulo só
-// anexa o retorno na tela certa e devolve os painéis prontos por `onScreensBuilt` (o game.js guarda `vpPause`
-// e o `pauseActor`, que são do slice de pausa/ícones). Ver docs/5-Refactoring/plano-modularizacao-mapa.md.
-//
-// Sem I/O no import: `document` só aparece DENTRO das funções → o módulo é importável no project node, onde os
-// testes exercitam só a metade PURA (screenGrid/screenRect/hudRowView/vphudHtml/waitBadgeHtml).
+// No I/O on import: `document` only appears INSIDE functions → the module is importable in the node project, where the
+// tests exercise only the PURE half (screenGrid/screenRect/hudRowView/vphudHtml/waitBadgeHtml).
 import { screenGrid } from '../core/screens.js';
-import { t } from '../core/i18n.js';
 // ---------------------------------------------------------------------------------------------
-// Lógica PURA (nenhum `document`; testável no project node)
+// PURE logic (no `document`; testable in the node project)
 // ---------------------------------------------------------------------------------------------
-/** Grade de telas: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (a 3ª tela é centralizada na linha de baixo). */
-// A grade agora mora em core/screens (folha, sem dependências), porque o layout e o CRT precisam da MESMA
-// conta e não têm o que fazer importando de um módulo de HUD. Reexportada aqui sob o nome de sempre.
+/** Screen grid: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (the 3rd screen is centred on the bottom row). */
+// The grid lives in core/screens (a leaf, no dependencies), because the layout and the CRT need the SAME arithmetic and
+// have no business importing from a HUD module. Re-exported here under its usual name.
 export { screenGrid } from '../core/screens.js';
 /**
- * Posição/tamanho da tela `i` numa grade de `n` jogadores. Verbatim de screenRect(i) — que lia `numPlayers`
- * global; aqui `n` é parâmetro (mesma conta, testável sem estado). Caso especial preservado: com 3 telas, a
- * terceira é centralizada na linha de baixo, para casar com o posicionamento do render (configureRender).
+ * Position/size of screen `i` in a grid of `n` players; `n` is a parameter, so it is testable without state. Special
+ * case: with 3 screens, the third is centred on the bottom row, to match the renderer's positioning.
  */
 export function screenRect(i, n) {
     const { cols, rows } = screenGrid(n);
@@ -45,83 +36,88 @@ export function screenRect(i, n) {
         colFrac = (1 - 1 / cols) / 2;
     return { L: (colFrac * 100) + '%', T: (row / rows * 100) + '%', W: (100 / cols) + '%', H: (100 / rows) + '%' };
 }
-/** Quantas telas o HUD monta: ao menos uma, mesmo antes de `players[]` existir no boot. Verbatim (Math.max(1,…)). */
+/** How many screens the HUD mounts: at least one, even before `players[]` exists at boot. */
 export function screenCount(n) { return Math.max(1, n); }
-/** O texto que o leitor de tela ouve no contador. A MOLDURA é a chave; o NOME do objetivo atravessa por
- *  parâmetro — a regra do pilar 3 (ADR-0010), a mesma que o currículo segue. */
-export const contadorLabel = (o) => t('hud.contador', { have: String(o.have), need: String(o.need), nome: o.name.text });
+/** The text a screen reader hears on the counter. The FRAME is the key; the objective's NAME passes through as a
+ *  parameter — pillar 3's rule (ADR-0010), the same the curriculum follows. */
+export const counterLabel = (t, o) => t('hud.contador', { have: String(o.have), need: String(o.need), nome: o.name.text });
 /**
- * Markup do contador (objetivo na 1ª coluna, poder na 2ª).
+ * The counter's markup (objective in the 1st column, power in the 2nd).
  *
- * O objetivo entra INTEIRO — nome, quanto tem, quanto precisa — em vez de só o alvo numérico, e o ícone entra
- * por injeção. É o que tira o desenho da moeda de dentro da engine: o HUD mostra o que o jogo declarou
- * (campo 5 do contrato), sem saber se é moeda, palavra ou conta.
+ * The objective comes in WHOLE — name, how much you have, how much you need — and the icon by injection: the HUD shows
+ * what the game declared (field 5 of the contract), without knowing whether it is a coin, a word or a sum.
  *
- * O `aria-label` é a parte que não é renomeação: sem o nome do objetivo não havia o que dizer, e o contador
- * era mudo para quem não vê a tela.
+ * The accessible name is set separately (`applyCounterLabel`), because the objective's name is outside data.
  */
-export function vphudHtml(objetivo, icone) {
-    return '<span class="vphud-obj"><b class="vphud-ico">' + icone
-        + '</b> <b class="vphud-n">' + numero(objetivo.have) + '</b> / ' + numero(objetivo.need)
+export function vphudHtml(objective, icon) {
+    return '<span class="vphud-obj"><b class="vphud-ico">' + icon
+        + '</b> <b class="vphud-n">' + finiteOrZero(objective.have) + '</b> / ' + finiteOrZero(objective.need)
         + '</span><span class="vphud-power"><b class="vphud-ico">✨</b> <span class="vphud-pw">—</span></span>';
 }
 /**
- * PÕE O NOME DECLARADO PELO JOGO NO RÓTULO DO LEITOR DE TELA — por atributo, nunca por markup (issue #106).
+ * PUTS THE NAME THE GAME DECLARED INTO THE SCREEN READER'S LABEL — by attribute, never by markup (issue #106).
  *
- * ⚠️ ESTE É UM VETOR QUE A AUDITORIA DE 2026-08-26 NÃO TINHA COMO CONHECER, e vale dizer por quê: ela varreu
- * por FONTE DE DADO e concluiu, com razão para a época, que nada de fora chegava a markup. Depois disso o
- * contrato passou a existir (ADR-0030) e os jogos passaram a viver em REPOSITÓRIOS SEPARADOS, consumindo a
- * engine como pacote (ADR-0083). O `name.text` do objetivo é texto de um jogo que esta árvore não revê.
+ * ⚠️ The games live in SEPARATE REPOSITORIES and consume the engine as a package (ADR-0083), so the objective's
+ * `name.text` is text from a game this tree does not review.
  *
- * ⚠️ E ELE ENTRAVA NUM ATRIBUTO, que é o pior contexto dos dois: dentro de um elemento uma aspa é inofensiva,
- * dentro de `aria-label="…"` ela FECHA o atributo e o que vem a seguir vira atributo — um `onmouseover` sem
- * precisar de uma única tag.
+ * ⚠️ AND IT GOES INTO AN ATTRIBUTE, the worse of the two contexts: inside an element a quote is harmless; inside
+ * `aria-label="…"` it CLOSES the attribute and what follows becomes an attribute — an `onmouseover` without a single
+ * tag.
  *
- * `setAttribute` escapa por construção, e é por isso que a resposta é «construir nós» e não «escapar à mão»:
- * um escape esquecido não deixa rasto; um `setAttribute` esquecido tira o rótulo, e há caso a prendê-lo.
+ * `setAttribute` escapes by construction, which is why the answer is building nodes and not escaping by hand: a
+ * forgotten escape leaves no trace; a forgotten `setAttribute` removes the label, and a case holds it.
  */
-export function aplicarRotuloDoContador(vphud, objetivo) {
-    vphud?.querySelector('.vphud-obj')?.setAttribute('aria-label', contadorLabel(objetivo));
+export function applyCounterLabel(t, vphud, objective) {
+    vphud?.querySelector('.vphud-obj')?.setAttribute('aria-label', counterLabel(t, objective));
 }
 /**
- * Um número do jogo, coagido.
+ * A number from the game, coerced.
  *
- * ⚠️ `Objective.have` É `number` NO TIPO E O TIPO NÃO ATRAVESSA A FRONTEIRA DO PACOTE: um jogo em JavaScript
- * puro, ou compilado de outra árvore, devolve o que quiser. Colar isso num template literal é a mesma
- * categoria de defeito que o nome — só que mais fácil de esquecer, porque «é um número» está escrito no tipo.
- * Um não-número vira `0`, que é falso mas inofensivo; deixar passar seria falso E perigoso.
+ * ⚠️ `Objective.have` IS `number` IN THE TYPE AND THE TYPE DOES NOT CROSS THE PACKAGE BOUNDARY: a game in plain
+ * JavaScript, or compiled from another tree, returns whatever it likes. Pasting that into a template literal is the
+ * same category of defect as the name — only easier to forget, because "it is a number" is written in the type. A
+ * non-number becomes `0`, which is false but harmless; letting it through would be false AND dangerous.
  */
-function numero(v) {
+function finiteOrZero(v) {
     return Number.isFinite(v) ? v : 0;
 }
-/** Markup do selo "aperte um botão para entrar" (tela criada em jogo, ainda sem dono). `i` é o índice 0-based. */
-export function waitBadgeHtml(i) {
-    return '<div class="vphud-quit vp-wait">Jogador ' + (i + 1)
-        + ': aperte um botão do SEU teclado ou de um controle livre para entrar</div>';
+/**
+ * The markup of the press-a-button-to-join badge (a screen created mid-game, still with no owner). `i` is 0-based.
+ *
+ * 🔴 FROM THE DICTIONARY, never raw text: it is the only sentence that tells the child who just got a screen HOW to join,
+ * and the badge is their whole screen at that instant, not a corner detail.
+ *
+ * 📌 ITS OWN KEY and not the existing `sr.player.pressToJoin`, although the two look alike: the screen reader's says to
+ * press a button, this one says WHICH — your own keyboard or a free controller —, because whoever reads it is looking
+ * at a screen with other people around and needs to know it is not just any keyboard. Merging them would erase that
+ * half of one of the two.
+ */
+export function waitBadgeHtml(t, i) {
+    return '<div class="vphud-quit vp-wait">' + t('hud.waitBadge', { n: i + 1 }) + '</div>';
 }
 /**
- * Estado do HUD de um jogador. Verbatim do corpo de updateGameHud(), só que como valor.
- * `powerShort` é o POWER_SHORT do game.js (injetado — a mesma FUNÇÃO que game/coin-spawning.ts já recebe).
- * Função e não tabela: o texto depende do idioma ATUAL, e uma tabela lida no boot ficaria congelada nele.
+ * One player's HUD state, as a value. `powerShort` is injected by the host (the same function other game modules
+ * receive). A function and not a table: the text depends on the CURRENT language, and a table read at boot would stay
+ * frozen in it.
  */
-export function hudRowView(p, powerShort, objetivo) {
+export function hudRowView(t, p, powerShort, objective) {
     return {
-        have: String(objetivo.have),
-        label: contadorLabel(objetivo),
-        // O `|| '—'` FICA, mesmo com o resolvedor já tratando desconhecido. Não é redundância: é a garantia de
-        // que o campo do poder NUNCA aparece em branco no HUD, e ela não pode depender de todo consumidor futuro
-        // lembrar de tratar o caso. Um teste meu ia perdê-la nesta mudança e reprovou por isso.
+        have: String(objective.have),
+        label: counterLabel(t, objective),
+        // The `|| '—'` STAYS, even with the resolver already handling unknowns. It is not redundancy: it guarantees the
+        // power field NEVER appears blank on the HUD, and that cannot depend on every future consumer remembering the case.
         power: powerShort(p.activePower) || '—',
         quitHidden: !p.quit,
         visibility: p.quit ? 'hidden' : 'visible',
     };
 }
 export function initHud(ctx) {
+    const { t } = ctx;
     let gameHudEl = null;
     let vpHudDom = [];
     let vpQuitDom = [];
     let vpScreens = [];
-    /** A sub-camada de EXPERIÊNCIA de cada tela — o que a empatia atrapalha. Ver `buildGameHud`. */
+    /** Each screen's EXPERIENCE sub-layer — what empathy gets in the way of. See `buildGameHud`. */
     let vpExpDom = [];
     function buildGameHud() {
         if (!gameHudEl)
@@ -136,44 +132,46 @@ export function initHud(ctx) {
         const panes = [];
         const bars = [];
         const n = ctx.getNumPlayers();
+        // the screens are made by the document the hud is drawn in — the host's own, never the global (ADR-0221 step 7d)
+        const doc = gameHudEl.ownerDocument;
         for (let i = 0; i < screenCount(n); i++) {
             const r = screenRect(i, n);
-            const scr = document.createElement('div');
+            const scr = doc.createElement('div');
             scr.className = 'player-screen';
             scr.dataset.player = String(i);
             scr.style.left = r.L;
             scr.style.top = r.T;
             scr.style.width = r.W;
             scr.style.height = r.H;
-            // A TELA TEM DUAS SUB-CAMADAS, e a divisão é de PAPEL (issue #82, decisão do Dev):
+            // THE SCREEN HAS TWO SUB-LAYERS, divided by ROLE (issue #82, the Dev's decision):
             //
-            //   · EXPERIÊNCIA (`.screen-exp`) — HUD, selo de abandono e a atividade pedagógica do multi-tela. O
-            //     modo de EMPATIA precisa atrapalhar aqui: é o prejuízo que a pessoa tem de sentir.
-            //   · CONTROLE (o painel de pausa, irmão) — nunca é atingido por empatia. Simulação não é
-            //     acessibilidade: é criar dificuldade onde a facilidade não existe. O que existe para DAR ACESSO
-            //     — pausa, legenda, controle de toque — não pode ser degradado por ela.
+            //   · EXPERIENCE (`.screen-exp`) — HUD, quit badge and the multi-screen learning activity. EMPATHY mode has to get
+            //     in the way here: it is the harm the person has to feel.
+            //   · CONTROL (the pause panel, a sibling) — never touched by empathy. Simulation is not accessibility: it creates
+            //     difficulty where ease does not exist. What exists to GIVE ACCESS — pause, captions, touch controls — cannot
+            //     be degraded by it.
             //
-            // Elas são IRMÃS e não pai/filho porque `filter` de CSS desce para os descendentes e um filho não
-            // consegue cancelá-lo: com a pausa dentro da experiência, não haveria como isentá-la.
-            const exp = document.createElement('div');
+            // They are SIBLINGS and not parent/child because a CSS `filter` descends to descendants and a child cannot cancel
+            // it: with the pause inside the experience, there would be no way to exempt it.
+            const exp = doc.createElement('div');
             exp.className = 'screen-exp';
             scr.appendChild(exp);
             vpExpDom.push(exp);
-            const d = document.createElement('div');
+            const d = doc.createElement('div');
             d.className = 'vphud';
             d.innerHTML = vphudHtml(ctx.hudObjective(i), ctx.hudIcon);
-            aplicarRotuloDoContador(d, ctx.hudObjective(i)); // #106: o nome vem do JOGO — atributo, nunca markup
+            applyCounterLabel(t, d, ctx.hudObjective(i)); // #106: the name comes from the GAME — attribute, never markup
             exp.appendChild(d);
             vpHudDom.push(d);
-            const q = document.createElement('div');
+            const q = doc.createElement('div');
             q.className = 'vphud-quit';
             q.hidden = true;
             q.textContent = 'Jogo abandonado';
             exp.appendChild(q);
             vpQuitDom.push(q);
-            // A BARRA RÁPIDA entra entre a experiência e a pausa, e é IRMÃ das duas. Não vai DENTRO da
-            // `.screen-exp` porque `filter` de CSS desce para os descendentes e um filho não consegue cancelá-lo:
-            // ali dentro, o modo empatia degradaria justamente o que existe para dar acesso.
+            // THE QUICK BAR goes between the experience and the pause, as a SIBLING of both. Not INSIDE `.screen-exp`, because
+            // a CSS `filter` descends to descendants and a child cannot cancel it: in there, empathy mode would degrade exactly
+            // what exists to give access.
             const bar = ctx.buildQuickBar(i);
             scr.appendChild(bar);
             bars.push(bar);
@@ -183,9 +181,7 @@ export function initHud(ctx) {
             gameHudEl.appendChild(scr);
             vpScreens.push(scr);
         }
-        // O original terminava com `vpPause` preenchido e dois efeitos DEFENSIVOS (applyLetra/renderPauseLegend em
-        // try/catch, porque no 1º build do init LETRA/PAD_DESIGNS ainda estão em TDZ). Ambos são de OUTROS slices →
-        // saem por este gancho, com o try/catch preservado no game.js. Ver "chamada defensiva" no relatório.
+        // What depends on the finished panels belongs to other modules, so it leaves through these hooks.
         ctx.onBarsBuilt?.(bars);
         ctx.onScreensBuilt?.(panes);
     }
@@ -195,12 +191,12 @@ export function initHud(ctx) {
             if (!p)
                 continue;
             const d = vpHudDom[i];
-            const v = hudRowView(p, ctx.powerShort, ctx.hudObjective(i));
+            const v = hudRowView(t, p, ctx.powerShort, ctx.hudObjective(i));
             const n = d.querySelector('.vphud-n');
             if (n)
                 n.textContent = v.have;
-            // O rótulo acessível acompanha o número. Escrevê-lo só na montagem deixaria o leitor de tela repetindo
-            // "0 de 10" a partida inteira — pior do que não ter rótulo, porque soa como informação.
+            // The accessible label follows the number. Writing it only at mount would leave the screen reader repeating
+            // "0 of 10" the whole match — worse than no label, because it sounds like information.
             const obj = d.querySelector('.vphud-obj');
             if (obj)
                 obj.setAttribute('aria-label', v.label);
@@ -210,14 +206,14 @@ export function initHud(ctx) {
             if (vpQuitDom[i])
                 vpQuitDom[i].hidden = v.quitHidden;
             if (d)
-                d.style.visibility = v.visibility; // jogador que saiu: tela preta "jogo abandonado"
+                d.style.visibility = v.visibility; // a player who left: black screen with the quit badge
         }
     }
     const getScreen = (i) => vpScreens[i] ?? null;
     function showWaitingBadge(i) {
         const scr = vpScreens[i];
         if (scr && !scr.querySelector('.vp-wait'))
-            scr.insertAdjacentHTML('beforeend', waitBadgeHtml(i));
+            scr.insertAdjacentHTML('beforeend', waitBadgeHtml(t, i));
     }
     function clearWaitingBadge(i) {
         const scr = vpScreens[i];

package/dist-pkg/ui/item-announcement.d.ts

@@ -1,19 +1,20 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 export interface ItemDeMenu {
-    /** O que o item é. Espaço em branco de markup é normalizado aqui. */
-    rotulo: string;
-    /** O valor ou estado: "ativado", "38%", a palavra de exemplo do minijogo. Opcional. */
-    estado?: string;
-    /** Posição na lista, contada a partir de 1 — é o número que a criança ouve, não o índice do array. */
-    posicao: number;
-    /** Quantos itens a lista tem. */
+    /** What the item is. Markup whitespace is normalised here. */
+    label: string;
+    /** The value or state: "on", "38%", the game's example word. Optional. */
+    state?: string;
+    /** Position in the list, counted from 1 — the number the child hears, not the array index. */
+    position: number;
+    /** How many items the list has. */
     total: number;
 }
 /**
- * A frase que o item narra.
+ * The sentence the item narrates.
  *
- * A posição fora de faixa NÃO é anunciada, e é decisão, não guarda defensivo: um item filtrado por
- * visibilidade sai da lista e deixa o índice de quem sobrou fora dela. "0 de 7" ensina uma geografia falsa
- * do menu, e a criança confia nela — número errado é pior que número nenhum.
+ * An out-of-range position is NOT announced, and that is a decision, not a defensive guard: an item filtered out
+ * by visibility leaves the list and can leave the index of the ones that remain out of range. "0 of 7" teaches a
+ * false geography of the menu, and the child trusts it — a wrong number is worse than no number.
  */
-export declare function anunciarItem(item: ItemDeMenu, comIndice: boolean): string;
+export declare function announceItem(t: Translate, item: ItemDeMenu, withIndex: boolean): string;

package/dist-pkg/ui/item-announcement.js

@@ -1,36 +1,35 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/item-announcement — COMO UM ITEM DE MENU SE ANUNCIA (ADR-0044, item 3).
+// ui/item-announcement — HOW A MENU ITEM ANNOUNCES ITSELF (ADR-0044, item 3; ADR-0167).
 //
-// A XAG 106 descreve a frase inteira — "Gamma, slider, 38%, 6 of 9" — e este módulo monta a parte que o jogo
-// controla: RÓTULO, ESTADO e ÍNDICE, nessa ordem, com o índice no FIM.
+// XAG 106 describes the whole sentence — "Gamma, slider, 38%, 6 of 9" — and this module builds the part the game
+// controls: LABEL, STATE and INDEX, in that order, with the index at the END.
 //
-// POR QUE O ÍNDICE VAI NO FIM. Quem varre um menu por escuta interrompe assim que reconhece o item — é o que
-// a narração interrompível do item 2 passou a permitir. Com o número na frente, a contagem seria a única
-// parte que SEMPRE daria tempo de ouvir, e o rótulo, a única que interessa, a que nunca chegaria.
+// WHY THE INDEX GOES LAST. Whoever scans a menu by ear interrupts as soon as they recognise the item — which the
+// interruptible narration allows. With the number first, the count would be the one part there is ALWAYS time to
+// hear, and the label, the only part that matters, the one that never arrives.
 //
-// POR QUE ELE PODE SER DESLIGADO. Para quem já sabe o menu de cor, o número vira ruído em toda passagem. A
-// XAG pede a opção explicitamente, e o princípio é o mesmo do resto do projeto: acessibilidade que não se
-// pode desligar é imposição, não ajuste.
+// WHY IT CAN BE TURNED OFF. For someone who knows the menu by heart, the number is noise on every pass. XAG asks
+// for the option explicitly, and the principle is the one the whole project follows: accessibility that cannot be
+// turned off is an imposition, not a setting.
 //
-// ESTE MÓDULO NÃO TOCA O DOM. Quem chama separa as partes (o rótulo do botão, o sub-rótulo, o estado do
-// alternador) e recebe uma frase. É o que permite que a regra seja a MESMA na abertura, na pausa e nas
-// atividades sem que cada tela reinvente a pontuação.
-import { t } from '../core/i18n.js';
-/** Espaço em branco de markup (quebras de linha, indentação) vira UM espaço; pontas somem. */
-const enxuto = (s) => (s || '').replace(/\s+/g, ' ').trim();
+// THIS MODULE DOES NOT TOUCH THE DOM. The caller separates the parts (the button's label, the sub-label, the
+// toggle's state) and gets a sentence back. That is what keeps the rule the SAME on every screen, without each
+// one reinventing the punctuation.
+/** Markup whitespace (line breaks, indentation) becomes ONE space; the ends are trimmed. */
+const tidy = (s) => (s || '').replace(/\s+/g, ' ').trim();
 /**
- * A frase que o item narra.
+ * The sentence the item narrates.
  *
- * A posição fora de faixa NÃO é anunciada, e é decisão, não guarda defensivo: um item filtrado por
- * visibilidade sai da lista e deixa o índice de quem sobrou fora dela. "0 de 7" ensina uma geografia falsa
- * do menu, e a criança confia nela — número errado é pior que número nenhum.
+ * An out-of-range position is NOT announced, and that is a decision, not a defensive guard: an item filtered out
+ * by visibility leaves the list and can leave the index of the ones that remain out of range. "0 of 7" teaches a
+ * false geography of the menu, and the child trusts it — a wrong number is worse than no number.
  */
-export function anunciarItem(item, comIndice) {
-    const valeIndice = comIndice && item.total >= 1 && item.posicao >= 1 && item.posicao <= item.total;
-    const partes = [
-        enxuto(item.rotulo),
-        enxuto(item.estado),
-        valeIndice ? t('sr.menu.index', { n: item.posicao, m: item.total }) : '',
+export function announceItem(t, item, withIndex) {
+    const indexApplies = withIndex && item.total >= 1 && item.position >= 1 && item.position <= item.total;
+    const parts = [
+        tidy(item.label),
+        tidy(item.state),
+        indexApplies ? t('sr.menu.index', { n: item.position, m: item.total }) : '',
     ];
-    return partes.filter(Boolean).join(', ');
+    return parts.filter(Boolean).join(', ');
 }

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

@@ -1,38 +1,113 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * A RÉGUA DO ALVO DE TOQUE, INDEXADA PELA ALTURA DO VIEWPORT (ADR-0095, decisão do Dev).
+ * THE TOUCH TARGET FLOOR, in CSS px, for a CSS scale factor `k` (ADR-0163).
  *
- * ⚠️ O ALVO DEIXOU DE SER UM NÚMERO E PASSOU A SER UMA FUNÇÃO DA TELA, e o motivo é um custo que o gate de
- * `pausa-44px` já tinha MEDIDO e deixado por resolver: a 640×360 o cartão de pausa não cabe e a lista ROLA.
- * Remedido em 06/09, porque o cartão mudou desde então: 391 px de conteúdo para 349 visíveis, ou seja 42 px
- * de excesso (o comentário antigo dizia 413/353). Um alvo de 44 px que exige rolagem para ser alcançado
- * pode custar mais dedo do que um de 24 px que está à vista.
+ * 🔴 IT WAS A RULER BY VIEWPORT HEIGHT (ADR-0095: 24 px under 540, 34 under 720, 44 above), because a 640×360 pause
+ * card with 44 px items scrolled. ADR-0163 made the resolution the engine's — never under 640×360 — and the Dev set the
+ * target — «44px é o correto, eu errei quando disse 42px» — so the floor is 44 px at the minimum (k = 2) and
+ * grows with the scale, like the text; there is no smaller screen left to shrink for.
+ */
+export declare function minimumTarget(k: number): number;
+/** One node inside the region, as measured by whoever calls: its computed font size if it holds text, its box if it is a target. */
+export interface NodeMeasure {
+    readonly name: string;
+    readonly daEngine: boolean;
+    readonly fontPx: number | null;
+    readonly target: {
+        readonly w: number;
+        readonly h: number;
+    } | null;
+}
+/**
+ * WHAT A CARTRIDGE DRAWS UNDER THE FLOOR (ADR-0163 rule 4): text under 8·k px (16 at 640×360) and targets whose SMALLER
+ * side is under 22·k px (44 at 640×360). The engine's own nodes are not the cartridge's to answer for, and a node with no
+ * area is not drawn. Half a pixel of slack absorbs subpixel layout.
+ */
+export declare function belowFloor(nodes: readonly NodeMeasure[], k: number): {
+    text: string[];
+    targets: string[];
+};
+/**
+ * THE GAME'S NODES THAT INVADE THE ACCESSIBILITY BAR'S RECTANGLE (ADR-0148 §3).
+ *
+ * 🔴 The bar is `position:absolute` INSIDE `#game-region`, so a game can draw right over it — a question title on top
+ * of the buttons, and the child looking for blind mode finds text over them.
+ *
+ * ⚠️ AND NOTHING FAILS. No error, no type, no console: just a row of covered buttons — and whoever depends on it most is
+ * precisely whoever cannot see it is covered.
  *
- * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ * 📌 PURE AND WITH THE BOXES INJECTED, so the gate can drive it with no browser. Whoever calls measures; what this
+ * function decides is what COUNTS as an invasion, which is the part people get wrong.
  *
- *     altura ≥ 720   44 px   WCAG 2.2 · 2.5.5 Target Size (Enhanced) — AAA
- *     altura ≥ 540   34 px   o degrau do meio
- *     altura <  540  24 px   WCAG 2.2 · 2.5.8 Target Size (Minimum)  — AA
+ * ⚠️ IT IGNORES THE BAR'S OWN DESCENDANTS: its buttons intersect it by definition, and counting them would make the gate
+ * accuse always — the defect ADR-0106 §2 calls drowning what can be fixed.
+ */
+export interface NamedBox {
+    readonly name: string;
+    readonly box: Box;
+    readonly isBar: boolean;
+}
+export interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export declare function barIntruders(barBox: Box | null, nodes: readonly NamedBox[]): string[];
+/** The document a layout measures — only the lookup it uses. */
+export type LayoutDoc = Pick<Document, 'querySelector'>;
+/**
+ * The scale ADR-0001 gives a stage: the factor in REAL pixels (whole, except at the floor — ADR-0179), the CSS factor, and
+ * the region's CSS size.
+ */
+export interface Scale {
+    readonly kDev: number;
+    readonly k: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * ADR-0001 AS A PURE FUNCTION — so the engine can apply it to every cartridge (ADR-0163) and a test can pin it.
  *
- * ⚠️ ISTO É «MARCAR HONESTAMENTE ONDE SÓ DÁ AA», que é regra escrita do projeto — e não uma renúncia
- * silenciosa. O que se perde em 360 está registrado com número no ADR-0095: a 96 px/pol, 24 CSS px são
- * 6,4 mm, abaixo do alvo de polegar de 9,6 mm que o painel de toque deste jogo cita. É por isso que o
- * ESPAÇAMENTO entre alvos passa a ser o que protege o dedo onde o tamanho não pode — a mesma saída que a
- * própria 2.5.8 dá na sua exceção de spacing.
+ * Integer multiple of 320×180 (per the screen grid) in REAL pixels; up to 5 logical px of crop per side when that buys one
+ * more step (the `−10`: `base·kDev − avail·dpr ≤ 10·kDev`). Never under 2 CSS px per logical pixel — 640×360 CSS, text 16 px,
+ * targets 44 px: where the whole multiple gives less (a fractional display scale on the minimum window) the scale is exactly
+ * 2 CSS px, whole in real pixels or not, because WCAG 2.2 AA decides (ADR-0179).
  */
-export declare const REGUA_DE_ALVO: readonly {
-    readonly altura: number;
-    readonly alvo: number;
-}[];
+export declare function stageScale(availW: number, availH: number, dpr: number, baseW: number, baseH: number): Scale;
 /**
- * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ * Writes a scale onto the game region: its size, and the UI variables that grow with it.
  *
- * ⚠️ NUNCA DEVOLVE MENOS DE 24: abaixo disso não é «AA num aparelho pequeno», é furar o piso da WCAG. Uma
- * tela mais baixa que 360 não compra o direito de encolher mais — compra o direito de mostrar menos itens.
+ * ⚠️ HOST-INJECTED (the region is passed in): `createGame` serves documents that
+ * are not the global one — the fault the root's finding 15 names about reaching `document` from under the injection.
+ */
+export declare function applyScale(region: HTMLElement, e: Scale): void;
+export interface LayoutCtx {
+    /** The document holding the stage shell and `#game-region` — passed, never the global one (ADR-0232). */
+    doc: LayoutDoc;
+    /** The window, for its pixel ratio only: the scale is locked to whole REAL pixels. */
+    win: Pick<Window, 'devicePixelRatio'>;
+    /**
+     * THE PLAYER COUNT, as the GETTER of the round the game owns (ADR-0038): the screen grid sets the base size. A number
+     * would freeze the count at the first layout.
+     */
+    numPlayers: () => number;
+    /**
+     * CALLED AFTER EVERY SCALE — the root's CRT re-anchoring its scanlines to real pixels (`engine.crt.scanVars`).
+     * REQUIRED: the layout used to call the page's one CRT by import, and a game that forgets this would get scanlines
+     * spaced for the previous scale, with no error. A game with no CRT passes `() => {}` and says so.
+     */
+    afterScale: () => void;
+    /** Logs the scale to the console (`?debug=true`). Optional: absent, nothing is logged. */
+    debug?: () => boolean;
+}
+/** A game's stage scaler. */
+export interface Layout {
+    /** Measures the shell, scales `#game-region` and calls `afterScale`. Call it at boot and on every `resize`. */
+    layout(): void;
+}
+/**
+ * Builds a stage scaler over the document and window it is handed. It keeps nothing between calls: every `layout()`
+ * measures again, reads the player count again, and writes onto the region.
  */
-export declare function alvoMinimoDeToque(alturaCss: number): number;
-/** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
-export declare function initLayout(deps: {
-    numJogadores: () => number;
-}): void;
-export declare function layout(): void;
+export declare function createLayout(ctx: LayoutCtx): Layout;