@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/input/touch.js

@@ -1,46 +1,49 @@
 // 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/
+// its config UI (#touchcfg, #touch-controls visibility). Extracted from the monolith'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.
+// territory, not this module's.
 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).
+import { migrateTouchMap } from './vocabulary-migration.js';
+import { KEYS } from '../platform/storage-keys.js'; // the names only — reading and writing go through ctx.store (ADR-0232)
+// ===================== PURE (no DOM/store — node project) =====================
+// Physical target anchored on a full-screen iPhone 16 (the long edge of the 1179×2556 @460ppi display is 141.1 mm →
+// ~6.04 CSS px/mm) — see `padPxPerMm` for what this estimate is and is not (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 const IPHONE16_PXMM = IPHONE16_LONG_PX / IPHONE16_LONG_MM; // ~6.04 CSS px/mm
+/**
+ * CSS px per ASSUMED millimetre — an estimate anchored on one phone, NOT a measurement of the device (plan phase 5b).
+ * On a mobile, the window's long edge is taken to be an iPhone 16's display (141.1 mm), whatever the device: a 10-inch
+ * tablet window of 1280×800 is read as 141.1 mm long, about 9.07 px/mm, where its glass is about 216 mm. On a desktop it is
+ * the iPhone 16 ratio, fixed (it does not grow with the monitor). The browser exposes no physical size, so a «real
+ * millimetre» is not reachable from here; targets that must meet a floor use the engine's `--alvo-min` (ADR-0163).
+ * Pure: `mobile`/`viewW`/`viewH` arrive resolved (isMobile()/innerWidth/innerHeight stay on the impure side).
+ */
 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). */
+/** Sorts a value in mm into the child's-hand / in-between / adult's-hand band (used by the touch settings panel's
+ *  tags). */
 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. */
+/** All the geometry in px from the configured mm + the px/mm factor — kept pure so it is testable (high/low dpr, small
+ *  screen, extreme values). applyPadPhysical() only calls this and writes the result into CSS custom properties + the
+ *  panel's labels. */
 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 diamPx = btnPx + Math.SQRT2 * (btnPx + gapPx); // diamond: edge clearance = 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
+    const basePx = knobPx + 2 * travelPx + 16; // stick base = contact + travel
+    const armPx = mm.dpad * pxPerMm, armWPx = armPx * 0.8, spanPx = 2 * armPx + armWPx; // cross: arm + width (0.8×)
+    const stickTravelPx = travelPx, stickDeadPx = Math.max(6, travelPx * 0.4); // dead zone ~40% of the travel
     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). */
+/** The button-labelling layout from the controller's reported id (a substring/VID heuristic). */
 export function padLayoutFromId(id) {
     const s = (id || '').toLowerCase();
     if (/dualshock|dualsense|playstation|054c/.test(s))
@@ -51,54 +54,50 @@ export function padLayoutFromId(id) {
         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.
+/** The 13 remappable touch slots (d-pad×4, START, buttons 0–3, the four shoulders) — `lbl` is the label's i18n key. */
+// `lbl` keeps the i18n KEY, not the text: a module table resolved on import would freeze the language at boot (see the
+// note in input/devices). The arrow and the button's name travel INSIDE the translation, because in English the
+// direction word changes and the arrow stays where it is — it is the whole frame, not interpolated content.
 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' },
+    { k: 'bl2', lbl: 'touch.slot.bl2' }, { k: 'bl1', lbl: 'touch.slot.bl1' },
+    { k: 'br2', lbl: 'touch.slot.br2' }, { k: 'br1', lbl: 'touch.slot.br1' },
 ];
 /**
- * As ações que o TRANSPORTE de toque consegue carregar.
+ * The actions the touch TRANSPORT can carry.
  *
- * ⚠️ 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.
+ * ⚠️ IT IS NOT THE `<select>`'S LIST: the options come from `ctx.gameActions()`, because the game decides which actions
+ * exist. This list is what THIS transport reaches — and it is against it that `input/touch-bindings`' gate checks the
+ * dispatch recognises everything that can be offered. The two were the same by accident while there was one game.
  */
-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 const TOUCH_ACTS = ['left', 'right', 'up', 'down', 'action2', 'action1', 'action3', 'action4', 'start',
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger'];
+/** Merges the persisted map (loose JSON from localStorage) over TOUCH_DEFAULT. It does NOT validate keys/values
+ *  against TOUCH_SLOTS/TOUCH_ACTS — malformed JSON with strange keys/values passes as it is (it only fails if it is not
+ *  an object). */
 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;
+    // ⚠️ WHAT IS STORED GOES THROUGH THE TRANSLATOR BEFORE THE MERGE, and the order is what matters: `Object.assign`
+    // lets the stored map WIN over the default, so a `b0: 'jump'` from before ADR-0086 would overwrite the correct
+    // `b0: 'action2'` and the on-screen button would stop doing anything — with no error at all. Here the action name
+    // is in the VALUE, not the key, which is why it needs its own translator. See `input/vocabulary-migration.ts`.
+    const migrated = migrateTouchMap(stored && typeof stored === 'object' ? stored : null);
+    return Object.assign({}, TOUCH_DEFAULT, migrated || {});
 }
+/** The five size sliders a page's touch panel may carry, each writing its own measure (mm). */
+const PAD_SLIDERS = [
+    ['#pad-size', 'btn'], ['#pad-gap', 'gap'], ['#pad-stick', 'stick'], ['#pad-travel', 'travel'], ['#pad-dpad', 'dpad'],
+];
+/** The two presets: every size at once, and the sentence that says so — a child who cannot see five sliders move hears it. */
+const PAD_PRESETS = [
+    ['#pad-preset-child', { btn: 12, gap: 2.5, stick: 16.5, travel: 4, dpad: 11.5 }, 'sr.touch.presetChild'],
+    ['#pad-preset-adult', { btn: 14, gap: 4.5, stick: 20, travel: 5.5, dpad: 14 }, 'sr.touch.presetAdult'],
+];
 export function initTouch(ctx) {
+    const { t } = 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);
@@ -106,24 +105,24 @@ export function initTouch(ctx) {
     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
+    let _stickTravelPx = 42, _stickDeadPx = 12; // boot values; applyPadPhysical() sets the real ones
     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('') +
+            // ⚠️ THE OPTION IS BORN EMPTY and the `label` goes in just below through `textContent` (issue #106). It is the
+            // game's WORD — `gameActions()` comes from the preset —, and a game lives in another repository (ADR-0083), so
+            // this text is not reviewed by this tree. `value="${slotAction}"` stays: `slotAction` is the ABSTRACT name, and
+            // the engine enumerates it in `core/actions`; it is the engine's and not the game's.
+            ctx.gameActions().map(({ action: slotAction }) => `<option value="${slotAction}"${touchMap[s.k] === slotAction ? ' selected' : ''}></option>`).join('') +
             `</select></div>`).join('');
-        // As palavras do jogo, por `textContent` — que escapa por construção. A ordem casa porque é a mesma lista.
+        // The game's words, through `textContent` — which escapes by construction. The order matches because it is the same list.
         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;
+            const words = ctx.gameActions();
+            for (let i = 0; i < sel.options.length && i < words.length; i++) {
+                sel.options[i].textContent = words[i].label;
             }
         }
         el.querySelectorAll('select[data-slot]').forEach((sel) => {
@@ -132,18 +131,18 @@ export function initTouch(ctx) {
                 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);
-                const nomeDoSlot = label || t('touch.slot.fallback');
-                // ⚠️ SEM PALAVRA DO JOGO, O ANÚNCIO PERDE A POSIÇÃO — NÃO RECUA PARA O ID. `sel.value` é o nome
-                // ABSTRATO (`action3`), e o ADR-0074 diz que ele nunca chega a uma pessoa; o `7742ac0` já pagou este
-                // defeito no ecrã de remapeamento e a saída é a mesma: uma chave própria que diz o que importa.
-                // 📌 O recuo é alcançável porque `acoesDoJogo()` é FUNÇÃO do cartucho, relida a cada `change`: num hub
-                // de atividades a lista muda por baixo e a `<option>` desenhada antes fica órfã.
-                ctx.srSay(escolhida
-                    ? t('sr.touch.slotSet', { slot: nomeDoSlot, acao: escolhida.rotulo })
-                    : t('sr.touch.slotSetUnnamed', { slot: nomeDoSlot }));
+                // ⚠️ The spoken word is the SAME as the one read: it comes from the list that just built the `<option>`, so
+                // nothing has to make two tables agree.
+                const chosen = ctx.gameActions().find((x) => x.action === sel.value);
+                const slotName = label || t('touch.slot.fallback');
+                // ⚠️ WITHOUT THE GAME'S WORD, THE ANNOUNCEMENT DROPS THE POSITION — IT DOES NOT FALL BACK TO THE ID. `sel.value`
+                // is the ABSTRACT name (`action3`), and ADR-0074 says it never reaches a person; `7742ac0` already paid for
+                // this defect on the remapping screen and the way out is the same: a key of its own that says what matters.
+                // 📌 The fallback is reachable because `gameActions()` is a FUNCTION of the cartridge, reread on every
+                // `change`: in an activity hub the list changes underneath and the `<option>` drawn before is orphaned.
+                ctx.srSay(chosen
+                    ? t('sr.touch.slotSet', { slot: slotName, acao: chosen.label })
+                    : t('sr.touch.slotSetUnnamed', { slot: slotName }));
             });
         });
     }
@@ -172,17 +171,16 @@ export function initTouch(ctx) {
         if (tc && !tc.hidden)
             tc.hidden = true;
         ctx.$('body')?.classList.remove('touch-mode');
-        setMinimapCorner(false);
+        ctx.onTouchControlsHidden?.();
     }
     function showTouchControls() {
-        // MENU ativo = sem controle virtual: dá pra tocar direto nos botões da tela. QUEM decide é o jogo.
+        // A MENU up = no virtual pad: the child touches the on-screen buttons directly. The GAME decides.
         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() {
@@ -267,47 +265,37 @@ export function initTouch(ctx) {
         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') }));
-        });
+    /**
+     * The touch panel's controls, where a PAGE carries them (the engine's own panels do not): open and close, the direction, the
+     * five sizes and the two presets. The selector is not set here — the boot's `applyDirStyle` sets it to the stored direction.
+     */
+    function wirePanel() {
+        ctx.$('#opt-touchcfg')?.addEventListener('click', openTouchCfg);
+        ctx.$('#touchcfg-close')?.addEventListener('click', closeTouchCfg);
+        const padDirSel = ctx.$('#pad-dir');
+        if (padDirSel) {
+            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') }));
+            });
+        }
+        for (const [id, field] of PAD_SLIDERS) {
+            const slider = ctx.$(id);
+            if (!slider)
+                continue;
+            slider.addEventListener('input', () => { const patch = {}; patch[field] = parseFloat(slider.value); setPadMm(patch); });
+        }
+        for (const [id, mm, said] of PAD_PRESETS) {
+            ctx.$(id)?.addEventListener('click', () => { setPadMm(mm); ctx.srSay(t(said)); });
+        }
     }
-    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)
+    wirePanel();
+    // Recomputes the px on rotate/resize; the mm are fixed.
+    // ⚠️ THE WINDOW COMES THROUGH THE `ctx` (see `TouchCtx.win`). Without a window there is nothing to listen to.
+    ctx.win?.addEventListener('resize', applyPadPhysical);
+    // initial state: the stored design, geometry and direction applied once at boot
     applyPadDesign();
     applyPadPhysical();
     applyDirStyle();
@@ -320,3 +308,213 @@ export function initTouch(ctx) {
         getStickDeadPx: () => _stickDeadPx,
     };
 }
+/**
+ * A BUTTON'S NAME, from the position it fires (ADR-0165): the same in every game — 1 to 4, L1/L2/R1/R2, SELECT, START,
+ * and the four directions by their spoken name. The cartridge's word is the FUNCTION, and it never reaches the face.
+ */
+const SLOT_NAME = {
+    action1: '1', action2: '2', action3: '3', action4: '4',
+    leftShoulder: 'L1', leftTrigger: 'L2', rightShoulder: 'R1', rightTrigger: 'R2',
+    select: 'SELECT', start: 'START',
+};
+function buttonName(t, slotAction) {
+    if (SLOT_NAME[slotAction])
+        return SLOT_NAME[slotAction];
+    return slotAction === 'up' || slotAction === 'down' || slotAction === 'left' || slotAction === 'right' ? t(`touch.nome.${slotAction}`) : null;
+}
+/** The four direction slots, in the order the cross draws them. */
+const DIRECTIONS = ['up', 'left', 'right', 'down'];
+/** The four action-button slots, in the diamond's order. */
+const BUTTONS = ['b0', 'b1', 'b2', 'b3'];
+/** The SHOULDERS per corner, top to bottom (ADR-0160): the trigger (2) over the shoulder (1). */
+const SHOULDERS = [['esq', ['bl2', 'bl1']], ['dir', ['br2', 'br1']]];
+/**
+ * Builds (or reuses) `#touch-controls` and returns it.
+ *
+ * ⚠️ IT IS BORN HIDDEN, and that is not a detail: switching by modality belongs to `touch-bindings` — a touch or click
+ * SHOWS it, the keyboard or a pad HIDES it. A pad born on screen covers the game of whoever will never touch it.
+ *
+ * 🔴 ONLY WHAT THE GAME NAMES, since ADR-0162 — which undid ADR-0157's minimum (directions and four buttons in every
+ * game, with the physical legend on the unnamed ones): «Vale para todos os botões: somente aparecem se o jogo os
+ * nomeia.» SELECT and START always stay, because they are the pause's doors. ⚠️ A game that names no direction does not
+ * move through menus by touch; that is why `consumer-quiz` declares the positions it uses. The four buttons sit in a 2×2
+ * block by the action's NUMBER (ADR-0160): 1 and 4 on top, 2 and 3 below.
+ *
+ * Idempotent: mounting twice returns the same node, its content rebuilt for the map of now.
+ */
+export function mountTouchControls(ctx, spec) {
+    const { t } = ctx;
+    const touchControls = ctx.find('#touch-controls') ?? ctx.create('div');
+    touchControls.id = 'touch-controls';
+    touchControls.className = 'touch';
+    touchControls.hidden = true;
+    while (touchControls.firstChild)
+        touchControls.removeChild(touchControls.firstChild);
+    const f = padFacesOf(t, spec);
+    // in the order they sit on the screen; a part the game names nothing for is an empty list, never an empty box
+    const parts = [...directionPad(ctx, spec, f), ...actionButtons(ctx, spec, f), ...shoulderCorners(ctx, f), systemPills(ctx, f)];
+    for (const part of parts)
+        touchControls.appendChild(part);
+    return touchControls;
+}
+function padFacesOf(t, spec) {
+    // 🔴 ONLY WHAT THE GAME NAMES (ADR-0162, superseding ADR-0157's minimum): «Vale para todos os botões: somente
+    // aparecem se o jogo os nomeia.» A button on screen is a promise that it does something, and the game is who knows.
+    const named = (slot) => spec.gameActions.has(spec.map[slot] ?? '');
+    // ADR-0165: the face is the NAME of the position the slot fires; the accessible name is «name, function».
+    const nameOf = (slot) => buttonName(t, spec.map[slot] ?? slot) ?? spec.slotLabel(slot);
+    const accessible = (slot) => {
+        const name = nameOf(slot);
+        const purpose = spec.slotLabel(slot);
+        return purpose && purpose !== name ? `${name}, ${purpose}` : name;
+    };
+    return { named, nameOf, accessible };
+}
+/** The directional, where the game names a direction: the analog stick with its knob, or the cross with its arms. */
+function directionPad(ctx, spec, f) {
+    const live = DIRECTIONS.filter(f.named);
+    if (!live.length)
+        return [];
+    const kind = spec.dpad === 'analogico' ? 'touch-stick' : 'touch-cross';
+    const dir = ctx.create('div');
+    dir.id = kind;
+    dir.className = kind; // the id is what `touch-bindings` finds; the class is what the stylesheet DRAWS
+    if (kind === 'touch-stick') {
+        // `touch-bindings` requires the `.touch-knob` inside the base (`if (stick && knob)`), and without it gives up on the
+        // whole stick — silently.
+        const knob = ctx.create('div');
+        knob.className = 'touch-knob';
+        dir.appendChild(knob);
+        return [dir];
+    }
+    for (const d of live) {
+        const arm = ctx.create('button');
+        // ⚠️ THE THREE CLASSES, and each has a reader. `touch-arm` is this module's; `dpad-arm` is the one the stylesheet
+        // DRAWS; `dpad-<dir>` is the one `touch-bindings` LIGHTS on touch (`.dpad-up` & co.). With only the first, the arm
+        // is an unstyled button that never lights, and no case sees it unless both are mounted together.
+        arm.className = `touch-arm dpad-arm dpad-${d}`;
+        arm.setAttribute('type', 'button');
+        arm.setAttribute('aria-label', f.accessible(d));
+        dir.appendChild(arm);
+    }
+    return [dir];
+}
+/**
+ * One button the dispatch can read back: `data-btn` is the slot without its `b` (`b2` -> `2`, `bl1` -> `l1`), which is
+ * what `'b' + dataset.btn` in `touch-bindings` recomposes. Writing the ACTION here would be a second source for the same
+ * answer, and the child's remapping would stop counting.
+ */
+function padButton(ctx, f, slot, className) {
+    const button = ctx.create('button');
+    button.className = className;
+    button.dataset.btn = slot.slice(1);
+    button.setAttribute('type', 'button');
+    button.setAttribute('aria-label', f.accessible(slot));
+    button.textContent = f.nameOf(slot);
+    return button;
+}
+/** The four action buttons, where the game names them, in a 2×2 block by the action's NUMBER (ADR-0160). */
+function actionButtons(ctx, spec, f) {
+    const live = BUTTONS.filter(f.named);
+    if (!live.length)
+        return [];
+    const rhombus = ctx.create('div');
+    rhombus.className = 'touch-pad';
+    for (const b of live) {
+        const button = padButton(ctx, f, b, 'touch-btn');
+        // THE PLACE FOLLOWS THE ACTION, not the slot (ADR-0160: 1 4 on top, 2 3 below): the stylesheet puts each button in
+        // its number's cell, and a remapped slot takes the button to the place of the action it now fires.
+        button.dataset.acao = spec.map[b] ?? '';
+        rhombus.appendChild(button);
+    }
+    return [rhombus];
+}
+/** THE SHOULDERS, each pair in its top corner (ADR-0160), and only those the game names (ADR-0162) — no empty corner. */
+function shoulderCorners(ctx, f) {
+    return SHOULDERS.flatMap(([side, slots]) => {
+        const named = slots.filter(f.named);
+        if (!named.length)
+            return [];
+        const corner = ctx.create('div');
+        corner.className = `touch-ombros touch-ombros--${side}`;
+        for (const s of named)
+            corner.appendChild(padButton(ctx, f, s, 'touch-btn touch-ombro'));
+        return [corner];
+    });
+}
+/*
+ * THE TWO SYSTEM PILLS, side by side in the centre: SELECT (the menus) and START (the quick pause), in a console pad's
+ * order. ⚠️ BOTH UNCONDITIONAL, for the same reason: since ADR-0155 they are the pause's two doors, and the pause cannot
+ * be declined (ADR-0122) — a tablet without a keyboard has no other way to reach "Quit".
+ */
+function systemPills(ctx, f) {
+    const system = ctx.create('div');
+    system.className = 'touch-sistema';
+    for (const slot of ['select', 'start']) {
+        const b = ctx.create('button');
+        b.id = `touch-${slot}`;
+        b.className = `touch-btn touch-${slot}`;
+        b.setAttribute('type', 'button');
+        b.setAttribute('aria-label', f.accessible(slot));
+        // ⚠️ AND WRITTEN, not only spoken: a pill with no text is a button a sighted child cannot read.
+        b.textContent = f.nameOf(slot);
+        system.appendChild(b);
+    }
+    return system;
+}
+/**
+ * What this game does NOT reach by touch, said instead of kept quiet — the half of ADR-0143 §4 that is not markup.
+ *
+ * 📌 It returns LINES and does not throw: a host gap never takes the boot down, by the same rule the rest of
+ * `problems` follows. The sentences go to the consumer that INTEGRATES the engine, not to a child.
+ */
+export function touchGaps(spec) {
+    // ⚠️ WITHOUT `preset` THE PAD HAS ONLY SELECT AND START (ADR-0162): no direction, no button — not even to move
+    // through menus. It is the integrator's gap, and it is said.
+    if (!spec.gameActions.size) {
+        return ['the virtual pad shows only SELECT and START — no direction and no button: a child on a tablet without a '
+                + 'keyboard cannot play — declare `preset` with the positions this game uses and a word for each'];
+    }
+    // ⚠️ AND THE PARTIAL GAP IS SAID TOO. A game may declare an action no slot fires: it exists on the keyboard and not on
+    // touch, and without this line that would show up nowhere.
+    const reached = new Set(TOUCH_SLOTS.map((s) => spec.map[s.k]).filter(Boolean));
+    const outsideTouch = [...spec.gameActions].filter((a) => !reached.has(a));
+    if (!outsideTouch.length)
+        return [];
+    return [`the virtual pad does not reach ${outsideTouch.join(', ')}: no slot fires them, so a child playing by touch `
+            + 'does not have them — remap a slot in the pad panel, or declare fewer actions'];
+}
+/** The factory pad of `input/touch`, the base the non-button sizes are proportioned from. */
+const FACTORY = { btn: 12.5, gap: 3, stick: 18, travel: 4.5, dpad: 12 };
+/** A persona's pad: the button from the sources, the rest in proportion to the factory pad. */
+function pad(btn) {
+    const k = btn / FACTORY.btn;
+    const r = (n) => Math.round(n * k * 10) / 10;
+    return { btn, gap: r(FACTORY.gap), stick: r(FACTORY.stick), travel: r(FACTORY.travel), dpad: r(FACTORY.dpad) };
+}
+/** The four, in the Dev's order. */
+export const PERSONAS_DO_PAD = Object.freeze([
+    // 16 mm: an adult's 9.6 mm plus twice the extra spread of a 3-year-old (≈ 2.4 mm each side), rounded up.
+    { key: 'crianca-pequena', label: 'motora.pad.crianca-pequena', mm: pad(16) },
+    // 14 mm: 9 mm is still missed once in six until 17 (Anthony), and 12.7 mm was the size that did not trouble them.
+    { key: 'crianca-grande', label: 'motora.pad.crianca-grande', mm: pad(14) },
+    // 11.5 mm: where adult performance levels off (Parhi) — above it there is no gain, only lost room.
+    { key: 'adulto-pequeno', label: 'motora.pad.adulto-pequeno', mm: pad(11.5) },
+    // 15 mm: a 16–20 mm finger covers anything smaller and hides the label under the thumb (MIT Touch Lab).
+    { key: 'adulto-maos-grandes', label: 'motora.pad.adulto-maos-grandes', mm: pad(15) },
+]);
+/**
+ * The persona whose button is closest to `btnMm` — what the step control shows for a pad that was sized before
+ * the personas existed (the factory 12.5 mm reads as «small adult»). Ties go to the LARGER button: when in doubt,
+ * the easier target.
+ */
+export function closestPersona(btnMm) {
+    let best = 0;
+    PERSONAS_DO_PAD.forEach((p, i) => {
+        const d = Math.abs(p.mm.btn - btnMm);
+        const dm = Math.abs(PERSONAS_DO_PAD[best].mm.btn - btnMm);
+        if (d < dm || (d === dm && p.mm.btn > PERSONAS_DO_PAD[best].mm.btn))
+            best = i;
+    });
+    return best;
+}