@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/focus-trap.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/focus-trap.ts — A ARMADILHA DE FOCO. O segundo fio da issue #109, e o único dos três que não existia
+// EM LADO NENHUM da engine: os outros dois eram construídos e deixados desligados, este nunca foi escrito.
+// `ui/settings-panel.ts:17-19` diz isso por escrito — *"não instala armadilha de foco (o original também não
+// tem)"*.
+//
+// ⚠️ E O DOCUMENTO JÁ PROMETE O CONTRÁRIO. Todo `.overlay__card` do `index.html` tem `aria-modal="true"`, o
+// que diz à tecnologia assistiva que o resto da página está inerte. O Tab não concorda: ele sai do diálogo e
+// entra no tabuleiro por baixo. É a pior forma de defeito de acessibilidade — não a ausência de uma promessa,
+// mas uma promessa que o teclado desmente. Quem usa leitor de tela sai para um jogo cujo estado não consegue
+// perceber, e não tem caminho de volta que perceba.
+//
+// ⚠️ SÓ INTERVÉM NAS BORDAS, e isso é decisão e não economia. Reimplementar a ordem de tabulação inteira
+// significaria reproduzir regras que o navegador já acerta — `tabindex` positivo, ordem do DOM em `shadow
+// root`, elementos que ficam focáveis por `contenteditable`. Uma armadilha que se mete no meio erra ao
+// caminhar; uma que só fecha o ciclo nas pontas não tem como errar o meio, porque não o toca.
+//
+// A regra fica em UMA função pura (`proximoNaArmadilha`), testável no project node sem DOM nenhum. O que
+// precisa de navegador é só ler quem está focado e chamar `.focus()`.
+/**
+ * O que conta como focável. Deliberadamente SEM `[contenteditable]` e sem `tabindex` positivo: os dois
+ * existem, mas não aparecem em nenhum diálogo desta engine (conferido), e um seletor que promete mais do que
+ * foi verificado é um seletor que mente na próxima revisão.
+ */
+export const SELETOR_FOCAVEL = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * Para onde o foco tem de ir quando o Tab está prestes a sair do diálogo — ou `null` quando não há nada a
+ * fazer e o navegador deve seguir sozinho.
+ *
+ * Os quatro casos, e o terceiro é a razão de isto existir:
+ *
+ *   1. lista VAZIA → `null`. Um diálogo sem nada focável é um defeito do diálogo, e prender o foco nele
+ *      deixaria a criança sem saída nenhuma. Melhor deixar sair do que trancar num lugar mudo.
+ *   2. o foco está no ÚLTIMO e vai para a frente → volta ao primeiro; no PRIMEIRO e vai para trás → vai ao
+ *      último. É o ciclo, que é o que «armadilha» quer dizer.
+ *   3. ⚠️ o foco está FORA da lista → traz de volta. É o caso que os outros três não cobrem: o foco pode já
+ *      ter escapado antes de esta armadilha existir, ou por um clique no tabuleiro, ou porque o diálogo
+ *      abriu sem focar nada. Sem ele a armadilha só funciona para quem já estava dentro.
+ *   4. o foco está no MEIO → `null`, e o navegador caminha. Ver o comentário do cabeçalho.
+ */
+export function proximoNaArmadilha(focaveis, atual, paraTras) {
+    if (focaveis.length === 0)
+        return null;
+    const primeiro = focaveis[0];
+    const ultimo = focaveis[focaveis.length - 1];
+    const i = atual === null ? -1 : focaveis.indexOf(atual);
+    if (i < 0)
+        return paraTras ? ultimo : primeiro; // caso 3: o foco estava fora
+    if (!paraTras && i === focaveis.length - 1)
+        return primeiro;
+    if (paraTras && i === 0)
+        return ultimo;
+    return null; // caso 4: o meio é do navegador
+}
+export function initFocusTrap(ctx) {
+    function aoTeclar(e) {
+        if (e.key !== 'Tab')
+            return;
+        const dialogo = ctx.overlayDeCima();
+        if (!dialogo)
+            return; // sem diálogo aberto o Tab é do jogo, e tem de continuar a ser
+        const alvo = proximoNaArmadilha(ctx.focaveisDe(dialogo), ctx.focoAtual(), e.shiftKey);
+        if (!alvo)
+            return;
+        e.preventDefault();
+        alvo.focus();
+    }
+    return {
+        aoTeclar,
+        attach: () => ctx.win.addEventListener('keydown', aoTeclar, true),
+        detach: () => ctx.win.removeEventListener?.('keydown', aoTeclar, true),
+    };
+}
+/**
+ * Os focáveis de um contêiner, no navegador. Vive aqui e não na raiz para as duas raízes não escreverem duas
+ * versões que divergiriam em silêncio — uma prenderia o foco e a outra deixaria escapar, no mesmo produto.
+ *
+ * ⚠️ A VISIBILIDADE É POR `getClientRects()`, e não por `offsetParent`.
+ *
+ * ⚠️ E A PRIMEIRA VERSÃO DESTE COMENTÁRIO ESTAVA ERRADA, o que vale mais registrar do que apagar: ele dizia
+ * que `offsetParent` é `null` para «qualquer elemento em `position: fixed`». Não é — é `null` para o elemento
+ * FIXO EM SI, e os descendentes dele devolvem o próprio contêiner. O teste de navegador reprovou a afirmação,
+ * que é exatamente o que um teste tem de fazer com uma justificativa inventada.
+ *
+ * A razão verdadeira é mais simples e mais forte: `getClientRects()` responde *«isto desenha alguma caixa?»*,
+ * o que cobre `display:none` em QUALQUER ancestral, elementos de tamanho zero e o caso do contêiner fixo —
+ * sem que quem lê precise de saber em que casos `offsetParent` tem buracos.
+ */
+export function focaveisNoDom(dentro) {
+    const todos = [...dentro.querySelectorAll(SELETOR_FOCAVEL)];
+    return todos.filter((el) => !el.hidden && el.getClientRects().length > 0);
+}

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

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Uma fonte do catálogo. `fam` é o NOME DA FONTE — nome próprio, nunca traduzido. `d` guarda CHAVE i18n da
+ * descrição, não o texto: mesma decisão de `VIZ_MODES` e `RM_LABEL`, e pelo mesmo motivo — uma tabela de
+ * `const` com texto resolve uma vez, no import, e fica congelada no idioma do boot.
+ */
+export type FontItem = {
+    k: string;
+    fam: string;
+    fb: string;
+    d?: string;
+    off?: string;
+};
+/** Um grupo do catálogo. `g` também guarda CHAVE ('font.group.sans'), pelo mesmo motivo. */
+export type FontGroup = {
+    g: string;
+    items: FontItem[];
+};
+export declare const FONT_GROUPS: FontGroup[];
+export declare const FONT_BY_KEY: Record<string, FontItem>;
+/** Narrow store shape these need — lets a caller inject a fake without touching real storage. */
+export interface FontStore {
+    get(key: string, fallback: string | null): string | null;
+    set(key: string, v: string): void;
+}
+export declare const FONT_KEY = "incl_font_k";
+export declare const FONT_KEY_LEGACY = "incl_fonte";
+/**
+ * A fonte de fábrica, com nome. Atkinson Hyperlegible foi desenhada pelo Braille Institute justamente para
+ * quem tem baixa visão — distingue as formas que mais se confundem (I/l/1, O/0). É por isso que ela é o padrão
+ * e não uma preferência estética, e é por isso que o "restaurar padrões" da tipografia (ADR-0028) volta para
+ * cá: o caminho de volta de um menu de acessibilidade tem que terminar na escolha mais legível, não numa
+ * qualquer. Usada em DOIS lugares — o fim da cadeia de boot logo abaixo e o reset do painel —, e uma constante
+ * porque duas cópias de um padrão são duas chances de o reset devolver algo que o jogo nunca usou.
+ */
+export declare const DEFAULT_FONT_KEY = "atkinson";
+/** Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY. */
+export declare function resolveFontKey(s: FontStore): string;
+export declare function persistFontKey(s: FontStore, k: string): void;
+export declare function loadFontKey(): string;
+export declare function saveFontKey(k: string): void;

package/dist-pkg/ui/fonts.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/fonts.ts — catálogo de fontes (dados) + índice por chave + carga/persistência da escolha. Módulo-folha
+// (só depende de storage). A instância `fontKey` e o setGameFont (aplica família/espaçamento) ficam no game.js.
+import * as store from '../platform/storage.js';
+export const FONT_GROUPS = [
+    { g: 'font.group.sans', items: [
+            { k: 'atkinson', fam: 'Atkinson Hyperlegible', fb: 'sans', d: 'font.desc.atkinson' },
+            { k: 'lexend', fam: 'Lexend', fb: 'sans', d: 'font.desc.lexend' },
+            { k: 'quattro', fam: 'iA Writer Quattro', fb: 'sans', d: 'font.desc.quattro' },
+            { k: 'andika', fam: 'Andika', fb: 'sans', d: 'font.desc.andika' },
+            { k: 'sourcesans', fam: 'Source Sans 3', fb: 'sans' },
+            { k: 'inter', fam: 'Inter', fb: 'sans' },
+            { k: 'opensans', fam: 'Open Sans', fb: 'sans' },
+            { k: 'lato', fam: 'Lato', fb: 'sans' }
+        ] },
+    { g: 'font.group.serif', items: [
+            { k: 'literata', fam: 'Literata', fb: 'serif' },
+            { k: 'sourceserif', fam: 'Source Serif 4', fb: 'serif' },
+            { k: 'newsreader', fam: 'Newsreader', fb: 'serif' }
+        ] },
+    { g: 'font.group.hand', items: [
+            { k: 'greatvibes', fam: 'Great Vibes', fb: 'cursive', d: 'font.desc.greatvibes' },
+            { k: 'pinyon', fam: 'Pinyon Script', fb: 'cursive', d: 'font.desc.pinyon' },
+            { k: 'ufcook', fam: 'UnifrakturCook', fb: 'cursive', d: 'font.desc.ufcook' },
+            { k: 'ufmag', fam: 'UnifrakturMaguntia', fb: 'cursive', d: 'font.desc.ufmag' },
+            { k: 'comicneue', fam: 'Comic Neue', fb: 'cursive', d: 'font.desc.comicneue' },
+            { k: 'learningcurve', fam: 'Learning Curve', fb: 'cursive', d: 'font.desc.learningcurve', off: 'font.off.pending' },
+            { k: 'kindergarten', fam: 'Kindergarten Pro', fb: 'cursive', d: 'font.desc.kindergarten', off: 'font.off.negotiating' }
+        ] },
+];
+export const FONT_BY_KEY = {};
+FONT_GROUPS.forEach((g) => g.items.forEach((it) => { FONT_BY_KEY[it.k] = it; }));
+export const FONT_KEY = 'incl_font_k';
+export const FONT_KEY_LEGACY = 'incl_fonte'; // pre-Fase-2: 'alfabetizacao' | 'dislexia'
+/**
+ * A fonte de fábrica, com nome. Atkinson Hyperlegible foi desenhada pelo Braille Institute justamente para
+ * quem tem baixa visão — distingue as formas que mais se confundem (I/l/1, O/0). É por isso que ela é o padrão
+ * e não uma preferência estética, e é por isso que o "restaurar padrões" da tipografia (ADR-0028) volta para
+ * cá: o caminho de volta de um menu de acessibilidade tem que terminar na escolha mais legível, não numa
+ * qualquer. Usada em DOIS lugares — o fim da cadeia de boot logo abaixo e o reset do painel —, e uma constante
+ * porque duas cópias de um padrão são duas chances de o reset devolver algo que o jogo nunca usou.
+ */
+export const DEFAULT_FONT_KEY = 'atkinson';
+/** Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY. */
+export function resolveFontKey(s) {
+    const k = s.get(FONT_KEY, null);
+    if (k && FONT_BY_KEY[k] && !FONT_BY_KEY[k].off)
+        return k;
+    const leg = s.get(FONT_KEY_LEGACY, null);
+    if (leg === 'alfabetizacao')
+        return 'andika';
+    if (leg === 'dislexia')
+        return 'lexend';
+    return DEFAULT_FONT_KEY;
+}
+export function persistFontKey(s, k) { s.set(FONT_KEY, k); }
+// Conveniencia sobre o storage real — mesma logica, sem duplicá-la.
+export function loadFontKey() { return resolveFontKey(store); }
+export function saveFontKey(k) { persistFontKey(store, k); }

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

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import type { Objective } from '../core/contract.js';
+import type { DomQuery } from '../core/dom-query.js';
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+/** Só os campos do jogador que o HUD lê. Estrutural de propósito: o `players[]` real é `unknown[]` no core/state. */
+/** O que o HUD lê do JOGADOR: o poder ativo e se ele desistiu. O progresso vem do `Objective`, não daqui —
+ *  `collected` saiu da fatia, e com ele a última coisa que o HUD sabia sobre juntar objetos. */
+export type HudPlayer = PlayerView<'activePower' | 'quit'>;
+/** Grade de telas: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (a 3ª tela é centralizada na linha de baixo). */
+export { screenGrid } from '../core/screens.js';
+export type { ScreenGrid } from '../core/screens.js';
+/** Retângulo da tela `i` em porcentagens de CSS, já prontas para `style.left/top/width/height`. */
+export interface ScreenRect {
+    L: string;
+    T: string;
+    W: string;
+    H: string;
+}
+/**
+ * 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).
+ */
+export declare function screenRect(i: number, n: number): ScreenRect;
+/** Quantas telas o HUD monta: ao menos uma, mesmo antes de `players[]` existir no boot. Verbatim (Math.max(1,…)). */
+export declare function screenCount(n: number): number;
+/** 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 declare const contadorLabel: (o: Objective) => string;
+/**
+ * Markup do contador (objetivo na 1ª coluna, poder na 2ª).
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function vphudHtml(objetivo: Objective, icone: string): string;
+/**
+ * PÕE O NOME DECLARADO PELO JOGO NO RÓTULO DO LEITOR DE TELA — por atributo, nunca por 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ê.
+ *
+ * ⚠️ 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.
+ *
+ * `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.
+ */
+export declare function aplicarRotuloDoContador(vphud: Element | null, objetivo: Objective): void;
+/** Markup do selo "aperte um botão para entrar" (tela criada em jogo, ainda sem dono). `i` é o índice 0-based. */
+export declare function waitBadgeHtml(i: number): string;
+/** Projeção do HUD de UMA tela: tudo que updateGameHud() escreve no DOM, sem tocar no DOM. */
+export interface HudRowView {
+    /** Texto do contador: quanto o jogador tem, verbatim (sem formatação nem clamp). */
+    have: string;
+    /** O que o leitor de tela ouve no contador — reescrito junto com o número, senão ele ficaria falando o
+     *  valor do primeiro quadro a partida inteira. É o defeito que um `aria-label` estático teria. */
+    label: string;
+    /** Rótulo curto do poder ativo, com o travessão como fallback de poder desconhecido/ausente. */
+    power: string;
+    /** `hidden` do selo "Jogo abandonado": escondido enquanto o jogador NÃO desistiu. */
+    quitHidden: boolean;
+    /** `style.visibility` do contador: quem desistiu vê tela preta com o selo, sem números. */
+    visibility: 'hidden' | 'visible';
+}
+/**
+ * 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.
+ */
+export declare function hudRowView(p: HudPlayer, powerShort: (kind: string) => string, objetivo: Objective): HudRowView;
+export interface HudCtx {
+    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
+     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
+     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    getNumPlayers: () => number;
+    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
+     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    getPlayers: () => readonly unknown[];
+    /** Seletor DOM (forma do `$` de ui/dom.ts), injetado — o módulo nunca alcança `document` por global. */
+    $: DomQuery;
+    /**
+     * POWER_SHORT: rótulos curtos de poder mostrados no HUD. Fica no game.js porque game/coin-spawning.ts
+     * (showPower) também o recebe — injetar evita a 2ª cópia da tabela.
+     */
+    powerShort: (kind: string) => string;
+    /**
+     * O OBJETIVO do jogador `i` — campo 5 do contrato (`core/contract.Objective`): o nome do que se junta,
+     * quanto tem e quanto precisa. FUNÇÃO e não valor, porque `have` muda a cada quadro.
+     *
+     * Era `hudTarget: number`, e antes disso `COIN_TARGET` por importação. Cada passo tirou uma coisa que o HUD
+     * sabia sobre o jogo: primeiro a dependência, agora o assunto.
+     */
+    hudObjective: (playerIndex: number) => Objective;
+    /** O ícone do contador. Era o desenho da moeda cravado no markup da engine; é do jogo, como o nome. */
+    hudIcon: string;
+    /**
+     * Painel de pausa da tela `i`. NÃO é deste módulo (slice de pausa/ícones): entra por injeção e o HUD só
+     * anexa o retorno dentro da `.player-screen` correspondente.
+     */
+    buildScreenPause: (i: number) => HTMLElement;
+    /**
+     * A BARRA RÁPIDA de acessibilidade da tela `i` (ui/pause-icons `buildQuickBar`). Anexada como IRMÃ da
+     * `.screen-exp`, e não dentro dela: a barra é CONTROLE, e o modo empatia não a alcança (issue #82).
+     */
+    buildQuickBar: (i: number) => HTMLElement;
+    /**
+     * Chamado no FIM de buildGameHud() com os painéis de pausa recém-criados, em ordem de tela. É o gancho onde o
+     * game.js reatribui `vpPause` (binding local dele) e roda o que o original rodava depois do laço
+     * (applyLetra/renderPauseLegend). Opcional: sem ele o HUD monta igual, só não avisa ninguém.
+     */
+    onScreensBuilt?: (pausePanels: HTMLElement[]) => void;
+    /** As barras rápidas recém-montadas, na ordem das telas. A raiz guarda para o `getA11yBars`. */
+    onBarsBuilt?: (bars: HTMLElement[]) => void;
+}
+export interface HudApi {
+    /** (Re)monta `#game-hud`: uma `.player-screen` por jogador, com HUD, selo de abandono e painel de pausa. */
+    buildGameHud: () => void;
+    /** Reescreve moedas/poder e o selo de abandono de todas as telas montadas. Chamado a cada frame. */
+    updateGameHud: () => void;
+    /** Contêiner `.player-screen` da tela `i` (o quiz de MP e outros overlays por jogador penduram aqui). */
+    getScreen: (i: number) => HTMLElement | null;
+    /** Cria o selo `.vp-wait` na tela `i` (idempotente: não duplica se já existir). */
+    showWaitingBadge: (i: number) => void;
+    /** Remove o selo `.vp-wait` da tela `i` (o jogador entrou). No-op se a tela ou o selo não existirem. */
+    clearWaitingBadge: (i: number) => void;
+}
+export declare function initHud(ctx: HudCtx): HudApi;

package/dist-pkg/ui/hud.js

@@ -0,0 +1,229 @@
+// 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().
+//
+// ========================= 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.
+//
+// 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.
+//
+// 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).
+import { screenGrid } from '../core/screens.js';
+import { t } from '../core/i18n.js';
+// ---------------------------------------------------------------------------------------------
+// Lógica PURA (nenhum `document`; testável no project node)
+// ---------------------------------------------------------------------------------------------
+/** 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.
+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).
+ */
+export function screenRect(i, n) {
+    const { cols, rows } = screenGrid(n);
+    const col = i % cols, row = Math.floor(i / cols);
+    let colFrac = col / cols;
+    if (n === 3 && i === 2)
+        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,…)). */
+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 });
+/**
+ * Markup do contador (objetivo na 1ª coluna, poder na 2ª).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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)
+        + '</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).
+ *
+ * ⚠️ 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ê.
+ *
+ * ⚠️ 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.
+ *
+ * `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.
+ */
+export function aplicarRotuloDoContador(vphud, objetivo) {
+    vphud?.querySelector('.vphud-obj')?.setAttribute('aria-label', contadorLabel(objetivo));
+}
+/**
+ * Um número do jogo, coagido.
+ *
+ * ⚠️ `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.
+ */
+function numero(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>';
+}
+/**
+ * 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.
+ */
+export function hudRowView(p, powerShort, objetivo) {
+    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.
+        power: powerShort(p.activePower) || '—',
+        quitHidden: !p.quit,
+        visibility: p.quit ? 'hidden' : 'visible',
+    };
+}
+export function initHud(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`. */
+    let vpExpDom = [];
+    function buildGameHud() {
+        if (!gameHudEl)
+            gameHudEl = ctx.$('#game-hud');
+        if (!gameHudEl)
+            return;
+        gameHudEl.innerHTML = '';
+        vpHudDom = [];
+        vpQuitDom = [];
+        vpScreens = [];
+        vpExpDom = [];
+        const panes = [];
+        const bars = [];
+        const n = ctx.getNumPlayers();
+        for (let i = 0; i < screenCount(n); i++) {
+            const r = screenRect(i, n);
+            const scr = document.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):
+            //
+            //   · 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.
+            //
+            // 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');
+            exp.className = 'screen-exp';
+            scr.appendChild(exp);
+            vpExpDom.push(exp);
+            const d = document.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
+            exp.appendChild(d);
+            vpHudDom.push(d);
+            const q = document.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.
+            const bar = ctx.buildQuickBar(i);
+            scr.appendChild(bar);
+            bars.push(bar);
+            const sp = ctx.buildScreenPause(i);
+            scr.appendChild(sp);
+            panes.push(sp);
+            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.
+        ctx.onBarsBuilt?.(bars);
+        ctx.onScreensBuilt?.(panes);
+    }
+    function updateGameHud() {
+        for (let i = 0; i < vpHudDom.length; i++) {
+            const p = ctx.getPlayers()[i];
+            if (!p)
+                continue;
+            const d = vpHudDom[i];
+            const v = hudRowView(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.
+            const obj = d.querySelector('.vphud-obj');
+            if (obj)
+                obj.setAttribute('aria-label', v.label);
+            const pw = d.querySelector('.vphud-pw');
+            if (pw)
+                pw.textContent = v.power;
+            if (vpQuitDom[i])
+                vpQuitDom[i].hidden = v.quitHidden;
+            if (d)
+                d.style.visibility = v.visibility; // jogador que saiu: tela preta "jogo abandonado"
+        }
+    }
+    const getScreen = (i) => vpScreens[i] ?? null;
+    function showWaitingBadge(i) {
+        const scr = vpScreens[i];
+        if (scr && !scr.querySelector('.vp-wait'))
+            scr.insertAdjacentHTML('beforeend', waitBadgeHtml(i));
+    }
+    function clearWaitingBadge(i) {
+        const scr = vpScreens[i];
+        const w = scr && scr.querySelector('.vp-wait');
+        if (w)
+            w.remove();
+    }
+    return { buildGameHud, updateGameHud, getScreen, showWaitingBadge, clearWaitingBadge };
+}

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

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+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. */
+    total: number;
+}
+/**
+ * A frase que o item narra.
+ *
+ * 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.
+ */
+export declare function anunciarItem(item: ItemDeMenu, comIndice: boolean): string;

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

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/item-announcement — COMO UM ITEM DE MENU SE ANUNCIA (ADR-0044, item 3).
+//
+// 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.
+//
+// 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.
+//
+// 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.
+//
+// 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();
+/**
+ * A frase que o item narra.
+ *
+ * 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.
+ */
+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 }) : '',
+    ];
+    return partes.filter(Boolean).join(', ');
+}

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

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** 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;