@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 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;
@@ -11,75 +10,104 @@ export interface TouchStore {
     setJSON(key: string, obj: unknown): void;
 }
 export interface TouchCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
     /** 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.
+     * THE POSITIONS THIS GAME USES, each with its own word, in the current language.
      *
-     * ⚠️ 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.
+     * ⚠️ The slot menu offers these and not a fixed list: with a fixed list the engine would be deciding that every
+     * game has jump, run, swap and special, and a child in a quiz could assign a button a power swap that then does
+     * nothing.
      *
-     * 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.
+     * The order comes from here too: it is `core/actions`' canonical order, the same the remapping screen uses, so the
+     * child does not have to relearn the list when switching panels.
      */
-    acoesDoJogo: () => readonly {
-        readonly acao: string;
-        readonly rotulo: string;
+    gameActions: () => readonly {
+        readonly action: string;
+        readonly label: 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. */
+    /** Shared device-class check (the host's, 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. */
+    /** Shared overlay z-index/focus helper, 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. */
+    /** Optional hook fired after applyPadDesign() changes padDesign — whatever draws the button glyphs elsewhere (a
+     *  pause legend, say) is NOT part of this module's boundary but must still refresh. */
     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.
+     * The on-screen control CAME ON. It exists so the root can turn on by itself what only makes sense on touch — the
+     * run button's latch, say: on a virtual button nobody "holds" comfortably, because the finger that holds is the
+     * same one that has to reach the others.
      *
-     * 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.
+     * A hook and not a rule in here: this module draws controls and knows no accessibility setting at all. Whoever owns
+     * the players knows what to turn on.
      */
     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.
+     * The on-screen controls LEFT the screen — the pair of `onTouchControlsShown`. A root that moves something out of the
+     * pad's way (the platformer's minimap corner) moves it back here; `input/` does not reach `render/` for it (issue #167).
+     */
+    onTouchControlsHidden?: () => void;
+    /**
+     * MAY the virtual pad show NOW? Injected, and it is the GAME's policy, not the engine's.
      *
-     * É 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.
+     * Reading the player count, the phase and whether a player has a quiz open here would write one game's policy
+     * into the engine — and make the touch layer know that a literacy activity exists. So it is the same move as
+     * `isNavigable`: inject the BOOLEAN, not the state. The platformer answers "one player, playing, no challenge
+     * open"; a game of another genre answers whatever is true in it.
      */
     padAllowed: () => boolean;
+    /**
+     * The window, only to listen for `resize` — the root's (ADR-0232 D4). REQUIRED, and `null` is an answer: a host with no
+     * window at all does not listen, and the geometry stays as at boot. A fallback to the global would reach a window the
+     * root never handed in, which is what took down every boot in a fake document once this was wired to `createGame`.
+     */
+    win: Pick<Window, 'addEventListener'> | null;
+    /**
+     * Draws ONE slot's choice by its size (ADR-0130 rule 3): five named positions or fewer are a cycle row, more a dropdown.
+     * Injected because the drawing lives in `ui/panel-widgets.mountChoice` and this module is a layer below it (ADR-0173);
+     * `createGame` hands it in. ABSENT, each slot stays a hand-built `<select>`, whatever its size — a host that builds its
+     * own touch panel keeps the control it always had.
+     */
+    drawChoice?: (spec: TouchSlotChoice, pick: (action: string) => void) => HTMLElement;
+}
+/** What a slot's choice is drawn from: the slot's name, the game's positions in its words, and the one it carries now. */
+export interface TouchSlotChoice {
+    readonly label: string;
+    readonly values: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly current: string;
 }
 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). */
+/**
+ * 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 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). */
+/** 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 declare function padHandTag(v: number, lo: number, hi: number): HandTag;
 export interface PadMm {
     btn: number;
@@ -99,37 +127,30 @@ export interface PadPhysicalPx {
     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. */
+/** 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 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). */
+/** The button-labelling layout from the controller's reported id (a substring/VID heuristic). */
 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. */
+/** The 13 remappable touch slots (d-pad×4, START, buttons 0–3, the four shoulders) — `lbl` is the label's i18n key. */
 export declare const TOUCH_SLOTS: ReadonlyArray<{
     k: string;
     lbl: string;
 }>;
 /**
- * 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 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. */
+/** 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 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;
@@ -138,36 +159,90 @@ export interface PadMmPatch {
     dpad?: number;
 }
 export interface TouchApi {
-    /** (Re)desenha #touchmap-list a partir do touchMap atual e prende os <select> de cada slot. */
+    /** (Re)draws #touchmap-list from the current touchMap and wires each slot's <select>. */
     renderTouchMap(): void;
-    /** Abre o diálogo "Botões de tela touch" (#touchcfg). */
+    /** Opens the on-screen buttons dialog (#touchcfg). */
     openTouchCfg(): void;
-    /** Fecha o diálogo #touchcfg e devolve o foco ao botão que o abriu. */
+    /** Closes the #touchcfg dialog and gives focus back to the button that opened it. */
     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. */
+    /** Hides the touch controls (the keyboard or a physical pad took over, or a menu opened on top). The `reason`
+     *  parameter is only a debugging label at call sites; the function ignores it and keeps it so existing calls do not
+     *  break. */
     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. */
+    /** Shows the touch controls (a touch/click was detected). A no-op whenever the game's `padAllowed()` says no — on
+     *  those screens the child touches the on-screen buttons directly. */
     showTouchControls(): void;
-    /** Alterna a visibilidade do analógico virtual vs. da cruz (D-pad), conforme `padDir`. */
+    /** Switches between the virtual stick and the cross (D-pad), following `padDir`. */
     applyDirStyle(): void;
-    /** Recalcula toda a geometria (mm→px) e escreve as custom properties + os rótulos do painel. */
+    /** Recomputes all the geometry (mm→px) and writes the custom properties + the panel's labels. */
     applyPadPhysical(): void;
-    /** Atualiza um ou mais tamanhos (mm), persiste e reaplica a geometria. */
+    /** Updates one or more sizes (mm), persists them and reapplies the geometry. */
     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. */
+    /** Applies (and optionally switches) the button design; persists it; repaints the touch diamond's buttons
+     *  (#pad-diamond); fires ctx.onPadDesignApplied(). Returns the resulting design. */
     applyPadDesign(d?: string): string;
-    /** Design de botão atualmente ativo ('generic'|'microsoft'|'sony'|'nintendo'). */
+    /** The button design currently active ('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. */
+    /** A live reference to the current touch map (slot → action) — mutated by renderTouchMap(); NOT a copy. */
     getTouchMap(): Record<string, string>;
-    /** Deslocamento útil do analógico virtual em px, recalculado a cada applyPadPhysical(). */
+    /** The virtual stick's useful travel in px, recomputed on every applyPadPhysical(). */
     getStickTravelPx(): number;
-    /** Zona-morta do analógico virtual em px, recalculada a cada applyPadPhysical(). */
+    /** The virtual stick's dead zone in px, recomputed on every applyPadPhysical(). */
     getStickDeadPx(): number;
 }
 export declare function initTouch(ctx: TouchCtx): TouchApi;
+/** The three `document` things the pad's markup needs. Same shape as `ui/panel-shell`. */
+export interface TouchMarkupCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    find: (sel: string) => HTMLElement | null;
+    create: (tag: string) => HTMLElement;
+}
+export interface TouchMarkupSpec {
+    /** The LIVE slot→action map (`TOUCH_DEFAULT` merged with what the child remapped). */
+    readonly map: Readonly<Record<string, string>>;
+    /** The actions THIS game declares (`presetActions(preset)`). Empty = nothing to draw. */
+    readonly gameActions: ReadonlySet<string>;
+    /** Each slot's label, already translated — the GAME's word for the action it fires. */
+    readonly slotLabel: (slot: string) => string;
+    /** The d-pad's drawing: `cruz` (cross) or `analogico` (stick). It comes from the pad's persisted setting (`padDir`). */
+    readonly dpad?: 'cruz' | 'analogico';
+}
+export declare function buttonName(t: Translate, slotAction: string): string | null;
+/**
+ * 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 declare function mountTouchControls(ctx: TouchMarkupCtx, spec: TouchMarkupSpec): HTMLElement;
+/**
+ * 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 declare function touchGaps(spec: Pick<TouchMarkupSpec, 'map' | 'gameActions'>): string[];
+export type PersonaKey = 'crianca-pequena' | 'crianca-grande' | 'adulto-pequeno' | 'adulto-maos-grandes';
+export interface PersonaDoPad {
+    readonly key: PersonaKey;
+    /** The i18n key of the persona's name. */
+    readonly label: string;
+    readonly mm: Readonly<PadMm>;
+}
+/** The four, in the Dev's order. */
+export declare const PERSONAS_DO_PAD: readonly PersonaDoPad[];
+/**
+ * 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 declare function closestPersona(btnMm: number): number;