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

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,80 @@ 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 AccionaveisDoJogo {
+    /** 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;
+    /**
+     * ESTE JOGO SEGURA ALGUMA TECLA? — `GameDeclaration.seguraTeclas`, o campo do ADR-0115.
+     *
+     * 🔴 Sem ele o ícone `altmove` não é montado, e a AUSÊNCIA é a decisão. A alternância existe para quem não
+     * consegue manter uma tecla premida; num jogo onde nada se segura ela não tem o que travar, e um controle
+     * que não faz nada ensina a uma criança que o ajuste de que ela depende está partido.
+     *
+     * ⚠️ E ISTO É UMA AUSÊNCIA DIFERENTE DA DO ADR-0113 cláusula 3, que também vive neste ficheiro: lá o
+     * controle fica DESABILITADO com o motivo, porque o aparelho EXIGE a alternância e ela não se pode
+     * desligar. Aqui não há nada a travar, e um controle que explica por que não faz nada continua a ser um
+     * controle que não faz nada.
+     */
+    readonly seguraTeclas: boolean;
+}
+/**
+ * @deprecated O nome dizia «escritores VISUAIS» e a pergunta deixou de ser só visual quando o `seguraTeclas`
+ * entrou (ADR-0115). Use `AccionaveisDoJogo`. O alias fica para o consumidor não pagar duas quebras no mesmo
+ * major — uma pelo campo novo e outra pelo nome.
+ */
+export type EscritoresVisuais = AccionaveisDoJogo;
+export declare function iconesQueAccionam(escritores: AccionaveisDoJogo): 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 +293,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 +327,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 +362,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 +373,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 +399,53 @@ 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;
+    /**
+     * ESTE JOGO SEGURA ALGUMA TECLA? — o valor de `GameDeclaration.seguraTeclas` (ADR-0115). Sem ele o ícone
+     * `altmove` não é montado.
+     *
+     * ⚠️ OBRIGATÓRIO, e vai contra a direcção do ADR-0106, que passou a tornar campos deste ctx OPCIONAIS para
+     * a engine poder montar sozinha. A excepção tem razão medida: os campos que ganharam padrão têm um padrão
+     * SEGURO — o modo cego começa desligado, a lista de botões vem da engine. Aqui não há: `true` monta um
+     * controle que pode não fazer nada, e `false` esconde um de que uma criança depende. Os dois lados erram, e
+     * é essa a condição que o `holdsAtOnce` já usou para ser obrigatório também.
+     *
+     * 📌 Quem passa pelo `createGame` não escreve isto: a raiz lê a declaração, que já é obrigatória. O campo
+     * só é visível para um cartucho que chame `initPauseIcons` por fora — e é exactamente esse que não pode
+     * ficar em silêncio.
+     */
+    seguraTeclas: boolean;
 }
 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. */