@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,96 +1,108 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { ControlledPlayer } from '../core/entity.js';
 import type { Action } from '../core/actions.js';
-import { type Transporte, type EstadoDaEntrada } from './transporte-em-uso.js';
-export declare const keys: Set<string>;
-/**
- * A ORIGEM DE CADA TECLA SEGURADA — código → aparelho que a produziu (ADR-0109).
- *
- * ⚠️ ESTE MAPA EXISTE PORQUE `keys` APAGA A ORIGEM À PORTA, e foi essa erasão que deixou o §C da issue #114
- * por construir durante dois meses: o toque escreve códigos aqui dentro (`press()` faz
- * `heldKeys.add(codeFor(act))`) e a webcam despacha `KeyboardEvent` sintético, então quando o `held()`
- * responde já não há como saber QUEM carregou. O único transporte que sobrevivia identificável era o
- * gamepad, e só porque passa por `padCur` em vez do conjunto.
- *
- * ⚠️ CAMPO NOVO AO LADO DO VELHO, sincronizado num ponto só (`marcarTecla`/`soltarTecla`), com os leitores a
- * migrar um a um — é a forma que este repositório já usou no `p.visual` ao lado do `p.viz` (#104), e a razão
- * é a mesma: uma troca de uma vez não tem estado verde onde parar, e isto é a espinha da entrada.
- *
- * 📌 Um código SEM entrada aqui não é um erro de dados — é uma tecla que entrou por um escritor que ainda não
- * migrou. `origemDe` devolve `undefined` e quem pergunta decide; ver a nota lá.
- */
-export declare const origemDaTecla: Map<string, Transporte>;
-/**
- * Uma tecla FOI SEGURADA, e sabe-se por quem. É o único sítio que escreve nos dois.
- *
- * ⚠️ OS DOIS JUNTOS OU NENHUM: enquanto forem duas estruturas, elas podem divergir, e uma divergência aqui é
- * silenciosa — o jogo continua a andar e só a alternância fica errada. Por isso não há `keys.add` público
- * neste módulo: quem escreve, escreve por aqui.
- */
-export declare function marcarTecla(code: string, origem: Transporte): void;
-/**
- * A tecla foi segurada e NÃO SE SABE por quem. A porta estreita, e ela é estreita de propósito.
- *
- * ⚠️ POR QUE UMA FUNÇÃO COM OUTRO NOME E NÃO UM SEGUNDO PARÂMETRO OPCIONAL. `marcarTecla(code)` com a origem
- * omitida é o que se escreve quando não se pensou; `marcarTeclaSemOrigem(code)` é o que se escreve quando se
- * pensou e a resposta é «não sei». O tipo não distingue as duas, mas o nome distingue — e é o nome que
- * aparece na revisão. Um parâmetro esquecido não se lê; uma função assim chamada lê-se de longe.
- *
- * ⚠️ E O `delete` É A METADE QUE IMPORTA, não o `add`. Sem ele, uma tecla premida de novo por uma fonte
- * desconhecida HERDAVA a origem da vez anterior: a criança joga por olhar, larga a tecla, um script de fora
- * despacha o mesmo código, e a alternância continua a responder «olhos» a uma aresta que já não é dela. Um
- * mapa que guarda a resposta certa de ontem é pior do que um que não guarda nada.
- *
- * 📌 Hoje há UM chamador — o `input/keydown`, para o evento sintético que ninguém assinou. Depois desta
- * migração nada nesta engine produz um; quem produz é código de consumidor, e é para ele que esta porta fica
- * aberta. Fechá-la faria a tecla dele simplesmente não funcionar, o que é uma quebra pior do que não saber.
- */
-export declare function marcarTeclaSemOrigem(code: string): void;
-/** A outra metade. Solta nos dois, pela mesma razão. */
-export declare function soltarTecla(code: string): void;
-/** Solta TUDO — o `blur` da janela. Os dois, ou o mapa fica a descrever teclas que já ninguém segura. */
-export declare function soltarTodas(): void;
-/**
- * Quem produziu esta tecla? `undefined` quando não se sabe.
- *
- * ⚠️ `undefined` E NÃO UM PADRÃO. Um padrão `'teclado'` faria a erasão voltar por outra porta: uma tecla do
- * toque que entrasse por um escritor não migrado seria lida como teclado, a alternância desligava-se, e nada
- * o diria. Não saber é uma resposta; fingir que se sabe não é.
- */
-export declare function origemDe(code: string): Transporte | undefined;
-/**
- * O ESTADO DA ENTRADA DESTE JOGADOR. Nunca `undefined`: quem nunca produziu uma aresta está no PADRÃO.
- *
- * ⚠️ `PADRAO` E NÃO `undefined`, pela mesma razão que o `origemDe` faz o contrário: ali «não sei» é uma
- * resposta honesta sobre uma tecla que já existe; aqui a pergunta é sobre um JOGADOR, e um jogador que
- * ainda não tocou em nada está mesmo no teclado sem assistida — que é o que `PADRAO` diz.
- */
-export declare function entradaDe(jogador: number): EstadoDaEntrada;
-/**
- * UMA ARESTA DESTE JOGADOR CHEGOU, com a sua origem.
- *
- * 📌 O `aposAresta` devolve o MESMO objecto quando nada muda, então guardar de volta não aloca por quadro.
- * ⚠️ E uma aresta de um transporte assistido NÃO o habilita — essa regra vive no `aposAresta` e a razão
- * está lá: um falso positivo da webcam trancaria a alternância de toda a gente sem ninguém ter pedido.
- */
-export declare function arestaDoJogador(jogador: number, origem: Transporte): void;
-/** Habilitar a assistida é um ACTO EXPLÍCITO (ADR-0109 regra 4), e por isso tem porta própria. */
-export declare function habilitarAssistidaDe(jogador: number): void;
-export declare function desabilitarAssistidaDe(jogador: number): void;
+import { type TransportName, type InputState } from './transport-in-use.js';
+/** The actions one pad holds this frame. Mutated IN PLACE by `input/gamepad`'s `pollPads`. */
+type PadState = Record<string, boolean>;
+type HeldPlayer = Pick<ControlledPlayer, 'ctrl' | 'pad'>;
+/** ONE ROOT'S INPUT STATE — what `createInputState()` returns and what `Engine.input` is. */
+export interface LiveInput {
+    /** Physical keys held NOW (KeyboardEvent.code). */
+    readonly keys: Set<string>;
+    /**
+     * THE SOURCE OF EACH HELD KEY — code → the device that produced it (ADR-0109).
+     *
+     * ⚠️ THIS MAP EXISTS BECAUSE `keys` ERASES THE SOURCE AT THE DOOR (issue #114): it is a set of CODES, and several
+     * transports hold keys in it — the keyboard, and the virtual controller for a position the eyes, the face, the hands
+     * or the voice pressed — so by the time `held()` answers there is no telling WHO pressed. The pad keeps its own
+     * identity only because it goes through `padCur` instead of the set.
+     *
+     * ⚠️ THE TWO ARE WRITTEN IN ONE PLACE (`markKey`/`releaseKey` and their siblings), because they are two structures and
+     * may drift apart.
+     *
+     * 📌 A code with NO entry here is not a data error — it is a key nobody signed, and every real key from the keyboard
+     * is one: an event the child produced carries no stamp. `sourceOf` returns `undefined` and whoever asks decides.
+     */
+    readonly keySource: Map<string, TransportName>;
+    /**
+     * A key WAS PRESSED, and who pressed it is known. The only place that writes both.
+     *
+     * ⚠️ BOTH TOGETHER OR NEITHER: while they are two structures they can drift apart, and a drift here is silent — the
+     * game keeps moving and only the latch goes wrong. Whoever writes, writes through here.
+     */
+    markKey(code: string, origin: TransportName): void;
+    /**
+     * The key was pressed and WHO pressed it is NOT KNOWN. The narrow door, and it is narrow on purpose.
+     *
+     * ⚠️ A FUNCTION WITH ANOTHER NAME AND NOT AN OPTIONAL SECOND PARAMETER: `markKey(code)` with the source left out is what
+     * gets written without thinking; `markKeyWithoutSource(code)` is what gets written after thinking, when the answer is
+     * "I don't know". The name is what shows in review.
+     *
+     * ⚠️ AND THE `delete` IS THE HALF THAT MATTERS: without it, a key pressed again by an unknown source INHERITED the
+     * source of the time before, and the latch kept answering "eyes" to an edge that is no longer theirs.
+     */
+    markKeyWithoutSource(code: string): void;
+    /**
+     * The key was pressed and the CALLER MAY NOT KNOW by whom — it picks the right one of the two doors above. The union
+     * is demanded EXPLICITLY: whoever knows who pressed keeps calling `markKey`; this one is for whoever receives the
+     * answer from someone else (the root's virtual controller, `input/keydown`) and cannot pretend to have it.
+     */
+    markKeyFrom(code: string, source: TransportName | undefined): void;
+    /** The other half. Lets go in both, for the same reason. */
+    releaseKey(code: string): void;
+    /**
+     * Lets go of EVERYTHING — both structures, or the map is left describing keys nobody holds any more. The window's
+     * `blur` does NOT use this: see `letGoOfTheKeyboard`.
+     */
+    releaseAllKeys(): void;
+    /**
+     * Hands `release` every key THE KEYBOARD holds — the ones the window's `blur` owes a keyup. ⚠️ ONLY THE KEYBOARD'S: a
+     * key with no source or the keyboard's own stamp. A camera or voice press does not depend on the window's focus, and
+     * letting go of it would take a held position from whoever cannot press it again quickly. It hands out codes and does
+     * not release them itself: the release has to travel the road a real keyup travels, which belongs to the root.
+     */
+    letGoOfTheKeyboard(release: (code: string) => void): void;
+    /**
+     * Who produced this key? `undefined` when it is not known. ⚠️ NOT A DEFAULT: a `'teclado'` default would read an
+     * unsigned key from an unknown producer as the keyboard, and the latch would turn off for whoever plays by gaze.
+     */
+    sourceOf(code: string): TransportName | undefined;
+    /**
+     * THIS PLAYER'S TRANSPORT STATE (ADR-0109 · ADR-0113). Never `undefined`: whoever never produced an edge is at the
+     * DEFAULT — a player who has not touched anything yet really is on the keyboard with nothing assisted.
+     */
+    inputOf(player: number): InputState;
+    /**
+     * AN EDGE FROM THIS PLAYER ARRIVED, with its source. ⚠️ An edge from an assisted transport does NOT enable it — that
+     * rule lives in `afterEdge` with its reason: a webcam false positive would lock latching on for everyone.
+     */
+    playerEdge(player: number, origin: TransportName): void;
+    /** Enabling the assisted transports is an EXPLICIT ACT (ADR-0109 rule 4), and so it has its own door. */
+    enableAssistedFor(player: number): void;
+    disableAssistedFor(player: number): void;
+    /**
+     * ⚠️ FORGETTING IS A SEPARATE DOOR, AND LETTING GO OF KEYS DOES NOT CALL IT. The child did not change devices by
+     * changing tabs; it exists for the end of a MATCH, where the question is asked again.
+     */
+    forgetInputs(): void;
+    /** Gamepad: the actions each pad (by index) holds this frame. The pad↔player assignment lives in `p.pad`. */
+    readonly padCur: Record<number, PadState>;
+    /** The previous frame's actions per pad — the edge is measured against it. */
+    readonly padPrevAct: Record<number, PadState>;
+    /** The previous frame's START per pad. */
+    readonly padPrevStart: Record<number, boolean>;
+    /**
+     * Is the player holding the action? keyboard (some code in the pl.ctrl scheme) OR the assigned pad (pl.pad).
+     * ⚠️ `?? []` and not a raw `pl.ctrl[act]`: since issue #118 a position the keyboard DOES NOT REACH is a declared
+     * `null`. Holding it is `false`, and the pad is asked right after: whoever has a pad reaches what their keyboard does not.
+     */
+    held(pl: HeldPlayer, act: Action): boolean;
+}
 /**
- * ⚠️ ESQUECER É UMA PORTA SEPARADA, E O `soltarTodas` NÃO A CHAMA — de propósito.
+ * BUILDS ONE ROOT'S INPUT STATE. Nothing is shared between two calls: that is the point (ADR-0232 D4, ADR-0142).
  *
- * O `blur` da janela solta as teclas porque elas deixaram mesmo de estar premidas. Mas a criança não trocou
- * de aparelho por mudar de separador: zerar o transporte em uso ali devolveria toda a gente ao teclado, e
- * quem joga por olhar perderia a alternância no meio da partida sem nada o dizer. Existe para o fim de uma
- * PARTIDA, onde a pergunta se põe de novo.
+ * ⚠️ THE CONTAINERS ARE CONSTANTS AND ARE MUTATED IN PLACE, as they were: the root, `input/keydown` and `input/gamepad`
+ * receive them once, and reassigning one would leave every reader holding the old object.
  */
-export declare function esquecerEntradas(): void;
-type PadState = Record<string, boolean>;
-export declare const padCur: Record<number, PadState>;
-export declare const padPrevAct: Record<number, PadState>;
-export declare const padPrevStart: Record<number, boolean>;
-export declare const PAD_DEAD = 0.5;
-type HeldPlayer = Pick<ControlledPlayer, 'ctrl' | 'pad'>;
-export declare const held: (pl: HeldPlayer, act: Action) => boolean;
+export declare function createInputState(): LiveInput;
 export {};

package/dist-pkg/input/state.js

@@ -1,139 +1,59 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// input/state.ts — ESTADO de input em runtime + query genérica, compartilhado pelos handlers (que ficam no
-// game.js e mutam estes objetos IN-PLACE): teclas seguradas (keys), estado de gamepad por controle
-// (padCur/padPrevAct/padPrevStart) e a zona morta do analógico (PAD_DEAD). held(pl,act) = o jogador está
-// segurando a ação, por teclado (pl.ctrl) OU pelo gamepad associado (pl.pad). Módulo-folha, ZERO deps. (Fase 2.22)
-// ⚠️ O cabeçalho deste módulo dizia «ZERO deps», e ele já tinha DUAS de tipo (`ControlledPlayer`, `Action`) —
-// a frase queria dizer «nada em tempo de execução», que continua verdade: os três imports são `type` e
-// desaparecem no build. A terceira entra pela mesma razão que as outras duas: o vocabulário mora com quem
-// tem as REGRAS sobre ele (`input/transporte-em-uso`), e repeti-lo aqui seria a segunda cópia de uma união.
-import { PADRAO, aposAresta, habilitarAssistida, desabilitarAssistida, } from './transporte-em-uso.js';
-export const keys = new Set();
+// The two above are type-only and vanish in the build. This one is not, and enters for the reason the vocabulary lives
+// where it does: with whoever has the RULES about it (`input/transport-in-use`, a leaf) — repeating it here would be a
+// second copy of a union.
+import { DEFAULT_INPUT_STATE, afterEdge, enableAssisted, disableAssisted, } from './transport-in-use.js';
 /**
- * A ORIGEM DE CADA TECLA SEGURADA — código → aparelho que a produziu (ADR-0109).
+ * BUILDS ONE ROOT'S INPUT STATE. Nothing is shared between two calls: that is the point (ADR-0232 D4, ADR-0142).
  *
- * ⚠️ ESTE MAPA EXISTE PORQUE `keys` APAGA A ORIGEM À PORTA, e foi essa erasão que deixou o §C da issue #114
- * por construir durante dois meses: o toque escreve códigos aqui dentro (`press()` faz
- * `heldKeys.add(codeFor(act))`) e a webcam despacha `KeyboardEvent` sintético, então quando o `held()`
- * responde já não há como saber QUEM carregou. O único transporte que sobrevivia identificável era o
- * gamepad, e só porque passa por `padCur` em vez do conjunto.
- *
- * ⚠️ CAMPO NOVO AO LADO DO VELHO, sincronizado num ponto só (`marcarTecla`/`soltarTecla`), com os leitores a
- * migrar um a um — é a forma que este repositório já usou no `p.visual` ao lado do `p.viz` (#104), e a razão
- * é a mesma: uma troca de uma vez não tem estado verde onde parar, e isto é a espinha da entrada.
- *
- * 📌 Um código SEM entrada aqui não é um erro de dados — é uma tecla que entrou por um escritor que ainda não
- * migrou. `origemDe` devolve `undefined` e quem pergunta decide; ver a nota lá.
- */
-export const origemDaTecla = new Map();
-/**
- * Uma tecla FOI SEGURADA, e sabe-se por quem. É o único sítio que escreve nos dois.
- *
- * ⚠️ OS DOIS JUNTOS OU NENHUM: enquanto forem duas estruturas, elas podem divergir, e uma divergência aqui é
- * silenciosa — o jogo continua a andar e só a alternância fica errada. Por isso não há `keys.add` público
- * neste módulo: quem escreve, escreve por aqui.
- */
-export function marcarTecla(code, origem) {
-    keys.add(code);
-    origemDaTecla.set(code, origem);
-}
-/**
- * A tecla foi segurada e NÃO SE SABE por quem. A porta estreita, e ela é estreita de propósito.
- *
- * ⚠️ POR QUE UMA FUNÇÃO COM OUTRO NOME E NÃO UM SEGUNDO PARÂMETRO OPCIONAL. `marcarTecla(code)` com a origem
- * omitida é o que se escreve quando não se pensou; `marcarTeclaSemOrigem(code)` é o que se escreve quando se
- * pensou e a resposta é «não sei». O tipo não distingue as duas, mas o nome distingue — e é o nome que
- * aparece na revisão. Um parâmetro esquecido não se lê; uma função assim chamada lê-se de longe.
- *
- * ⚠️ E O `delete` É A METADE QUE IMPORTA, não o `add`. Sem ele, uma tecla premida de novo por uma fonte
- * desconhecida HERDAVA a origem da vez anterior: a criança joga por olhar, larga a tecla, um script de fora
- * despacha o mesmo código, e a alternância continua a responder «olhos» a uma aresta que já não é dela. Um
- * mapa que guarda a resposta certa de ontem é pior do que um que não guarda nada.
- *
- * 📌 Hoje há UM chamador — o `input/keydown`, para o evento sintético que ninguém assinou. Depois desta
- * migração nada nesta engine produz um; quem produz é código de consumidor, e é para ele que esta porta fica
- * aberta. Fechá-la faria a tecla dele simplesmente não funcionar, o que é uma quebra pior do que não saber.
- */
-export function marcarTeclaSemOrigem(code) {
-    keys.add(code);
-    origemDaTecla.delete(code);
-}
-/** A outra metade. Solta nos dois, pela mesma razão. */
-export function soltarTecla(code) {
-    keys.delete(code);
-    origemDaTecla.delete(code);
-}
-/** Solta TUDO — o `blur` da janela. Os dois, ou o mapa fica a descrever teclas que já ninguém segura. */
-export function soltarTodas() {
-    keys.clear();
-    origemDaTecla.clear();
-}
-/**
- * Quem produziu esta tecla? `undefined` quando não se sabe.
- *
- * ⚠️ `undefined` E NÃO UM PADRÃO. Um padrão `'teclado'` faria a erasão voltar por outra porta: uma tecla do
- * toque que entrasse por um escritor não migrado seria lida como teclado, a alternância desligava-se, e nada
- * o diria. Não saber é uma resposta; fingir que se sabe não é.
- */
-export function origemDe(code) {
-    return origemDaTecla.get(code);
-}
-// ===================== O TRANSPORTE EM USO, POR JOGADOR (ADR-0109 · ADR-0113) =====================
-//
-// ⚠️ AQUI E NÃO NO `PlayerBase`, e a escolha é medida. O autómato responde «que aparelho está a produzir as
-// arestas deste jogador» — isso é estado de ENTRADA, e a entrada já guarda estado por jogador neste módulo
-// exactamente com esta forma: o `padCur` logo abaixo é um `Record<number, …>`. Pô-lo no `PlayerBase` faria
-// dele parte do CONTRATO, e trezentos cartuchos passariam a declarar um campo sobre o qual não decidem nada.
-//
-// 📌 O que o jogador CARREGA é a alternância resolvida (`toggleMove`), que é o que a física lê. Este mapa é
-// o que está a montante dela: com ele e com o `input/latch-store`, a resposta do ADR-0113 fica completa.
-const entradaPorJogador = {};
-/**
- * O ESTADO DA ENTRADA DESTE JOGADOR. Nunca `undefined`: quem nunca produziu uma aresta está no PADRÃO.
- *
- * ⚠️ `PADRAO` E NÃO `undefined`, pela mesma razão que o `origemDe` faz o contrário: ali «não sei» é uma
- * resposta honesta sobre uma tecla que já existe; aqui a pergunta é sobre um JOGADOR, e um jogador que
- * ainda não tocou em nada está mesmo no teclado sem assistida — que é o que `PADRAO` diz.
- */
-export function entradaDe(jogador) {
-    return entradaPorJogador[jogador] ?? PADRAO;
-}
-/**
- * UMA ARESTA DESTE JOGADOR CHEGOU, com a sua origem.
- *
- * 📌 O `aposAresta` devolve o MESMO objecto quando nada muda, então guardar de volta não aloca por quadro.
- * ⚠️ E uma aresta de um transporte assistido NÃO o habilita — essa regra vive no `aposAresta` e a razão
- * está lá: um falso positivo da webcam trancaria a alternância de toda a gente sem ninguém ter pedido.
- */
-export function arestaDoJogador(jogador, origem) {
-    entradaPorJogador[jogador] = aposAresta(entradaDe(jogador), origem);
-}
-/** Habilitar a assistida é um ACTO EXPLÍCITO (ADR-0109 regra 4), e por isso tem porta própria. */
-export function habilitarAssistidaDe(jogador) {
-    entradaPorJogador[jogador] = habilitarAssistida(entradaDe(jogador));
-}
-export function desabilitarAssistidaDe(jogador) {
-    entradaPorJogador[jogador] = desabilitarAssistida(entradaDe(jogador));
-}
-/**
- * ⚠️ ESQUECER É UMA PORTA SEPARADA, E O `soltarTodas` NÃO A CHAMA — de propósito.
- *
- * O `blur` da janela solta as teclas porque elas deixaram mesmo de estar premidas. Mas a criança não trocou
- * de aparelho por mudar de separador: zerar o transporte em uso ali devolveria toda a gente ao teclado, e
- * quem joga por olhar perderia a alternância no meio da partida sem nada o dizer. Existe para o fim de uma
- * PARTIDA, onde a pergunta se põe de novo.
+ * ⚠️ THE CONTAINERS ARE CONSTANTS AND ARE MUTATED IN PLACE, as they were: the root, `input/keydown` and `input/gamepad`
+ * receive them once, and reassigning one would leave every reader holding the old object.
  */
-export function esquecerEntradas() {
-    for (const k of Object.keys(entradaPorJogador))
-        delete entradaPorJogador[Number(k)];
+export function createInputState() {
+    const keys = new Set();
+    const keySource = new Map();
+    // ⚠️ HERE AND NOT ON `PlayerBase`: the automaton answers "which device is producing this player's edges" — INPUT
+    // state, kept per player in exactly the shape `padCur` has. On `PlayerBase` every cartridge would have to declare a
+    // field it decides nothing about.
+    const inputByPlayer = {};
+    const padCur = {};
+    const padPrevAct = {};
+    const padPrevStart = {};
+    function markKey(code, origin) {
+        keys.add(code);
+        keySource.set(code, origin);
+    }
+    function markKeyWithoutSource(code) {
+        keys.add(code);
+        keySource.delete(code);
+    }
+    function inputOf(player) {
+        return inputByPlayer[player] ?? DEFAULT_INPUT_STATE;
+    }
+    return {
+        keys, keySource, padCur, padPrevAct, padPrevStart,
+        markKey, markKeyWithoutSource,
+        markKeyFrom(code, source) { if (source)
+            markKey(code, source);
+        else
+            markKeyWithoutSource(code); },
+        releaseKey(code) { keys.delete(code); keySource.delete(code); },
+        releaseAllKeys() { keys.clear(); keySource.clear(); },
+        letGoOfTheKeyboard(release) {
+            for (const code of [...keys]) {
+                const source = keySource.get(code);
+                if (!source || source === 'teclado')
+                    release(code);
+            }
+        },
+        sourceOf: (code) => keySource.get(code),
+        inputOf,
+        // 📌 `afterEdge` returns the SAME object when nothing changes, so storing it back allocates nothing per frame.
+        playerEdge(player, origin) { inputByPlayer[player] = afterEdge(inputOf(player), origin); },
+        enableAssistedFor(player) { inputByPlayer[player] = enableAssisted(inputOf(player)); },
+        disableAssistedFor(player) { inputByPlayer[player] = disableAssisted(inputOf(player)); },
+        forgetInputs() { for (const k of Object.keys(inputByPlayer))
+            delete inputByPlayer[Number(k)]; },
+        held: (pl, act) => (pl.ctrl[act] ?? []).some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]),
+    };
 }
-export const padCur = {};
-export const padPrevAct = {};
-export const padPrevStart = {};
-export const PAD_DEAD = 0.5; // zona morta = primeira METADE do curso do analógico (ergonomia — José 2026-07-02)
-// Jogador está segurando a ação? teclado (algum code do esquema pl.ctrl) OU o gamepad associado (pl.pad).
-// ⚠️ `?? []` e não `pl.ctrl[act]` cru: desde a issue #118 uma posição que o teclado NÃO ALCANÇA é um `null`
-// declarado — num teclado partido por quatro não há lugar físico para ombros e gatilhos. Segurar uma ação
-// que o teclado não alcança é `false`, e o gamepad continua a ser perguntado logo a seguir: quem tem pad
-// alcança o que o teclado dele não alcança, que é o ponto de haver dois transportes.
-export const held = (pl, act) => (pl.ctrl[act] ?? []).some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]);

package/dist-pkg/input/switch-scan.d.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+/** The safe item: taking it commands nothing. Same word the gaze cycle uses, and the same job. */
+export declare const SCAN_CANCEL = "cancel";
+/** What a scan offers: the items it was given — positions in play, a menu's steps in a menu — and «cancel» in front. */
+export type ScanItem<T extends string = Action> = T | typeof SCAN_CANCEL;
+export interface SwitchScanOptions {
+    /** How long each item is offered. 1 s is the gaze cycle's step, which the Dev ran for a day (ADR-0213). */
+    readonly stepMs?: number;
+    /** How long the taken action stays pressed, so a game and a menu see a normal press and release. */
+    readonly pulseMs?: number;
+}
+export declare const SWITCH_SCAN_DEFAULTS: {
+    readonly stepMs: 1000;
+    readonly pulseMs: 400;
+};
+/**
+ * THE ENGINE'S OWN DOORS, and whether each has something behind it (ADR-0218 §3). A door with nothing behind it is not offered:
+ * a cycle never stops on a position that does nothing (ADR-0155).
+ */
+export interface ScanDoors {
+    /** The card SELECT opens is mounted. */
+    readonly menus: boolean;
+    /** The quick pause START opens has its bar — the menu the scan steps there, and «back» is how it is left. */
+    readonly quickPause: boolean;
+}
+/**
+ * What the scan offers IN PLAY after «cancel»: the game's named positions, then the doors in the order ADR-0218 §3 names them —
+ * the menus (SELECT), then the quick pause (START). Taking a door presses it on the virtual controller, which hands it to the
+ * engine as its keys are.
+ */
+export declare function playScanList(game: readonly Action[], doors: ScanDoors): readonly Action[];
+export interface ScanFrame {
+    /** Her switch went down on this frame. Whatever sends it — a key, a touch, a gesture, a word. */
+    readonly press?: boolean;
+}
+export interface ScanOutput<T extends string = Action> {
+    /** The item being pressed, for `pulseMs` after it was taken. */
+    readonly pressed: T | null;
+    /** The item taken on THIS frame — what a caller turns into a press. */
+    readonly commanded: T | null;
+    /** What is being offered right now, and where it sits in the list. Never `null`: something is always showing. */
+    readonly showing: {
+        readonly item: ScanItem<T>;
+        readonly index: number;
+    };
+}
+export interface SwitchScan<T extends string = Action> {
+    (nowMs: number, frame?: ScanFrame): ScanOutput<T>;
+}
+/**
+ * The scanner. `actions` is what is offered now — in play this game's declared positions and the engine's own doors, in a menu
+ * that menu's steps — and `cancel` is put in front of them.
+ *
+ * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
+ * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and
+ * here it would cost a child a full pass of fourteen items to reach the one thing that works.
+ */
+export declare function createSwitchScan<T extends string = Action>(actions: readonly T[], options?: SwitchScanOptions): SwitchScan<T>;

package/dist-pkg/input/switch-scan.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/switch-scan — PLAYING WITH ONE BUTTON: the machine offers, the child takes (ADR-0218, issue #201).
+//
+// The Dev, 2026-09-21: «vamos ciclar entre controle padrão > teclas de aderência > jogar com um botão só». This module is the
+// third position, and it answers a different question from the second one. Sticky keys are about HOW LONG a press lasts — the
+// child taps instead of holding, and still has to reach every position. This is about HOW MANY inputs exist in the world: with
+// one switch, fourteen positions cannot be reached at all, so the controller stops being fourteen places and becomes one place
+// plus TIME. It is scanning, the technique switch access has used since long before this engine.
+//
+// 🎯 THE FIRST ITEM IS «CANCEL», AND IT IS ALSO THE PROTECTION. A press that lands by accident has to be able to mean nothing;
+// and because the scan RESTARTS on cancel after every press, a hand that bounces twice takes cancel the second time. That is why
+// there is no dead time here: the restart already is one, and it costs the child nothing to explain.
+//
+// ⚠️ This module knows nothing about keys, switches or pixels. It is given a list and a clock, and it says what is showing and
+// what a press just took — the same division that let `input/gaze-cycle` be tested without a camera.
+//
+// MUTATIONS CHECKED: `tests/switch-scan.node.test.js`.
+/** The safe item: taking it commands nothing. Same word the gaze cycle uses, and the same job. */
+export const SCAN_CANCEL = 'cancel';
+export const SWITCH_SCAN_DEFAULTS = { stepMs: 1000, pulseMs: 400 };
+/**
+ * What the scan offers IN PLAY after «cancel»: the game's named positions, then the doors in the order ADR-0218 §3 names them —
+ * the menus (SELECT), then the quick pause (START). Taking a door presses it on the virtual controller, which hands it to the
+ * engine as its keys are.
+ */
+export function playScanList(game, doors) {
+    const list = [...game];
+    if (doors.menus)
+        list.push('select');
+    if (doors.quickPause)
+        list.push('start');
+    return list;
+}
+/**
+ * The scanner. `actions` is what is offered now — in play this game's declared positions and the engine's own doors, in a menu
+ * that menu's steps — and `cancel` is put in front of them.
+ *
+ * ⚠️ An empty list is not an error: a game that declared nothing leaves a scan of one item, `cancel`, and a press takes nothing.
+ * The alternative — offering the whole controller to a game that reads none of it — is the dead button ADR-0106 §5 refuses, and
+ * here it would cost a child a full pass of fourteen items to reach the one thing that works.
+ */
+export function createSwitchScan(actions, options = {}) {
+    const o = { ...SWITCH_SCAN_DEFAULTS, ...options };
+    const items = [SCAN_CANCEL, ...actions];
+    let startedAt = null;
+    let pressed = null, pressedAt = 0;
+    return (now, frame = {}) => {
+        startedAt ??= now;
+        const stepMs = Math.max(1, o.stepMs);
+        const index = items.length < 2 ? 0 : Math.floor((now - startedAt) / stepMs) % items.length;
+        let commanded = null;
+        if (frame.press) {
+            const item = items[index];
+            if (item !== SCAN_CANCEL) {
+                commanded = item;
+                pressed = item;
+                pressedAt = now;
+            }
+            // 📌 EVERY PRESS RESTARTS THE PASS, taken or not: the next thing offered is «cancel», never the neighbour of what she just
+            // took. Without it a second bounce of the same hand would take the item beside the one she chose.
+            startedAt = now;
+        }
+        if (pressed && now - pressedAt >= o.pulseMs)
+            pressed = null;
+        return { pressed, commanded, showing: { item: items[index], index } };
+    };
+}

package/dist-pkg/input/synthetic-source.d.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { TransportName } 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 declare const SOURCE_KEY = "__vpOrigem";
+/**
+ * The minimum this module reads from a key event — STRUCTURAL, so a real `KeyboardEvent` and a test double both serve.
+ *
+ * ⚠️ `isTrusted` is OPTIONAL, and its absence is not `false` by accident: a double that does not declare it is saying "I
+ * asserted nothing about this", and the right answer to that is `undefined`, not the keyboard. The same rule as
+ * `input/state`'s `sourceOf`, one layer up.
+ */
+export interface KeyEventLike {
+    readonly isTrusted?: boolean;
+}
+/**
+ * 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 declare function stampSource<T extends object>(ev: T, source: TransportName): T;
+/**
+ * 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 declare function sourceOfEvent(ev: KeyEventLike): TransportName | undefined;