@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/synthetic-source.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/synthetic-source.ts — WHO DISPATCHED THIS KEY, when it was not a finger on a keyboard (ADR-0109).
+//
+// ========================= THE HARD PART OF THE EDGE, AND IT WAS NAMED =========================
+// The gate `tests/the-keys-source-survives-the-door` has named it since the funnel began: a synthetic `KeyboardEvent`
+// enters through `keydown` and would be stamped as the keyboard — the erasure coming back through the front door. Today
+// the engine's only synthetic key is the menu key the pad and the virtual controller hand to the menus.
+//
+// `isTrusted` tells PRESSED from DISPATCHED — the one property a script cannot forge — but not WHICH assisted transport
+// dispatched it. That has to arrive DECLARED, and that is what this module is.
+//
+// ⚠️ WHY THE STAMP TRAVELS ON THE EVENT, and not in an injected "what is the synthetic source now?". The injected answer
+// is GLOBAL state, and input is not global: a child playing by gaze with an adult pressing a key beside them produces both
+// edges at the same instant, and global state would stamp both as gaze. The event cannot be confused with itself — the
+// origin travels with the edge it belongs to, the same reason the key source is a map by CODE and not a single field.
+//
+// 📌 And it is additive by construction: an unstamped event still works. That is what let the writers migrate one at a
+// time without a single red commit in between.
+import { isTransportName } from './transport-in-use.js';
+/**
+ * The property hung on the event.
+ *
+ * 📌 Prefixed and ugly on purpose: it is an expando on an object that is not ours, and a short name could collide with
+ * another library's without anything saying so.
+ */
+export const SOURCE_KEY = '__vpOrigem';
+/**
+ * DECLARES that this event came from that device. Returns the event itself, so the dispatch fits on one line.
+ *
+ * ⚠️ Stamp it BEFORE dispatching. After `dispatchEvent` the listeners have already run, and the stamp would reach an
+ * event nobody reads any more.
+ */
+export function stampSource(ev, source) {
+    ev[SOURCE_KEY] = source;
+    return ev;
+}
+/**
+ * WHO PRODUCED THIS EVENT? `undefined` when it is not known.
+ *
+ * The whole rule, in three lines and in this order:
+ *
+ *   1. **A valid stamp wins.** An explicit declaration always beats an inference — inverting it would make a REAL event
+ *      someone remapped (a pedal, a sip-and-puff switch that emits real keys) read as the keyboard, erasing exactly the
+ *      information whoever stamped it took the trouble to put there.
+ *   2. **No stamp but trusted → `'teclado'`.** That is what `isTrusted` means: the browser saw the person press. It is the
+ *      one inference this module makes, and it makes it on the property that cannot be forged.
+ *   3. **No stamp and not trusted → `undefined`.** A synthetic event nobody signed. Nothing in this engine produces one;
+ *      code from outside does, and code from outside did not declare. ⚠️ Returning the keyboard here would be the erasure
+ *      coming back another way, the defect the whole of ADR-0109 exists to close — and worse than the original, because
+ *      it would have the shape of an answer.
+ */
+export function sourceOfEvent(ev) {
+    const declared = ev[SOURCE_KEY];
+    if (isTransportName(declared))
+        return declared;
+    return ev.isTrusted ? 'teclado' : undefined;
+}

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

@@ -1,158 +1,147 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Transporte } from './transporte-em-uso.js';
+import type { TransportName } from './transport-in-use.js';
 import { type RectLike } from './pointer-space.js';
 import type { PlayerView } from '../core/entity.js';
 import type { DomQuery } from '../core/dom-query.js';
 import type { KeyScheme } from '../core/entity.js';
-export type { DomQuery } from '../core/dom-query.js';
-/** ação -> lista de códigos físicos. Cópia ESTRUTURAL do `KeyScheme` de `input/keyboard-runtime.ts` — a casa
- *  prefere a cópia a puxar um alias de tipo através de camadas (mesmo precedente de `input/keydown.ts`). */
-export type { KeyScheme } from '../core/entity.js';
-/** As seis bordas de entrada que o toque levanta no jogador (consumidas e zeradas pela física). */
+import { type Action } from '../core/actions.js';
+/** The six input edges touch raises on the player (consumed and cleared by the game's physics). */
 export type EdgeFlag = 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge';
-/** Uma borda a levantar: qual jogador (POSIÇÃO no array) e qual flag. */
+/** An edge to raise: which player (POSITION in the array) and which flag. */
 export interface EdgeRaise {
     playerIndex: number;
     edge: EdgeFlag;
 }
-/** O que este módulo lê (e escreve) de um jogador — e SÓ isso. DERIVADA de core/entity.
- *  `easy`: quem está no modo Fácil não levanta `runEdge`, e portanto não gruda na parede — a mesma regra do
- *  teclado e do controle, que é justamente a que divergiu em três cópias uma vez. Ver o cabeçalho. */
-export type TouchBindPlayer = PlayerView<'ctrl' | 'easy' | 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge'>;
-/** TUDO o que a decisão precisa saber do mundo, num objeto só, montado ANTES de qualquer efeito. */
+/** What this module reads (and writes) of a player — and ONLY that. DERIVED from core/entity.
+ *  `easy`: whoever is in Easy mode raises no `runEdge`, and so does not cling to the wall — the same rule as the
+ *  keyboard and the pad, which is exactly the one that once drifted across three copies. See the header. */
+export type TouchBindPlayer = PlayerView<'ctrl'> & Partial<PlayerView<'easy' | 'jumpEdge' | 'runEdge' | 'leftEdge' | 'rightEdge' | 'swapEdge' | 'specialEdge'>>;
+/** EVERYTHING the decision needs to know about the world, in one object, built BEFORE any effect. */
 export interface TouchBindSnapshot {
-    /** `kbRuntime.controlsState().controls` — o esquema do Jogador 1 (remapeável). É dele, e só dele, que sai a
-     *  tecla que o botão da tela injeta: o toque é sempre o J1, mesmo em multi-tela. */
+    /** Player 1's scheme (remappable). The key a screen button holds comes from it, and only it: touch is always P1,
+     *  even with several screens. */
     controls: KeyScheme;
-    /** o array vivo de jogadores: as bordas são levantadas em TODOS que tenham o código no próprio esquema. */
+    /** the live array of players: edges are raised on ALL who have the code in their own scheme. */
     players: readonly TouchBindPlayer[];
-    /** `keys` de `input/state.ts`: as teclas seguradas AGORA (teclado, toque e webcam, misturados). */
+    /** `input/state.ts`'s `keys`: the keys held NOW (every transport's, mixed). */
     heldKeys: ReadonlySet<string>;
 }
-/** Reexportado: a definicao passou a viver em `input/pointer-space`, com a conta que a usa (issue #105). */
-export type { RectLike } from './pointer-space.js';
-/** As quatro direções físicas do direcional, ligadas ou não. */
+/** The d-pad's four physical directions, on or off. */
 export interface DirSet {
     left: boolean;
     right: boolean;
     up: boolean;
     down: boolean;
 }
-/** Um evento de ponteiro, reduzido ao que este módulo lê (`PointerEvent` real é atribuível a isto). */
+/** A pointer event, reduced to what this module reads (a real `PointerEvent` is assignable to this). */
 export interface PointerLike {
     pointerId: number;
     clientX: number;
     clientY: number;
     preventDefault(): void;
 }
-/** A resposta única: o que este toque SIGNIFICA. */
+/**
+ * The single answer: what this touch MEANS.
+ *
+ * 🔴 THE CURRENCY OF THIS DECISION IS THE POSITION, NOT THE KEY (ADR-0223). Touch PRESSES the virtual controller, the
+ * single door, and the key is an effect of the press written in one place — a screen button that pretended to be the
+ * keyboard never reached a cartridge that listens to `onCommand`, because the root's window listener leaves `toque`
+ * out.
+ *
+ * ⚠️ AND A POSITION WITH NO MAPPED KEY IS NOT A `noop`. The map is the GAME's, not the keyboard's (ADR-0111), so a
+ * position the cartridge declared reaches it even if the child has no key for it.
+ */
 export type TouchDecision = 
-/** ação sem tecla mapeada, slot vazio, ou SOLTAR de `pause` — nada acontece. */
+/** an empty slot, an action that does not exist, or RELEASING `pause` — nothing happens. */
 {
     kind: 'noop';
 }
-/** `pause` é o único caso especial: não vira tecla, chama `togglePause()` direto (e só no APERTAR). */
+/** `pause` is the only special case: it is not a position, it calls `togglePause()` directly (and only on PRESS). */
  | {
     kind: 'pause';
 }
-/** apertar. `addKey=false` = a tecla JÁ estava segurada (outro dedo, ou o teclado): não re-injeta nem
- *  levanta borda de novo — é isso que faz disto uma BORDA e não um estado. `hideTips` é independente. */
+/** press. `addKey=false` = the key was ALREADY held (another finger, or the keyboard): no edge is raised again — that
+ *  is what makes this an EDGE and not a state. `hideTips` is independent. */
  | {
     kind: 'press';
-    code: string;
+    action: Action;
     addKey: boolean;
     edges: EdgeRaise[];
     hideTips: boolean;
 }
-/** soltar: some com o código do conjunto. NÃO abaixa borda nenhuma (quem zera as bordas é a física). */
+/** release. It lowers NO edge (the game's physics clears the edges). */
  | {
     kind: 'release';
-    code: string;
+    action: Action;
 };
-/**
- * Ação → borda, na MESMA ordem das outras duas cópias do projeto.
- * ⚠️ TERCEIRA CÓPIA DE UMA TABELA QUE JÁ EXISTE DUAS VEZES — `input/keydown.ts` (`EDGE_BY_ACTION`) e
- * `input/gamepad.ts` (seis `if` dentro de `pollPads`). Ver o bloco de aviso no cabeçalho: as três não
- * concordam sobre o modo Fácil, e a divergência está PRESERVADA de propósito.
- */
+/** Action → edge: the ONE table keyboard, pad and touch share (`input/edges`), re-exported under touch's old name. */
 export { EDGE_BY_ACTION as TOUCH_EDGE_BY_ACTION } from './edges.js';
-/** `?touch=1` na URL força os controles de toque a aparecerem no desktop (atalho de teste do José). */
-export declare const TOUCH_FORCE_RE: RegExp;
-/** Predicado do `?touch=1`, isolado para o teste não repetir o regex. */
+/** The `?touch=1` predicate, isolated so the test does not repeat the regex. */
 export declare function wantsForcedTouch(search: string): boolean;
 /**
- * Que TECLA este botão de tela finge apertar? A 1ª do esquema do Jogador 1 para aquela ação — 1ª, e não
- * todas, porque só uma precisa entrar em `keys` para o jogo inteiro reagir. Remapear o teclado remapeia o
- * toque junto, de graça: é a mesma tabela.
- * `null` = a ação não existe no esquema (ou o slot do mapa de toque está vazio) → o toque não faz nada.
+ * Which KEY does this screen button's position hold? The 1st in Player 1's scheme for that action — the 1st and not all,
+ * because only one has to enter `keys` for the whole game to react. Remapping the keyboard remaps touch along with it,
+ * for free: it is the same table.
+ * `null` = the action is not in the scheme (or the touch map's slot is empty) → no key, and so no edge.
  */
 export declare function codeForAction(act: string | undefined | null, controls: KeyScheme): string | null;
 /**
- * As bordas que este toque levanta, e em quem.
+ * The edges this touch raises, and on whom.
  *
- * ⚠️ SEM A GUARDA DO MODO FÁCIL — VERBATIM DO main.js, DEFEITO PRESERVADO.
- * `input/keydown.ts:edgesFor` pula `run` quando `p.easy` ("Fácil: sem correr"); `input/gamepad.ts:pollPads`
- * também (`if (edge('run') && !p.easy)`). Este caminho NÃO pula. Como `runEdge` é o gatilho de grudar/soltar
- * da parede (`game/physics.ts:177` e `:179`), e não a velocidade de corrida, o efeito prático é que no modo
- * Fácil a escalada existe pelo botão da tela e não existe pelo teclado nem pelo controle.
- * NÃO acrescente a guarda aqui sem consertar as três cópias de uma vez — ver o cabeçalho.
+ * WITH THE EASY-MODE GUARD (`edgeAllowed`, from `input/edges`), the same as the keyboard and the pad: `runEdge` is the
+ * trigger that clings to and lets go of a wall, not running speed, so without the guard a child in Easy mode could
+ * climb by the screen button and not by keyboard or pad.
  *
- * ÚNICO DESVIO DE LITERALIDADE, declarado: `p.ctrl[a] || []`. O original alcançava `p.ctrl.jump`/`.run`/
- * `.left`/`.right` DIRETO (e estouraria num esquema sem a ação), enquanto guardava `swap` e `especial` com
- * `&&` — assimetria sem intenção. Trocar um TypeError por um no-op não remove rede de conserto nenhuma; é o
- * mesmo precedente que `input/keydown.ts:edgesFor` já abriu, e está anotado lá pelo mesmo motivo.
+ * `p.ctrl[a] || []` and not a raw `p.ctrl[a]`: a scheme without the action turns a TypeError into a no-op — the same
+ * choice `input/keydown`'s `edgesFor` makes, for the same reason.
  */
 export declare function touchEdgesFor(act: string, code: string, players: readonly TouchBindPlayer[]): EdgeRaise[];
 /**
- * A DECISÃO. Gesto (ação mapeada + apertar/soltar) + mundo → o que isso significa.
- * `pause` primeiro, porque é o único que não passa pelo teclado sintético. Depois a tecla; sem tecla, nada.
+ * THE DECISION. A gesture (mapped action + press/release) + the world → what it means.
+ * `pause` first, because it is the only one that is not a position. Then the position and its key; without a key, the
+ * press still happens, with no edge.
  */
 export declare function decideTouch(act: string | undefined | null, on: boolean, s: TouchBindSnapshot): TouchDecision;
-/** Zona morta da CRUZ: ~18% do LADO a partir do centro, em cada eixo. Ver a nota de `crossDirsAt` sobre o
- *  `width` valer também para o eixo vertical — é verbatim, e é uma assimetria de verdade. */
+/** The CROSS's dead zone: ~18% of the SIDE from the centre, on each axis. See the note on `crossDirsAt` about `width`
+ *  also counting for the vertical axis — it is a real asymmetry. */
 export declare const CROSS_DEAD_FRACTION = 0.18;
 /**
- * Cruz (D-pad): onde o dedo está → quais direções ligam. Miolo neutro para não disparar por encostar no meio.
- * As quatro comparações são INDEPENDENTES: fora do miolo, uma diagonal liga DUAS direções (é o que dá o
- * comportamento de D-pad físico de 8 setores). O centro exato não liga nenhuma.
+ * Cross (D-pad): where the finger is → which directions turn on. A neutral core so brushing the middle does not fire.
+ * The four comparisons are INDEPENDENT: outside the core, a diagonal turns on TWO directions (which gives a physical
+ * 8-sector D-pad's behaviour). The exact centre turns on none.
  *
- * VERBATIM, incluindo a assimetria: a zona morta dos DOIS eixos sai de `rect.width` — a altura nunca entra na
- * conta. Numa cruz quadrada (é o que o CSS `--dpad-span` produz) dá no mesmo; numa cruz achatada, o miolo
- * vertical ficaria proporcionalmente maior ou menor que o horizontal. Anotado, não consertado.
+ * Including the asymmetry: both axes' dead zone comes from `rect.width` — the height never enters. On a square cross
+ * (what the CSS `--dpad-span` produces) it is the same; on a flattened one, the vertical core would be proportionally
+ * larger or smaller than the horizontal. Noted, not fixed.
  */
 export declare function crossDirsAt(px: number, py: number, rect: RectLike): DirSet;
 /**
- * Analógico virtual: mesma regra da cruz, mas a zona morta vem em PX de `input/touch.ts` (derivada dos mm
- * configuráveis — A12e motora), não de uma fração do elemento.
+ * Virtual stick: the cross's rule, but the dead zone comes in PX from `input/touch.ts` (derived from the configurable
+ * mm), not as a fraction of the element.
  */
 export declare function stickDirsAt(px: number, py: number, rect: RectLike, deadPx: number): DirSet;
 /**
- * Para onde a manopla do analógico anda (px, relativo ao centro da base): segue o dedo até o limite do curso
- * `travelPx` e ali PARA, mantendo o ângulo (recorte radial, não por eixo — por isso `hypot`, e não `clamp`).
- * O `|| 1` do original evita divisão por zero quando o dedo cai no centro exato.
+ * Where the stick's knob goes (px, relative to the base's centre): it follows the finger up to the `travelPx` limit
+ * and STOPS there, keeping the angle (a radial clip, not per axis — hence `hypot` and not `clamp`).
+ * The `|| 1` avoids a division by zero when the finger lands on the exact centre.
  */
 export declare function stickKnobOffset(px: number, py: number, rect: RectLike, travelPx: number): {
     x: number;
     y: number;
 };
-/** Só o que `attach()` precisa da janela. `(e: never)` é o mesmo truque de `input/keydown.ts`: o handler é
- *  convertido no ponto de registro, e o alvo real (window) satisfaz isto de sobra. */
 /**
- * A porta de ESCUTA de eventos, e ela é genérica sobre o mapa de eventos porque é isso que o `window` é.
+ * The event-LISTENING door, generic over the event map because that is what `window` is.
  *
- * ⚠️ ELA DIZIA `fn: (e: never) => void`, E ESTAVA ERRADA — de um jeito que já tinha cobrado duas vezes. Um
- * parâmetro `never` parece dizer "o ouvinte não olha o evento", mas por contravariância ele exige que o
- * ALVO aceite qualquer coisa, e o `window` real declara `ev: any`, que não é atribuível a `never`. O
- * resultado era o pior dos dois lados: um `as (e: never) => void` em CADA registro dentro da engine, e um
- * adaptador de uma linha em CADA consumidor. O `boot/create-game` escrevia esse adaptador (Achado 12) e o
- * `consumer-quiz/main-quiz` registrou por escrito que "a engine pede uma forma de `window` que o `window`
- * não tem".
+ * ⚠️ NOT `fn: (e: never) => void`: a `never` parameter looks like "the listener does not look at the event", but by
+ * contravariance it demands that the TARGET accept anything, and the real `window` declares `ev: any`, which is not
+ * assignable to `never`. That cost a cast at every registration inside the engine and a one-line adapter in every
+ * consumer.
  *
- * Genérica sobre `WindowEventMap`, o `window` a satisfaz DIRETO e cada ouvinte recebe o evento certo:
- * `'keydown'` casa com `KeyboardEvent`, `'pointerdown'` com `PointerEvent`. Sem cast e sem adaptador.
+ * Generic over `WindowEventMap`, `window` satisfies it DIRECTLY and each listener gets the right event: `'keydown'`
+ * matches `KeyboardEvent`, `'pointerdown'` matches `PointerEvent`. No cast and no adapter.
  *
- * `WindowEventMap` é global de `lib.dom`, ligado no `tsconfig` — não há import a fazer, e portanto não há
- * aresta nova de dependência.
+ * `WindowEventMap` is a `lib.dom` global, enabled in `tsconfig` — there is no import to make, and so no new dependency
+ * edge.
  */
 export interface EventTargetLike {
     addEventListener<K extends keyof WindowEventMap>(type: K, fn: (e: WindowEventMap[K]) => void, opts?: boolean | {
@@ -160,70 +149,92 @@ export interface EventTargetLike {
         passive?: boolean;
     }): void;
 }
-/** Quanto tempo o START segura a ação, quando ela é momentânea (não é `pause`). */
+/** How long START holds the action when it is momentary (not `pause`). */
 export declare const START_TAP_MS = 140;
 export interface TouchBindingsCtx {
-    /** `ui/dom.ts` `$` — injetado; o módulo nunca alcança `document`. */
+    /** `ui/dom.ts` `$` — injected; the module never reaches `document`. */
     $: DomQuery;
-    /** `window`, só para os dois ouvintes globais de "houve um dedo/ponteiro". */
+    /** `window`, only for the two global "there was a finger/pointer" listeners. */
     win: EventTargetLike;
-    /** `location.search` — lido por getter para o teste poder mentir sem mexer na URL. */
+    /** `location.search` — read by getter so the test can lie without touching the URL. */
     getSearch: () => string;
-    /** `kbRuntime.controlsState().controls` (memorizado do lado de lá) — o esquema do J1, lido a cada toque. */
+    /** Player 1's scheme (memoised on the other side), read on every touch. */
     getControls: () => KeyScheme;
-    /** o array vivo de jogadores. Getter: o main.js o repovoa a cada `restartGame`. */
+    /** the live array of players. A getter: the host may repopulate it on a restart. */
     getPlayers: () => readonly TouchBindPlayer[];
-    marcarTecla: (code: string, origem: Transporte) => void;
     /**
-     * ESTA ARESTA É DESTE JOGADOR, E VEIO DO TOQUE (ADR-0113 cláusula 4, issue #127) —
-     * `input/state.arestaDoJogador`.
+     * THE SINGLE DOOR TO THE CARTRIDGE (ADR-0223): press a POSITION. Answers whether the press reached the GAME — `false`
+     * means a menu took it.
+     *
+     * 🔴 One decision, taken once: what the controller does for touch is what it does for the eyes and the voice, as
+     * ADR-0111 decided — with a menu open the position becomes the menu's key, in play it holds the child's key AND
+     * delivers the command to the cartridge. A second copy of that decision here is how the two doors once came to
+     * disagree.
      *
-     * 🔴 OBRIGATÓRIO, e é aqui que a troca de aparelho fica VISÍVEL: o toque é o transporte que a criança usa
-     * ao lado do teclado, e sem esta linha o autómato responde `teclado` mesmo com o dedo no ecrã — logo a
-     * alternância lida seria a do teclado, no aparelho errado. 📌 O `onTouchControlsShown` do cartucho
-     * (`main.ts:1695`) é o remendo que existe hoje exactamente para compensar esta falta.
+     * 📌 NO SEAT, and the absence is the statement: this engine's multiplayer is on SEPARATE screens (pillar 7), so a
+     * device with a pad has ONE finger and ONE seat. A signature accepting a seat would offer a capability this transport
+     * does not have, and nobody could exercise it to prove it.
      */
-    arestaDoJogador: (jogador: number, origem: Transporte) => void;
-    soltarTecla: (code: string) => void;
+    press: (action: Action, source: TransportName) => boolean;
+    /** Release the POSITION. The controller lets go of the key it held and delivers the release — only for a press the game heard. */
+    release: (action: Action, source: TransportName) => void;
     /**
-     * O conjunto para LER — a decisão pura pergunta que teclas já estão seguradas.
+     * THIS EDGE IS THIS PLAYER'S, AND IT CAME FROM TOUCH (ADR-0113 clause 4, issue #127) — `input/state.playerEdge`.
      *
-     * ⚠️ `ReadonlySet` e não `Set`, e a diferença é a razão de este par existir: LER o conjunto nunca foi o
-     * problema; ESCREVER nele é que apagava a origem. O tipo passa a dizer isso, e uma escrita crua que
-     * voltasse aqui deixa de compilar em vez de passar despercebida.
+     * 🔴 REQUIRED, and it is where the device switch becomes VISIBLE: touch is the transport the child uses beside the
+     * keyboard, and without this line the automaton answers `teclado` even with the finger on the screen — so the latch
+     * read would be the keyboard's, on the wrong device. 📌 In the root the press has already recorded this edge and resolved
+     * touch's latch at the virtual controller's `pressedBy` (ADR-0109 rule 3); a host without that door passes the latched edge
+     * of `input/latch-edge` here.
+     */
+    playerEdge: (player: number, source: TransportName) => void;
+    /**
+     * The set for READING — the pure decision asks which keys are already held.
+     *
+     * ⚠️ `ReadonlySet` and not `Set`: READING the set was never the problem; WRITING into it is what erased the source.
+     * The type says so, and a raw write coming back here stops compiling instead of slipping by.
      */
     readonly heldKeys: ReadonlySet<string>;
-    /** `game/attract.ts`: zera a ociosidade e encerra a demo; `true` = o toque foi só para acordar.
-     *  LAZY obrigatoriamente — `attractCtl` é `const` declarado ABAIXO do ponto de init no main.js. */
+    /** The demo: resets idleness and ends the demo; `true` = the touch was only to wake it up. A function, called when a
+     *  touch happens, because the demo may be built after this module. */
     attractOnInput: () => boolean;
-    /** `input/touch.ts`: o toque REVELA os botões (o `hideTouchControls` é do keydown, não daqui). */
+    /** `input/touch.ts`: touch REVEALS the buttons (`hideTouchControls` belongs to whoever sees the keyboard take over). */
     showTouchControls: () => void;
-    /** main.js: hoje um stub vazio (as dicas de início saíram em 2026-07-04); o call-site é mantido verbatim. */
+    /** Hides the host's start tips on a jump; the root has none and passes a no-op. */
     hideTips: () => void;
     togglePause: () => void;
-    /** `input/touch.ts:getTouchMap()` — slot → ação, remapeável. Lido A CADA evento, verbatim: remapear no
-     *  painel passa a valer no toque seguinte, sem re-amarrar ouvinte nenhum. */
+    /** The SELECT pill opens the pause menus (ADR-0155). Absent, the pill does nothing — only the root that draws it wires it. */
+    openMenus?: () => void;
+    /** `input/touch.ts:getTouchMap()` — slot → action, remappable. Read ON EVERY event: a remap in the panel counts on the
+     *  next touch, without rewiring any listener. */
     getTouchMap: () => Record<string, string>;
-    /** A ação do slot `start`. VER O RELATO DA EXTRAÇÃO: no main.js a linha original é `touchMap.start`, e
-     *  `touchMap` NÃO EXISTE naquele escopo — o botão START da tela está quebrado hoje. Este campo é o ponto
-     *  exato onde esse defeito vive, isolado para poder ser consertado (ou não) numa linha só, com decisão. */
+    /** The action of the `start` slot — the root reads it from the live touch map. */
     getStartAction: () => string | undefined;
-    /** `input/touch.ts`: curso e zona morta do analógico, em px, recalculados a cada `applyPadPhysical()`. */
+    /** `input/touch.ts`: the stick's travel and dead zone, in px, recomputed on every `applyPadPhysical()`. */
     getStickTravelPx: () => number;
     getStickDeadPx: () => number;
-    /** `setTimeout` — injetável só para o teste do START não esperar 140 ms de relógio. */
+    /** `setTimeout` — injectable only so the START test does not wait 140 ms of clock. */
     defer?: (fn: () => void, ms: number) => void;
 }
 export interface TouchBindingsApi {
-    /** A decisão pura, já com o mundo de agora. Exposta para o teste comparar sem aplicar. */
+    /** The pure decision, with the world of now. Exposed so the test can compare without applying. */
     decide: (act: string | undefined, on: boolean) => TouchDecision;
-    /** O despacho inteiro: decide e carimba no mundo. É o `doTouch` do main.js. */
+    /** The whole dispatch: decides and stamps it on the world. */
     doTouch: (act: string | undefined, on: boolean) => void;
-    /** O que o botão START faz num clique (pausar, ou apertar-e-soltar depois de `START_TAP_MS`). */
+    /** What the START button does on a click (pause, or press-and-release after `START_TAP_MS`). */
     pressStart: () => void;
-    /** `window.__incl.showTouch` — revela os botões à força, para teste em desktop. */
+    /** Reveals the buttons by force, for testing on a desktop. */
     revealForTests: () => void;
-    /** Amarra tudo: os dois ouvintes globais, os `.touch-btn`, o START, o analógico e a cruz. */
+    /** Wires everything: the two global listeners, the `.touch-btn`s, START, the stick and the cross. */
     attach: () => void;
+    /**
+     * Wires ONLY what is inside `#touch-controls` — buttons, START, stick, cross —, without the window listeners. It is
+     * what gets called after the pad is REDRAWN (another cartridge's `mount()`, ADR-0142).
+     *
+     * ⚠️ IT EXISTS BECAUSE `attach()` TWICE PILES LISTENERS ON THE WINDOW: a hub mounting ten cartridges would end up with
+     * twenty `pointerdown` listeners. The pad's nodes are new on every drawing, and their listeners die with the old
+     * nodes; the window's do not.
+     */
+    rewire: () => void;
 }
 export declare function initTouchBindings(ctx: TouchBindingsCtx): TouchBindingsApi;