@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/transports.js

@@ -1,151 +1,149 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/transports — O REGISTRO DE TRANSPORTES (ADR-0079). Módulo-folha: só tipos e aritmética.
+// input/transports — THE TRANSPORT REGISTRY (ADR-0079). A leaf module: only types and arithmetic.
 //
-// ========================= O QUE UM TRANSPORTE É =========================
-// Uma forma de alcançar as ações, e nada sobre significado. Ele declara o que OFERECE FISICAMENTE — quantos
-// lugares atribuíveis tem — e o jogador atribui a eles as ações do jogo. `TOUCH_DEFAULT` já era uma instância
-// disto antes de o modelo existir: uma atribuição padrão que a criança pode mudar.
+// ========================= WHAT A TRANSPORT IS =========================
+// A way of reaching the actions, and nothing about meaning. It declares what it OFFERS PHYSICALLY — how many
+// assignable places it has — and the player assigns the game's actions to them. `TOUCH_DEFAULT` was already an
+// instance of this before the model existed: a default assignment the child can change.
 //
-// ========================= A GARANTIA MUDOU DE FORMA =========================
-// ⚠️ NÃO é «todo transporte alcança toda ação». É: **para os transportes disponíveis a esta criança, PELO
-// MENOS UM carrega o conjunto de ações deste jogo.** A diferença é o que permite um transporte estreito
-// existir — um acionador de dois toques, um piscar — sem que ele reprove o produto inteiro.
+// ========================= THE GUARANTEE CHANGED SHAPE =========================
+// ⚠️ It is NOT "every transport reaches every action". It is: **of the transports available to this child, AT
+// LEAST ONE carries this game's set of actions.** The difference is what lets a narrow transport exist — a
+// two-tap switch, a blink — without it failing the whole product.
 //
-// ========================= E UM TRANSPORTE NUNCA REMOVE OUTRO =========================
-// Escolher o rato não desliga o teclado, o controle nem o toque. A engine OFERECE; quem escolhe é a criança
-// (ou quem a acompanha). Um método que exige coordenação fina não é exclusão enquanto os outros existirem —
-// a exclusão seria uma lista curta, não um item exigente numa lista longa.
+// ========================= AND A TRANSPORT NEVER REMOVES ANOTHER =========================
+// Choosing the mouse does not turn off the keyboard, the pad or touch. The engine OFFERS; the one who chooses is the
+// child (or whoever is with them). A method that demands fine coordination is not exclusion while the others exist
+// — exclusion would be a short list, not a demanding item in a long one.
 //
-// ========================= O QUE ESTE MÓDULO EXISTE PARA IMPEDIR =========================
-// ⚠️ Um jogo que precisa de doze ações e um transporte de nove lugares é uma combinação REAL — o controle de
-// tela tem nove slots desde sempre e o conjunto de ações passou a catorze em 2026-09-06. A resposta honesta é
-// UMA FRASE ANTES DE COMEÇAR, e não meia tela jogável: a criança que descobre no meio que não consegue
-// alcançar uma ação conclui que o jogo está partido, e ela não tem como saber que não está.
+// ========================= WHAT THIS MODULE EXISTS TO PREVENT =========================
+// ⚠️ A game that needs twelve actions and a transport with fewer places is a REAL combination — the on-screen
+// control has thirteen slots and the action set has fourteen. The honest answer is ONE SENTENCE BEFORE STARTING,
+// not half a playable screen: the child who discovers midway that they cannot reach an action concludes the game is
+// broken, and they have no way of knowing it is not.
 import { ACTIONS } 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.
+ * HOW MANY PLACES EACH REAL TRANSPORT HAS, and where each number comes from. They were measured and lived only in
+ * the test; a number that exists only in a test reaches no child.
  *
- *   · `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.
+ *   · `gamepad: 17` — the Gamepad API's "standard" mapping declares seventeen buttons. Not our choice.
+ *   · `toque: 13` — `TOUCH_DEFAULT` (input/devices) names thirteen slots: the nine plus ADR-0160's four shoulders.
+ *   · `teclado: ACTIONS.length` — ⚠️ and this is the one that needed a decision.
  *
- * ⚠️ 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.
+ * ⚠️ THE KEYBOARD'S NUMBER IS NOT THE NUMBER OF KEYS, nor the number of bindings in the current scheme. Not the keys,
+ * because a hundred keys are not a hundred places a child finds and remembers; not the scheme, because the scheme
+ * grows, and the limit would become the configuration instead of the device.
  *
- * É `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.
+ * It is `ACTIONS.length` because what limits a keyboard, in this product's practice, is THE VOCABULARY THE ENGINE
+ * CAN NAME: a transport that covers every position that exists cannot be the short one. Derived and not written by
+ * hand on purpose — when the vocabulary grows (it went from nine to fourteen), this number grows with it and never
+ * starts lying.
  */
-export const LUGARES = Object.freeze({ gamepad: 17, toque: 9, teclado: ACTIONS.length });
+export const SLOTS = Object.freeze({ gamepad: 17, toque: 13, teclado: ACTIONS.length });
 /**
- * QUANTAS POSIÇÕES O CONTROLE DE TELA SEGURA AO MESMO TEMPO. Dois, e é uma DECLARAÇÃO (ADR-0104 §B).
+ * HOW MANY POSITIONS THE ON-SCREEN CONTROL HOLDS AT ONCE. Two, and it is a DECLARATION (ADR-0104 §B).
  *
- * ⚠️ E A DECISÃO É NÃO PERGUNTAR AO APARELHO. O `navigator.maxTouchPoints` existe, responde depressa, e
- * MENTE — mente para cima: muitos aparelhos anunciam cinco e reconhecem dois. Um modelo assente nele falha
- * exactamente no telemóvel barato da escola pública, que é o pilar 1 deste projeto, e falha em silêncio: a
- * criança tenta correr e pular ao mesmo tempo, não acontece nada, e ela conclui que o jogo está partido.
+ * ⚠️ AND THE DECISION IS NOT TO ASK THE DEVICE. `navigator.maxTouchPoints` exists, answers fast, and LIES — upwards:
+ * many devices announce five and recognise two. A model built on it fails exactly on the public school's cheap
+ * phone, which is this project's pillar 1, and fails silently: the child tries to run and jump at once, nothing
+ * happens, and they conclude the game is broken.
  *
- * Um piso declarado não pode errar para cima. Ele erra para baixo — um aparelho que segurava três fica
- * servido por dois —, e esse erro tem conserto: a opção do terceiro botão, PROVADA POR TESTE, porque um
- * gesto real é a única evidência que um aparelho não consegue falsificar. Nada é recusado e nada é assumido.
+ * A declared floor cannot err upwards. It errs downwards — a device that held three is served by two —, and that
+ * error has a fix: the third-button option, PROVEN BY A TEST, because a real gesture is the only evidence a device
+ * cannot fake. Nothing is refused and nothing is assumed.
  *
- * ⚠️ NÃO É UM REGISTO DE TETOS POR TRANSPORTE, e o ADR diz isso em `more-information`: só o toque tem número
- * declarado. O `holds` do `Transport` é opcional justamente por isso — ausente significa «não há tecto
- * conhecido», não «segura uma». Um registo de tetos para teclado e controle é uma mudança maior, e nada
- * precisa dela hoje.
+ * ⚠️ IT IS NOT A REGISTRY OF CEILINGS PER TRANSPORT, and the ADR says so in `more-information`: only touch has a
+ * declared number. `Transport.holds` is optional precisely for that — absent means "no known ceiling", not "holds
+ * one". A ceiling registry for keyboard and pad is a bigger change, and nothing needs it today.
  */
-export const SEGURA_TOQUE = 2;
+const HOLDS_TOUCH = 2;
 /**
- * Os três transportes que esta engine sabe oferecer hoje.
+ * The three transports this engine knows how to offer today.
  *
- * ⚠️ 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.
+ * ⚠️ THE KEYBOARD DETECTION IS IMPRECISE AND THAT IS ACCEPTABLE — but only because the screen that consumes this
+ * INFORMS instead of REFUSING. No API says "a physical keyboard is plugged in"; what the root asks is
+ * `pointer:coarse && hover:none`, and a tablet WITH a keyboard answers "touch" to that. If the screen blocked, that
+ * tablet would get a false refusal in a game it plays. Since it only says what is missing and lets the child go on,
+ * the error costs one extra sentence and never a closed door.
  */
-export function transportesPadrao(d) {
+export function defaultTransports(d) {
     return [
-        // ⚠️ O GAMEPAD NÃO DECLARA PONTEIRO, e a ausência é medida e não esquecimento: o stick tem o sinal
-        // contínuo e a engine deita-o fora na fonte (`PAD_DEAD = 0.5`, `PadState = Record<string, boolean>`).
-        // Ligá-lo ao ponteiro é possível e traz de volta uma pergunta que o ADR-0112 já deixou nomeada — metade
-        // do curso morta é ergonomia certa para um BOTÃO e errada para um CURSOR.
-        { id: 'gamepad', slots: LUGARES.gamepad, available: d.gamepad },
-        // O teclado aponta QUANDO HÁ RATO — a cláusula do Dev, e a fundação dos transportes 8 e 9 do ADR-0074.
-        { id: 'teclado', slots: LUGARES.teclado, available: d.teclado, aponta: d.rato },
-        // O toque aponta por natureza: a superfície É o ponteiro, e é o mesmo dedo que carrega nos botões.
-        { id: 'toque', slots: LUGARES.toque, holds: SEGURA_TOQUE, available: d.toque, aponta: d.toque },
+        // ⚠️ THE GAMEPAD DECLARES NO POINTER, and the absence is measured, not forgotten: the stick has the continuous
+        // signal and the engine throws it away at the source (`PAD_DEAD = 0.5`, `PadState = Record<string, boolean>`).
+        // Wiring it to the pointer is possible and brings back a question ADR-0112 already named — half the travel dead is
+        // the right ergonomics for a BUTTON and the wrong one for a CURSOR.
+        { id: 'gamepad', slots: SLOTS.gamepad, available: d.gamepad },
+        // The keyboard points WHEN THERE IS A MOUSE — the Dev's clause, and the foundation of ADR-0074's transports 8 and 9.
+        { id: 'teclado', slots: SLOTS.teclado, available: d.keyboard, points: d.mouse },
+        // Touch points by nature: the surface IS the pointer, and it is the same finger that presses the buttons.
+        { id: 'toque', slots: SLOTS.toque, holds: HOLDS_TOUCH, available: d.touch, points: d.touch },
     ];
 }
-/** Este transporte carrega este conjunto de ações? Aritmética, como o ADR-0079 §3 a descreve. */
-export function carries(t, acoes) {
-    return t.slots >= acoes.length;
+/** Does this transport carry this set of actions? Arithmetic, as ADR-0079 §3 describes it. */
+export function carries(t, actions) {
+    return t.slots >= actions.length;
 }
 /**
- * Este transporte SEGURA quantas o jogo pede ao mesmo tempo? (ADR-0104 §A.)
+ * Does this transport HOLD as many as the game asks at once? (ADR-0104 §A.)
  *
- * ⚠️ TRANSPORTE SEM TECTO DECLARADO RESPONDE SIM, e a escolha é deliberada: o `holds` ausente quer dizer «não
- * medimos isto», e recusar por falta de medida transformaria uma ignorância em acusação — o teclado e o
- * controle passariam a reprovar todos os jogos por não terem número nenhum. Onde não há decisão, o modelo
- * cala; é o toque que tem decisão, e é só ele que pode reprovar aqui.
+ * ⚠️ A TRANSPORT WITH NO DECLARED CEILING ANSWERS YES, and the choice is deliberate: an absent `holds` means "we did
+ * not measure this", and refusing for lack of a measure would turn ignorance into an accusation — keyboard and pad
+ * would fail every game for having no number at all. Where there is no decision, the model stays silent; touch is
+ * the one with a decision, and it alone can fail here.
  */
-export function holds(t, pedidas) {
-    return t.holds === undefined || t.holds >= pedidas;
+function holds(t, asked) {
+    return t.holds === undefined || t.holds >= asked;
 }
 /**
- * Os transportes DISPONÍVEIS que carregam este conjunto.
+ * The AVAILABLE transports that carry this set.
  *
- * ⚠️ 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.
+ * ⚠️ Availability and capacity are checked in this order on purpose: a transport that would fit but is not plugged
+ * in is no answer for a child sitting at the device now.
  */
-export function carriedBy(lista, acoes) {
-    return lista.filter((t) => t.available() && carries(t, acoes));
+export function carriedBy(list, actions) {
+    return list.filter((t) => t.available() && carries(t, actions));
 }
 /**
- * A garantia do ADR-0079 §3, como pergunta de sim ou não.
+ * ADR-0079 §3's guarantee, as a yes-or-no question.
  *
- * ⚠️ 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.
+ * ⚠️ AN EMPTY SET OF ACTIONS RETURNS `false`, not a vacuous `true`. A game that declares no action is not a game any
+ * transport serves — it is a game nobody can play, and `actionSetProblems` already fails it. Returning `true` here
+ * would hide that defect behind this function.
  */
-export function reachable(lista, acoes) {
-    return acoes.length > 0 && carriedBy(lista, acoes).length > 0;
+export function reachable(list, actions) {
+    return actions.length > 0 && carriedBy(list, actions).length > 0;
 }
 /**
- * Mede o alcance ANTES de a criança começar.
+ * Measures the reach BEFORE the child starts.
  *
- * ⚠️ 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.
+ * ⚠️ It returns DATA and not text. The sentence belongs to the interface and has to go through `t()`; returning
+ * prose from here would put a language in a module that has none.
  */
-export function alcance(lista, acoes, seguraPedidas, pedePonteiro = false) {
-    const disponiveis = lista.filter((t) => t.available());
+export function reach(list, actions, askedHolds, wantsPointer = false) {
+    const availableNow = list.filter((t) => t.available());
     /**
-     * ⚠️ PADRÃO `false` E NÃO PARÂMETRO OBRIGATÓRIO: os trezentos jogos que não desenham não podem sentir esta
-     * mudança, e um quarto argumento exigido faria cada chamador existente decidir hoje uma coisa que não lhe
-     * diz respeito.
+     * ⚠️ A `false` DEFAULT AND NOT A REQUIRED PARAMETER: games that do not draw must not feel this change, and a
+     * required fourth argument would make every existing caller decide today something that is none of its business.
      */
-    const apontaSeFor = (t) => !pedePonteiro || (!!t.aponta && t.aponta());
-    // ⚠️ «Serve» passou a ser TRÊS coisas. Foi DUAS na #114 (o `ok` dizia sim a quem não segurava três dedos), e
-    // é três desde o ADR-0112 — pela mesma razão das duas vezes: um `ok` verdadeiro sobre um jogo que a criança
-    // não consegue jogar é a pior coisa que este campo pode fazer.
-    const serve = (t) => carries(t, acoes) && holds(t, seguraPedidas) && apontaSeFor(t);
+    const pointsIfNeeded = (t) => !wantsPointer || (!!t.points && t.points());
+    // ⚠️ "Serves" became THREE things. It was TWO with #114 (`ok` said yes to whoever could not hold three fingers), and
+    // three since ADR-0112 — for the same reason both times: a true `ok` about a game the child cannot play is the worst
+    // thing this field can do.
+    const serve = (t) => carries(t, actions) && holds(t, askedHolds) && pointsIfNeeded(t);
     return {
-        ok: acoes.length > 0 && disponiveis.some(serve),
-        pedidas: acoes.length,
-        seguraPedidas,
-        pedePonteiro,
-        serviriamSeLigados: lista.filter((t) => !t.available() && serve(t)).map((t) => t.id),
-        curtos: disponiveis.filter((t) => !carries(t, acoes)).map((t) => ({ id: t.id, slots: t.slots })),
-        naoApontam: disponiveis
-            .filter((t) => carries(t, acoes) && holds(t, seguraPedidas) && !apontaSeFor(t))
+        ok: actions.length > 0 && availableNow.some(serve),
+        asked: actions.length,
+        holdsAsked: askedHolds,
+        needsPointer: wantsPointer,
+        wouldServeIfOn: list.filter((t) => !t.available() && serve(t)).map((t) => t.id),
+        short: availableNow.filter((t) => !carries(t, actions)).map((t) => ({ id: t.id, slots: t.slots })),
+        cannotPoint: availableNow
+            .filter((t) => carries(t, actions) && holds(t, askedHolds) && !pointsIfNeeded(t))
             .map((t) => t.id),
-        // ⚠️ SÓ QUEM CHEGA, e não quem já reprovou por lugares. Um transporte que aparecesse nas duas listas
-        // faria o cartão dizer duas coisas sobre o mesmo defeito, e a criança leria dois problemas onde há um.
-        naoSeguram: disponiveis
-            .filter((t) => carries(t, acoes) && !holds(t, seguraPedidas))
+        // ⚠️ ONLY THOSE THAT REACH, and not those already failed for places. A transport on both lists would make the card
+        // say two things about the same defect, and the child would read two problems where there is one.
+        cannotHold: availableNow
+            .filter((t) => carries(t, actions) && !holds(t, askedHolds))
             .map((t) => ({ id: t.id, holds: t.holds })),
     };
 }

package/dist-pkg/input/virtual-controller.d.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Action } from '../core/actions.js';
+import type { KeyScheme } from '../core/entity.js';
+import type { TransportName } from './transport-in-use.js';
+export interface VirtualCommand {
+    readonly action: Action;
+    readonly pressed: boolean;
+    /** Who produced it (ADR-0111 §2); `undefined` when nobody said. */
+    readonly source: TransportName | undefined;
+    readonly player: number;
+}
+export interface VirtualControllerDeps {
+    readonly scheme: (player: number) => KeyScheme;
+    readonly menuOpen: () => boolean;
+    /**
+     * Holds the child's key for this position.
+     *
+     * ⚠️ `source` CAN BE UNDEFINED, and that is not sloppiness: a real key press carries no stamp, so the keyboard —
+     * the one transport whose native currency IS the key — arrives unsigned. `input/state` already has the narrow
+     * door for exactly that (`markKeyWithoutSource`), and the host wires this to it: a key whose producer nobody
+     * declared must ERASE the previous producer rather than inherit it (ADR-0109).
+     */
+    readonly holdKey: (code: string, source: TransportName | undefined) => void;
+    readonly releaseKey: (code: string) => void;
+    /**
+     * A menu is moved by its key, as the touch pad does, stamped with the transport that pressed it.
+     *
+     * 📌 This is the POSITION → KEY translator, and it exists for transports that do not produce keys. The keyboard
+     * does, so its key is already in the world before this is reached — the host's implementation says so.
+     */
+    readonly menuKey: (code: string, source: TransportName | undefined) => void;
+    readonly deliver: (command: VirtualCommand) => void;
+    /**
+     * A position the ENGINE answers itself while a menu is open, before it becomes a menu key: the sonar reads the menu in
+     * front (ADR-0234, `ui/screen-text.menuSonarPress`). Answers whether it took the press. Absent: every position is a key.
+     */
+    readonly menuAnswers?: (action: Action, player: number) => boolean;
+    /**
+     * A SYSTEM position pressed, in play or with a menu open: the engine answers it for that seat as its keys do — `start` the
+     * quick pause (again: leaves it), `select` the menus (ADR-0144 §1 and its erratum of 2026-09-26, ADR-0155). Absent: it does
+     * nothing.
+     *
+     * ⚠️ The keyboard does not come here: its key is already in the world, and the engine's own key listeners answer it even for
+     * a cartridge with no `onCommand` — the host's keyboard conductor does not press these two, or one key would pause twice.
+     */
+    readonly systemPress?: (action: Action, player: number) => void;
+    /**
+     * ONE BUTTON ONLY (ADR-0218 §4): asked FIRST, for every press from every transport that presses here — the eyes, the face,
+     * the hands, the voice, the on-screen pad, the gamepad. `true` means one-button scanning took the press as «take the one
+     * shown»: the position reaches nothing else — not play, not a menu, not the engine — and no release is owed for it. A press
+     * that lands on the scan's «cancel» is taken too, and means nothing. Absent: every press is itself.
+     */
+    readonly takeShown?: (source: TransportName | undefined) => boolean;
+    /**
+     * A PRESS FROM A NAMED TRANSPORT, told FIRST — before one button only, a menu or play decides where it goes. This is the one
+     * place every position-pressing transport shares, so it is where «the child is using this device» can be heard for all of
+     * them (ADR-0109 rule 3), and where the root records that device's edge and resolves its latch before the press reaches the
+     * game (ADR-0113, ADR-0249). Not told for a press with no source: a key nobody stamped is nobody's edge — the real keyboard
+     * arrives here as `teclado`, read off the event by `input/synthetic-source.sourceOfEvent`. Absent: nothing is told.
+     */
+    readonly pressedBy?: (source: TransportName, player: number) => void;
+}
+export interface VirtualController {
+    /**
+     * Presses a position. Answers whether it reached PLAY — `false` means a menu took it, or it was held back (`toPlay`).
+     *
+     * 🔴 THE ANSWER EXISTS BECAUSE EVERY TRANSPORT NEEDS IT AND EACH WAS GUESSING IT (ADR-0223). The touch pad asked its own
+     * `emMenu()` before deciding what to do, which is the same question this function has just answered — and two answers to
+     * one question is how the two doors came to disagree about what happens with a menu open. A transport that raises an edge,
+     * or hides its tips, or announces something, does it only when the press reached the game; now it is told.
+     *
+     * `toPlay` false: in play the press belongs to something else — the keyboard knows what has the focus, a field being typed
+     * into or the engine's own control being pressed (`input/key-default`) — so it reaches nobody: nothing held, nothing delivered.
+     * With a menu open it is the menu's all the same, as every press is (ADR-0111 erratum of 2026-09-26: one press, one action).
+     *
+     * A system position (`start`, `select`) never reaches play and never becomes a menu key: it is the engine's (ADR-0144 §4), and
+     * it goes to `systemPress` — unless, in play, `toPlay` is false, when the press belongs to something else and reaches nobody.
+     */
+    press(action: Action, source: TransportName | undefined, player?: number, toPlay?: boolean): boolean;
+    release(action: Action, source: TransportName | undefined, player?: number): void;
+}
+export declare function createVirtualController(d: VirtualControllerDeps): VirtualController;

package/dist-pkg/input/virtual-controller.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/virtual-controller — THE ENGINE CARRIES THE VIRTUAL BUTTON TO THE GAME (ADR-0111 and its erratum of 2026-09-16; issue #197).
+//
+// The Dev: «a engine lida com o hardware e passa para o jogo o nome virtual do botão, o jogo por sua vez devolve o nome do que é executado
+// ao apertar cada botão… a engine leva o evento para o jogo». A transport that reads positions (the eyes, and later the face and the
+// hands) presses and releases a position here, with its source; this decides what that reaches:
+// · with a menu open, the position is the menu's key — the way the touch pad already moves menus (ADR-0157), since menus read keys —
+//   unless the engine answers it there itself (`menuAnswers`: the sonar reads the menu, ADR-0234);
+// · in play, the child's key for that position is held (games that ask what is held keep answering), and the command is delivered to the
+//   cartridge: the position, pressed or released, the source, the seat. The cartridge's map (its `preset`) says what it executes.
+// A position the child's scheme gives no key is still delivered: the map belongs to the game, not to the keyboard.
+// 🔴 EXCEPT THE TWO SYSTEM POSITIONS, which never reach play (ADR-0144 §4, ADR-0155 §4): `start` is the quick pause and `select`
+// opens the menus, a cartridge may not declare either, so the game has no word for them and nothing to do with them. 📏 Before
+// this, Enter in play opened the quick pause AND the quiz's `onCommand` heard `start`; F opened the card AND it heard `select`.
+// They go to the ENGINE instead (`systemPress`), so START and SELECT open the pause «from any transport» (ADR-0144 §1): the eyes,
+// the face, the hands, the voice and the scan press here and have no key in the world for the engine to hear.
+// 🔴 AND WITH A MENU OPEN TOO, never as a key (ADR-0144 erratum of 2026-09-26). The first key of `start` is whatever the child put
+// first: with `start` remapped to `Enter`, a camera's START on the quick pause's bar was the bar's «confirm» and not the way out.
+// The engine answers the POSITION the same way its key listeners do — START again leaves the quick pause, SELECT goes on to the
+// card, and an open card or panel refuses both.
+// 🔴 AND WITH ONE BUTTON ONLY ON, NONE OF THE ABOVE (ADR-0218 §4): every press here is the child's one switch, and it takes the
+// item the scan shows (`takeShown`, asked before anything else). This is the one place every position-pressing transport shares.
+import { SYSTEM } from '../core/actions.js';
+/** The positions that are the engine's and never the game's (`core/actions.SYSTEM`). */
+const ENGINE_POSITIONS = new Set(SYSTEM);
+export function createVirtualController(d) {
+    // `${player}:${action}` → the key held for a press the game received (or null when the scheme has none), so the release lets go of the
+    // same key, and only a press the game heard is released to it
+    const held = new Map();
+    return {
+        press(action, source, player = 0, toPlay = true) {
+            if (source)
+                d.pressedBy?.(source, player);
+            if (d.takeShown?.(source))
+                return false; // one button only: whatever was pressed, it was the switch (ADR-0218 §4)
+            const menu = d.menuOpen();
+            // the POSITION, not its first key: a key means what the child bound to it, and `Enter` on a menu is «confirm»
+            if (ENGINE_POSITIONS.has(action)) {
+                if (menu || toPlay)
+                    d.systemPress?.(action, player);
+                return false;
+            }
+            const code = d.scheme(player)[action]?.[0];
+            if (menu) {
+                if (!d.menuAnswers?.(action, player) && code)
+                    d.menuKey(code, source);
+                return false;
+            }
+            if (!toPlay)
+                return false;
+            if (code)
+                d.holdKey(code, source);
+            held.set(`${player}:${action}`, code ?? null);
+            d.deliver({ action, pressed: true, source, player });
+            return true;
+        },
+        release(action, source, player = 0) {
+            const key = `${player}:${action}`;
+            if (!held.has(key))
+                return;
+            const code = held.get(key);
+            held.delete(key);
+            if (code)
+                d.releaseKey(code);
+            // delivered even if a menu opened meanwhile: a game must never be left believing a button is still down
+            d.deliver({ action, pressed: false, source, player });
+        },
+    };
+}

package/dist-pkg/input/vocabulary-migration.d.ts

@@ -1,69 +1,70 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * ⚠️ O DADO SALVO NÃO É UM `KeyScheme`, e a issue #118 tornou isso um erro de compilação em vez de uma
- * suposição. Um `KeyScheme` é FECHADO nas quatorze posições e completo; o que está no navegador da criança é
- * uma SOBREPOSIÇÃO — parcial por construção (`loadKB` funde-a sobre os padrões com `Object.assign`) e capaz
- * de carregar chaves que este código não conhece, o que o cabeçalho de `migrarEsquema` já dizia com todas as
- * letras: «chave desconhecida atravessa intacta».
+ * ⚠️ THE SAVED DATA IS NOT A `KeyScheme`, and issue #118 made that a compile error instead of an assumption. A
+ * `KeyScheme` is CLOSED over the fourteen positions and complete; what sits in the child's browser is an
+ * OVERLAY — partial by construction (`loadKB` merges it over the defaults with `Object.assign`) and able to
+ * carry keys this code does not know, which the header of `migrateScheme` already says in so many words: an
+ * unknown key passes through untouched.
  *
- * Dar-lhe o tipo fechado obrigaria este ficheiro a inventar as posições que faltam no dado antigo — quer
- * dizer, a escrever teclas que a criança nunca escolheu, no exacto módulo que existe para não lhe perder o
- * remapeamento. O tipo aberto é o honesto aqui, e é só aqui.
+ * Giving it the closed type would force this file to invent the positions missing from the old data — that is,
+ * to write keys the child never chose, in the very module that exists so as not to lose their remapping. The
+ * open type is the honest one here, and only here.
  */
-export type EsquemaSalvo = Record<string, readonly string[]>;
+export type SavedScheme = Record<string, readonly string[]>;
 /**
- * Nome de plataforma → posição abstrata. **ADR-0086 §2**, e não o ADR-0074.
+ * Platform name → abstract position. **ADR-0086 §2**, not ADR-0074.
  *
- * ⚠️ A DIFERENÇA ENTRE OS DOIS REGISTROS É A TECLA DA CRIANÇA. O ADR-0074 dizia `jump → action1` e
- * `run → action4`; o ADR-0086 corrigiu para `run → action1` e `jump → action2`, medindo que a correção é a
- * leitura CONSERVADORA — ela deixa cada verbo na tecla e no botão que já ocupava. Traduzir por engano pela
- * tabela do 0074 não daria erro nenhum: moveria o pulo de `J` para `U` em silêncio.
+ * ⚠️ THE DIFFERENCE BETWEEN THE TWO RECORDS IS THE CHILD'S KEY. ADR-0074 said `jump → action1` and
+ * `run → action4`; ADR-0086 corrected it to `run → action1` and `jump → action2`, having measured that the
+ * correction is the CONSERVATIVE reading — it leaves each verb on the key and the button it already held.
+ * Translating by mistake with 0074's table would raise no error at all: it would move jump from `J` to `U`
+ * silently.
  */
-export declare const VOCABULARIO_ANTIGO: Readonly<Record<string, string>>;
+export declare const OLD_VOCABULARY: Readonly<Record<string, string>>;
 /**
- * ⚠️ O SEGUNDO DADO SALVO, e ele quase passou. O mapa de toque (`incl_touchmap`) guarda SLOT → AÇÃO, ou seja
- * o nome da ação está no VALOR e não na chave: `{ b0: 'jump', b1: 'especial' }`. O tradutor de esquemas de
- * teclado, que traduz CHAVES, passaria por cima dele sem tocar em nada.
+ * ⚠️ THE SECOND SAVED DATA, and it nearly slipped through. The touch map (`incl_touchmap`) stores SLOT → ACTION,
+ * so the action name is in the VALUE and not the key: `{ b0: 'jump', b1: 'especial' }`. The keyboard scheme
+ * translator, which translates KEYS, would pass over it without touching anything.
  *
- * ⚠️ E O DANO SERIA PIOR DO QUE NO TECLADO. `normalizeTouchMap` funde o guardado SOBRE o padrão, então um
- * `b0: 'jump'` gravado sobrescreveria o `b0: 'action2'` correto — e o botão da tela deixaria de fazer
- * qualquer coisa. Num tablet de escola pública o toque não é o caminho alternativo: é o único.
+ * ⚠️ AND THE DAMAGE WOULD BE WORSE THAN ON THE KEYBOARD. `normalizeTouchMap` merges what is stored OVER the
+ * default, so a saved `b0: 'jump'` would overwrite the correct `b0: 'action2'` — and the on-screen button would
+ * stop doing anything. On a public-school tablet, touch is not the alternative path: it is the only one.
  *
- * Foi um teste de NAVEGADOR que o encontrou (`tests/touch.browser.test.js`), depois de a suíte `node` já
- * estar verde — o que é o argumento para os dois projetos existirem.
+ * A BROWSER test found it (`tests/touch.browser.test.js`), after the `node` suite was already green — which is
+ * the argument for having both projects.
  */
-export declare function migrarMapaDeToque(mapa: Record<string, string> | null | undefined): Record<string, string> | null;
+export declare function migrateTouchMap(touchMap: Record<string, string> | null | undefined): Record<string, string> | null;
 /**
- * ⚠️ O TERCEIRO DADO SALVO, encontrado por varredura e não por acidente. Depois de o segundo aparecer num
- * teste de navegador, a pergunta certa deixou de ser «este está migrado?» e passou a ser «QUANTOS formatos
- * persistidos existem?». São três, e este é o do assistente de controle: `incl_padmap_<id>` guarda
- * AÇÃO → BINDING FÍSICO, `{ jump: { b: 0 }, run: { b: 2 } }`, um por modelo de controle.
+ * ⚠️ THE THIRD SAVED DATA, found by a sweep and not by accident. After the second turned up in a browser test,
+ * the right question stopped being "is this one migrated?" and became "HOW MANY persisted formats exist?". There
+ * are three, and this is the pad wizard's: `incl_padmap_<id>` stores ACTION → PHYSICAL BINDING,
+ * `{ jump: { b: 0 }, run: { b: 2 } }`, one per pad model.
  *
- * ⚠️ E ELE É O MAIS CARO DE PERDER DOS TRÊS. Um mapa desses existe porque a criança (ou quem a acompanha)
- * passou por um assistente de nove passos apertando botão a botão, provavelmente porque o controle dela não
- * é «standard» — controles genéricos e adaptados raramente são. Perdê-lo manda essa pessoa de volta ao
- * assistente inteiro.
+ * ⚠️ AND IT IS THE MOST EXPENSIVE OF THE THREE TO LOSE. Such a map exists because the child (or whoever is with
+ * them) went through the wizard pressing button after button, one step per position the game names — probably
+ * because their pad is not "standard", and generic and adapted pads rarely are. Losing it sends that person back
+ * through the whole wizard.
  *
- * `_skip` e qualquer chave desconhecida atravessam, pela mesma razão das outras duas migrações.
+ * `_skip` and any unknown key pass through, for the same reason as the other two migrations.
  */
-export declare function migrarMapaDeControle<T>(mapa: Record<string, T> | null | undefined): Record<string, T> | null;
-/** O objeto salvo, tal como `input/keyboard` o persiste. `p34` é o formato mais antigo de todos. */
+export declare function migrateControlMap<T>(touchMap: Record<string, T> | null | undefined): Record<string, T> | null;
+/** The saved object, as `input/keyboard` persists it. `p34` is the oldest format of all. */
 export interface SavedKB {
-    solo?: EsquemaSalvo;
-    p2?: EsquemaSalvo[];
-    p3?: EsquemaSalvo[];
-    p4?: EsquemaSalvo[];
-    p34?: (EsquemaSalvo | null)[];
+    solo?: SavedScheme;
+    p2?: SavedScheme[];
+    p3?: SavedScheme[];
+    p4?: SavedScheme[];
+    p34?: (SavedScheme | null)[];
 }
 /**
- * Traduz UM esquema salvo do vocabulário antigo para o abstrato.
+ * Translates ONE saved scheme from the old vocabulary to the abstract one.
  *
- * ⚠️ CHAVE DESCONHECIDA ATRAVESSA INTACTA, e é decisão e não descuido: `up`, `down`, `left` e `right` nunca
- * mudaram de nome, e um esquema pode carregar uma chave que este código não conhece — dado de uma versão
- * futura, ou lixo. Apagá-la seria destruir dado que não entendemos, e é o que faria as quatro direções
- * sumirem. É também o que torna esta função IDEMPOTENTE: aplicada sobre um esquema já migrado, nenhuma chave
- * casa e o resultado é igual à entrada, o que importa porque `loadKB` pode correr mais de uma vez na sessão.
+ * ⚠️ AN UNKNOWN KEY PASSES THROUGH UNTOUCHED, and that is a decision, not carelessness: `up`, `down`, `left` and
+ * `right` never changed names, and a scheme may carry a key this code does not know — data from a future
+ * version, or garbage. Deleting it would destroy data we do not understand, and it is what would make the four
+ * directions vanish. It is also what makes this function IDEMPOTENT: applied to an already migrated scheme, no
+ * key matches and the result equals the input, which matters because `loadKB` may run more than once a session.
  */
-export declare function migrarEsquema(esquema: EsquemaSalvo | null | undefined): EsquemaSalvo | null;
-/** Traduz o objeto salvo inteiro — o esquema solo e as listas por contagem de jogadores. */
-export declare function migrarSalvo(s: SavedKB | null | undefined): SavedKB | null;
+export declare function migrateScheme(saved: SavedScheme | null | undefined): SavedScheme | null;
+/** Translates the whole saved object — the solo scheme and the lists per player count. */
+export declare function migrateSaved(s: SavedKB | null | undefined): SavedKB | null;