@the-inclusionist/engine 7.0.1 → 8.0.0-rc.1

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

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Transporte } from './transporte-em-uso.js';
+import type { EmFracao } from './pointer-space.js';
+/**
+ * Onde o ponteiro está e o que ele está a fazer.
+ *
+ * `fx`/`fy` são fracção do elemento do jogo, na convenção do `pointer-space`: `0,0` é o canto superior
+ * esquerdo e `1,1` o inferior direito. ⚠️ Podem sair de `0..1` — ver `dentro`.
+ */
+export interface AmostraDoPonteiro {
+    readonly fx: number;
+    readonly fy: number;
+    /** Quem produziu esta amostra (ADR-0111). */
+    readonly origem: Transporte;
+    /** A «caneta» está em baixo? Rato: botão premido. Toque: dedo em contacto. Olhar: permanência. */
+    readonly apertado: boolean;
+}
+/** O repouso: centro da região, sem aperto, teclado — o mesmo padrão que o `transporte-em-uso` assume. */
+export declare const PADRAO: AmostraDoPonteiro;
+/**
+ * A amostra está DENTRO da região do jogo?
+ *
+ * ⚠️ ESTA PERGUNTA EXISTE SEPARADA DA POSIÇÃO, e é a decisão inteira deste ficheiro. O `emFracao` não satura
+ * de propósito («quem saturasse aqui não teria como voltar atrás»), e há duas coisas a jusante que precisam
+ * de metades opostas dela:
+ *
+ *   · DESENHAR precisa da posição PRESA a `0..1`, senão o traço salta para fora da tela quando a mão
+ *     ultrapassa a borda durante um arrasto capturado;
+ *   · o MODO OLHOS 3 do ADR-0104 usa «olhar para fora da tela» como comando de navegação — para uma criança
+ *     com ELA severa, olhar para cima FORA do écran é o gesto que abre a lista de acções.
+ *
+ * ⚠️ SATURAR SEM GUARDAR ESTA RESPOSTA MATARIA O SEGUNDO. É a mesma família de defeito que este repositório
+ * já pagou várias vezes: uma informação deitada fora à porta, e o consumidor que dela dependia a descobrir
+ * tarde que a pergunta já não tem resposta.
+ */
+export declare function dentro(f: EmFracao): boolean;
+/**
+ * A posição PRESA a `0..1`, para quem desenha.
+ *
+ * 📌 Devolve o MESMO objecto quando já está dentro, e não uma cópia. O ponteiro é amostrado a cada quadro, e
+ * uma alocação por quadro num aparelho de escola é exactamente o tipo de custo que o pilar 1 recusa.
+ */
+export declare function prender(f: EmFracao): EmFracao;
+/** A borda do aperto entre duas amostras: a caneta desceu, subiu, ou nada mudou. */
+export type BordaDoAperto = 'desceu' | 'subiu' | null;
+/**
+ * Comparar duas amostras dá a BORDA, que é o que um jogo lê.
+ *
+ * ⚠️ A BORDA E NÃO O ESTADO, pela razão que o `padPrevAct` deste repositório já escreve para o gamepad: um
+ * jogo que perguntasse «está apertado?» a cada quadro desenharia o mesmo ponto sessenta vezes, e um que
+ * quisesse reagir ao clique teria de guardar o quadro anterior por sua conta — trezentas vezes.
+ */
+export declare function bordaDoAperto(anterior: AmostraDoPonteiro, atual: AmostraDoPonteiro): BordaDoAperto;
+/**
+ * O TRANSPORTE MUDOU entre estas duas amostras?
+ *
+ * ⚠️ Existe porque o ADR-0109 faz da troca de aparelho um evento com consequência — a alternância segue o
+ * aparelho em uso —, e um ponteiro é um dos sítios onde a troca acontece sem que nenhuma tecla seja premida:
+ * a criança larga o rato e olha para a tela. Sem esta pergunta, a troca seria invisível até à próxima tecla.
+ */
+export declare function trocouDeTransporte(anterior: AmostraDoPonteiro, atual: AmostraDoPonteiro): boolean;

package/dist-pkg/input/pointer.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/pointer.ts — O QUE O JOGO RECEBE QUANDO PEDE UM PONTEIRO (ADR-0112), na metade PURA.
+//
+// ========================= O QUE ESTE MÓDULO É =========================
+// Uma AMOSTRA de ponteiro e as perguntas que se fazem sobre ela. Sem DOM, sem tempo, sem eventos. Quem captura
+// é `input/touch-bindings.wirePointerPad`, que a issue #105 mediu como já existindo inteiro; quem converte um
+// ponto de tela é `input/pointer-space`, que também já existe. Falta o que fica ENTRE os dois: a forma que
+// atravessa a fronteira até ao cartucho.
+//
+// ⚠️ E A AMOSTRA CARREGA A ORIGEM, porque o ADR-0111 diz que todo comando a carrega. Um traço feito com o
+// olhar e um traço feito com o rato têm de ser distinguíveis pela engine — as regras de transporte assistido
+// do ADR-0109 dependem de saber qual aparelho está em uso, e um desenho não é excepção.
+//
+// 📌 A ORIGEM É OBRIGATÓRIA AQUI, ao contrário do `origemDe` das teclas, que devolve `undefined`. A diferença
+// não é de rigor, é de estrutura: uma tecla entra num conjunto PARTILHADO onde qualquer código pode despachar
+// um evento sintético, então «não sei» é uma resposta honesta. Uma amostra de ponteiro é construída PELO
+// transporte que a produziu — ele sabe sempre o que é, porque é ele próprio.
+/** O repouso: centro da região, sem aperto, teclado — o mesmo padrão que o `transporte-em-uso` assume. */
+export const PADRAO = Object.freeze({ fx: 0.5, fy: 0.5, origem: 'teclado', apertado: false });
+/**
+ * A amostra está DENTRO da região do jogo?
+ *
+ * ⚠️ ESTA PERGUNTA EXISTE SEPARADA DA POSIÇÃO, e é a decisão inteira deste ficheiro. O `emFracao` não satura
+ * de propósito («quem saturasse aqui não teria como voltar atrás»), e há duas coisas a jusante que precisam
+ * de metades opostas dela:
+ *
+ *   · DESENHAR precisa da posição PRESA a `0..1`, senão o traço salta para fora da tela quando a mão
+ *     ultrapassa a borda durante um arrasto capturado;
+ *   · o MODO OLHOS 3 do ADR-0104 usa «olhar para fora da tela» como comando de navegação — para uma criança
+ *     com ELA severa, olhar para cima FORA do écran é o gesto que abre a lista de acções.
+ *
+ * ⚠️ SATURAR SEM GUARDAR ESTA RESPOSTA MATARIA O SEGUNDO. É a mesma família de defeito que este repositório
+ * já pagou várias vezes: uma informação deitada fora à porta, e o consumidor que dela dependia a descobrir
+ * tarde que a pergunta já não tem resposta.
+ */
+export function dentro(f) {
+    return f.fx >= 0 && f.fx <= 1 && f.fy >= 0 && f.fy <= 1;
+}
+/**
+ * A posição PRESA a `0..1`, para quem desenha.
+ *
+ * 📌 Devolve o MESMO objecto quando já está dentro, e não uma cópia. O ponteiro é amostrado a cada quadro, e
+ * uma alocação por quadro num aparelho de escola é exactamente o tipo de custo que o pilar 1 recusa.
+ */
+export function prender(f) {
+    if (dentro(f))
+        return f;
+    return { fx: Math.min(1, Math.max(0, f.fx)), fy: Math.min(1, Math.max(0, f.fy)) };
+}
+/**
+ * Comparar duas amostras dá a BORDA, que é o que um jogo lê.
+ *
+ * ⚠️ A BORDA E NÃO O ESTADO, pela razão que o `padPrevAct` deste repositório já escreve para o gamepad: um
+ * jogo que perguntasse «está apertado?» a cada quadro desenharia o mesmo ponto sessenta vezes, e um que
+ * quisesse reagir ao clique teria de guardar o quadro anterior por sua conta — trezentas vezes.
+ */
+export function bordaDoAperto(anterior, atual) {
+    if (anterior.apertado === atual.apertado)
+        return null;
+    return atual.apertado ? 'desceu' : 'subiu';
+}
+/**
+ * O TRANSPORTE MUDOU entre estas duas amostras?
+ *
+ * ⚠️ Existe porque o ADR-0109 faz da troca de aparelho um evento com consequência — a alternância segue o
+ * aparelho em uso —, e um ponteiro é um dos sítios onde a troca acontece sem que nenhuma tecla seja premida:
+ * a criança larga o rato e olha para a tela. Sem esta pergunta, a troca seria invisível até à próxima tecla.
+ */
+export function trocouDeTransporte(anterior, atual) {
+    return anterior.origem !== atual.origem;
+}

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

@@ -1,11 +1,96 @@
 // 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;
+/**
+ * ⚠️ 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.
+ */
+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: string) => boolean;
+export declare const held: (pl: HeldPlayer, act: Action) => boolean;
 export {};

package/dist-pkg/input/state.js

@@ -3,10 +3,137 @@
 // 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();
+/**
+ * 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 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.
+ */
+export function esquecerEntradas() {
+    for (const k of Object.keys(entradaPorJogador))
+        delete entradaPorJogador[Number(k)];
+}
 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).
-export const held = (pl, act) => pl.ctrl[act].some((k) => keys.has(k)) || (pl.pad >= 0 && !!padCur[pl.pad]?.[act]);
+// ⚠️ `?? []` 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/touch-bindings.d.ts

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Transporte } from './transporte-em-uso.js';
 import { type RectLike } from './pointer-space.js';
 import type { PlayerView } from '../core/entity.js';
 import type { DomQuery } from '../core/dom-query.js';
@@ -172,8 +173,16 @@ export interface TouchBindingsCtx {
     getControls: () => KeyScheme;
     /** o array vivo de jogadores. Getter: o main.js o repovoa a cada `restartGame`. */
     getPlayers: () => readonly TouchBindPlayer[];
-    /** `keys` de `input/state.ts`: `const` mutado in place → entra por VALOR (é sempre o mesmo objeto). */
-    heldKeys: Set<string>;
+    marcarTecla: (code: string, origem: Transporte) => void;
+    soltarTecla: (code: string) => void;
+    /**
+     * O conjunto para LER — a decisão pura pergunta que teclas já estão seguradas.
+     *
+     * ⚠️ `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.
+     */
+    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. */
     attractOnInput: () => boolean;

package/dist-pkg/input/touch-bindings.js

@@ -85,6 +85,10 @@
 /** `ui/dom.ts` `$` — injetado; o módulo nunca alcança `document`. */
 import { EDGE_BY_ACTION, edgeAllowed } from './edges.js';
 import { doCentro } from './pointer-space.js';
+// `isAction` guarda a porta: o `act` chega como string de um `data-` do markup de toque, e desde a #118 o
+// esquema só aceita as quatorze posições. Uma string que não é posição devolve `null` — o toque não faz nada,
+// que é exactamente o que o cabeçalho desta função já prometia.
+import { isAction } from '../core/actions.js';
 /* ===================== PURO (sem DOM — project node) ===================== */
 /**
  * Ação → borda, na MESMA ordem das outras duas cópias do projeto.
@@ -106,7 +110,7 @@ export function wantsForcedTouch(search) {
  * `null` = a ação não existe no esquema (ou o slot do mapa de toque está vazio) → o toque não faz nada.
  */
 export function codeForAction(act, controls) {
-    if (!act)
+    if (!act || !isAction(act))
         return null;
     const list = controls[act];
     return (list && list[0]) || null;
@@ -220,11 +224,13 @@ export function initTouchBindings(ctx) {
             return;
         }
         if (d.kind === 'release') {
-            ctx.heldKeys.delete(d.code);
+            ctx.soltarTecla(d.code);
             return;
         }
         if (d.addKey) {
-            ctx.heldKeys.add(d.code);
+            // ⚠️ `'toque'` é o carimbo, e é a regra 2 do ADR-0109 a tornar-se executável: é ESTE transporte cuja
+            // alternância liga. Enquanto o código entrava cru no conjunto, a regra não tinha como se aplicar.
+            ctx.marcarTecla(d.code, 'toque');
             const players = ctx.getPlayers();
             for (const { playerIndex, edge } of d.edges) {
                 const p = players[playerIndex];

package/dist-pkg/input/touch.js

@@ -135,7 +135,15 @@ export function initTouch(ctx) {
                 // ⚠️ A palavra falada é a MESMA que a lida: sai da mesma lista que acabou de montar o `<option>`.
                 // Antes vinham de tabelas diferentes e nada obrigava as duas a concordar.
                 const escolhida = ctx.acoesDoJogo().find((x) => x.acao === sel.value);
-                ctx.srSay(t('sr.touch.slotSet', { slot: label || t('touch.slot.fallback'), acao: escolhida ? escolhida.rotulo : sel.value }));
+                const nomeDoSlot = label || t('touch.slot.fallback');
+                // ⚠️ SEM PALAVRA DO JOGO, O ANÚNCIO PERDE A POSIÇÃO — NÃO RECUA PARA O ID. `sel.value` é o nome
+                // ABSTRATO (`action3`), e o ADR-0074 diz que ele nunca chega a uma pessoa; o `7742ac0` já pagou este
+                // defeito no ecrã de remapeamento e a saída é a mesma: uma chave própria que diz o que importa.
+                // 📌 O recuo é alcançável porque `acoesDoJogo()` é FUNÇÃO do cartucho, relida a cada `change`: num hub
+                // de atividades a lista muda por baixo e a `<option>` desenhada antes fica órfã.
+                ctx.srSay(escolhida
+                    ? t('sr.touch.slotSet', { slot: nomeDoSlot, acao: escolhida.rotulo })
+                    : t('sr.touch.slotSetUnnamed', { slot: nomeDoSlot }));
             });
         });
     }

package/dist-pkg/input/transporte-em-uso.d.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Os aparelhos por onde uma criança joga. Fechado: um transporte novo tem de decidir a sua regra aqui. */
+export type Transporte = 'teclado' | 'gamepad' | 'toque' | 'olhos' | 'rosto' | 'gestos' | 'fala';
+/**
+ * A UNIÃO COMO VALOR, porque há um sítio onde ela tem de ser verificada em runtime.
+ *
+ * ⚠️ EXISTE POR CAUSA DE UMA FRONTEIRA, e é a única razão que a justifica: o `input/origem-sintetica` lê o
+ * transporte de um EXPANDO pendurado num `KeyboardEvent` — um objecto que este código não construiu e que
+ * qualquer script da página pode construir. Um valor que atravessa essa fronteira não é um `Transporte` por
+ * o TypeScript o dizer; é uma `string` até alguém a conferir. Sem lista, `'olho'` entrava no mapa de origens
+ * como transporte fantasma, e nada o diria.
+ *
+ * 📌 Não é o defeito da lista-ao-lado-da-união que este repositório já desfez três vezes (o `RM_KEYS`, os
+ * rótulos de movimento reduzido, as chaves de armazenamento), porque a guarda abaixo é do COMPILADOR: as duas
+ * não podem divergir. Uma cópia que não pode divergir é uma projecção, não uma segunda fonte.
+ */
+export declare const TRANSPORTES: readonly ["teclado", "gamepad", "toque", "olhos", "rosto", "gestos", "fala"];
+/**
+ * Isto que veio de fora é mesmo um transporte?
+ *
+ * ⚠️ A pergunta não é de segurança — os scripts desta página são todos da casa, e quem quisesse mentir usaria
+ * um valor VÁLIDO. É de correcção: impede que um carimbo errado ou ausente vire uma entrada silenciosa no
+ * `origemDaTecla`, que é a estrutura de que a alternância inteira depende.
+ */
+export declare function ehTransporte(v: unknown): v is Transporte;
+/**
+ * OS QUATRO QUE EXIGEM HABILITAÇÃO EXPLÍCITA e, uma vez habilitados, mandam em todos (regra 4).
+ *
+ * ⚠️ É a mesma lista do `UM_COMANDO_DE_CADA_VEZ` do `input/latch-scope`, e a coincidência não é acaso: são
+ * os transportes de quem NÃO CONSEGUE SEGURAR NADA. O que o ADR-0109 acrescenta é que eles não ligam a
+ * alternância só para si — ligam-na para o resto, porque quem usa a webcam pode também tocar na tela, e uma
+ * alternância que se desliga ao mudar de aparelho é uma armadilha para exactamente essa pessoa.
+ */
+export declare const EXIGEM_HABILITACAO: ReadonlySet<Transporte>;
+/** O transporte que liga a alternância por si só, sem prioridade nenhuma envolvida (regra 2). */
+export declare const COM_ALTERNANCIA_PROPRIA: ReadonlySet<Transporte>;
+export interface EstadoDaEntrada {
+    /** Qual aparelho está a ser usado AGORA por este jogador. */
+    readonly emUso: Transporte;
+    /**
+     * A câmera/microfone foi habilitada? ⚠️ Uma vez `true`, NUNCA volta a `false` por uma aresta — só uma
+     * decisão explícita a desliga, e o ADR-0109 §4 diz que a criança não tem essa decisão. Ver `desabilitar`.
+     */
+    readonly assistidaLigada: boolean;
+}
+/**
+ * O ESTADO INICIAL: teclado, sem alternância.
+ *
+ * ⚠️ A regra 1 diz «controle E teclado, ambos sem alternância», e é por isso que o padrão pode nomear um só
+ * sem mentir: entre os dois a resposta à única pergunta que este módulo faz — há alternância? — é a MESMA.
+ * O `emUso` só passa a distingui-los quando alguém quiser MOSTRAR o aparelho corrente, que é outra questão
+ * e o ADR-0109 deixa-a explicitamente por decidir.
+ */
+export declare const PADRAO: EstadoDaEntrada;
+/**
+ * HÁ ALTERNÂNCIA AGORA? — ⚠️ **NÃO PERGUNTE ISTO A ESTA FUNÇÃO.** Ver o parágrafo abaixo.
+ *
+ * ⚠️ A prioridade da assistida vem PRIMEIRO, e a ordem é a regra 4 inteira: enquanto ela estiver ligada,
+ * nenhum outro aparelho a desliga — nem o teclado, que noutro caso a desligaria. Inverter estas duas linhas
+ * é o defeito que trancaria uma criança fora do próprio jogo, e é silencioso.
+ *
+ * @deprecated 🔴 **ESTA FUNÇÃO IMPLEMENTA O MODELO QUE O ADR-0113 SUPERSEDEU**, e fica exportada por ser
+ * superfície publicada (`./input/*.js`) e por o registo ter valor histórico — não por ser a resposta.
+ *
+ * O ADR-0109 decidia a alternância **só pelo aparelho**: assistida ligada → sim; toque → sim; todo o resto
+ * → não. O ADR-0113 retirou essa cláusula, com a razão do Dev: a alternância é um **caps-lock guardado com
+ * o mapeamento do controle**, e o valor que a criança gravou vale.
+ *
+ * 🔴 A DIVERGÊNCIA TEM UMA CRIANÇA CONCRETA, e é a que motivou o registo: quem tem dificuldade motora, joga
+ * no TECLADO e gravou a alternância ligada. Esta função devolve `false` para ela — `teclado` não está em
+ * `COM_ALTERNANCIA_PROPRIA` — e é exactamente o controle que lhe seria retirado. O `latch-scope.alternanciaDe`
+ * devolve `true`, porque lê o que ela gravou.
+ *
+ * ⚠️ E A CLÁUSULA DO TOQUE TAMBÉM CAIU: sob o ADR-0113 o toque é um transporte como os outros — o valor dele
+ * é escolha e fica guardado. Só olhos, rosto, gestos e fala podem recusar-se a DESLIGAR, e essa metade vive
+ * em `latch-scope.alternanciaSempreLigada`, com um conjunto diferente deste e a responder a outra pergunta.
+ *
+ * **A resposta certa é `latch-scope.alternanciaDe(estado.emUso, leitura)`.** O papel que sobra a este
+ * módulo é o que o nome dele diz: QUAL transporte está em uso — que é o que alimenta aquele primeiro
+ * argumento. `tests/alternancia-por-transporte.node.test.js` afirma que esta função continua sem consumidor.
+ */
+export declare function alternanciaAgora(estado: EstadoDaEntrada): boolean;
+/**
+ * UMA ARESTA CHEGOU, com a sua origem. Devolve o estado NOVO.
+ *
+ * ⚠️ Uma aresta de um transporte assistido NÃO o habilita. Habilitar é um acto explícito (regra 4: «precisam
+ * ser habilitados»), e deixar uma aresta fazê-lo significaria que um falso positivo da webcam — uma sombra,
+ * um segundo rosto a passar — trancava a alternância de toda a gente sem ninguém ter pedido.
+ */
+export declare function aposAresta(estado: EstadoDaEntrada, origem: Transporte): EstadoDaEntrada;
+/** A criança (ou quem a acompanha) habilitou câmera/microfone. Daqui em diante a alternância é lei. */
+export declare function habilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;
+/**
+ * DESABILITAR a assistida. Existe, e o ADR-0109 diz de quem é: NÃO é da criança durante a partida.
+ *
+ * ⚠️ Fica exportada porque desligar a câmera tem de ser possível em algum lugar — trocar de utilizador,
+ * fechar o jogo, um adulto a reconfigurar. O que o §4 proíbe é oferecê-la como um botão ao lado do jogo.
+ * Uma função que existe e não é oferecida é diferente de uma função que não existe: a primeira diz onde a
+ * decisão mora.
+ */
+export declare function desabilitarAssistida(estado: EstadoDaEntrada): EstadoDaEntrada;