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

package/dist-pkg/ui/latch-refusal.d.ts

@@ -0,0 +1,32 @@
+// 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 chave i18n do motivo, POR TRANSPORTE.
+ *
+ * ⚠️ 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.
+ */
+export declare const CHAVE_DA_RECUSA: Readonly<Record<string, string>>;
+/**
+ * A alternância pode ser desligada neste aparelho? E se não, o que dizer.
+ *
+ * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
+ */
+export declare function recusaDaAlternancia(transporte: string): RecusaDaAlternancia | null;
+/**
+ * O controle continua NA TELA quando a alternância é exigida?
+ *
+ * ⚠️ 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».
+ */
+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>;

package/dist-pkg/ui/latch-refusal.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/latch-refusal.ts — QUANDO A ALTERNÂNCIA NÃO É UMA ESCOLHA, e o que se diz a quem carregou no botão.
+//
+// ========================= A CLÁUSULA 3 DO ADR-0113 =========================
+// «É impossível desligá-la em modos que não tem como funcionar sem ela (voz e câmera)» — a frase do Dev. Em
+// olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar: sem ela, um comando de cada vez
+// significa que a criança não consegue andar e agir.
+//
+// ⚠️ E O CONTROLE NÃO SOME — FICA DESABILITADO, COM O MOTIVO DITO. Sumir ensina que a coisa não existe: um
+// adulto conclui que ela foi retirada, não que a webcam a exige. É a mesma metade «never silently removed»
+// que o ADR-0076 escreveu para a simulação, e este ficheiro é o irmão do `ui/simulation-refusal` de propósito
+// — mesma forma, mesmo lugar na camada, e portanto conferível no project `node`, sem documento.
+//
+// 🔴 E O MOTIVO É UM FACTO SOBRE O APARELHO, NUNCA UMA REPREENSÃO. «O controle por olhar precisa das teclas de
+// alternância para funcionar» diz por que o botão não responde; «não desligue isto» repreende uma criança por
+// mexer num ajuste de que ela depende. O ADR-0076 já pagou esta distinção uma vez, e a mutação que a apanhou
+// trocava a frase por uma mais curta, mais clara e mais útil — que reprovava na mesma.
+//
+// Módulo-folha: importa só a regra pura da alternância.
+import { alternanciaEhEscolha, UM_COMANDO_DE_CADA_VEZ } from '../input/latch-scope.js';
+/**
+ * A chave i18n do motivo, POR TRANSPORTE.
+ *
+ * ⚠️ 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.
+ */
+export const CHAVE_DA_RECUSA = Object.freeze({
+    olhos: 'alt.exigida.olhos',
+    rosto: 'alt.exigida.rosto',
+    gestos: 'alt.exigida.gestos',
+    fala: 'alt.exigida.fala',
+});
+/**
+ * A alternância pode ser desligada neste aparelho? E se não, o que dizer.
+ *
+ * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
+ */
+export function recusaDaAlternancia(transporte) {
+    if (alternanciaEhEscolha(transporte))
+        return null;
+    const chave = CHAVE_DA_RECUSA[transporte];
+    // 📌 Um transporte que exija alternância e não tenha frase seria um botão desabilitado SEM motivo — pior do
+    // que o defeito que isto conserta, porque a criança deixa de saber sequer que há uma razão. O gate afirma
+    // que os dois conjuntos coincidem; aqui a ausência degrada para «não recuso», que mantém o controle vivo.
+    return chave ? { chave, transporte } : null;
+}
+/**
+ * O controle continua NA TELA quando a alternância é exigida?
+ *
+ * ⚠️ 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».
+ */
+export function mostraMesmoExigida() {
+    return true;
+}
+/** Os transportes que exigem alternância, para quem precisa de os enumerar. Vem da REGRA, não de uma cópia. */
+export const EXIGEM_ALTERNANCIA = UM_COMANDO_DE_CADA_VEZ;

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;
+}