@the-inclusionist/engine 6.36.1

package/dist-pkg/ui/caa-sets.d.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export type CaaTier = 
+/** CC BY-SA ou nosso: pode viajar dentro do jogo, funciona sem rede nenhuma. */
+'bundled'
+/** A licença permite usar, não redistribuir: quem baixa é a pessoa, uma vez, e fica em cache. */
+ | 'fetched'
+/** Falta permissão. Aparece no menu, não é escolhível. */
+ | 'negotiating';
+export interface CaaSet {
+    readonly key: string;
+    readonly nome: string;
+    readonly tier: CaaTier;
+    /** Licença como ela foi VERIFICADA, ou null quando ainda não há. Texto curto, para caber na tela. */
+    readonly licenca: string | null;
+    /** Funciona NESTA build? Hoje só as letras — os pictogramas são arquivos que ainda não vieram. */
+    readonly disponivel: boolean;
+    /** Só para pictogramas: uma linha sobre a origem, quando ela muda o que a escolha significa. */
+    readonly nota?: string;
+}
+export declare const CAA_SETS: readonly CaaSet[];
+export declare const CAA_BY_KEY: Readonly<Record<string, CaaSet>>;
+/** Quais CONJUNTOS a criança pode escolher hoje: nenhum. O menu não finge o contrário — os pictogramas são
+ *  milhares de arquivos que ainda não entraram no repositório, e quatro deles dependem de negociação. */
+export declare function caaDisponiveis(): CaaSet[];
+/**
+ * Por que este conjunto não está disponível — chave i18n, nunca texto pronto.
+ *
+ * As duas respostas dizem coisas diferentes a quem lê, e é por isso que são duas: "em preparação" quer dizer
+ * que a licença está resolvida e o trabalho é NOSSO; "aguardando negociação" quer dizer que a permissão é de
+ * OUTRA PESSOA e nenhum esforço nosso a antecipa.
+ *
+ * E é por isso que os indisponíveis aparecem em vez de serem escondidos: são justamente os conjuntos que uma
+ * escola brasileira tem mais chance de já usar em outro produto. O educador que procura PCS e não acha conclui
+ * que o jogo não faz — quando o obstáculo é uma licença, não uma capacidade. Esconder responderia a pergunta
+ * errada, e responderia errado.
+ */
+export declare function caaMotivo(s: CaaSet): string | null;
+/** Rótulo pronto para a linha do menu: nome + o motivo, quando há um. */
+export declare function caaRotulo(s: CaaSet): string;

package/dist-pkg/ui/caa-sets.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/caa-sets.ts — O CATÁLOGO DA COMUNICAÇÃO AUMENTADA E ALTERNATIVA (ADR-0028). Módulo-folha: dados puros e
+// dois predicados, zero DOM, zero I/O. Quem desenha o menu é ui/settings-caa; quem decide o que ele oferece
+// é este arquivo, porque a decisão é de LICENÇA e não de interface.
+//
+// PARA QUEM ISTO EXISTE: há crianças que leem símbolos e não letras. Para elas, o pictograma não é um enfeite
+// nem uma muleta — é a escrita. Um jogo educativo que só sabe exibir letras simplesmente não fala com elas.
+//
+// A REGRA QUE ORGANIZA A LISTA: a camada de cada conjunto é decidida pela LICENÇA DELE e por mais nada — não
+// pela qualidade, não pelo tamanho, não pela facilidade de integrar. No instante em que um conjunto mudar de
+// camada por outro motivo, este arquivo terá deixado de ser verdadeiro.
+//
+// `tier` é o FATO JURÍDICO (podemos redistribuir? é preciso baixar? falta permissão?). `disponivel` é o FATO
+// DE HOJE (funciona nesta build?). São duas perguntas diferentes e o menu precisa das duas: a primeira diz
+// quem tem de agir, a segunda diz o que a criança consegue escolher agora.
+import { t } from '../core/i18n.js';
+// AS LETRAS NÃO ESTÃO NESTA LISTA, e a ausência é decisão do Dev. Elas eram duas entradas — "maiúsculas e
+// minúsculas" e "maiúsculas somente" — e viraram UM interruptor: "Letras maiúsculas", ligado ou desligado,
+// com o desligado significando as duas caixas. Uma escolha binária apresentada como duas opções faz a criança
+// comparar duas linhas para descobrir que são a mesma pergunta; um interruptor pergunta uma vez.
+//
+// Sobra aqui o que é de verdade uma LISTA: os conjuntos de pictogramas, entre os quais se escolhe um.
+export const CAA_SETS = [
+    // --- PICTOGRAMAS que PODEM viajar com o jogo (CC BY-SA, verificado pelo Dev em 2026-08-24). ---
+    { key: 'mulberry', nome: 'Mulberry Symbols', tier: 'bundled', licenca: 'CC BY-SA', disponivel: false },
+    { key: 'blissymbolics', nome: 'Blissymbolics', tier: 'bundled', licenca: 'CC BY-SA 4.0', disponivel: false,
+        nota: 'Escrita simbólica própria: os símbolos se combinam para formar sentidos novos.' },
+    { key: 'tawasol', nome: 'Tawasol', tier: 'bundled', licenca: 'CC BY-SA 4.0', disponivel: false,
+        nota: 'Desenhado na e para a cultura árabe. Um pictograma não é neutro — a criança reconhece mais depressa os objetos, as roupas e os rostos do próprio mundo.' },
+    // --- PICTOGRAMA que precisa ser BAIXADO. ---
+    { key: 'arasaac', nome: 'ARASAAC', tier: 'fetched', licenca: 'baixado à parte', disponivel: false },
+    // --- AGUARDANDO NEGOCIAÇÃO. Ficam visíveis de propósito: ver `caaMotivo`. ---
+    { key: 'sclera', nome: 'Sclera', tier: 'negotiating', licenca: null, disponivel: false },
+    { key: 'pcs', nome: 'PCS', tier: 'negotiating', licenca: null, disponivel: false },
+    { key: 'symbolstix', nome: 'SymbolStix', tier: 'negotiating', licenca: null, disponivel: false },
+    { key: 'widgit', nome: 'Widgit Symbols', tier: 'negotiating', licenca: null, disponivel: false },
+];
+export const CAA_BY_KEY = Object.fromEntries(CAA_SETS.map((s) => [s.key, s]));
+/** Quais CONJUNTOS a criança pode escolher hoje: nenhum. O menu não finge o contrário — os pictogramas são
+ *  milhares de arquivos que ainda não entraram no repositório, e quatro deles dependem de negociação. */
+export function caaDisponiveis() {
+    return CAA_SETS.filter((s) => s.disponivel);
+}
+/**
+ * Por que este conjunto não está disponível — chave i18n, nunca texto pronto.
+ *
+ * As duas respostas dizem coisas diferentes a quem lê, e é por isso que são duas: "em preparação" quer dizer
+ * que a licença está resolvida e o trabalho é NOSSO; "aguardando negociação" quer dizer que a permissão é de
+ * OUTRA PESSOA e nenhum esforço nosso a antecipa.
+ *
+ * E é por isso que os indisponíveis aparecem em vez de serem escondidos: são justamente os conjuntos que uma
+ * escola brasileira tem mais chance de já usar em outro produto. O educador que procura PCS e não acha conclui
+ * que o jogo não faz — quando o obstáculo é uma licença, não uma capacidade. Esconder responderia a pergunta
+ * errada, e responderia errado.
+ */
+export function caaMotivo(s) {
+    if (s.disponivel)
+        return null;
+    return s.tier === 'negotiating' ? 'caa.aguardandoNegociacao' : 'caa.emPreparo';
+}
+/** Rótulo pronto para a linha do menu: nome + o motivo, quando há um. */
+export function caaRotulo(s) {
+    const motivo = caaMotivo(s);
+    return motivo ? `${s.nome} — ${t(motivo)}` : s.nome;
+}

package/dist-pkg/ui/changed-mark.d.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare const CHANGED_CLASS = "is-changed";
+/**
+ * Marca (ou desmarca) UM controle. Idempotente por construção: limpa e só então aplica. Os painéis chamam
+ * isto de dentro do mesmo `reflect*` que já redesenha o controle, então ele roda muitas vezes seguidas.
+ */
+export declare function markChanged(el: HTMLElement | null, changed: boolean): void;
+/**
+ * Sobe a marca um nível: o botão que ABRE o menu fica marcado enquanto qualquer opção dentro dele estiver.
+ * Sem isso a trilha começaria dentro do menu, e achar o menu certo continuaria custando abrir os sete.
+ *
+ * `changes` é uma lista de booleanos e não de elementos porque quem sabe comparar com o padrão é o painel;
+ * este módulo não deve ter opinião sobre o que é padrão — há uma fonte só, e é o DEFAULTS do ADR-0028.
+ */
+export declare function markMenuChanged(opener: HTMLElement | null, changes: readonly boolean[]): void;

package/dist-pkg/ui/changed-mark.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/changed-mark.ts — MARCA O QUE SAIU DO PADRÃO (ADR-0029). Módulo-folha: só DOM e i18n, nenhuma dep de
+// estado. Quem sabe o que é padrão é cada painel, que já leu DEFAULTS (ADR-0028); aqui mora só o COMO marcar.
+//
+// O problema que ele resolve: o reset por menu do ADR-0028 só serve a quem sabe que há algo para desfazer.
+// Sete menus, ~40 controles, e o que a criança mexeu tem exatamente a mesma aparência do que ela não mexeu.
+// Os menus não estavam mal rotulados — estavam IMPESQUISÁVEIS.
+//
+// TRÊS CANAIS, e nenhum é enfeite. O ADR-0029 explica por quê; em resumo: a moldura branca sozinha não serve
+// a quem não distingue cores, some no alto contraste (onde `--ink-soft` JÁ é branco) e não existe para quem
+// não enxerga. Então:
+//
+//   1. COR   — `--changed` na moldura (CSS; troca sozinha no alto contraste).
+//   2. FORMA — anel interno, uma moldura dupla. Sobrevive a escala de cinza e a qualquer paleta, porque é uma
+//              CONTAGEM DE ANÉIS e não uma matiz.
+//   3. NOME  — o nome acessível do controle ganha um sufixo. É o canal que faz mais trabalho pelo menor preço:
+//              a criança cega PERCORRE o menu e OUVE, em ordem, o que saiu do padrão.
+//
+// O canal 3 tem dois caminhos porque os painéis constroem o nome de duas formas, e um `aria-label` vence o
+// conteúdo do botão. Marcar só um deles deixaria metade dos controles mudos — em silêncio, que é o pior jeito
+// de uma marca de acessibilidade falhar, porque nada na tela denuncia a falta.
+//
+// O sufixo NUNCA toca o `textContent`. A primeira versão pendurava um `<span class="sr-only">` dentro do
+// botão, e um teste que aferia o rótulo visível caiu — mostrando o problema real: os painéis reescrevem
+// `textContent` inteiro a cada reflect, então o sufixo vivia à mercê da ordem das chamadas. Agora o caminho
+// sem `aria-label` CRIA um, a partir do conteúdo, e o desmarcar simplesmente o remove.
+//
+// E a idempotência é ESTRUTURAL, não caso a caso: toda chamada primeiro devolve o controle ao estado
+// original — tirando qualquer rastro nosso, dos dois caminhos — e só então aplica. Uma marca que só soubesse
+// acrescentar acabaria em tudo, e uma marca em tudo não é marca.
+import { t } from '../core/i18n.js';
+export const CHANGED_CLASS = 'is-changed';
+/** Guarda o `aria-label` ORIGINAL quando ele é do painel, para devolvê-lo sem adivinhar por texto. */
+const BASE_ATTR = 'markBase';
+/** Marca que o `aria-label` foi criado por NÓS: desmarcar tira o atributo inteiro em vez de restaurar algo. */
+const OWNED_ATTR = 'markOwnsLabel';
+/**
+ * O nó cujo NOME acessível recebe o sufixo: o PRIMEIRO controle da linha em ordem de documento, ou a própria
+ * linha quando ela não tem controle dentro.
+ *
+ * "O primeiro" é decisão, não acaso — e ela apareceu ao verificar no jogo. Uma linha do mixer tem DOIS
+ * controles: o volume e o liga/desliga. O sufixo foi para o volume, que vem antes no markup, e isso está
+ * certo por dois motivos: é o controle que a criança alcança primeiro ao tabular, então ela ouve "alterado"
+ * ANTES de decidir se para nesta linha; e repetir o sufixo nos dois faria o leitor de tela dizer a mesma
+ * coisa duas vezes ao atravessar uma linha só, que é ruído com cara de informação.
+ *
+ * O que isto deixa frágil, e por isso está preso por teste: reordenar o markup move o sufixo de controle sem
+ * quebrar nada visível.
+ */
+function namedNode(el) {
+    return el.querySelector('button, select, input, [role="button"]') ?? el;
+}
+/** Devolve o controle ao estado original, venha o rótulo do painel ou de nós. Base de toda chamada. */
+function clearMark(node) {
+    if (node.dataset[OWNED_ATTR] !== undefined) {
+        node.removeAttribute('aria-label');
+        delete node.dataset[OWNED_ATTR];
+    }
+    else if (node.dataset[BASE_ATTR] !== undefined) {
+        node.setAttribute('aria-label', node.dataset[BASE_ATTR]);
+        delete node.dataset[BASE_ATTR];
+    }
+}
+/**
+ * Marca (ou desmarca) UM controle. Idempotente por construção: limpa e só então aplica. Os painéis chamam
+ * isto de dentro do mesmo `reflect*` que já redesenha o controle, então ele roda muitas vezes seguidas.
+ */
+export function markChanged(el, changed) {
+    if (!el)
+        return;
+    el.classList.toggle(CHANGED_CLASS, changed);
+    const node = namedNode(el);
+    clearMark(node);
+    if (!changed)
+        return;
+    const suffix = t('a11y.changed');
+    const label = node.getAttribute('aria-label');
+    if (label !== null) {
+        node.dataset[BASE_ATTR] = label; // rótulo do painel: guardamos e devolvemos depois
+        node.setAttribute('aria-label', label + ', ' + suffix);
+    }
+    else {
+        node.dataset[OWNED_ATTR] = '1'; // rótulo vinha do conteúdo: criamos um e o assumimos
+        node.setAttribute('aria-label', (node.textContent ?? '').trim() + ', ' + suffix);
+    }
+}
+/**
+ * Sobe a marca um nível: o botão que ABRE o menu fica marcado enquanto qualquer opção dentro dele estiver.
+ * Sem isso a trilha começaria dentro do menu, e achar o menu certo continuaria custando abrir os sete.
+ *
+ * `changes` é uma lista de booleanos e não de elementos porque quem sabe comparar com o padrão é o painel;
+ * este módulo não deve ter opinião sobre o que é padrão — há uma fonte só, e é o DEFAULTS do ADR-0028.
+ */
+export function markMenuChanged(opener, changes) {
+    markChanged(opener, changes.some(Boolean));
+}

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

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { JuiceFlags } from '../render/fx.js';
+type Tune = Record<string, number>;
+type Anim = Record<string, number>;
+type Juice = JuiceFlags;
+/**
+ * UMA FOTO DO PERSONAGEM num quadro — DADOS, e nenhum objeto do PixiJS.
+ *
+ * A raiz de composição, que é o único lugar onde o PixiJS já é conhecido, tira a foto e entrega strings. É a
+ * mesma escolha de `RenderizarEm` e `CriarSprite` em render/port: pedir o VERBO cabe onde emprestar o objeto
+ * não cabe — e aqui ela paga duas vezes, porque mantém `ui/debug-panel` testável no project `node`.
+ */
+export interface AmostraDoPersonagem {
+    /** Identidade da textura DENTRO desta gravação. Não é geometria: os quatro quadros de idle têm a mesma. */
+    texturaId: number;
+    /** O recorte, "x,y LxA". */
+    recorte: string;
+    /** A base da textura, "LxA". */
+    base: string;
+    /** A posição do sprite, "x,y". */
+    posicao: string;
+    /** A escala, "x,y" — o squash & stretch mexe nela. */
+    escala: string;
+    /** Quantos IRMÃOS da câmera estavam desenhando alguma textura do personagem neste quadro. */
+    irmaosDesenhando: number;
+    /** Onde eles estavam, para o caso de haver algum. */
+    posIrmaos: string;
+}
+/** O que a sonda responde. Três perguntas, porque são elas que separam as causas que sobraram. */
+export interface ResumoDaSonda {
+    quadros: number;
+    texturas: number;
+    maxIrmaos: number;
+    exemploIrmaos: string;
+    /** As texturas cujo recorte é grande demais para um quadro de personagem — sangramento de atlas. */
+    sangramento: string[];
+    escalas: string[];
+    veredito: string;
+}
+/**
+ * Reduz a gravação a três perguntas e um veredito.
+ *
+ * A ORDEM DO VEREDITO É A DECISÃO: irmão desenhando vence sangramento, porque é ele que produz cópias
+ * INTEIRAS em posições diferentes — que é exatamente o que foi relatado. E quando as três perguntas vêm
+ * limpas o veredito NÃO diz "está tudo bem": ele diz ONDE procurar em seguida. Ausência de prova nas três
+ * não é prova de ausência, e encerrar a busca aqui a encerraria no lugar errado.
+ */
+export declare function resumirSonda(amostras: readonly AmostraDoPersonagem[]): ResumoDaSonda;
+export interface DebugPanelCtx {
+    TUNE: Tune;
+    ANIM: Anim;
+    JUICE: Juice;
+    saveJuice: () => void;
+    /**
+     * Uma foto do personagem AGORA, ou `null` se ainda não há personagem na cena.
+     *
+     * OPCIONAL: um hospedeiro sem personagem (o quiz) não a fornece, e a sonda simplesmente não aparece. O
+     * painel continua sem conhecer o PixiJS.
+     */
+    amostrarPersonagem?: () => AmostraDoPersonagem | null;
+    /** Chama `fn` a cada quadro e devolve como cancelar. É o relógio do render, injetado como verbo. */
+    aoQuadro?: (fn: () => void) => () => void;
+    /** Override for tests; defaults to location.search. */
+    search?: string;
+}
+export declare function initDebugPanel(ctx: DebugPanelCtx): HTMLElement | null;
+export {};

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

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/debug-panel — the ?debug=true live-tuning panel (physics/animation sliders + juice toggles). Leaf UI module.
+// Built via closure DI: receives the LIVE TUNE/ANIM/JUICE objects (mutated in place) + saveJuice from the composition
+// root, so the sliders/checkboxes tune the same state the game reads. Extracted from game.js (modularization Tier 1).
+// Returns the panel element (or null when not in ?debug=true) — testable without booting the game.
+/** Um recorte maior que isto não é um quadro de personagem: é um pedaço do atlas. O maior real tem 31x35. */
+const MAIOR_QUADRO = 64;
+/**
+ * Reduz a gravação a três perguntas e um veredito.
+ *
+ * A ORDEM DO VEREDITO É A DECISÃO: irmão desenhando vence sangramento, porque é ele que produz cópias
+ * INTEIRAS em posições diferentes — que é exatamente o que foi relatado. E quando as três perguntas vêm
+ * limpas o veredito NÃO diz "está tudo bem": ele diz ONDE procurar em seguida. Ausência de prova nas três
+ * não é prova de ausência, e encerrar a busca aqui a encerraria no lugar errado.
+ */
+export function resumirSonda(amostras) {
+    if (!amostras.length) {
+        return { quadros: 0, texturas: 0, maxIrmaos: 0, exemploIrmaos: '', sangramento: [], escalas: [], veredito: 'não gravou nada — o personagem existia?' };
+    }
+    const texturas = new Set(amostras.map((a) => a.texturaId)).size;
+    const comIrmaos = amostras.filter((a) => a.irmaosDesenhando > 0);
+    const maxIrmaos = comIrmaos.reduce((m, a) => Math.max(m, a.irmaosDesenhando), 0);
+    const grande = (r) => {
+        const m = /(\d+)x(\d+)$/.exec(r);
+        return !!m && (+m[1] > MAIOR_QUADRO || +m[2] > MAIOR_QUADRO);
+    };
+    const sangramento = [...new Set(amostras.filter((a) => grande(a.recorte)).map((a) => a.recorte + ' (base ' + a.base + ')'))];
+    const escalas = [...new Set(amostras.map((a) => a.escala))].sort();
+    const veredito = maxIrmaos > 0
+        ? 'ALGUÉM DESENHA DUAS VEZES: até ' + maxIrmaos + ' irmão(s) da câmera com a textura do personagem'
+        : sangramento.length
+            ? 'RECORTE GRANDE DEMAIS: o quadro está pegando pedaço do atlas'
+            : 'sprite limpo (uma textura por quadro, sem irmão, recorte de quadro) — procure em composição: filtro, pós-efeito ou câmera';
+    return { quadros: amostras.length, texturas, maxIrmaos, exemploIrmaos: comIrmaos.length ? comIrmaos[0].posIrmaos : '', sangramento, escalas, veredito };
+}
+export function initDebugPanel(ctx) {
+    const search = ctx.search ?? location.search;
+    if (!/[?&]debug=true/.test(search))
+        return null;
+    const { TUNE, ANIM, JUICE, saveJuice } = ctx;
+    const KNOBS = [
+        { h: 'Movimento (valores absolutos)' },
+        { label: 'Velocidade de andar', get: () => TUNE.hWalk, set: (v) => (TUNE.hWalk = v), min: 0.5, max: 5, step: 0.1 },
+        { label: 'Velocidade de correr', get: () => TUNE.hRun, set: (v) => (TUNE.hRun = v), min: 1, max: 7, step: 0.1 },
+        { label: 'Super-corrida (turbo)', get: () => TUNE.hTurbo, set: (v) => (TUNE.hTurbo = v), min: 1, max: 9, step: 0.1 },
+        { label: 'Pulo (impulso inicial)', get: () => TUNE.jumpVel, set: (v) => (TUNE.jumpVel = v), min: 1, max: 8, step: 0.1 },
+        { label: 'Ultra-pulo', get: () => TUNE.ultraJumpVel, set: (v) => (TUNE.ultraJumpVel = v), min: 3, max: 16, step: 0.1 },
+        { label: 'Trampolim (base)', get: () => TUNE.trampBase, set: (v) => (TUNE.trampBase = v), min: 2, max: 10, step: 0.1 },
+        { label: 'Trampolim (máximo)', get: () => TUNE.trampMax, set: (v) => (TUNE.trampMax = v), min: 3, max: 14, step: 0.1 },
+        { label: 'Nado: impulso', get: () => TUNE.waterJump, set: (v) => (TUNE.waterJump = v), min: 1, max: 7, step: 0.1 },
+        { label: 'Nado: impulso correndo', get: () => TUNE.waterJumpRun, set: (v) => (TUNE.waterJumpRun = v), min: 1, max: 8, step: 0.1 },
+        { label: 'Nado: quadros/braçada', get: () => TUNE.waterStrokeFrames, set: (v) => (TUNE.waterStrokeFrames = v), min: 10, max: 60, step: 1 },
+        { label: 'Escalada (velocidade)', get: () => TUNE.climbSpeed, set: (v) => (TUNE.climbSpeed = v), min: 0.5, max: 4, step: 0.1 },
+        { label: 'Gravidade', get: () => TUNE.gravity, set: (v) => (TUNE.gravity = v), min: 0.05, max: 0.4, step: 0.01 },
+        { label: 'Queda máxima', get: () => TUNE.maxFall, set: (v) => (TUNE.maxFall = v), min: 3, max: 14, step: 0.5 },
+        { label: 'Queda máxima na água', get: () => TUNE.waterMaxFall, set: (v) => (TUNE.waterMaxFall = v), min: 1, max: 8, step: 0.5 },
+        { h: 'Animação (cadência: ticks/quadro)' },
+        { label: 'Andar', get: () => ANIM.walkHold, set: (v) => (ANIM.walkHold = v), min: 1, max: 20, step: 1, cad: true },
+        { label: 'Correr', get: () => ANIM.runHold, set: (v) => (ANIM.runHold = v), min: 1, max: 20, step: 1, cad: true },
+        { label: 'Parado (idle)', get: () => ANIM.idleHold, set: (v) => (ANIM.idleHold = v), min: 2, max: 40, step: 1, cad: true },
+        { label: 'Nado', get: () => ANIM.swimHold, set: (v) => (ANIM.swimHold = v), min: 2, max: 24, step: 1, cad: true },
+        { h: 'Juice (efeitos de resposta) — toggles independentes' },
+        { label: '💨 Poeira (pulo/pouso/corrida)', chk: () => JUICE.dust, set: (v) => { JUICE.dust = v; saveJuice(); } },
+        { label: '✨ Brilho ao coletar', chk: () => JUICE.sparkle, set: (v) => { JUICE.sparkle = v; saveJuice(); } },
+        { label: '🤸 Squash & stretch', chk: () => JUICE.squash, set: (v) => { JUICE.squash = v; saveJuice(); } },
+        { label: '⏱️ Hit-stop (impacto)', chk: () => JUICE.hitstop, set: (v) => { JUICE.hitstop = v; saveJuice(); } },
+        { label: '📳 Tremor de tela', chk: () => JUICE.shake, set: (v) => { JUICE.shake = v; saveJuice(); } },
+        { label: '🌟 Cintilar dos itens', chk: () => JUICE.shimmer, set: (v) => { JUICE.shimmer = v; saveJuice(); } },
+    ]; // Estética CRT saiu daqui: mora no menu Sensibilidade visual (pedido do José).
+    const p = document.createElement('div');
+    p.id = 'debug-panel';
+    p.hidden = true; // começa oculto; abre pelo botão 🐞 Debug
+    p.setAttribute('role', 'group');
+    p.setAttribute('aria-label', 'Painel de depuração');
+    p.style.cssText = 'position:fixed;top:8px;right:8px;z-index:200;background:rgba(11,16,32,.97);color:#fff;border:2px solid #ffd23f;border-radius:8px;padding:.6rem .7rem;font:13px/1.4 system-ui,sans-serif;max-width:270px;max-height:86vh;overflow:auto;box-shadow:0 4px 16px rgba(0,0,0,.5)';
+    p.innerHTML = '<strong>🔧 ?debug — valores ao vivo</strong>';
+    for (const k of KNOBS) {
+        if ('h' in k) {
+            const h = document.createElement('div');
+            h.textContent = k.h;
+            h.style.cssText = 'margin:.7rem 0 .1rem;font-weight:700;color:#ffd23f;border-bottom:1px solid rgba(255,210,63,.4)';
+            p.appendChild(h);
+            continue;
+        }
+        if ('chk' in k) {
+            const row = document.createElement('label');
+            row.style.cssText = 'display:flex;gap:.4rem;align-items:center;margin-top:.4rem;font-size:12px;cursor:pointer';
+            const inp = document.createElement('input');
+            inp.type = 'checkbox';
+            inp.checked = k.chk();
+            inp.addEventListener('change', () => k.set(inp.checked));
+            row.appendChild(inp);
+            row.appendChild(document.createTextNode(k.label));
+            p.appendChild(row);
+            continue;
+        }
+        const row = document.createElement('div');
+        row.style.cssText = 'margin-top:.5rem';
+        const lab = document.createElement('label');
+        lab.style.cssText = 'display:block;font-size:12px;margin-bottom:2px';
+        const val = document.createElement('strong');
+        val.style.cssText = 'color:#ffd23f;float:right';
+        const upd = () => { val.textContent = k.cad ? `${k.get()} (${Math.round(60 / k.get())}fps)` : String(k.get()); };
+        lab.textContent = k.label;
+        lab.appendChild(val);
+        const inp = document.createElement('input');
+        inp.type = 'range';
+        inp.min = String(k.min);
+        inp.max = String(k.max);
+        inp.step = String(k.step);
+        inp.value = String(k.get());
+        inp.style.cssText = 'width:100%';
+        inp.setAttribute('aria-label', k.label);
+        inp.addEventListener('input', () => { k.set(parseFloat(inp.value)); upd(); });
+        row.appendChild(lab);
+        row.appendChild(inp);
+        p.appendChild(row);
+        upd();
+    }
+    /* ===================== A SONDA DO PERSONAGEM =====================
+       Ela mora AQUI, e não num script para colar no console, porque foi o que o Dev pediu — e ele tem razão
+       pelo motivo de sempre: um instrumento que só existe enquanto alguém lembra de colar não é instrumento, é
+       lembrança. Aqui ele fica ao lado dos outros valores ao vivo, atrás do mesmo `?debug=true`.
+  
+       Só aparece se o hospedeiro souber tirar a foto: um jogo sem personagem não ganha um botão que não faz
+       nada. */
+    if (ctx.amostrarPersonagem && ctx.aoQuadro) {
+        const amostrar = ctx.amostrarPersonagem, aoQuadro = ctx.aoQuadro;
+        const h = document.createElement('div');
+        h.textContent = 'Sonda do personagem';
+        h.style.cssText = 'margin:.7rem 0 .1rem;font-weight:700;color:#ffd23f;border-bottom:1px solid rgba(255,210,63,.4)';
+        p.appendChild(h);
+        const saida = document.createElement('pre');
+        saida.style.cssText = 'margin:.4rem 0 0;font:11px/1.35 ui-monospace,monospace;white-space:pre-wrap;color:#cfe';
+        saida.setAttribute('aria-live', 'polite');
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.textContent = '🥷 Gravar 180 quadros';
+        btn.style.cssText = 'margin-top:.4rem;width:100%;min-height:32px;font:inherit;font-weight:700;cursor:pointer;border-radius:6px;border:1px solid #ffd23f;background:#1a2740;color:#fff';
+        btn.addEventListener('click', () => {
+            if (btn.disabled)
+                return;
+            btn.disabled = true;
+            const amostras = [];
+            let n = 0;
+            saida.textContent = 'gravando… PULE agora';
+            const parar = aoQuadro(() => {
+                const a = amostrar();
+                if (a)
+                    amostras.push(a);
+                if (++n < 180)
+                    return;
+                parar();
+                btn.disabled = false;
+                const r = resumirSonda(amostras);
+                saida.textContent = [
+                    'quadros: ' + r.quadros + '  texturas: ' + r.texturas,
+                    'irmãos desenhando: ' + r.maxIrmaos + (r.exemploIrmaos ? ' em ' + r.exemploIrmaos : ''),
+                    'recorte grande: ' + (r.sangramento.length ? r.sangramento.join(' ') : 'nenhum'),
+                    'escalas: ' + r.escalas.join(' '),
+                    '',
+                    '→ ' + r.veredito,
+                ].join(String.fromCharCode(10));
+                // O BRUTO fica alcançável para quem quiser ir além do resumo — sem poluir o painel com 180 linhas.
+                window.__sonda = amostras;
+            });
+        });
+        p.appendChild(btn);
+        p.appendChild(saida);
+    }
+    document.body.appendChild(p);
+    return p;
+}

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

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare const $: <T extends Element = HTMLElement>(s: string) => T | null;
+export declare const $$: <T extends Element = HTMLElement>(s: string) => T[];
+/**
+ * Reflects an on/off state onto a toggle button: the visual class AND `aria-pressed`.
+ * Lives here because the two must never drift apart — a button that looks pressed but does not
+ * say so is invisible to a screen reader, which is a pillar violation, not a style slip.
+ */
+export declare function toggleBtn(b: Element | null, on: boolean): void;
+/**
+ * O TEXTO do botão de alternância: '❚❚ Ligado' / '▶ Desligado'.
+ *
+ * Mora aqui pelo mesmo motivo do `toggleBtn` logo acima — os dois são as duas metades do mesmo gesto, e a
+ * nota daquela função diz que elas "não podem se separar". Elas tinham se separado em TREZE cópias, em nove
+ * arquivos, e dois deles declaravam um helper que se chamava compartilhado e servia um chamador só
+ * (`settings-empathy.toggleLabel` e `settings-motor.onOffLabel`, ambos apagados agora).
+ *
+ * O custo dessa dispersão não era estético: com o texto em treze lugares, traduzir o jogo exigiria achar os
+ * treze, e esquecer um deixaria um botão em português no meio do inglês — sem erro, sem teste vermelho.
+ */
+export declare function toggleLabel(on: boolean): string;
+/** O `aria-label` da mesma alternância: '{alvo}: ligado'. Separado do rótulo visível porque o leitor de tela
+ *  precisa do NOME do alvo junto, e a tela não (o nome já está na linha ao lado do botão). */
+export declare function toggleAria(alvo: string, on: boolean): string;

package/dist-pkg/ui/dom.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/dom.ts — atalhos de seleção do DOM, usados em toda a UI (menus/HUD/pausa/quiz/opções). PURO no import:
+// só define as funções (não toca no DOM → importável em node). $ = querySelector; $$ = querySelectorAll
+// como Array. Genéricos: $<HTMLInputElement>('#x') já tipa o retorno. (Fase 2.27 / Tier 1)
+//
+// DEIXOU DE SER FOLHA no item 14, e de propósito: passou a importar `core/i18n` para que `toggleLabel` (o
+// texto do botão de alternância) more ao lado do `toggleBtn` (a classe e o `aria-pressed`). A propriedade que
+// importa — importável em node, sem I/O no import — continua valendo; o que se perdeu foi a contagem de zero
+// dependências, e o que se ganhou está escrito no comentário de `toggleLabel`.
+import { t } from '../core/i18n.js';
+// O PADRAO E `HTMLElement`, NAO `Element`, e a diferenca aparece em dezessete pontos de chamada: `.hidden`,
+// `.focus()` e `.value` nao existem em `Element`, e sao exatamente o que uma aplicacao faz com o que
+// seleciona. `Element` e o padrao do lib.dom porque `querySelector` tambem serve para SVG e MathML —
+// nenhum seletor deste projeto pega um desses (conferido). Quem precisar de um tipo mais estreito passa
+// o parametro: `$<HTMLSelectElement>('#pad-design')`.
+export const $ = (s) => document.querySelector(s);
+export const $$ = (s) => [...document.querySelectorAll(s)];
+/**
+ * Reflects an on/off state onto a toggle button: the visual class AND `aria-pressed`.
+ * Lives here because the two must never drift apart — a button that looks pressed but does not
+ * say so is invisible to a screen reader, which is a pillar violation, not a style slip.
+ */
+export function toggleBtn(b, on) {
+    if (!b)
+        return;
+    b.classList.toggle('is-on', on);
+    b.setAttribute('aria-pressed', String(on));
+}
+/**
+ * O TEXTO do botão de alternância: '❚❚ Ligado' / '▶ Desligado'.
+ *
+ * Mora aqui pelo mesmo motivo do `toggleBtn` logo acima — os dois são as duas metades do mesmo gesto, e a
+ * nota daquela função diz que elas "não podem se separar". Elas tinham se separado em TREZE cópias, em nove
+ * arquivos, e dois deles declaravam um helper que se chamava compartilhado e servia um chamador só
+ * (`settings-empathy.toggleLabel` e `settings-motor.onOffLabel`, ambos apagados agora).
+ *
+ * O custo dessa dispersão não era estético: com o texto em treze lugares, traduzir o jogo exigiria achar os
+ * treze, e esquecer um deixaria um botão em português no meio do inglês — sem erro, sem teste vermelho.
+ */
+export function toggleLabel(on) {
+    return t(on ? 'ui.toggle.on' : 'ui.toggle.off');
+}
+/** O `aria-label` da mesma alternância: '{alvo}: ligado'. Separado do rótulo visível porque o leitor de tela
+ *  precisa do NOME do alvo junto, e a tela não (o nome já está na linha ao lado do botão). */
+export function toggleAria(alvo, on) {
+    return t(on ? 'ui.toggle.ariaOn' : 'ui.toggle.ariaOff', { alvo });
+}

package/dist-pkg/ui/focus-trap.d.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * 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 declare const SELETOR_FOCAVEL: string;
+/**
+ * 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 declare function proximoNaArmadilha<T>(focaveis: readonly T[], atual: T | null, paraTras: boolean): T | null;
+interface AlvoDeEvento {
+    addEventListener: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
+    removeEventListener?: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
+}
+export interface FocusTrapCtx {
+    /** O diálogo VISÍVEL mais alto da pilha, ou `null`. É o `topVisibleOverlay` de `ui/settings-panel`. */
+    overlayDeCima: () => HTMLElement | null;
+    /** Quem tem o foco agora — `() => document.activeElement`. Injetado: o project node não tem documento. */
+    focoAtual: () => Element | null;
+    /** Os focáveis DENTRO do diálogo, na ordem do documento e já filtrados por visibilidade. */
+    focaveisDe: (dentro: HTMLElement) => HTMLElement[];
+    win: AlvoDeEvento;
+}
+export interface FocusTrapApi {
+    /** O manipulador, exposto para o teste o chamar sem instalar nada. */
+    aoTeclar: (e: KeyboardEvent) => void;
+    /** Instala na fase de CAPTURA, pelo mesmo motivo do `menu-nav`: ver a tecla antes de quem está por baixo. */
+    attach: () => void;
+    /**
+     * Desinstala.
+     *
+     * ⚠️ ELE NASCEU DE UM TESTE QUE REPROVOU, e não de simetria: dois casos no mesmo ficheiro instalaram duas
+     * armadilhas na mesma janela, e a primeira continuou a prender o foco durante o segundo — o caso «sem
+     * diálogo aberto o Tab é do jogo» ficou vermelho por causa de uma armadilha que já devia ter saído.
+     *
+     * O que isso mostra vale fora do teste: uma armadilha que não se desinstala é um vazamento para qualquer
+     * página que monte a engine duas vezes — o `demos`, que troca de jogo sem recarregar, é exatamente isso.
+     */
+    detach: () => void;
+}
+export declare function initFocusTrap(ctx: FocusTrapCtx): FocusTrapApi;
+/**
+ * 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 declare function focaveisNoDom(dentro: HTMLElement): HTMLElement[];
+export {};