@the-inclusionist/engine 6.36.1

package/dist-pkg/input/touch.d.ts

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { DomQuery } from '../core/dom-query.js';
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+/** Minimal platform/storage.ts shape this module needs. */
+export interface TouchStore {
+    get(key: string, fallback?: string | null): string | null;
+    set(key: string, value: string | number | boolean): boolean;
+    getNum(key: string, fallback?: number): number;
+    getJSON<T = unknown>(key: string, fallback?: T | null): T | null;
+    setJSON(key: string, obj: unknown): void;
+}
+export interface TouchCtx {
+    /** DOM selector (querySelector), injected — never reaches `document` globally. */
+    $: DomQuery;
+    /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
+    srSay: (msg: string) => void;
+    /**
+     * AS POSIÇÕES QUE ESTE JOGO USA, cada uma com a palavra dele, no idioma vigente.
+     *
+     * ⚠️ Substitui `TOUCH_ACTS` + `TOUCH_ACT_LABELS`. O menu de cada slot oferecia NOVE opções fixas — quer
+     * dizer, a engine decidia que todo jogo tem pular, correr, trocar e especial, e uma criança num quiz
+     * poderia atribuir «Trocar poder» a um botão da tela, que depois não faria nada.
+     *
+     * A ordem também vem daqui: é a ordem canônica de `core/actions`, a mesma que a tela de remapeamento usa,
+     * para a criança não ter de reaprender a lista ao trocar de painel.
+     */
+    acoesDoJogo: () => readonly {
+        readonly acao: string;
+        readonly rotulo: string;
+    }[];
+    /** Persistence (platform/storage.ts), injected. */
+    store: TouchStore;
+    /** Element the --pad-* CSS custom properties are written to: document.documentElement in production
+     *  (mirrors ui/settings-typo.ts's `root` injection for the same reason — no direct `document` access). */
+    root: HTMLElement;
+    /** Shared device-class check (game.js's isMobile(), used by several subsystems) — injected, not duplicated. */
+    isMobile: () => boolean;
+    /** Screen dimensions, injected (never reads `window.innerWidth/innerHeight` directly). */
+    viewport: () => {
+        w: number;
+        h: number;
+    };
+    /** Shared overlay z-index/focus helper (game.js's frontOverlay), used by every panel — injected. */
+    frontOverlay: (el: HTMLElement | null) => void;
+    /** Optional hook fired after applyPadDesign() changes padDesign — game.js's renderPauseLegend() (Sim/Não
+     *  glyphs in the pause menu) is NOT part of this module's boundary but must still refresh; see report. */
+    onPadDesignApplied?: () => void;
+    /**
+     * O controle de tela ENTROU em cena. Existe para que a raiz possa ligar sozinha o que só faz sentido no
+     * toque — hoje, a alternância do botão de correr: num botão virtual ninguém "segura" com conforto, porque
+     * o dedo que segura é o mesmo que precisa alcançar os outros.
+     *
+     * Gancho e não regra aqui dentro: este módulo desenha controles e não conhece ajuste de acessibilidade
+     * nenhum. Quem sabe o que ligar é quem possui os jogadores.
+     */
+    onTouchControlsShown?: () => void;
+    /**
+     * PODE mostrar o pad virtual AGORA? Injetado, e é o corte do item 19 neste módulo.
+     *
+     * Era uma linha que lia TRÊS coisas por importação de `core/state`:
+     *     `if (numPlayers > 1 || phase !== 'playing' || players.some((p) => p.quiz)) return;`
+     * — o número de jogadores, a fase, e se algum jogador tem um QUIZ aberto. A última é a que denunciava: a
+     * camada de TOQUE sabia que existe atividade de alfabetização. E as três juntas eram uma POLÍTICA do jogo
+     * escrita dentro da engine.
+     *
+     * É o mesmo movimento do achado 10 (`isNavigable`): injetar o BOOLEANO, não o estado. A plataforma responde
+     * "um jogador, jogando, sem desafio aberto"; um jogo de outro gênero responde o que for verdade nele. E o
+     * módulo deixou de importar `core/state` — não sobrou leitura de estado compartilhado nenhuma.
+     */
+    padAllowed: () => boolean;
+}
+export declare const IPHONE16_LONG_MM = 141.1;
+export declare const IPHONE16_LONG_PX = 852;
+export declare const IPHONE16_PXMM: number;
+/** mm→px CSS. No celular, ancora na aresta longa da JANELA (físico exato, retrato ou paisagem). No
+ *  desktop/notebook, fixa no ratio do iPhone 16 (não cresce com a largura do monitor). Determinístico e puro:
+ *  `mobile`/`viewW`/`viewH` chegam já resolvidos (isMobile()/innerWidth/innerHeight ficam no lado impuro). */
+export declare function padPxPerMm(mobile: boolean, viewW: number, viewH: number): number;
+export type HandTag = 'crianca' | 'adulto' | 'inter';
+/** Classifica um valor em mm na faixa mão-de-criança / intermediário / mão-de-adulto (usado nas etiquetas
+ *  do painel de configuração de toque). */
+export declare function padHandTag(v: number, lo: number, hi: number): HandTag;
+export interface PadMm {
+    btn: number;
+    gap: number;
+    stick: number;
+    travel: number;
+    dpad: number;
+}
+export interface PadPhysicalPx {
+    btnPx: number;
+    diamPx: number;
+    knobPx: number;
+    basePx: number;
+    armPx: number;
+    armWPx: number;
+    spanPx: number;
+    stickTravelPx: number;
+    stickDeadPx: number;
+}
+/** Toda a geometria em px a partir dos mm configurados + do fator px/mm — extraída de applyPadPhysical() para
+ *  ficar pura/testável (dpr alto/baixo, tela pequena, valores extremos). applyPadPhysical() só chama isto e
+ *  escreve o resultado em custom properties CSS + nos rótulos do painel. */
+export declare function computePadPhysicalPx(mm: PadMm, pxPerMm: number): PadPhysicalPx;
+export type PadLayout = 'sony' | 'nintendo' | 'microsoft' | 'generic';
+/** Layout de rotulagem dos botões pelo id reportado do controle (heurística por substring/VID). */
+export declare function padLayoutFromId(id: string | null | undefined): PadLayout;
+/** As 9 posições de toque remapeáveis (direcional×4, START, botões 0–3) — `lbl` é a chave i18n do rótulo. */
+export declare const TOUCH_SLOTS: ReadonlyArray<{
+    k: string;
+    lbl: string;
+}>;
+/**
+ * As ações que o TRANSPORTE de toque consegue carregar.
+ *
+ * ⚠️ DEIXOU DE SER A LISTA DO `<select>`: as opções vêm agora de `ctx.acoesDoJogo()`, porque quem decide
+ * quais ações existem é o jogo. Esta lista continua a valer como o que ESTE transporte alcança — e é contra
+ * ela que o gate de `input/touch-bindings` confere se o despacho reconhece tudo o que se pode oferecer.
+ * As duas coisas eram a mesma por acidente enquanto só havia um jogo.
+ */
+export declare const TOUCH_ACTS: readonly string[];
+/** Funde o mapa persistido (JSON solto do localStorage) sobre TOUCH_DEFAULT. Mantido IDÊNTICO ao original:
+ *  NÃO valida chaves/valores contra TOUCH_SLOTS/TOUCH_ACTS — um JSON malformado com chaves/valores estranhos
+ *  passa como está (só falha se não for um objeto). Ver a nota "bug surfaced" no retorno da extração. */
+export declare function normalizeTouchMap(stored: unknown): Record<string, string>;
+export type PadKind = 'kb' | 'x' | 'd';
+/** UNUSED hoje — grep em game.js (`\bpadKind\b`) só acha a própria definição, nenhum chamador. Extraído porque
+ *  a fronteira explicitamente listou; NÃO apagado (relatado, não conserto). Lê navigator.getGamepads() direto,
+ *  no mesmo padrão de ui/settings-audio.ts / core/i18n.ts (acesso direto a navigator, sem DI) — mesmo assim,
+ *  é semanticamente "ler o controle", território do agente de input/gamepad; ver a nota de fronteira no retorno. */
+export declare function padKind(): PadKind;
+export interface PadMmPatch {
+    btn?: number;
+    gap?: number;
+    stick?: number;
+    travel?: number;
+    dpad?: number;
+}
+export interface TouchApi {
+    /** (Re)desenha #touchmap-list a partir do touchMap atual e prende os <select> de cada slot. */
+    renderTouchMap(): void;
+    /** Abre o diálogo "Botões de tela touch" (#touchcfg). */
+    openTouchCfg(): void;
+    /** Fecha o diálogo #touchcfg e devolve o foco ao botão que o abriu. */
+    closeTouchCfg(): void;
+    /** Esconde os controles de toque (teclado/controle físico assumiu, ou um menu abriu por cima). O parâmetro
+     *  `reason` é só um rótulo de depuração nos call-sites originais — o game.js já o descartava (função de
+     *  zero parâmetros); mantido aqui só de fachada para não quebrar chamadas existentes. */
+    hideTouchControls(reason?: string): void;
+    /** Mostra os controles de toque (toque/clique detectado). No-op em multi-tela, fora de 'playing', ou com
+     *  quiz aberto — dá pra tocar direto nos botões da tela nesses casos. */
+    showTouchControls(): void;
+    /** Alterna a visibilidade do analógico virtual vs. da cruz (D-pad), conforme `padDir`. */
+    applyDirStyle(): void;
+    /** Recalcula toda a geometria (mm→px) e escreve as custom properties + os rótulos do painel. */
+    applyPadPhysical(): void;
+    /** Atualiza um ou mais tamanhos (mm), persiste e reaplica a geometria. */
+    setPadMm(patch: PadMmPatch): void;
+    /** Aplica (e opcionalmente troca) o desenho dos botões; persiste; repinta os botões físicos do losango de
+     *  toque (#pad-diamond); dispara ctx.onPadDesignApplied() (legenda Sim/Não da pausa, fora daqui). Retorna o
+     *  design resultante. */
+    applyPadDesign(d?: string): string;
+    /** Design de botão atualmente ativo ('generic'|'microsoft'|'sony'|'nintendo'). */
+    getPadDesign(): string;
+    /** Referência viva do mapa de toque atual (slot → ação) — mutada por renderTouchMap(); NÃO é uma cópia. */
+    getTouchMap(): Record<string, string>;
+    /** Deslocamento útil do analógico virtual em px, recalculado a cada applyPadPhysical(). */
+    getStickTravelPx(): number;
+    /** Zona-morta do analógico virtual em px, recalculada a cada applyPadPhysical(). */
+    getStickDeadPx(): number;
+}
+export declare function initTouch(ctx: TouchCtx): TouchApi;

package/dist-pkg/input/touch.js

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/touch.ts — on-screen touch controls (Estágio 4): the physical geometry of the touch pad (mm→px) and
+// its config UI (#touchcfg, #touch-controls visibility). Extracted from game.js's E13 block. Geometry/layout/
+// touch-map-merge are pure (padPxPerMm/padHandTag/computePadPhysicalPx/padLayoutFromId/normalizeTouchMap —
+// project node); DOM wiring + persisted state (touchMap/padDesign/padBtnMm/padGapMm/padStickMm/padTravelMm/
+// padDpadMm/padDir) live behind initTouch(ctx). PAD_DESIGNS/TOUCH_ACT_LABELS/TOUCH_DEFAULT come from
+// ./devices.js (not reimplemented). Reading the real Gamepad API (polling, mapping wizard) is input/gamepad's
+// territory, not this module's — see the header note on padKind() for the one deliberate exception.
+import { PAD_DESIGNS, TOUCH_DEFAULT } from './devices.js';
+import { migrarMapaDeToque } from './vocabulary-migration.js';
+import { t } from '../core/i18n.js';
+import { KEYS } from '../platform/storage.js'; // só as CHAVES (constantes) — leitura/escrita passam por ctx.store (DI)
+import { setMinimapCorner } from '../render/minimap.js'; // já módulo próprio (Estágio 4, Tier 1) — importado direto
+// ===================== PURO (sem DOM/store — project node) =====================
+// Alvo físico ancorado no iPhone 16 a tela cheia (aresta longa 141,1mm do display 1179×2556 @460ppi →
+// ~6,04 px CSS/mm). Ver o comentário original em game.js para a justificativa completa (WCAG 2.5.5 / GAG).
+export const IPHONE16_LONG_MM = 141.1;
+export const IPHONE16_LONG_PX = 852;
+export const IPHONE16_PXMM = IPHONE16_LONG_PX / IPHONE16_LONG_MM; // ~6,04 px CSS/mm
+/** mm→px CSS. No celular, ancora na aresta longa da JANELA (físico exato, retrato ou paisagem). No
+ *  desktop/notebook, fixa no ratio do iPhone 16 (não cresce com a largura do monitor). Determinístico e puro:
+ *  `mobile`/`viewW`/`viewH` chegam já resolvidos (isMobile()/innerWidth/innerHeight ficam no lado impuro). */
+export function padPxPerMm(mobile, viewW, viewH) {
+    return mobile ? Math.max(viewW, viewH) / IPHONE16_LONG_MM : IPHONE16_PXMM;
+}
+/** Classifica um valor em mm na faixa mão-de-criança / intermediário / mão-de-adulto (usado nas etiquetas
+ *  do painel de configuração de toque). */
+export function padHandTag(v, lo, hi) {
+    return v <= lo ? 'crianca' : v >= hi ? 'adulto' : 'inter';
+}
+/** Toda a geometria em px a partir dos mm configurados + do fator px/mm — extraída de applyPadPhysical() para
+ *  ficar pura/testável (dpr alto/baixo, tela pequena, valores extremos). applyPadPhysical() só chama isto e
+ *  escreve o resultado em custom properties CSS + nos rótulos do painel. */
+export function computePadPhysicalPx(mm, pxPerMm) {
+    const btnPx = mm.btn * pxPerMm, gapPx = mm.gap * pxPerMm;
+    const diamPx = btnPx + Math.SQRT2 * (btnPx + gapPx); // losango: folga de aresta = gap
+    const knobPx = mm.stick * pxPerMm, travelPx = mm.travel * pxPerMm;
+    const basePx = knobPx + 2 * travelPx + 16; // base do analógico = contato + curso
+    const armPx = mm.dpad * pxPerMm, armWPx = armPx * 0.8, spanPx = 2 * armPx + armWPx; // cruz: braço + largura(0,8×)
+    const stickTravelPx = travelPx, stickDeadPx = Math.max(6, travelPx * 0.4); // zona-morta ~40% do curso
+    return { btnPx, diamPx, knobPx, basePx, armPx, armWPx, spanPx, stickTravelPx, stickDeadPx };
+}
+/** Layout de rotulagem dos botões pelo id reportado do controle (heurística por substring/VID). */
+export function padLayoutFromId(id) {
+    const s = (id || '').toLowerCase();
+    if (/dualshock|dualsense|playstation|054c/.test(s))
+        return 'sony';
+    if (/switch|nintendo|joy-con|057e/.test(s))
+        return 'nintendo';
+    if (/xbox|xinput|microsoft|045e/.test(s))
+        return 'microsoft';
+    return 'generic';
+}
+/** As 9 posições de toque remapeáveis (direcional×4, START, botões 0–3) — `lbl` é a chave i18n do rótulo. */
+// `lbl` guarda a CHAVE i18n, não o texto: tabela de módulo resolvida no import congelaria o idioma no boot
+// (ver a nota em input/devices). A seta e o nome do botão viajam DENTRO da tradução, porque em inglês o
+// "(cima)" vira "(up)" e a seta fica onde está — é moldura inteira, não conteúdo interpolado.
+export const TOUCH_SLOTS = [
+    { k: 'up', lbl: 'touch.slot.up' }, { k: 'down', lbl: 'touch.slot.down' },
+    { k: 'left', lbl: 'touch.slot.left' }, { k: 'right', lbl: 'touch.slot.right' },
+    { k: 'start', lbl: 'touch.slot.start' },
+    { k: 'b0', lbl: 'touch.slot.b0' }, { k: 'b1', lbl: 'touch.slot.b1' },
+    { k: 'b2', lbl: 'touch.slot.b2' }, { k: 'b3', lbl: 'touch.slot.b3' },
+];
+/**
+ * As ações que o TRANSPORTE de toque consegue carregar.
+ *
+ * ⚠️ DEIXOU DE SER A LISTA DO `<select>`: as opções vêm agora de `ctx.acoesDoJogo()`, porque quem decide
+ * quais ações existem é o jogo. Esta lista continua a valer como o que ESTE transporte alcança — e é contra
+ * ela que o gate de `input/touch-bindings` confere se o despacho reconhece tudo o que se pode oferecer.
+ * As duas coisas eram a mesma por acidente enquanto só havia um jogo.
+ */
+export const TOUCH_ACTS = ['left', 'right', 'up', 'down', 'action2', 'action1', 'action3', 'action4', 'start'];
+/** Funde o mapa persistido (JSON solto do localStorage) sobre TOUCH_DEFAULT. Mantido IDÊNTICO ao original:
+ *  NÃO valida chaves/valores contra TOUCH_SLOTS/TOUCH_ACTS — um JSON malformado com chaves/valores estranhos
+ *  passa como está (só falha se não for um objeto). Ver a nota "bug surfaced" no retorno da extração. */
+export function normalizeTouchMap(stored) {
+    // ⚠️ O GUARDADO PASSA PELO TRADUTOR ANTES DA FUSÃO, e a ordem é o que importa: `Object.assign` deixa o
+    // guardado VENCER o padrão, então um `b0: 'jump'` de antes do ADR-0086 sobrescreveria o `b0: 'action2'`
+    // correto e o botão da tela deixaria de fazer nada — sem erro nenhum. Aqui o nome da ação está no VALOR,
+    // não na chave, e por isso precisa de um tradutor próprio. Ver `input/vocabulary-migration.ts`.
+    const migrado = migrarMapaDeToque(stored && typeof stored === 'object' ? stored : null);
+    return Object.assign({}, TOUCH_DEFAULT, migrado || {});
+}
+/** UNUSED hoje — grep em game.js (`\bpadKind\b`) só acha a própria definição, nenhum chamador. Extraído porque
+ *  a fronteira explicitamente listou; NÃO apagado (relatado, não conserto). Lê navigator.getGamepads() direto,
+ *  no mesmo padrão de ui/settings-audio.ts / core/i18n.ts (acesso direto a navigator, sem DI) — mesmo assim,
+ *  é semanticamente "ler o controle", território do agente de input/gamepad; ver a nota de fronteira no retorno. */
+export function padKind() {
+    let kind = 'kb';
+    const pads = navigator.getGamepads ? navigator.getGamepads() : [];
+    for (const gp of pads) {
+        if (!gp)
+            continue;
+        kind = gp.mapping === 'standard' ? 'x' : 'd';
+        if (kind === 'x')
+            break;
+    }
+    return kind;
+}
+export function initTouch(ctx) {
+    let padDesign = ctx.store.get(KEYS.padDesign, 'generic') || 'generic';
+    let padBtnMm = ctx.store.getNum(KEYS.padBtnMm, 12.5);
+    let padGapMm = ctx.store.getNum(KEYS.padGapMm, 3);
+    let padStickMm = ctx.store.getNum(KEYS.padStickMm, 18);
+    let padTravelMm = ctx.store.getNum(KEYS.padTravelMm, 4.5);
+    let padDpadMm = ctx.store.getNum(KEYS.padDpadMm, 12);
+    let padDir = ctx.store.get(KEYS.padDir, 'stick') || 'stick';
+    let _stickTravelPx = 42, _stickDeadPx = 12; // valores de arranque; applyPadPhysical() atualiza de verdade
+    const touchMap = normalizeTouchMap(ctx.store.getJSON(KEYS.touchmap, null));
+    function renderTouchMap() {
+        const el = ctx.$('#touchmap-list');
+        if (!el)
+            return;
+        el.innerHTML = TOUCH_SLOTS.map((s) => `<div class="ctrl-row"><label for="tm-${s.k}">${t(s.lbl)}</label><select id="tm-${s.k}" class="vol" data-slot="${s.k}">` +
+            // ⚠️ A OPÇÃO NASCE VAZIA e o `rotulo` entra logo abaixo por `textContent` (issue #106). Ele é a PALAVRA
+            // do jogo — `acoesDoJogo()` sai do preset —, e um jogo vive noutro repositório (ADR-0083), então este
+            // texto não é revisto por esta árvore. `value="${acao}"` fica: `acao` é o nome ABSTRATO, e a engine
+            // enumera-o em `core/actions`; é dela e não do jogo.
+            ctx.acoesDoJogo().map(({ acao }) => `<option value="${acao}"${touchMap[s.k] === acao ? ' selected' : ''}></option>`).join('') +
+            `</select></div>`).join('');
+        // As palavras do jogo, por `textContent` — que escapa por construção. A ordem casa porque é a mesma lista.
+        for (const sel of el.querySelectorAll('select[data-slot]')) {
+            const palavras = ctx.acoesDoJogo();
+            for (let i = 0; i < sel.options.length && i < palavras.length; i++) {
+                sel.options[i].textContent = palavras[i].rotulo;
+            }
+        }
+        el.querySelectorAll('select[data-slot]').forEach((sel) => {
+            sel.addEventListener('change', () => {
+                const slot = sel.dataset.slot || '';
+                touchMap[slot] = sel.value;
+                ctx.store.setJSON(KEYS.touchmap, touchMap);
+                const label = sel.previousElementSibling ? sel.previousElementSibling.textContent : null;
+                // ⚠️ A palavra falada é a MESMA que a lida: sai da mesma lista que acabou de montar o `<option>`.
+                // Antes vinham de tabelas diferentes e nada obrigava as duas a concordar.
+                const escolhida = ctx.acoesDoJogo().find((x) => x.acao === sel.value);
+                ctx.srSay(t('sr.touch.slotSet', { slot: label || t('touch.slot.fallback'), acao: escolhida ? escolhida.rotulo : sel.value }));
+            });
+        });
+    }
+    function openTouchCfg() {
+        const ov = ctx.$('#touchcfg');
+        if (!ov)
+            return;
+        renderTouchMap();
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        const f = ov.querySelector('select,button');
+        if (f)
+            f.focus();
+    }
+    function closeTouchCfg() {
+        const ov = ctx.$('#touchcfg');
+        if (!ov)
+            return;
+        ov.hidden = true;
+        const b = ctx.$('#opt-touchcfg');
+        if (b)
+            b.focus();
+    }
+    function hideTouchControls(_reason) {
+        const tc = ctx.$('#touch-controls');
+        if (tc && !tc.hidden)
+            tc.hidden = true;
+        ctx.$('body')?.classList.remove('touch-mode');
+        setMinimapCorner(false);
+    }
+    function showTouchControls() {
+        // MENU ativo = sem controle virtual: dá pra tocar direto nos botões da tela. QUEM decide é o jogo.
+        if (!ctx.padAllowed())
+            return;
+        const tc = ctx.$('#touch-controls');
+        if (tc)
+            tc.hidden = false;
+        ctx.$('body')?.classList.add('touch-mode');
+        setMinimapCorner(true);
+        ctx.onTouchControlsShown?.();
+    }
+    function applyDirStyle() {
+        const st = ctx.$('#touch-stick'), cr = ctx.$('#touch-cross');
+        if (st)
+            st.hidden = padDir === 'cross';
+        if (cr)
+            cr.hidden = padDir !== 'cross';
+        const sel = ctx.$('#pad-dir');
+        if (sel && sel.value !== padDir)
+            sel.value = padDir;
+    }
+    function applyPadPhysical() {
+        const vp = ctx.viewport();
+        const r = padPxPerMm(ctx.isMobile(), vp.w, vp.h);
+        const px = computePadPhysicalPx({ btn: padBtnMm, gap: padGapMm, stick: padStickMm, travel: padTravelMm, dpad: padDpadMm }, r);
+        _stickTravelPx = px.stickTravelPx;
+        _stickDeadPx = px.stickDeadPx;
+        const S = ctx.root.style;
+        S.setProperty('--pad-btn', px.btnPx.toFixed(1) + 'px');
+        S.setProperty('--pad-diam', px.diamPx.toFixed(1) + 'px');
+        S.setProperty('--stick-knob', px.knobPx.toFixed(1) + 'px');
+        S.setProperty('--stick-base', px.basePx.toFixed(1) + 'px');
+        S.setProperty('--dpad-arm-l', px.armPx.toFixed(1) + 'px');
+        S.setProperty('--dpad-arm-w', px.armWPx.toFixed(1) + 'px');
+        S.setProperty('--dpad-span', px.spanPx.toFixed(1) + 'px');
+        const fmt = (n) => n.toFixed(1).replace('.', ',');
+        const lbl = { crianca: 'mão de criança', adulto: 'mão de adulto', inter: 'intermediário' };
+        const upd = (valId, tagId, mm, lo, hi, slId) => {
+            const v = ctx.$(valId);
+            if (v)
+                v.textContent = fmt(mm) + ' mm';
+            const t = ctx.$(tagId);
+            if (t) {
+                const w = padHandTag(mm, lo, hi);
+                t.dataset.who = w;
+                t.textContent = lbl[w];
+            }
+            const s = ctx.$(slId);
+            if (s && parseFloat(s.value) !== mm)
+                s.value = String(mm);
+        };
+        upd('#pad-size-val', '#pad-size-tag', padBtnMm, 12.5, 13, '#pad-size');
+        upd('#pad-gap-val', '#pad-gap-tag', padGapMm, 3, 4.5, '#pad-gap');
+        upd('#pad-stick-val', '#pad-stick-tag', padStickMm, 17, 19, '#pad-stick');
+        upd('#pad-travel-val', '#pad-travel-tag', padTravelMm, 4, 5.5, '#pad-travel');
+        upd('#pad-dpad-val', '#pad-dpad-tag', padDpadMm, 12, 14, '#pad-dpad');
+    }
+    function setPadMm(o) {
+        if (o.btn != null)
+            padBtnMm = o.btn;
+        if (o.gap != null)
+            padGapMm = o.gap;
+        if (o.stick != null)
+            padStickMm = o.stick;
+        if (o.travel != null)
+            padTravelMm = o.travel;
+        if (o.dpad != null)
+            padDpadMm = o.dpad;
+        ctx.store.set(KEYS.padBtnMm, padBtnMm);
+        ctx.store.set(KEYS.padGapMm, padGapMm);
+        ctx.store.set(KEYS.padStickMm, padStickMm);
+        ctx.store.set(KEYS.padTravelMm, padTravelMm);
+        ctx.store.set(KEYS.padDpadMm, padDpadMm);
+        applyPadPhysical();
+    }
+    function applyPadDesign(d) {
+        if (d && PAD_DESIGNS[d])
+            padDesign = d;
+        ctx.store.set(KEYS.padDesign, padDesign);
+        const set = PAD_DESIGNS[padDesign] || PAD_DESIGNS.generic;
+        const diamond = ctx.$('#pad-diamond');
+        if (diamond) {
+            diamond.querySelectorAll('.pad-b').forEach((b) => {
+                const s = set[b.dataset.btn || ''];
+                if (s) {
+                    b.textContent = s[0];
+                    b.style.background = s[1];
+                }
+            });
+        }
+        ctx.onPadDesignApplied?.();
+        return padDesign;
+    }
+    // --- wiring: #touchcfg (painel "Botões de tela touch") + o botão que o abre/fecha (#opt-touchcfg no painel
+    //     de Movimento) — todo elemento abaixo mora dentro (ou controla) o overlay #touchcfg. ---
+    const touchCfgBtn = ctx.$('#opt-touchcfg');
+    if (touchCfgBtn)
+        touchCfgBtn.addEventListener('click', openTouchCfg);
+    const touchCfgClose = ctx.$('#touchcfg-close');
+    if (touchCfgClose)
+        touchCfgClose.addEventListener('click', closeTouchCfg);
+    const padDirSel = ctx.$('#pad-dir');
+    if (padDirSel) {
+        padDirSel.value = padDir;
+        padDirSel.addEventListener('change', () => {
+            padDir = padDirSel.value;
+            ctx.store.set(KEYS.padDir, padDir);
+            applyDirStyle();
+            ctx.srSay(t('sr.touch.dirSet', { tipo: t(padDir === 'cross' ? 'touch.dir.cross' : 'touch.dir.stick') }));
+        });
+    }
+    const padSizeEl = ctx.$('#pad-size');
+    if (padSizeEl)
+        padSizeEl.addEventListener('input', () => setPadMm({ btn: parseFloat(padSizeEl.value) }));
+    const padGapEl = ctx.$('#pad-gap');
+    if (padGapEl)
+        padGapEl.addEventListener('input', () => setPadMm({ gap: parseFloat(padGapEl.value) }));
+    const padStickEl = ctx.$('#pad-stick');
+    if (padStickEl)
+        padStickEl.addEventListener('input', () => setPadMm({ stick: parseFloat(padStickEl.value) }));
+    const padTravelEl = ctx.$('#pad-travel');
+    if (padTravelEl)
+        padTravelEl.addEventListener('input', () => setPadMm({ travel: parseFloat(padTravelEl.value) }));
+    const padDpadEl = ctx.$('#pad-dpad');
+    if (padDpadEl)
+        padDpadEl.addEventListener('input', () => setPadMm({ dpad: parseFloat(padDpadEl.value) }));
+    const padPresetChild = ctx.$('#pad-preset-child');
+    if (padPresetChild)
+        padPresetChild.addEventListener('click', () => { setPadMm({ btn: 12, gap: 2.5, stick: 16.5, travel: 4, dpad: 11.5 }); ctx.srSay(t('sr.touch.presetChild')); });
+    const padPresetAdult = ctx.$('#pad-preset-adult');
+    if (padPresetAdult)
+        padPresetAdult.addEventListener('click', () => { setPadMm({ btn: 14, gap: 4.5, stick: 20, travel: 5.5, dpad: 14 }); ctx.srSay(t('sr.touch.presetAdult')); });
+    addEventListener('resize', applyPadPhysical); // recalcula os px ao girar/redimensionar; os mm são fixos
+    // estado inicial (equivalente aos `applyPadDesign(padDesign); applyPadPhysical(); applyDirStyle();` de boot no game.js)
+    applyPadDesign();
+    applyPadPhysical();
+    applyDirStyle();
+    return {
+        renderTouchMap, openTouchCfg, closeTouchCfg, hideTouchControls, showTouchControls,
+        applyDirStyle, applyPadPhysical, setPadMm, applyPadDesign,
+        getPadDesign: () => padDesign,
+        getTouchMap: () => touchMap,
+        getStickTravelPx: () => _stickTravelPx,
+        getStickDeadPx: () => _stickDeadPx,
+    };
+}

package/dist-pkg/input/transports.d.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Action } from '../core/actions.js';
+/**
+ * QUANTOS LUGARES CADA TRANSPORTE REAL TEM, e de onde cada número vem. Estavam medidos e viviam só no teste;
+ * um número que só existe num teste não chega a criança nenhuma.
+ *
+ *   · `gamepad: 17` — a Gamepad API «standard» declara dezassete botões. Não é escolha nossa.
+ *   · `toque: 9` — `TOUCH_DEFAULT` (input/devices) nomeia nove slots, e são nove desde sempre.
+ *   · `teclado: ACTIONS.length` — ⚠️ e este é o que precisou de decisão.
+ *
+ * ⚠️ O NÚMERO DO TECLADO NÃO É O NÚMERO DE TECLAS, e também não é o número de ligações do esquema atual. Não
+ * é o de teclas porque cem teclas não são cem lugares que uma criança encontra e lembra; não é o do esquema
+ * porque o esquema cresce, e o limite passaria a ser a configuração e não o aparelho.
+ *
+ * É `ACTIONS.length` porque o que limita um teclado, na prática deste produto, é O VOCABULÁRIO QUE A ENGINE
+ * SABE NOMEAR: um transporte que cobre todas as posições que existem não tem como ser o curto. Derivado e não
+ * escrito à mão de propósito — quando o vocabulário crescer (foi de nove para catorze em 2026-09-06), este
+ * número cresce com ele e nunca passa a mentir.
+ */
+export declare const LUGARES: Readonly<{
+    gamepad: 17;
+    toque: 9;
+    teclado: 14;
+}>;
+/** Como se descobre que cada transporte está aqui AGORA. Injetado: nenhuma destas perguntas é pura. */
+export interface Disponibilidade {
+    gamepad: () => boolean;
+    toque: () => boolean;
+    teclado: () => boolean;
+}
+/**
+ * Os três transportes que esta engine sabe oferecer hoje.
+ *
+ * ⚠️ A DETECÇÃO DO TECLADO É IMPRECISA E ISSO É ACEITÁVEL — mas só porque a tela que consome isto INFORMA em
+ * vez de RECUSAR. Não há API que diga «há um teclado físico ligado»; o que o projeto já usa para a mesma
+ * pergunta é `pointer:coarse && hover:none` (o `isCoarsePointer` do `game/session`), e um tablet COM teclado
+ * responde «toque» a isso. Se a tela barrasse, esse tablet levaria uma recusa falsa num jogo que ele joga.
+ * Como ela apenas diz o que falta e deixa continuar, o erro custa uma frase a mais e nunca uma porta fechada.
+ */
+export declare function transportesPadrao(d: Disponibilidade): Transport[];
+/** Um transporte, como ele se declara. Zero significado: quantos lugares, e se está aqui agora. */
+export interface Transport {
+    /** Identificador estável, para preferências salvas. Nunca chega a uma pessoa. */
+    readonly id: string;
+    /** Quantos lugares ATRIBUÍVEIS. É o número que a aritmética da garantia usa. */
+    readonly slots: number;
+    /**
+     * Está disponível NESTE aparelho, AGORA? Função e não valor: um controle é ligado no meio da partida, e
+     * uma tela de toque aparece quando a criança gira o tablet.
+     */
+    readonly available: () => boolean;
+}
+/** Este transporte carrega este conjunto de ações? Aritmética, como o ADR-0079 §3 a descreve. */
+export declare function carries(t: Transport, acoes: readonly Action[]): boolean;
+/**
+ * Os transportes DISPONÍVEIS que carregam este conjunto.
+ *
+ * ⚠️ Disponibilidade e capacidade são conferidas nesta ordem de propósito: um transporte que caberia mas não
+ * está ligado não é resposta para uma criança que está à frente do aparelho agora.
+ */
+export declare function carriedBy(lista: readonly Transport[], acoes: readonly Action[]): Transport[];
+/**
+ * A garantia do ADR-0079 §3, como pergunta de sim ou não.
+ *
+ * ⚠️ CONJUNTO VAZIO DE AÇÕES DEVOLVE `false`, e não `true` por vacuidade. Um jogo que não declara ação
+ * nenhuma não é um jogo que qualquer transporte serve — é um jogo que ninguém consegue jogar, e
+ * `actionSetProblems` já o reprova. Devolver `true` aqui esconderia esse defeito atrás desta função.
+ */
+export declare function reachable(lista: readonly Transport[], acoes: readonly Action[]): boolean;
+/** O que a tela de seleção precisa dizer, e o que ela precisa saber para o dizer. */
+export interface Alcance {
+    /** Verdadeiro = pelo menos um transporte disponível carrega o conjunto. */
+    readonly ok: boolean;
+    /** Quantas ações o jogo pede. */
+    readonly pedidas: number;
+    /** Os que serviriam se estivessem ligados — a informação acionável: «ligue um controle». */
+    readonly serviriamSeLigados: readonly string[];
+    /** Os disponíveis que NÃO cabem, com quantos lugares têm. Para a frase dizer o número. */
+    readonly curtos: readonly {
+        readonly id: string;
+        readonly slots: number;
+    }[];
+}
+/**
+ * Mede o alcance ANTES de a criança começar.
+ *
+ * ⚠️ Devolve DADO e não texto. A frase é da interface e tem de passar por `t()`; devolver português daqui
+ * repetiria o defeito que o `PADWIZ_STEPS` acabou de deixar de cometer.
+ */
+export declare function alcance(lista: readonly Transport[], acoes: readonly Action[]): Alcance;