@the-inclusionist/engine 9.0.0 → 10.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/latch-refusal.d.ts

@@ -1,32 +1,33 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Uma linha pronta a traduzir. `null` = há escolha, e não há nada a dizer. */
-export interface RecusaDaAlternancia {
-    readonly chave: string;
-    /** O transporte que a exige — fica disponível para quem quiser compor a frase de outro modo. */
-    readonly transporte: string;
+/** A line ready to translate. `null` = there is a choice, and nothing to say. */
+export interface LatchRefusal {
+    readonly key: string;
+    /** The transport that requires it — available to whoever wants to compose the sentence another way. */
+    readonly transport: string;
 }
 /**
- * A chave i18n do motivo, POR TRANSPORTE.
+ * The i18n key of the reason, PER TRANSPORT.
  *
- * ⚠️ QUATRO CHAVES E NÃO UMA COM `{aparelho}`, e a razão é de tradução e não de estilo: «os gestos» é plural
- * e «o olhar» não, logo uma frase única obrigaria cada idioma a montar concordância a partir de um
- * substantivo solto. É exactamente o defeito que o `sr.nav.clockOne` registou para «às 1 horas», e que o
- * `ui/simulation-refusal` já recusou pela mesma razão com os três eixos dele.
+ * ⚠️ FOUR KEYS AND NOT ONE WITH `{aparelho}`, and the reason is translation, not style: «os gestos» is plural and
+ * «o olhar» is not, so a single sentence would force each language to build agreement from a loose noun. It is
+ * exactly the defect `sr.nav.clockOne` recorded for «às 1 horas», and that `ui/simulation-refusal` already refused
+ * for the same reason with its three axes.
  */
-export declare const CHAVE_DA_RECUSA: Readonly<Record<string, string>>;
+export declare const REFUSAL_KEY: Readonly<Record<string, string>>;
 /**
- * A alternância pode ser desligada neste aparelho? E se não, o que dizer.
+ * Can latching be turned off on this device? And if not, what to say.
  *
- * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
+ * `null` = it can; the interface shows nothing, because a warning that always appears stops being read.
  */
-export declare function recusaDaAlternancia(transporte: string): RecusaDaAlternancia | null;
+export declare function latchRefusal(transportName: string): LatchRefusal | null;
 /**
- * O controle continua NA TELA quando a alternância é exigida?
+ * Does the control stay ON SCREEN when latching is required?
  *
- * ⚠️ SEMPRE, e é a metade «não some» da cláusula 3. Existe como função com nome próprio, e não como um
- * `!recusa` no ponto de uso, porque responde a outra pergunta: `recusaDaAlternancia` diz *por que* não dá;
- * esta diz *que a linha continua na tela*. Juntá-las faria «não há motivo» parecer «não desenhe a linha».
+ * ⚠️ ALWAYS, and it is the "does not disappear" half of clause 3. It exists as a function with its own name, and
+ * not as a negated refusal at the point of use, because it answers another question: `latchRefusal` says *why* it
+ * cannot; this says *that the row stays on screen*. Merging them would make "no reason" look like "do not draw the
+ * row".
  */
-export declare function mostraMesmoExigida(): boolean;
-/** Os transportes que exigem alternância, para quem precisa de os enumerar. Vem da REGRA, não de uma cópia. */
-export declare const EXIGEM_ALTERNANCIA: ReadonlySet<string>;
+export declare function showsEvenWhenRequired(): boolean;
+/** The transports that require latching, for whoever needs to enumerate them. It comes from the RULE, not a copy. */
+export declare const NEED_LATCH: ReadonlySet<string>;