@the-inclusionist/engine 7.0.1 → 8.0.0-rc.1

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

@@ -1,4 +1,36 @@
 // 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).
+ *
+ * ⚠️ 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.
+ *
+ * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ *
+ *     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
+ *
+ * ⚠️ 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.
+ */
+export declare const REGUA_DE_ALVO: readonly {
+    readonly altura: number;
+    readonly alvo: number;
+}[];
+/**
+ * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ *
+ * ⚠️ 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.
+ */
+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;

package/dist-pkg/ui/layout.js

@@ -11,6 +11,45 @@
 import { $ } from './dom.js';
 import { screenBaseSize } from '../core/screens.js';
 import { crtScanVars } from '../render/crt.js';
+/**
+ * A RÉGUA DO ALVO DE TOQUE, INDEXADA PELA ALTURA DO VIEWPORT (ADR-0095, decisão do Dev).
+ *
+ * ⚠️ 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.
+ *
+ * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ *
+ *     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
+ *
+ * ⚠️ 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.
+ */
+export const REGUA_DE_ALVO = Object.freeze([
+    { altura: 720, alvo: 44 },
+    { altura: 540, alvo: 34 },
+    { altura: 0, alvo: 24 },
+]);
+/**
+ * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ *
+ * ⚠️ 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.
+ */
+export function alvoMinimoDeToque(alturaCss) {
+    const h = Number.isFinite(alturaCss) ? alturaCss : 0;
+    for (const degrau of REGUA_DE_ALVO)
+        if (h >= degrau.altura)
+            return degrau.alvo;
+    return 24;
+}
 // A CONTAGEM DE JOGADORES entra por injeção desde 2026-08-26. 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`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
@@ -18,8 +57,23 @@ import { crtScanVars } from '../render/crt.js';
 let _numJogadores = () => 1;
 /** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
 export function initLayout(deps) { _numJogadores = deps.numJogadores; }
+/**
+ * A CASCA QUE DÁ O ESPAÇO DISPONÍVEL — por id OU por classe, e as duas formas valem o mesmo.
+ *
+ * ⚠️ ERA SÓ `#stage-wrap`, E ISSO DEIXOU A ENGINE SEM ESCALA NO PRÓPRIO HOST. O `app/index.html` do jogo
+ * trazia `<div id="stage-wrap">`; quando o cartucho saiu (issue #111) sobrou o `app/quiz.html`, que tem
+ * `<div class="stage-wrap">`. A procura por id falhava, `layout()` fazia early-return, e **nada reportava
+ * nada**: um `return` silencioso é indistinguível de «não havia o que fazer». O comentário do próprio
+ * `quiz.html` dizia «mesmo id que ui/layout escala» — quem o escreveu acreditava que corria.
+ *
+ * O consumidor não erra ao usar a classe: um documento pode ter várias telas, e um id é único. Aceitar as
+ * duas é o que torna a engine consumível por quem não copiou o markup dela.
+ */
+function cascaDoPalco() {
+    return $('#stage-wrap') ?? $('.stage-wrap');
+}
 export function layout() {
-    const wrap = $('#stage-wrap');
+    const wrap = cascaDoPalco();
     if (!wrap)
         return;
     wrap.style.paddingRight = '0px';
@@ -47,6 +101,15 @@ export function layout() {
         gr.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * k * 0.052)) + 'px');
         gr.style.setProperty('--ui-fs', (8 * k) + 'px'); // base LÓGICA 8px × k (16px em k=2)
         gr.style.setProperty('--tap', (22 * k) + 'px'); // toque 22px × k (44px em k=2, piso WCAG)
+        // ⚠️ O PISO DA RÉGUA (ADR-0095), e ele é OUTRA COISA que o `--tap`. O `--tap` é o tamanho PREFERIDO e
+        // cresce com a escala do canvas; `--alvo-min` é o CHÃO por altura de tela — 24 px abaixo de 540, 34 a
+        // partir de 540, 44 a partir de 720. Um botão isolado usa o preferido; um item de LISTA, que tem de
+        // caber inteiro na tela, usa o chão.
+        //
+        // ⚠️ A ALTURA É A DO ESPAÇO DISPONÍVEL, e não a da sub-tela de um jogador: o dedo toca o aparelho, não
+        // o viewport lógico. Em quatro telas divididas cada uma tem 180 px de alto, e encolher o alvo por causa
+        // disso seria ler o número errado — o aparelho continua o mesmo.
+        gr.style.setProperty('--alvo-min', alvoMinimoDeToque(availH) + 'px');
     }
     crtScanVars(); // scanlines re-alinham quando a escala k muda
     if (/[?&]debug=true/.test(location.search))

package/dist-pkg/ui/motion-scene.d.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+/** As quatro animações de CENA, como vocabulário fechado. */
+export type MotionSceneKey = 'parallax' | 'decor' | 'items' | 'particles';
+/** As três do PERSONAGEM, que são campos do jogador. */
+export type MotionCharProp = 'rmWalk' | 'rmBreath' | 'rmFlavor';
+/** Uma animação do personagem e a chave i18n do seu rótulo. */
+export interface MotionCharDef {
+    readonly prop: MotionCharProp;
+    readonly lbl: string;
+}
+/** ⚠️ `PlayerView` e não `Record`: um `Record` aceita qualquer objecto com essas chaves, jogador ou não. */
+export type MotionPlayer = PlayerView<'rmWalk' | 'rmBreath' | 'rmFlavor'>;
+/** Os quatro interruptores de cena. Objecto VIVO — ver a nota sobre partilha por referência no topo. */
+export type MotionSceneFlags = Record<MotionSceneKey, boolean>;
+/** As quatro animações de CENA. São a união inteira, e o compilador prova-o logo abaixo. */
+export declare const CHAVES_DE_CENA: readonly ["parallax", "decor", "items", "particles"];
+/** As três animações do PERSONAGEM, com as chaves que o `RM_LABEL` desta mesma camada já traduz. */
+export declare const ANIMACOES_DO_PERSONAGEM: readonly [{
+    readonly prop: "rmWalk";
+    readonly lbl: "rm.walk";
+}, {
+    readonly prop: "rmBreath";
+    readonly lbl: "rm.breath";
+}, {
+    readonly prop: "rmFlavor";
+    readonly lbl: "rm.flavor";
+}];
+/** Os quatro interruptores no padrão do sistema — `prefers-reduced-motion`, por `defaultReducedMotion()`. */
+export declare function padraoDeCena(): MotionSceneFlags;
+/**
+ * O estado guardado, ou o padrão do sistema quando não há nada guardado.
+ *
+ * ⚠️ CADA CHAVE É LIDA UMA A UMA, e não `{...guardado}`. O que está no armazenamento veio do navegador de uma
+ * criança e pode estar truncado ou de uma versão anterior: espalhar o objecto traria chaves a mais e deixaria
+ * chaves a menos por preencher, e uma chave em falta lê-se como `undefined` — que é «não reduzido» para quem
+ * pediu redução. O laço garante exactamente as quatro.
+ */
+export declare function lerCenaGuardada(): MotionSceneFlags;
+/** Guarda os quatro interruptores. Chamada depois de cada mudança, como o `saveRM` do cartucho fazia. */
+export declare function guardarCena(rm: MotionSceneFlags): void;

package/dist-pkg/ui/motion-scene.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/motion-scene — O MOVIMENTO REDUZIDO DE CENA VOLTA PARA A ENGINE (ADR-0106 §4, etapa 1).
+//
+// ========================= O QUE ESTAVA ERRADO, MEDIDO E NÃO SUPOSTO =========================
+// O `PauseIconsCtx` e o `SettingsMotionCtx` pediam ao JOGO quatro coisas — `rm`, `rmKeys`, `rmChar`,
+// `saveRM` — e o ADR-0106 chamou-lhes «do jogo POR ACIDENTE». A medição de 2026-09-08 no `game-platformer`
+// mostra que a palavra é exacta, porque nenhuma das quatro contém uma escolha do jogo:
+//
+//   · `RM_KEYS` era `['parallax','decor','items','particles']` escrito à mão — que é a união `MotionSceneKey`
+//     INTEIRA, declarada na engine. Não é «quais destes este jogo tem»: são os quatro, sempre;
+//   · `RM_CHAR` era as três propriedades de `MotionCharProp` com as chaves i18n `rm.walk`/`rm.breath`/
+//     `rm.flavor` — e o `RM_LABEL` da engine já traduz essas mesmas chaves;
+//   · `rm` era lido de `store.KEYS.reducedMotion` (chave da engine) com `defaultReducedMotion()` (padrão da
+//     engine);
+//   · `saveRM` era `store.setJSON` para a mesma chave da engine.
+//
+// ⚠️ ERA UMA CÓPIA, NÃO UMA DECISÃO. E o custo não é elegância: **cinco jogos não têm nada disto**, porque
+// cada cartucho tinha de se lembrar de escrever as quatro linhas. Uma criança que precisa de parar o
+// movimento da cena abre esses cinco e não tem por onde.
+//
+// ⚠️ O QUE CONTINUA A SER DO JOGO, e por natureza: o EFEITO. Quem lê `rm.decor` para congelar as nuvens é o
+// jogo — a engine possui o interruptor, não o que ele apaga. É a mesma divisão do ADR-0106: o valor é da
+// engine, o efeito colateral é do cartucho.
+//
+// ⚠️ E O OBJECTO É PARTILHADO POR REFERÊNCIA, de propósito. No cartucho ele entra em oito módulos
+// (`weather`, `life`, `fx`, …) que leem `rm.decor`/`rm.particles` a cada quadro. Devolver uma cópia faria
+// cada leitor ver um valor congelado no arranque, e o interruptor deixaria de fazer nada — em silêncio.
+// ⚠️ O VOCABULÁRIO DESCEU PARA CÁ, e foi um gate que o mandou. Escrito ao contrário — os tipos no
+// `settings-motion` e este módulo a importá-los —, o `tests/lotes-passo5` reprovou por CICLO: o painel importa
+// os valores daqui e este importava os tipos de lá. O analisador conta o `import type` como aresta, e tem
+// razão para o que mede (ordem de extração). A saída certa não era calar o gate: o vocabulário pertence a quem
+// possui os VALORES, e o painel é consumidor dele. O `settings-motion` mantém os nomes publicados por alias,
+// então nenhuma linha de importação de nenhum consumidor muda.
+import * as store from '../platform/storage.js';
+import { defaultReducedMotion } from '../core/state.js';
+/** As quatro animações de CENA. São a união inteira, e o compilador prova-o logo abaixo. */
+export const CHAVES_DE_CENA = ['parallax', 'decor', 'items', 'particles'];
+const _COBRE_A_UNIAO = true;
+void _COBRE_A_UNIAO;
+/** As três animações do PERSONAGEM, com as chaves que o `RM_LABEL` desta mesma camada já traduz. */
+export const ANIMACOES_DO_PERSONAGEM = Object.freeze([
+    { prop: 'rmWalk', lbl: 'rm.walk' },
+    { prop: 'rmBreath', lbl: 'rm.breath' },
+    { prop: 'rmFlavor', lbl: 'rm.flavor' },
+]);
+const _COBRE_O_PERSONAGEM = true;
+void _COBRE_O_PERSONAGEM;
+/** Os quatro interruptores no padrão do sistema — `prefers-reduced-motion`, por `defaultReducedMotion()`. */
+export function padraoDeCena() {
+    const o = {};
+    const padrao = defaultReducedMotion();
+    for (const k of CHAVES_DE_CENA)
+        o[k] = padrao;
+    return o;
+}
+/**
+ * O estado guardado, ou o padrão do sistema quando não há nada guardado.
+ *
+ * ⚠️ CADA CHAVE É LIDA UMA A UMA, e não `{...guardado}`. O que está no armazenamento veio do navegador de uma
+ * criança e pode estar truncado ou de uma versão anterior: espalhar o objecto traria chaves a mais e deixaria
+ * chaves a menos por preencher, e uma chave em falta lê-se como `undefined` — que é «não reduzido» para quem
+ * pediu redução. O laço garante exactamente as quatro.
+ */
+export function lerCenaGuardada() {
+    const guardado = store.getJSON(store.KEYS.reducedMotion, null);
+    if (!guardado || typeof guardado !== 'object')
+        return padraoDeCena();
+    const o = {};
+    for (const k of CHAVES_DE_CENA)
+        o[k] = !!guardado[k];
+    return o;
+}
+/** Guarda os quatro interruptores. Chamada depois de cada mudança, como o `saveRM` do cartucho fazia. */
+export function guardarCena(rm) {
+    store.setJSON(store.KEYS.reducedMotion, rm);
+}

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

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** As três coisas do `document` de que a casca precisa. Mesma forma de `ui/loop-crash`. */
+export interface PanelShellCtx {
+    /** `document.querySelector`, injetado — a casca nunca alcança o `document` global. */
+    procurar: (sel: string) => HTMLElement | null;
+    /** `document.createElement`, injetado. */
+    criar: (tag: string) => HTMLElement;
+}
+export interface PanelShellSpec {
+    /** O id do painel: `typo`, `audio`, `visual`… Gera `#X`, `#X-title`, `#X-list`, `#X-reset`, `#X-close`. */
+    id: string;
+    /** O título, JÁ TRADUZIDO. Vai por `textContent`. */
+    titulo: string;
+    /** O `aria-label` da lista, já traduzido — o nome do grupo que a criança ouve ao entrar nele. */
+    rotuloDaLista: string;
+    /** Os rótulos dos dois botões, já traduzidos. */
+    rotuloReset: string;
+    rotuloFechar: string;
+    /**
+     * A introdução do painel, já traduzida. Vira o texto de REPOUSO do rodapé, via `data-explain-idle`.
+     *
+     * ⚠️ É O ÚNICO CAMINHO QUE ESTA CASCA OFERECE PARA UMA INTRODUÇÃO, e é o ponto da issue #62: não há por
+     * onde passar um parágrafo de prosa para o topo do cartão. Ausente = o painel não tem introdução, que é
+     * uma resposta legítima e não uma omissão.
+     */
+    introducao?: string;
+}
+/** O que a casca devolve: o nó e os ids que ela criou, para o painel não os adivinhar. */
+export interface PanelShell {
+    overlay: HTMLElement;
+    card: HTMLElement;
+    lista: HTMLElement;
+    reset: HTMLElement;
+    fechar: HTMLElement;
+    /** Os cinco selectores que este painel passa a garantir. É o contrato, agora dito em vez de descoberto. */
+    ids: {
+        overlay: string;
+        title: string;
+        lista: string;
+        reset: string;
+        fechar: string;
+    };
+}
+/** Os ids que um painel de `id` ocupa. Exportado porque um gate e um consumidor precisam de os nomear. */
+export declare function idsDaCasca(id: string): PanelShell['ids'];
+/**
+ * Monta (ou reaproveita) a casca do painel `spec.id` e devolve as suas partes.
+ *
+ * IDEMPOTENTE: se já existir um `#id`, ele é reutilizado e o conteúdo do cartão é reconstruído. Um painel que
+ * a raiz monte duas vezes não pode acabar com dois véus — e a raiz monta mais do que uma vez, porque a
+ * contagem de jogadores muda a grade de telas.
+ */
+export declare function montarCasca(ctx: PanelShellCtx, spec: PanelShellSpec): PanelShell;

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

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/panel-shell — A CASCA DE UM PAINEL DE AJUSTES, construída em vez de exigida.
+//
+// ========================= O ACHADO QUE ISTO CONSERTA =========================
+// O segundo consumidor (a etapa C da issue #63) mediu-o e escreveu-o no achado 6:
+//
+//     «O CONTRATO DE MARKUP É INVISÍVEL. O ctx do painel pede `$` e `store`; o que ele REALMENTE exige é que
+//      o documento do consumidor contenha `#typo`, `#typo-list`, `#typo-preview`, `#typo-close` e
+//      `#typo-reset`. Nada no tipo diz isso — descobre-se por tentativa, e o modo de falhar é o pior
+//      possível: o painel abre VAZIO, sem erro.»
+//
+// Cada `ui/settings-*.ts` preenche o INTERIOR do seu painel; o EXTERIOR — o véu, o cartão, o título, o
+// rodapé de ações e o botão de restaurar — vinha do `app/index.html`, que saiu com o cartucho (#111). Desde
+// então a engine EXIGE cinco ids por painel e não os declara em lado nenhum.
+//
+// ⚠️ E A REGRA DE MENU DO `CLAUDE.md` §4 DEPENDIA DE ALGUÉM SE LEMBRAR DELA. A introdução de um painel vai no
+// `data-explain-idle` do cartão — nunca num `<p>` de prosa no topo —, porque um menu que explica item a item
+// obriga a criança a LER TUDO para achar o que procura. A issue #62 mandava editar seis blocos de markup para
+// isso; o markup saiu, e a regra ficou sem alvo. Aqui ela deixa de ser lembrete e passa a ser construção: a
+// casca não tem por onde receber um `<p>` no topo.
+//
+// ========================= A FORMA, QUE FOI MEDIDA E NÃO INVENTADA =========================
+// É a do painel de tipografia do `app/quiz.html`, que é o único que sobrou e o que o segundo consumidor
+// exercitou de facto:
+//
+//     <div id="X" class="overlay" hidden>
+//       <div class="overlay__card" role="dialog" aria-modal="true" aria-labelledby="X-title" [data-explain-idle]>
+//         <h2 id="X-title">…</h2>
+//         <div id="X-list" class="ctrl-list" role="group" aria-label="…"></div>   ← o interior, do settings-*
+//         <div class="overlay__actions">
+//           <button id="X-reset">…</button>  <button id="X-close">…</button>
+//         </div>
+//       </div>
+//     </div>
+//
+// ⚠️ O RODAPÉ `.opt-explain` NÃO É CRIADO AQUI, e isso é deliberado: `ui/settings-panel.fillExplain` cria-o
+// quando move a primeira dica para lá. Criá-lo vazio aqui daria uma região `aria-live` que anuncia nada, e
+// duas mãos a criar o mesmo nó é como ele acabaria duplicado.
+//
+// Sem `innerHTML`: tudo por `criar` + `textContent`, no molde de `ui/loop-crash` e `ui/focus-trap`. O título
+// e o rótulo da lista vêm do CHAMADOR já resolvidos — este módulo não traduz, para poder ser exercitado sem
+// dicionário.
+//
+// ⚠️ E NÃO IMPORTA NADA. Uma casca que não usa `innerHTML` também não precisa de escapar texto: `textContent`
+// escapa por construção. Chegou a haver aqui um `escaparHtml` importado «por conveniência» — que é como um
+// módulo-folha deixa de o ser, e como um leitor futuro passa a procurar a interpolação que não existe.
+/** Os ids que um painel de `id` ocupa. Exportado porque um gate e um consumidor precisam de os nomear. */
+export function idsDaCasca(id) {
+    return { overlay: id, title: `${id}-title`, lista: `${id}-list`, reset: `${id}-reset`, fechar: `${id}-close` };
+}
+/**
+ * Monta (ou reaproveita) a casca do painel `spec.id` e devolve as suas partes.
+ *
+ * IDEMPOTENTE: se já existir um `#id`, ele é reutilizado e o conteúdo do cartão é reconstruído. Um painel que
+ * a raiz monte duas vezes não pode acabar com dois véus — e a raiz monta mais do que uma vez, porque a
+ * contagem de jogadores muda a grade de telas.
+ */
+export function montarCasca(ctx, spec) {
+    const ids = idsDaCasca(spec.id);
+    const overlay = ctx.procurar('#' + ids.overlay) ?? ctx.criar('div');
+    overlay.id = ids.overlay;
+    overlay.className = 'overlay';
+    overlay.hidden = true;
+    while (overlay.firstChild)
+        overlay.removeChild(overlay.firstChild);
+    const card = ctx.criar('div');
+    card.className = 'overlay__card';
+    card.setAttribute('role', 'dialog');
+    card.setAttribute('aria-modal', 'true');
+    card.setAttribute('aria-labelledby', ids.title);
+    // A introdução do painel é o texto de REPOUSO do rodapé (CLAUDE.md §4), nunca um `<p>` no topo.
+    if (spec.introducao)
+        card.setAttribute('data-explain-idle', spec.introducao);
+    const h2 = ctx.criar('h2');
+    h2.id = ids.title;
+    h2.textContent = spec.titulo;
+    card.appendChild(h2);
+    const lista = ctx.criar('div');
+    lista.id = ids.lista;
+    lista.className = 'ctrl-list';
+    lista.setAttribute('role', 'group');
+    lista.setAttribute('aria-label', spec.rotuloDaLista);
+    card.appendChild(lista);
+    const acoes = ctx.criar('div');
+    acoes.className = 'overlay__actions';
+    const reset = botao(ctx, ids.reset, spec.rotuloReset, 'mode-btn');
+    const fechar = botao(ctx, ids.fechar, spec.rotuloFechar, 'mode-btn is-on');
+    acoes.appendChild(reset);
+    acoes.appendChild(fechar);
+    card.appendChild(acoes);
+    overlay.appendChild(card);
+    return { overlay, card, lista, reset, fechar, ids };
+}
+function botao(ctx, id, rotulo, classe) {
+    const b = ctx.criar('button');
+    b.id = id;
+    b.className = classe;
+    b.setAttribute('type', 'button');
+    // `textContent` e não `innerHTML`: um rótulo traduzido é dado de fora como qualquer outro, e um dicionário
+    // de consumidor pode trazer o que quiser dentro dele.
+    b.textContent = rotulo;
+    return b;
+}

package/dist-pkg/ui/pause-icons.d.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { PlayerView } from '../core/entity.js';
 import type { NavKeys } from '../input/edges.js';
+import { type Tema, type Correcao, type VisualState } from '../render/viz-axes.js';
 import type { MotionSceneFlags, MotionSceneKey, MotionCharDef } from './settings-motion.js';
 import type { AudioCatState } from './settings-audio.js';
 /**
@@ -32,6 +33,11 @@ export declare const PAUSE_ICONS: readonly PauseIcon[];
 export declare function pauseIcon(k: string): PauseIcon | undefined;
 /** TEA cycle: 0 = normal · 1 = calmo (reduces) · 2 = silencioso (switches off). Never touches TTS/blind mode. */
 export declare const CALM_NAMES: readonly string[];
+/**
+ * O nível TEA guardado, saneado. Fora de 0..2 devolve o padrão — dado do navegador é dado de fora, e um
+ * nível inventado escolheria `CALM_NAMES[3]`, que é `undefined`, e o anúncio ao leitor de tela sairia vazio.
+ */
+export declare function saneiaNivelTea(bruto: number): number;
 /** The audio categories `applyCalm` governs. TTS/sonar/guarda/guia stay untouched — a calm player still needs them. */
 export declare const CALM_AUDIO_CATS: readonly string[];
 /** Colour-vision-deficiency cycle, in `player.viz` values. */
@@ -62,7 +68,7 @@ export declare const CVD_LABELS: Readonly<Record<string, string>>;
  * tipar `core/state.players` como `Player[]`: o compilador recusou converter um `Player` — que não tem
  * assinatura de índice — para ela, e essa recusa é a informação.
  */
-export type PausePlayer = PlayerView<'viz' | 'toggleMove' | 'audioSink' | 'rmWalk' | 'rmBreath' | 'rmFlavor'>;
+export type PausePlayer = PlayerView<'visual' | 'toggleMove' | 'walkDir' | 'audioSink' | 'rmWalk' | 'rmBreath' | 'rmFlavor'>;
 /** One `.pm-btn` descriptor — the shape of game.js's PM_BTNS (owned by ui/activities-menu). */
 export interface PauseMenuButton {
     act: string;
@@ -81,10 +87,32 @@ export interface IconStateSnapshot {
     librasOn: boolean;
     calmMode: number;
     toggleMove: boolean;
-    /** `player.viz` — shared by the contrast and CVD icons (they overwrite each other; that is by design). */
-    viz: string;
+    /**
+     * O estado visual em DOIS EIXOS (#104).
+     *
+     * ⚠️ ERA `viz: string`, E O COMENTÁRIO DIZIA: «shared by the contrast and CVD icons (they overwrite each
+     * other; **that is by design**)». Não era desenho — era o campo único a impor-se, e a frase é o defeito
+     * escrito como se fosse decisão. Os dois ícones sempre ciclaram DENTRO do seu eixo (`nextContrast` e
+     * `nextCvd` existem desde sempre, separados); só não tinham onde guardar o resultado sem apagar o vizinho.
+     */
+    visual: VisualState;
     /** False disables the blind/TTS icons: those need an audio output nobody else is listening to. */
     privateOutput: boolean;
+    /**
+     * O aparelho em uso EXIGE a alternância? (ADR-0113 cláusula 3.)
+     *
+     * ⚠️ Em olhos, rosto, gestos e fala ela é o que faz a entrada funcionar, logo não há escolha a oferecer.
+     * O ícone fica desabilitado COM MOTIVO, como o painel — e não pode divergir dele: as duas superfícies
+     * escrevem o mesmo valor, e uma que aceitasse o clique enquanto a outra recusa deixaria a criança com
+     * dois botões que discordam sobre o mesmo ajuste.
+     *
+     * 🔴 OPCIONAL PORQUE O GATE DA FORMA ME APANHOU: eu escrevi-o obrigatório, e o
+     * `tests/superficie-publica` reprovou com «ENTROU como obrigatório» — que é uma MUDANÇA QUEBRANTE do
+     * pacote, porque quem constrói este snapshot passa a ter de o preencher. Foi para isto que o gate da
+     * FORMA (`2f2582f`) foi escrito, e é a primeira vez que ele apanha um campo A ENTRAR e não a sair.
+     * Ausente significa «ninguém me disse», que degrada para «não exijo» — o comportamento de hoje.
+     */
+    alternanciaExigida?: boolean;
 }
 /** A player has private output when nobody else is on the same sink. Single screen ⇒ always private.
  *  Pure form of game.js's hasPrivateOutput (see the report: it had no other caller left). */
@@ -135,9 +163,61 @@ export declare const ICON_STATE_CLASSES: readonly string[];
  *  reflected. `ic.n` is an i18n key, so it must be resolved here too — the markup is rendered once at build
  *  time and would otherwise ship the raw key to a screen reader. */
 export declare function iconBtnMarkup(ic: PauseIcon): string;
+/**
+ * OS ÍCONES QUE ESTE JOGO CONSEGUE MESMO ACCIONAR (ADR-0106 §5).
+ *
+ * ⚠️ NENHUMA ETAPA PODE ENTREGAR BOTÃO MORTO, e o registo diz porquê com todas as letras: «uma barra que
+ * oferece a uma criança um caminho e depois o recusa é pior do que uma barra que ela vê que não está lá,
+ * porque a primeira ensina-lhe que o caminho não é para ela».
+ *
+ * ⚠️ E O CONTRASTE E A COR SÃO O CASO REAL, medido em 2026-09-08 e diferente dos outros seis campos
+ * «acidentais»: eles não são estado que um cartucho calhou de guardar — precisam de um `render/viz-setters`,
+ * cujo contexto tem **34 campos** do grafo de render de UM jogo (`parallaxLayers`, `decoSprites`,
+ * `getPowerups`, `rebuildCoins`, `worldSprite`…). O `createGame` não monta isso, e um quiz não tem nada
+ * disso para montar. Então aqui a engine não pode oferecer um padrão — o que ela pode é **não fingir**.
+ *
+ * ⚠️ Isto NÃO é o mesmo que `soon`. `soon` é «ainda não construímos»; isto é «este jogo não tem por onde», e
+ * um botão que anuncia «em breve» diria a coisa errada.
+ */
+export interface EscritoresVisuais {
+    /** Há quem escreva o TEMA (o alto contraste)? Sem ele, o ícone `contrast` não é montado. */
+    readonly tema: boolean;
+    /** Há quem escreva a CORREÇÃO de cor? Sem ela, o ícone `cvd` não é montado. */
+    readonly correcao: boolean;
+}
+export declare function iconesQueAccionam(escritores: EscritoresVisuais): readonly PauseIcon[];
+/**
+ * OS TRÊS ITENS QUE A ENGINE ACCIONA SOZINHA, e que por isso nunca dependem do `getPauseActs` de um jogo.
+ *
+ * 📏 Lidos do despacho, e não decididos aqui: `options`/`pmback` trocam qual lista está no cartão e
+ * `acessibilidade` leva o cursor à barra rápida — os três são tratados neste módulo e voltam antes de a
+ * tabela do jogo ser consultada.
+ */
+export declare const ITENS_DA_ENGINE: ReadonlySet<string>;
+/**
+ * OS ITENS DO MENU QUE ESTE JOGO CONSEGUE MESMO ACCIONAR (ADR-0106 §5).
+ *
+ * ⚠️ HOJE UM ITEM SEM ACÇÃO É UM BOTÃO MORTO, E EM SILÊNCIO. O despacho faz `const fn = acts[act]; if (fn)
+ * fn();` — quem carrega num item que o jogo não implementou não recebe erro, não recebe anúncio, não recebe
+ * nada. Para quem vê, parece que o clique falhou; para quem navega por leitor de tela, o menu leu-lhe um
+ * item que não existe. É exactamente o que o §5 chama de pior do que a ausência: «uma barra que oferece um
+ * caminho e depois o recusa ensina-lhe que o caminho não é para ela».
+ */
+export declare function itensQueAccionam(botoes: readonly PauseMenuButton[], acts: Record<string, (() => void) | undefined>): readonly PauseMenuButton[];
+/**
+ * A LISTA RAIZ, com uma regra a mais: `options` é uma PORTA, e uma porta para uma sala vazia também é um
+ * botão morto.
+ *
+ * ⚠️ Esta é a parte que um filtro item-a-item não apanha. Se todos os painéis de ajuste forem filtrados —
+ * um jogo que não monta nenhum —, o item `options` sobrevive (a engine acciona-o) e abre uma lista sem nada.
+ * A criança atravessa uma porta e fica presa num submenu vazio, cuja única saída é o `pmback` que também
+ * sumiu com ele.
+ */
+export declare function raizQueAcciona(raiz: readonly PauseMenuButton[], opcoes: readonly PauseMenuButton[], acts: Record<string, (() => void) | undefined>): readonly PauseMenuButton[];
 /** The whole icon bar. Used by the pause screen AND by the splash `#title-icons` (which built the same string
- *  by hand in game.js — that duplication dies with this export). */
-export declare function iconsMarkup(): string;
+ *  by hand in game.js — that duplication dies with this export).
+ *  O parâmetro é ADITIVO e o padrão é a lista inteira: quem já chamava sem argumentos não muda de resultado. */
+export declare function iconsMarkup(icones?: readonly PauseIcon[]): string;
 /** One `.pm-btn`. Dynamic labels (`letra`/`nivel`) are rendered eagerly and carry NO `data-i18n`, so
  *  i18n.applyDom() cannot overwrite them. */
 /**
@@ -194,7 +274,7 @@ export declare function mostrarSubmenuDaPausa(sp: HTMLElement, sub: PauseSub): H
  * A LEGENDA VIAJA JUNTO. Ela é a dica que substitui, para quem não vê, o `title` que só o mouse revela;
  * deixá-la no cartão tornaria a barra do HUD muda.
  */
-export declare function quickBarMarkup(): string;
+export declare function quickBarMarkup(icones?: readonly PauseIcon[]): string;
 /**
  * O QUE UMA INTENÇÃO SIGNIFICA DENTRO DO MODO `accessibility` (ADR-0044, item 7).
  *
@@ -228,6 +308,21 @@ export interface ScreenPauseMarkupOpts {
 /** The full innerHTML of a `.screen-pause`. Pure — every input is a parameter. */
 export declare function screenPauseMarkup(o: ScreenPauseMarkupOpts): string;
 export interface PauseIconsCtx {
+    /**
+     * O DOCUMENTO onde a pausa e a barra são CONSTRUÍDAS. Ausente, vale o global.
+     *
+     * ⚠️ ISTO É O ACHADO 15 OUTRA VEZ, e o `boot/create-game` já o descreve no próprio cabeçalho: «`initI18n()`
+     * chamava `applyDom(document)`, o GLOBAL, por baixo de quem a chamasse. Num navegador dá no mesmo e por
+     * isso sobreviveu; num teste de lógica pura é a diferença entre bootar e não bootar, e num futuro com dois
+     * documentos (uma engine em iframe, um editor ao lado do jogo) seria a diferença entre traduzir o documento
+     * certo e o outro.»
+     *
+     * 📏 Medido em 2026-09-08: as duas metades que constroem DOM (`buildScreenPause`, `buildQuickBar`) faziam
+     * `document.createElement` no global. Enquanto a raiz de composição de cada jogo era um `main.ts` a correr
+     * num navegador, dava no mesmo — e foi por isso que sobreviveu. Deixa de dar assim que a ENGINE monta,
+     * porque o `createGame` recebe o documento por `host.doc` e pode estar a montar noutro.
+     */
+    doc?: Document;
     /** 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`). */
@@ -248,9 +343,9 @@ export interface PauseIconsCtx {
      */
     getA11yBars: () => readonly HTMLElement[];
     /** PM_OPTIONS_BTNS — o submenu de opções. Mesma dona, mesmo motivo: ninguém tem duas cópias de uma lista. */
-    optionsButtons: readonly PauseMenuButton[];
+    optionsButtons?: readonly PauseMenuButton[];
     /** PM_BTNS — the `.pm-btn` list. Owned by ui/activities-menu; injected, never copied. */
-    pmButtons: readonly PauseMenuButton[];
+    pmButtons?: readonly PauseMenuButton[];
     /** QL_NAME — literacy-level names, for the (dormant) `nivel` button. Same owner as pmButtons. */
     /**
      * O RÓTULO de um botão dinâmico, pronto — ou `null` quando aquele botão não tem um (item 19).
@@ -259,16 +354,15 @@ export interface PauseIconsCtx {
      * frase. Um menu de pausa da ENGINE não sabe o que é nível de alfabetização, nem em que idioma dizê-lo.
      * Função e não valor, porque o rótulo muda em execução — de nível E de idioma.
      */
-    dynLabel: (b: PauseMenuButton) => string | null;
+    /** O rótulo dinâmico, pronto — ou `null`. Ausente: nenhum botão deste jogo tem rótulo dinâmico. */
+    dynLabel?: (b: PauseMenuButton) => string | null;
     /** The `.pm-btn` action table. LAZY: `pauseActs` is a `const` declared far below the init site in game.js. */
-    getPauseActs: () => Record<string, (() => void) | undefined>;
+    getPauseActs?: () => Record<string, (() => void) | undefined>;
     /** Records which player opened the menu. `pauseActor` itself stays in game.js — the gamepad, the keyboard
      *  router, openHelp() and openOptions() all read it there. */
-    setPauseActor: (i: number) => void;
-    /** The live `vpPause` array (game.js rebuilds it on every buildGameHud). Getter, not the array. */
-    getPauseScreens: () => readonly Element[];
+    setPauseActor?: (i: number) => void;
     getModoCego: () => boolean;
-    setModoCego: (on: boolean) => void;
+    setModoCego?: (on: boolean) => void;
     /**
      * O mixer por categoria. NULO até `initAudioMixer()` — `platform/audio` o declara
      * `Record<string, CatState> | null` porque o import dele é PURO (não lê localStorage), e quem inicializa
@@ -286,18 +380,38 @@ export interface PauseIconsCtx {
     reflectTtsPanelEnabled: boolean;
     isLibrasOn: () => boolean;
     toggleLibras: () => void;
-    rm: MotionSceneFlags;
-    rmKeys: readonly MotionSceneKey[];
-    rmChar: readonly MotionCharDef[];
-    saveRM: () => void;
-    setToggleMove: (i: number, on: boolean) => void;
-    setPlayerViz: (i: number, mode: string) => void;
+    rm?: MotionSceneFlags;
+    rmKeys?: readonly MotionSceneKey[];
+    rmChar?: readonly MotionCharDef[];
+    saveRM?: () => void;
+    setToggleMove?: (i: number, on: boolean) => void;
+    /**
+     * QUAL APARELHO ESTE JOGADOR ESTÁ A USAR (ADR-0113).
+     *
+     * 📌 O ícone `altmove` desta barra é a OUTRA superfície que escreve a alternância — a mesma razão pela
+     * qual o escritor voltou para a engine (ADR-0106 §4). Sem este campo, ele escreveria só a chave antiga
+     * enquanto o painel escreve as duas, e as duas superfícies divergiriam em silêncio.
+     */
+    transporteEmUso?: (jogador: number) => string;
+    setPlayerViz?: (i: number, mode: string) => void;
+    /** Os escritores POR EIXO (#104): mexer no tema não apaga a correção, e vice-versa. */
+    setTemaDoJogador?: (i: number, tema: Tema) => void;
+    setCorrecaoDoJogador?: (i: number, correcao: Correcao) => void;
 }
 export interface PauseIconsApi {
     /** Builds one `.screen-pause` (hidden), wired for click + hover/focus caption. Caller appends it. */
     buildScreenPause: (i: number) => HTMLElement;
     /** Monta a BARRA RÁPIDA (`.screen-a11y`) da tela `i`, já fiada. Chamada por ui/hud.ts, uma por tela. */
     buildQuickBar: (i: number) => HTMLElement;
+    /**
+     * OS ÍCONES QUE ESTA INSTÂNCIA MONTA — já filtrados pelo §5 do ADR-0106.
+     *
+     * ⚠️ Existe para que quem monta a barra do TÍTULO não repita o filtro. A barra do título não pode usar
+     * `buildQuickBar` (ele põe `tabIndex = -1`, e o próprio comentário lá diz porquê: no título não se está a
+     * jogar), então ela chama `iconsMarkup` directamente — e sem este acessor teria de recalcular quais ícones
+     * accionam, que é uma segunda cópia da mesma decisão.
+     */
+    iconesMontados: readonly PauseIcon[];
     /** ENTRA no modo `accessibility` da tela `i` — é o que o item `acessibilidade` da pausa faz. */
     entrarNaBarra: (i: number) => void;
     /** SAI do modo e devolve o direcional ao personagem. */