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

package/dist-pkg/input/latch-edge.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type JogadorDaAlternancia } from './latch-sync.js';
+import type { ArmazemDaAlternancia } from './latch-store.js';
+import type { Transporte } from './transporte-em-uso.js';
+export interface ArestaComAlternanciaOpts {
+    /**
+     * O armazenamento. Injectável **para o gate**, e com padrão para o consumidor não poder esquecê-lo.
+     *
+     * ⚠️ Padrão e não campo obrigatório, e a razão é a mesma do `ui/pause-icons`: um armazém injectado é uma
+     * coisa que um cartucho pode omitir, e omiti-la faria a criança perder a escolha guardada — em silêncio, e
+     * só naquele jogo.
+     */
+    readonly armazem?: ArmazemDaAlternancia;
+    /** O padrão de fábrica. `DEFAULTS.toggleMove`, e não `false` escrito à mão: há UMA fonte (ADR-0029). */
+    readonly padrao?: boolean;
+}
+/**
+ * DEVOLVE O `arestaDoJogador` QUE TAMBÉM RESOLVE A ALTERNÂNCIA — para passar a `initKeydown` e a
+ * `initTouchBindings` no lugar do cru.
+ *
+ * ⚠️ RESOLVE CONTRA `entradaDe(jogador).emUso` E NÃO CONTRA `origem`, e a distinção é de desenho e não de
+ * comportamento: hoje o `aposAresta` põe sempre `emUso = origem`, logo trocar uma pela outra é uma mutação
+ * EQUIVALENTE — está registada como tal no gate, em vez de fingir cobertura. O que a escolha compra é o
+ * futuro: quem decide que aparelho está em uso é o autómato, e o dia em que ele ganhar uma regra que RECUSE
+ * uma aresta (um falso positivo da webcam a ser filtrado, por exemplo) esta linha segue-o sem ser editada.
+ * Ler `origem` seria uma segunda resposta à pergunta que o `input/transporte-em-uso` existe para responder.
+ */
+export declare function criarArestaComAlternancia(getPlayers: () => readonly (JogadorDaAlternancia | null | undefined)[], opts?: ArestaComAlternanciaOpts): (jogador: number, origem: Transporte) => void;

package/dist-pkg/input/latch-edge.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/latch-edge.ts — A ARESTA E A ALTERNÂNCIA, NUMA FUNÇÃO SÓ (ADR-0113, issue #127).
+//
+// ========================= POR QUE O PAR NÃO PODE SEPARAR-SE =========================
+// Registar de que aparelho veio a aresta e resolver a alternância desse aparelho são duas metades de UM
+// acontecimento: a criança mudou de controle. Feitas em sítios diferentes, a segunda pode faltar — e o
+// resultado é a forma de defeito que este projecto já pagou várias vezes: o autómato sabe que ela pegou no
+// controle, e o jogo continua a andar com a alternância do teclado. Sem erro, e só ela dá por isso.
+//
+// 📌 É o mesmo movimento do `consumir` no `ui/menu-nav` («uma função só para o par nunca se separar») e da
+// escrita dupla no `ui/settings-motor`.
+//
+// ⚠️ E É UMA FÁBRICA, NÃO UM CAMPO NOVO NO CONTEXTO DE CADA MÓDULO DE ENTRADA. O `input/keydown` e o
+// `input/touch-bindings` já recebem `arestaDoJogador(jogador, origem)`; esta função devolve uma com essa
+// mesma assinatura, e por isso a fiação passa a estar certa sem nenhum dos dois saber que a alternância
+// existe. Um segundo campo obrigatório em dois contextos seria mais superfície pública, mais uma coisa que um
+// cartucho pode esquecer, e a mesma pergunta feita duas vezes.
+import * as store from '../platform/storage.js';
+import { DEFAULTS } from '../core/state.js';
+import { arestaDoJogador, entradaDe } from './state.js';
+import { sincronizarAlternancia } from './latch-sync.js';
+/**
+ * DEVOLVE O `arestaDoJogador` QUE TAMBÉM RESOLVE A ALTERNÂNCIA — para passar a `initKeydown` e a
+ * `initTouchBindings` no lugar do cru.
+ *
+ * ⚠️ RESOLVE CONTRA `entradaDe(jogador).emUso` E NÃO CONTRA `origem`, e a distinção é de desenho e não de
+ * comportamento: hoje o `aposAresta` põe sempre `emUso = origem`, logo trocar uma pela outra é uma mutação
+ * EQUIVALENTE — está registada como tal no gate, em vez de fingir cobertura. O que a escolha compra é o
+ * futuro: quem decide que aparelho está em uso é o autómato, e o dia em que ele ganhar uma regra que RECUSE
+ * uma aresta (um falso positivo da webcam a ser filtrado, por exemplo) esta linha segue-o sem ser editada.
+ * Ler `origem` seria uma segunda resposta à pergunta que o `input/transporte-em-uso` existe para responder.
+ */
+export function criarArestaComAlternancia(getPlayers, opts = {}) {
+    const armazem = opts.armazem ?? store;
+    const padrao = opts.padrao ?? DEFAULTS.toggleMove;
+    return (jogador, origem) => {
+        arestaDoJogador(jogador, origem);
+        // 📌 O JOGADOR PODE NÃO EXISTIR — uma tela em espera, um assento que ainda não entrou —, e isso não torna
+        // a aresta inválida: o transporte em uso é facto sobre a ENTRADA e fica registado à mesma. O que não
+        // acontece é a segunda metade, porque não há onde a escrever.
+        const p = getPlayers()[jogador];
+        if (p)
+            sincronizarAlternancia(p, armazem, jogador, entradaDe(jogador).emUso, padrao);
+    };
+}

package/dist-pkg/input/latch-scope.d.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Os transportes que emitem UM COMANDO DE CADA VEZ, e em que a alternância está sempre ligada.
+ *
+ * Os nomes são os que a barra rápida já usa para os ícones (`face`, `eyes`, `voice`), mais `gestos`, que é o
+ * quarto que o ADR-0104 §C nomeia. Ficam em português como o resto do vocabulário de transporte
+ * (`teclado`, `toque`) — `transportesPadrao` já mistura, e mudar isso é outra conversa.
+ */
+export declare const UM_COMANDO_DE_CADA_VEZ: ReadonlySet<string>;
+/**
+ * Neste transporte a alternância está sempre ligada?
+ *
+ * ⚠️ «Sempre ligada» e «ligada por omissão» são coisas diferentes, e a diferença é a que o ADR-0104 §C faz:
+ * um padrão pode ser mudado, e mudá-lo aqui deixaria o controle inutilizável. Por isso o valor guardado nem
+ * chega a ser lido nestes transportes — ver `alternanciaDe`.
+ */
+export declare function alternanciaSempreLigada(transporte: string): boolean;
+/**
+ * A opção deve ser OFERECIDA para este transporte?
+ *
+ * O contrário de `alternanciaSempreLigada`, e existe com nome próprio porque quem pergunta é outro: um
+ * chama para decidir o estado, o outro para decidir se desenha o botão. Um painel que desenhasse o botão e
+ * ignorasse o clique seria pior do que não o desenhar.
+ */
+export declare function alternanciaEhEscolha(transporte: string): boolean;
+/**
+ * A chave de armazenamento da alternância, agora com o transporte no nome.
+ *
+ * ⚠️ FUNÇÃO, e não concatenação no ponto de uso, pela razão que o `platform/storage` já escreveu sobre as
+ * chaves por jogador: «virar função aqui é o que impede que um deles escreva num nome torto». Não é
+ * hipótese — o `ui/settings-motor` reescrevia `'incl_togglerun_p' + i` à mão, com um comentário ao lado a
+ * dizer «== toggleRunP de platform/storage». Duas cópias de um nome mudam uma de cada vez.
+ *
+ * `base` é `togglemove` ou `togglerun`, os dois nomes que já existem no armazenamento da criança.
+ */
+export declare function chaveDaAlternancia(base: string, jogador: number, transporte: string): string;
+/**
+ * A chave ANTIGA, por jogador e sem transporte. Continua a ser lida, e nunca mais escrita.
+ *
+ * ⚠️ ELA HERDA PARA TODOS OS TRANSPORTES, e a escolha custa uma frase a explicar. O valor velho foi posto
+ * pela criança nalgum contexto, e não há como saber qual — a chave não o registava, que é o defeito. As
+ * saídas eram três: perder o ajuste dela, adivinhar um transporte, ou herdar para todos. Herdar para todos é
+ * a única que não tira nada a quem depende do ajuste, e o vazamento que ela mantém dura só até a criança
+ * mexer no assunto uma vez em cada aparelho. Perder o ajuste custaria mais, e a quem menos pode pagar.
+ *
+ * É também o padrão que este repositório já escolheu para este mesmo valor: o `KEYS.toggleMoveLegacy` existe
+ * desde a migração anterior, e a nota do `platform/storage` diz porquê — «a chave velha fica onde está: é
+ * dado da criança, não meu para apagar, e a sua permanência é o que torna um retorno possível».
+ */
+export declare function chaveLegadaDaAlternancia(base: string, jogador: number): string;
+/** O que se sabe ao resolver a alternância de um transporte. */
+export interface LeituraDaAlternancia {
+    /** O que está guardado para ESTE transporte. `null` = nunca foi escrito. */
+    readonly doTransporte: boolean | null;
+    /** O que está guardado na chave antiga, sem transporte. `null` = nunca foi escrito. */
+    readonly doLegado: boolean | null;
+    /** O padrão de fábrica (`DEFAULTS.toggleMove` / `DEFAULTS.toggleRun`). */
+    readonly padrao: boolean;
+}
+/**
+ * A alternância deste transporte, resolvida.
+ *
+ * A ordem é: transporte de um comando → SEMPRE ligada, e nem se lê o resto · valor deste transporte · valor
+ * legado · padrão de fábrica.
+ *
+ * ⚠️ O TRANSPORTE DE UM COMANDO VEM PRIMEIRO, e não por atalho: se ele lesse o guardado primeiro, uma
+ * criança que tivesse desligado a alternância no teclado herdaria esse `false` pelo legado e ficaria com um
+ * controle de olhar que não responde — o pior defeito possível, no controle de quem tem menos alternativas.
+ */
+export declare function alternanciaDe(transporte: string, l: LeituraDaAlternancia): boolean;

package/dist-pkg/input/latch-scope.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/latch-scope — A ALTERNÂNCIA É DE UM TRANSPORTE, e não da criança (ADR-0104 §C, issue #114).
+//
+// ========================= O DEFEITO QUE ISTO CONSERTA, E ELE NÃO TINHA NOME =========================
+// «Segurar vira alternar» estava guardado POR JOGADOR — `incl_togglemove_p0` —, o que quer dizer: por
+// pessoa, e para todos os aparelhos ao mesmo tempo. Uma criança que liga a alternância no controle de TELA,
+// porque num botão virtual ninguém segura com conforto, liga-a também no teclado, onde segurar uma tecla é
+// exactamente o que ela sabe fazer. Ela não pediu isso e nada lho diz.
+//
+// ⚠️ E O REPOSITÓRIO JÁ CONHECIA O DEFEITO SEM O NOMEAR: o `core/state` traz a nota «a alternância do botão
+// de CORRER nasce desligada de FÁBRICA — e liga sozinha no controle de tela, que é CONTEXTO e não escolha».
+// Contexto é precisamente a palavra: o valor depende do aparelho em que a criança está. Guardá-lo por pessoa
+// obrigava a distinguir «ligou porque quis» de «ligou porque é toque» com uma marca à parte (o ADR-0029), e
+// essa marca existia para compensar uma chave que estava no escopo errado.
+//
+// O mapeamento de teclas já se guarda por transporte, e sempre se guardou. Esta é a mesma coisa.
+//
+// ========================= E PARA QUATRO TRANSPORTES ELA NÃO É ESCOLHA NENHUMA =========================
+// ⚠️ Olhos, rosto, gestos e fala emitem UM COMANDO DE CADA VEZ. Não há como olhar para a esquerda e para o
+// botão de pular ao mesmo tempo; não há como dizer duas palavras em simultâneo. Neles a alternância não é
+// preferência — é a única forma de o controle funcionar, e oferecê-la como opção seria oferecer a uma
+// criança a escolha de um controle que não funciona.
+//
+// Isto resolve, de passagem, uma tensão que o ADR-0084 tinha contra a sua própria regra «valor salvo
+// significa escolha»: a alternância a ligar-se sozinha na webcam era uma excepção àquela regra. Deixa de
+// ser, porque nestes transportes ela nunca foi um valor salvo — é uma propriedade do transporte.
+//
+// ⚠️ OS QUATRO AINDA NÃO EXISTEM COMO TRANSPORTE, e a regra fica escrita à mesma. Medido em 2026-09-08: o
+// `transportesPadrao` devolve três (gamepad, teclado, toque), e o `ui/webcam` sintetiza `KeyboardEvent` — do
+// ponto de vista da engine, ele É o teclado. Os três ícones da barra rápida dizem-no: `face`, `eyes` e
+// `voice` estão marcados `soon`. Escrever a regra agora custa nada e faz com que eles cheguem COBERTOS, em
+// vez de chegarem a uma excepção que alguém terá de se lembrar de abrir.
+//
+// Módulo-folha: não importa nada, nem sequer o `platform/storage` cujas chaves ele monta.
+/**
+ * Os transportes que emitem UM COMANDO DE CADA VEZ, e em que a alternância está sempre ligada.
+ *
+ * Os nomes são os que a barra rápida já usa para os ícones (`face`, `eyes`, `voice`), mais `gestos`, que é o
+ * quarto que o ADR-0104 §C nomeia. Ficam em português como o resto do vocabulário de transporte
+ * (`teclado`, `toque`) — `transportesPadrao` já mistura, e mudar isso é outra conversa.
+ */
+export const UM_COMANDO_DE_CADA_VEZ = new Set(['olhos', 'rosto', 'gestos', 'fala']);
+/**
+ * Neste transporte a alternância está sempre ligada?
+ *
+ * ⚠️ «Sempre ligada» e «ligada por omissão» são coisas diferentes, e a diferença é a que o ADR-0104 §C faz:
+ * um padrão pode ser mudado, e mudá-lo aqui deixaria o controle inutilizável. Por isso o valor guardado nem
+ * chega a ser lido nestes transportes — ver `alternanciaDe`.
+ */
+export function alternanciaSempreLigada(transporte) {
+    return UM_COMANDO_DE_CADA_VEZ.has(transporte);
+}
+/**
+ * A opção deve ser OFERECIDA para este transporte?
+ *
+ * O contrário de `alternanciaSempreLigada`, e existe com nome próprio porque quem pergunta é outro: um
+ * chama para decidir o estado, o outro para decidir se desenha o botão. Um painel que desenhasse o botão e
+ * ignorasse o clique seria pior do que não o desenhar.
+ */
+export function alternanciaEhEscolha(transporte) {
+    return !alternanciaSempreLigada(transporte);
+}
+/**
+ * A chave de armazenamento da alternância, agora com o transporte no nome.
+ *
+ * ⚠️ FUNÇÃO, e não concatenação no ponto de uso, pela razão que o `platform/storage` já escreveu sobre as
+ * chaves por jogador: «virar função aqui é o que impede que um deles escreva num nome torto». Não é
+ * hipótese — o `ui/settings-motor` reescrevia `'incl_togglerun_p' + i` à mão, com um comentário ao lado a
+ * dizer «== toggleRunP de platform/storage». Duas cópias de um nome mudam uma de cada vez.
+ *
+ * `base` é `togglemove` ou `togglerun`, os dois nomes que já existem no armazenamento da criança.
+ */
+export function chaveDaAlternancia(base, jogador, transporte) {
+    return `incl_${base}_p${jogador}_${transporte}`;
+}
+/**
+ * A chave ANTIGA, por jogador e sem transporte. Continua a ser lida, e nunca mais escrita.
+ *
+ * ⚠️ ELA HERDA PARA TODOS OS TRANSPORTES, e a escolha custa uma frase a explicar. O valor velho foi posto
+ * pela criança nalgum contexto, e não há como saber qual — a chave não o registava, que é o defeito. As
+ * saídas eram três: perder o ajuste dela, adivinhar um transporte, ou herdar para todos. Herdar para todos é
+ * a única que não tira nada a quem depende do ajuste, e o vazamento que ela mantém dura só até a criança
+ * mexer no assunto uma vez em cada aparelho. Perder o ajuste custaria mais, e a quem menos pode pagar.
+ *
+ * É também o padrão que este repositório já escolheu para este mesmo valor: o `KEYS.toggleMoveLegacy` existe
+ * desde a migração anterior, e a nota do `platform/storage` diz porquê — «a chave velha fica onde está: é
+ * dado da criança, não meu para apagar, e a sua permanência é o que torna um retorno possível».
+ */
+export function chaveLegadaDaAlternancia(base, jogador) {
+    return `incl_${base}_p${jogador}`;
+}
+/**
+ * A alternância deste transporte, resolvida.
+ *
+ * A ordem é: transporte de um comando → SEMPRE ligada, e nem se lê o resto · valor deste transporte · valor
+ * legado · padrão de fábrica.
+ *
+ * ⚠️ O TRANSPORTE DE UM COMANDO VEM PRIMEIRO, e não por atalho: se ele lesse o guardado primeiro, uma
+ * criança que tivesse desligado a alternância no teclado herdaria esse `false` pelo legado e ficaria com um
+ * controle de olhar que não responde — o pior defeito possível, no controle de quem tem menos alternativas.
+ */
+export function alternanciaDe(transporte, l) {
+    if (alternanciaSempreLigada(transporte))
+        return true;
+    if (l.doTransporte !== null)
+        return l.doTransporte;
+    if (l.doLegado !== null)
+        return l.doLegado;
+    return l.padrao;
+}

package/dist-pkg/input/latch-store.d.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type LeituraDaAlternancia } from './latch-scope.js';
+/** O mínimo do `platform/storage` que isto precisa. Injectado, para o gate não precisar de um navegador. */
+export interface ArmazemDaAlternancia {
+    /** ⚠️ O CRU, e não `getBool`. Ver `lerTriEstado`. */
+    get(chave: string, padrao?: null): string | null;
+    set(chave: string, valor: string): void;
+}
+/**
+ * TRÊS ESTADOS E NÃO DOIS: `true`, `false`, e NUNCA ESCRITO.
+ *
+ * 🔴 ESTA FUNÇÃO EXISTE PARA NÃO SE USAR `getBool`, e a diferença custa o ajuste de uma criança. O `getBool`
+ * colapsa «nunca escrito» em `false`. Com ele, o `doTransporte` de uma criança que nunca mexeu neste aparelho
+ * chegaria à regra como `false` — e a regra responde na PRIMEIRA linha que encontra um valor, logo devolveria
+ * `false` e **nunca consultaria a chave legada**, que é onde vive o ajuste que ela já tinha.
+ *
+ * ⚠️ É por isso que o `latch-scope` tipa os dois campos como `boolean | null` e tem um caso próprio a dizer
+ * que «`false` guardado é um VALOR, e não uma ausência». Este é o lado do armazenamento da mesma frase.
+ */
+export declare function lerTriEstado(armazem: ArmazemDaAlternancia, chave: string): boolean | null;
+/**
+ * A LEITURA COMPLETA que a regra pede, montada a partir do armazenamento.
+ *
+ * `base` é `togglemove` ou `togglerun` — os dois nomes que já existem no armazenamento da criança.
+ */
+export declare function leituraDaAlternancia(armazem: ArmazemDaAlternancia, base: string, jogador: number, transporte: string, padrao: boolean): LeituraDaAlternancia;
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR NESTE TRANSPORTE — a pergunta inteira, numa chamada.
+ *
+ * 📌 TROCAR DE TRANSPORTE TROCA A RESPOSTA SEM ESCREVER NADA, que é a cláusula 1 do ADR-0113 em código: o
+ * valor pertence ao mapeamento do controle, como um caps-lock, e mudar de controle é mudar de mapeamento.
+ */
+export declare function alternanciaGuardada(armazem: ArmazemDaAlternancia, base: string, jogador: number, transporte: string, padrao: boolean): boolean;
+/**
+ * GRAVA A ESCOLHA DA CRIANÇA para o transporte em uso. Devolve se gravou.
+ *
+ * ⚠️ RECUSA NOS TRANSPORTES DE UM COMANDO, e a recusa é um `false` devolvido e não um lançamento: em olhos,
+ * rosto, gestos e fala a alternância é o que faz a entrada funcionar (ADR-0113 cláusula 3), então não há
+ * escolha a gravar. Quem chama usa a resposta para DESABILITAR o controle COM MOTIVO — que é a metade que
+ * falta e que vive na interface, não aqui.
+ *
+ * 📌 Gravar mesmo assim seria pior do que inútil: a criança mexeria no ícone, o valor iria para o disco, e o
+ * jogo continuaria a ignorá-lo — um controle que mente sobre ter funcionado.
+ */
+export declare function gravarAlternancia(escrever: (chave: string, ligada: boolean) => void, base: string, jogador: number, transporte: string, ligada: boolean): boolean;

package/dist-pkg/input/latch-store.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/latch-store.ts — A ALTERNÂNCIA, LIDA E ESCRITA NO ARMAZENAMENTO (ADR-0113).
+//
+// ========================= O QUE ESTE MÓDULO É, E POR QUE É SEPARADO =========================
+// O `input/latch-scope` é a REGRA e não toca em nada: recebe uma `LeituraDaAlternancia` já feita e responde.
+// Este módulo é a única coisa que faltava entre ela e o mundo — quem vai ao armazenamento buscar os três
+// valores que a regra pede, e quem grava o que a criança escolhe.
+//
+// 📌 SEPARADO DE PROPÓSITO, e não por arrumação: a regra é pura e tem gate próprio; misturar armazenamento
+// dentro dela obrigaria todo caso da regra a montar um `localStorage` de mentira para afirmar uma coisa que
+// não depende dele. É a mesma divisão que o `render/viz-axes` (modelo) e o `render/viz-setters` (escrita)
+// já fazem neste repositório.
+//
+// ⚠️ E O QUE ELE NÃO FAZ: não sabe QUAL transporte está em uso. Isso é do `input/transporte-em-uso`, e chega
+// aqui como argumento. Um módulo de armazenamento que adivinhasse o transporte escreveria a escolha de uma
+// criança na chave de outro aparelho — em silêncio, que é o defeito que o ADR-0113 existe para evitar.
+import { chaveDaAlternancia, chaveLegadaDaAlternancia, alternanciaDe, alternanciaEhEscolha, } from './latch-scope.js';
+/**
+ * TRÊS ESTADOS E NÃO DOIS: `true`, `false`, e NUNCA ESCRITO.
+ *
+ * 🔴 ESTA FUNÇÃO EXISTE PARA NÃO SE USAR `getBool`, e a diferença custa o ajuste de uma criança. O `getBool`
+ * colapsa «nunca escrito» em `false`. Com ele, o `doTransporte` de uma criança que nunca mexeu neste aparelho
+ * chegaria à regra como `false` — e a regra responde na PRIMEIRA linha que encontra um valor, logo devolveria
+ * `false` e **nunca consultaria a chave legada**, que é onde vive o ajuste que ela já tinha.
+ *
+ * ⚠️ É por isso que o `latch-scope` tipa os dois campos como `boolean | null` e tem um caso próprio a dizer
+ * que «`false` guardado é um VALOR, e não uma ausência». Este é o lado do armazenamento da mesma frase.
+ */
+export function lerTriEstado(armazem, chave) {
+    const v = armazem.get(chave, null);
+    return v == null ? null : v === '1';
+}
+/**
+ * A LEITURA COMPLETA que a regra pede, montada a partir do armazenamento.
+ *
+ * `base` é `togglemove` ou `togglerun` — os dois nomes que já existem no armazenamento da criança.
+ */
+export function leituraDaAlternancia(armazem, base, jogador, transporte, padrao) {
+    return {
+        doTransporte: lerTriEstado(armazem, chaveDaAlternancia(base, jogador, transporte)),
+        doLegado: lerTriEstado(armazem, chaveLegadaDaAlternancia(base, jogador)),
+        padrao,
+    };
+}
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR NESTE TRANSPORTE — a pergunta inteira, numa chamada.
+ *
+ * 📌 TROCAR DE TRANSPORTE TROCA A RESPOSTA SEM ESCREVER NADA, que é a cláusula 1 do ADR-0113 em código: o
+ * valor pertence ao mapeamento do controle, como um caps-lock, e mudar de controle é mudar de mapeamento.
+ */
+export function alternanciaGuardada(armazem, base, jogador, transporte, padrao) {
+    return alternanciaDe(transporte, leituraDaAlternancia(armazem, base, jogador, transporte, padrao));
+}
+/**
+ * GRAVA A ESCOLHA DA CRIANÇA para o transporte em uso. Devolve se gravou.
+ *
+ * ⚠️ RECUSA NOS TRANSPORTES DE UM COMANDO, e a recusa é um `false` devolvido e não um lançamento: em olhos,
+ * rosto, gestos e fala a alternância é o que faz a entrada funcionar (ADR-0113 cláusula 3), então não há
+ * escolha a gravar. Quem chama usa a resposta para DESABILITAR o controle COM MOTIVO — que é a metade que
+ * falta e que vive na interface, não aqui.
+ *
+ * 📌 Gravar mesmo assim seria pior do que inútil: a criança mexeria no ícone, o valor iria para o disco, e o
+ * jogo continuaria a ignorá-lo — um controle que mente sobre ter funcionado.
+ */
+// ⚠️ RECEBE O ESCRITOR E NÃO UM ARMAZÉM, e a mudança é de 2026-09-08, quando o painel foi ligar-se a isto.
+// O `ui/settings-motor` já tem um `store: { setBool }` injectado — exigir-lhe um objecto com `get`/`set`
+// crus obrigaria a inventar um adaptador no ponto de uso, e um adaptador ali é onde uma segunda forma de
+// escrever a mesma chave nasce. Uma função é o mínimo que a escrita precisa.
+export function gravarAlternancia(escrever, base, jogador, transporte, ligada) {
+    if (!alternanciaEhEscolha(transporte))
+        return false;
+    escrever(chaveDaAlternancia(base, jogador, transporte), ligada);
+    return true;
+}

package/dist-pkg/input/latch-sync.d.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import { type ArmazemDaAlternancia } from './latch-store.js';
+/**
+ * O MÍNIMO DO JOGADOR que a alternância toca — dois campos, e nenhum deles é do contrato do jogo.
+ *
+ * 📌 `PlayerView` e não `PlayerBase`: este módulo não tem nada que fazer com sprites, física ou câmara, e um
+ * tipo largo aqui faria um gate precisar de um jogador inteiro de mentira para afirmar duas linhas.
+ *
+ * ⚠️ E ELE MUDOU DE CASA EM VEZ DE NASCER SEGUNDO. Esta linha existia, palavra por palavra, no
+ * `ui/settings-motor` — e escrevê-la aqui outra vez seria a segunda cópia de um tipo, que é o defeito que
+ * este repositório já pagou dezasseis vezes com o `DomQuery`. O painel passou a publicá-la por ALIAS, para o
+ * retrato de nomes não a ler como removida.
+ */
+export type JogadorDaAlternancia = PlayerView<'toggleMove' | 'walkDir'>;
+/**
+ * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ *
+ * ⚠️ A IRMÃ (`togglerun`, a alternância de CORRER) NÃO ENTRA AQUI HOJE, e a ausência é declarada em vez de
+ * esquecida: `p.toggleRun` tem um leitor de RODADA no cartucho (`game/run-toggle`), com uma trava própria que
+ * diz se está a correr AGORA — o `walkDir = 0` daqui não é o gesto certo para ela, e inventar-lhe um sem o
+ * leitor à frente seria decidir por um jogo que não abri. O `input/latch-store` já aceita a base como
+ * argumento, então quando ela entrar entra sem uma segunda forma da mesma pergunta.
+ */
+export declare const BASE_DA_MARCHA = "togglemove";
+/**
+ * PÕE A ALTERNÂNCIA DE MARCHA NO JOGADOR, com a regra que a acompanha. Devolve se MUDOU alguma coisa.
+ *
+ * ⚠️ O `walkDir = 0` só corre quando a alternância CAI. Zerá-lo em toda chamada tiraria a direcção a quem
+ * está a andar, uma vez por aresta — que é o defeito ao contrário, e mais frequente.
+ *
+ * 📌 Devolver «mudou» não é conveniência: quem chama na aresta corre isto muitas vezes por segundo, e anunciar
+ * ou reflectir a cada chamada encheria o leitor de tela com a mesma frase.
+ */
+export declare function aplicarAlternancia(p: JogadorDaAlternancia, ligada: boolean): boolean;
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ *
+ * É a cláusula 1 do ADR-0113 em código, e a propriedade que ela promete é NEGATIVA: chamar isto ao trocar de
+ * aparelho troca a resposta **sem escrever no armazenamento**. Um `sincronizar` que gravasse o valor resolvido
+ * apagaria, na primeira aresta, a escolha que a criança fez no outro controle.
+ *
+ * ⚠️ E NOS QUATRO ASSISTIDOS ELE RESPONDE `true` SEM CONSULTAR NADA — a regra vive no `latch-scope` e a razão
+ * está lá: em olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar, e herdar um `false`
+ * que a criança escolheu no teclado deixá-la-ia com um controle de olhar que não responde.
+ */
+export declare function sincronizarAlternancia(p: JogadorDaAlternancia, armazem: ArmazemDaAlternancia, jogador: number, transporte: string, padrao: boolean): boolean;

package/dist-pkg/input/latch-sync.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { alternanciaGuardada } from './latch-store.js';
+/**
+ * A base com que a alternância de MARCHA vive no armazenamento da criança.
+ *
+ * ⚠️ A IRMÃ (`togglerun`, a alternância de CORRER) NÃO ENTRA AQUI HOJE, e a ausência é declarada em vez de
+ * esquecida: `p.toggleRun` tem um leitor de RODADA no cartucho (`game/run-toggle`), com uma trava própria que
+ * diz se está a correr AGORA — o `walkDir = 0` daqui não é o gesto certo para ela, e inventar-lhe um sem o
+ * leitor à frente seria decidir por um jogo que não abri. O `input/latch-store` já aceita a base como
+ * argumento, então quando ela entrar entra sem uma segunda forma da mesma pergunta.
+ */
+export const BASE_DA_MARCHA = 'togglemove';
+/**
+ * PÕE A ALTERNÂNCIA DE MARCHA NO JOGADOR, com a regra que a acompanha. Devolve se MUDOU alguma coisa.
+ *
+ * ⚠️ O `walkDir = 0` só corre quando a alternância CAI. Zerá-lo em toda chamada tiraria a direcção a quem
+ * está a andar, uma vez por aresta — que é o defeito ao contrário, e mais frequente.
+ *
+ * 📌 Devolver «mudou» não é conveniência: quem chama na aresta corre isto muitas vezes por segundo, e anunciar
+ * ou reflectir a cada chamada encheria o leitor de tela com a mesma frase.
+ */
+export function aplicarAlternancia(p, ligada) {
+    if (p.toggleMove === ligada)
+        return false;
+    p.toggleMove = ligada;
+    if (!ligada)
+        p.walkDir = 0;
+    return true;
+}
+/**
+ * A ALTERNÂNCIA DESTE JOGADOR, RESOLVIDA PARA O TRANSPORTE EM USO E ESCRITA NELE. Devolve se mudou.
+ *
+ * É a cláusula 1 do ADR-0113 em código, e a propriedade que ela promete é NEGATIVA: chamar isto ao trocar de
+ * aparelho troca a resposta **sem escrever no armazenamento**. Um `sincronizar` que gravasse o valor resolvido
+ * apagaria, na primeira aresta, a escolha que a criança fez no outro controle.
+ *
+ * ⚠️ E NOS QUATRO ASSISTIDOS ELE RESPONDE `true` SEM CONSULTAR NADA — a regra vive no `latch-scope` e a razão
+ * está lá: em olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar, e herdar um `false`
+ * que a criança escolheu no teclado deixá-la-ia com um controle de olhar que não responde.
+ */
+export function sincronizarAlternancia(p, armazem, jogador, transporte, padrao) {
+    return aplicarAlternancia(p, alternanciaGuardada(armazem, BASE_DA_MARCHA, jogador, transporte, padrao));
+}

package/dist-pkg/input/origem-sintetica.d.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Transporte } from './transporte-em-uso.js';
+/**
+ * A propriedade pendurada no evento.
+ *
+ * 📌 Prefixada e feia de propósito: é um expando num objecto que não é nosso, e um nome curto («origem»)
+ * podia colidir com o de outra biblioteca sem que nada o dissesse.
+ */
+export declare const CHAVE_DE_ORIGEM = "__vpOrigem";
+/**
+ * O mínimo que este módulo lê de um evento de tecla — ESTRUTURAL, para um `KeyboardEvent` real e um duplo de
+ * teste servirem os dois.
+ *
+ * ⚠️ `isTrusted` é OPCIONAL, e a ausência dele não é o mesmo que `false` por acaso: um duplo que não o declara
+ * está a dizer «não afirmei nada sobre isto», e a resposta certa a isso é `undefined` e não `'teclado'`. É a
+ * mesma regra do `origemDe` do `input/state`, aplicada uma camada acima.
+ */
+export interface EventoDeTeclaLike {
+    readonly isTrusted?: boolean;
+}
+/**
+ * DECLARA que este evento veio daquele aparelho. Devolve o próprio evento, para o despacho ficar numa linha.
+ *
+ * ⚠️ Carimba-se ANTES de despachar. Depois de `dispatchEvent` os ouvintes já correram, e o carimbo chegaria
+ * a um evento que ninguém mais vai ler.
+ */
+export declare function carimbarOrigem<T extends object>(ev: T, origem: Transporte): T;
+/**
+ * QUEM PRODUZIU ESTE EVENTO? `undefined` quando não se sabe.
+ *
+ * A regra inteira, em três linhas e por esta ordem:
+ *
+ *   1. **Carimbo válido ganha.** Uma declaração explícita vence sempre uma inferência — inverter isto faria
+ *      um evento REAL que alguém reatribuiu (um pedal, um interruptor de sopro que emite teclas de verdade)
+ *      ser lido como teclado, apagando exactamente a informação que quem carimbou se deu ao trabalho de pôr.
+ *   2. **Sem carimbo mas de confiança → `'teclado'`.** É o que `isTrusted` significa: o navegador viu a
+ *      pessoa carregar. É a única inferência que este módulo faz, e fá-la sobre a propriedade que não se forja.
+ *   3. **Sem carimbo e sem confiança → `undefined`.** Um evento sintético que ninguém assinou. Depois desta
+ *      migração nada nesta engine produz um; quem o produz é código de fora, e código de fora não declarou.
+ *      ⚠️ Devolver `'teclado'` aqui seria a erasão a voltar por outra porta, que é o defeito que o ADR-0109
+ *      inteiro existe para fechar — e seria pior do que a erasão original, porque teria a forma de uma
+ *      resposta.
+ */
+export declare function origemDoEvento(ev: EventoDeTeclaLike): Transporte | undefined;

package/dist-pkg/input/origem-sintetica.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/origem-sintetica.ts — QUEM DESPACHOU ESTA TECLA, quando não foi um dedo num teclado (ADR-0109).
+//
+// ========================= O PONTO DIFÍCIL DA ARESTA, E ELE ESTAVA NOMEADO =========================
+// O crivo `tests/origem-da-tecla` carrega esta frase na entrada do `input/keydown` desde que o
+// estrangulamento começou: «a webcam despacha `KeyboardEvent` SINTÉTICO, entra pelo `keydown` e seria
+// carimbada `teclado` — a erasão a voltar pela porta da frente». O `ui/webcam` constrói um `KeyboardEvent` e
+// despacha-o na janela (`ui/webcam.ts`, `eyeSet`), e do lado de lá ele é indistinguível de uma tecla premida.
+//
+// `isTrusted` distingue PREMIDA de DESPACHADA — é a única propriedade que um script não consegue forjar — mas
+// não diz QUAL transporte assistido despachou. Isso tem de chegar DECLARADO, e é o que este módulo é.
+//
+// ⚠️ POR QUE O CARIMBO VIAJA NO EVENTO, e não num «qual é a fonte sintética agora?» injectado. A resposta
+// injectada é um estado GLOBAL, e a entrada não é global: uma criança que joga por olhar e tem um adulto a
+// carregar numa tecla ao lado produz as duas arestas no mesmo instante, e o estado global carimbaria as duas
+// como olhar. O evento não se confunde consigo próprio — a origem anda com a aresta a que pertence, que é a
+// mesma razão por que o `origemDaTecla` é um mapa por CÓDIGO e não um campo só.
+//
+// 📌 E é aditivo por construção: um evento sem carimbo continua a funcionar. Foi isso que permitiu migrar os
+// escritores um a um sem nenhum commit vermelho pelo meio.
+import { ehTransporte } from './transporte-em-uso.js';
+/**
+ * A propriedade pendurada no evento.
+ *
+ * 📌 Prefixada e feia de propósito: é um expando num objecto que não é nosso, e um nome curto («origem»)
+ * podia colidir com o de outra biblioteca sem que nada o dissesse.
+ */
+export const CHAVE_DE_ORIGEM = '__vpOrigem';
+/**
+ * DECLARA que este evento veio daquele aparelho. Devolve o próprio evento, para o despacho ficar numa linha.
+ *
+ * ⚠️ Carimba-se ANTES de despachar. Depois de `dispatchEvent` os ouvintes já correram, e o carimbo chegaria
+ * a um evento que ninguém mais vai ler.
+ */
+export function carimbarOrigem(ev, origem) {
+    ev[CHAVE_DE_ORIGEM] = origem;
+    return ev;
+}
+/**
+ * QUEM PRODUZIU ESTE EVENTO? `undefined` quando não se sabe.
+ *
+ * A regra inteira, em três linhas e por esta ordem:
+ *
+ *   1. **Carimbo válido ganha.** Uma declaração explícita vence sempre uma inferência — inverter isto faria
+ *      um evento REAL que alguém reatribuiu (um pedal, um interruptor de sopro que emite teclas de verdade)
+ *      ser lido como teclado, apagando exactamente a informação que quem carimbou se deu ao trabalho de pôr.
+ *   2. **Sem carimbo mas de confiança → `'teclado'`.** É o que `isTrusted` significa: o navegador viu a
+ *      pessoa carregar. É a única inferência que este módulo faz, e fá-la sobre a propriedade que não se forja.
+ *   3. **Sem carimbo e sem confiança → `undefined`.** Um evento sintético que ninguém assinou. Depois desta
+ *      migração nada nesta engine produz um; quem o produz é código de fora, e código de fora não declarou.
+ *      ⚠️ Devolver `'teclado'` aqui seria a erasão a voltar por outra porta, que é o defeito que o ADR-0109
+ *      inteiro existe para fechar — e seria pior do que a erasão original, porque teria a forma de uma
+ *      resposta.
+ */
+export function origemDoEvento(ev) {
+    const declarada = ev[CHAVE_DE_ORIGEM];
+    if (ehTransporte(declarada))
+        return declarada;
+    return ev.isTrusted ? 'teclado' : undefined;
+}

package/dist-pkg/input/pad-defaults.d.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import { type Binding } from './default-bindings.js';
+/** O que o jogo declara: só o que ele quer mudar. `null` num botão é «esta posição não existe neste jogo». */
+export type MapeamentoDoPad = (jogadores: number, assento: number) => Partial<Record<Action, number | null>> | null;
+export type TabelaDoPad = Readonly<Record<Action, Binding<number>>>;
+/**
+ * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque; `null` limpa (é o que um jogo sem opinião produz).
+ *
+ * ⚠️ LIMPA A MEMÓRIA, e sem esta linha o registo seria pior do que não existir: uma segunda montagem — outro
+ * jogo na mesma página, um teste a seguir a outro — leria a tabela do jogo anterior, e a leitura estaria
+ * certa em toda parte menos no valor.
+ */
+export declare function registrarMapeamentoDoPad(f: MapeamentoDoPad | null): void;
+/**
+ * A TABELA DE BOTÕES PARA ESTE ARRANJO E ESTE ASSENTO — fábrica da engine com o padrão do jogo por cima.
+ *
+ * 📌 MEMOIZADA porque isto é lido no laço de sondagem, uma vez por controle e por quadro: fundir dois objectos
+ * sessenta vezes por segundo por jogador é lixo que nenhuma criança vê e que o coletor paga. A chave é
+ * `arranjo:assento`, e o registo limpa-a — que é o único momento em que a resposta pode mudar.
+ */
+export declare function tabelaDoPad(jogadores: number, assento: number): TabelaDoPad;

package/dist-pkg/input/pad-defaults.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { GAMEPAD_STANDARD } from './default-bindings.js';
+let mapeamentoDoJogo = null;
+const memo = new Map();
+/**
+ * REGISTA O PADRÃO DO JOGO. Chamado uma vez pelo arranque; `null` limpa (é o que um jogo sem opinião produz).
+ *
+ * ⚠️ LIMPA A MEMÓRIA, e sem esta linha o registo seria pior do que não existir: uma segunda montagem — outro
+ * jogo na mesma página, um teste a seguir a outro — leria a tabela do jogo anterior, e a leitura estaria
+ * certa em toda parte menos no valor.
+ */
+export function registrarMapeamentoDoPad(f) {
+    mapeamentoDoJogo = f;
+    memo.clear();
+}
+/**
+ * A TABELA DE BOTÕES PARA ESTE ARRANJO E ESTE ASSENTO — fábrica da engine com o padrão do jogo por cima.
+ *
+ * 📌 MEMOIZADA porque isto é lido no laço de sondagem, uma vez por controle e por quadro: fundir dois objectos
+ * sessenta vezes por segundo por jogador é lixo que nenhuma criança vê e que o coletor paga. A chave é
+ * `arranjo:assento`, e o registo limpa-a — que é o único momento em que a resposta pode mudar.
+ */
+export function tabelaDoPad(jogadores, assento) {
+    if (!mapeamentoDoJogo)
+        return GAMEPAD_STANDARD;
+    const chave = `${jogadores}:${assento}`;
+    const guardada = memo.get(chave);
+    if (guardada)
+        return guardada;
+    const parcial = mapeamentoDoJogo(jogadores, assento);
+    const tabela = parcial ? Object.freeze({ ...GAMEPAD_STANDARD, ...parcial }) : GAMEPAD_STANDARD;
+    memo.set(chave, tabela);
+    return tabela;
+}