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

package/dist-pkg/input/keyboard.js

@@ -6,22 +6,52 @@
 // e o ADR-0086 §2 diz qual é para a plataforma. Esquemas por contagem de jogadores (solo/p2/p3/p4).
 // A INSTÂNCIA atual (KB) e o remap ficam no composition root — aqui só config/load/save/reset.
 import * as store from '../platform/storage.js';
+// ⚠️ A DECLARAÇÃO DOS ESQUEMAS MORA LÁ (ADR-0096), e este ficheiro passou a derivá-los em vez de os repetir
+// — é a união que a issue #118 pede. `default-bindings` é folha (só importa `core/actions`), então não há
+// ciclo: quem depende é o ficheiro de persistência, e não o contrário.
+import { KEYBOARD_SOLO, KEYBOARD_DUO } from './default-bindings.js';
 const CKEY = 'inclusionist.kbcontrols.v3';
+/**
+ * AS SEIS POSIÇÕES QUE UM TECLADO PARTIDO NÃO ALCANÇA, declaradas como ausência (issue #118, decisão do Dev).
+ *
+ * ⚠️ `null` AQUI É UMA AFIRMAÇÃO, e é o que torna o `KeyScheme` fechado útil em vez de burocrático: quando o
+ * teclado é repartido por três ou quatro crianças, não há lugar físico para ombros, gatilhos, start e select
+ * de cada uma — o bloco de cada jogador tem oito teclas e acabou. Inventar teclas para preencher seria dar a
+ * cada criança um alcance que ela não tem, e o `ui/reach-notice` (#112) diria a coisa errada.
+ *
+ * O que `null` compra: o aviso de alcance pode dizer, ANTES de a criança começar, quais das ações do jogo o
+ * controlo dela não alcança — e o jogo pode decidir não usar essas posições no modo de quatro.
+ */
+const SEM_ALCANCE_NO_TECLADO_PARTIDO = Object.freeze({
+    leftShoulder: null, leftTrigger: null, rightShoulder: null, rightTrigger: null, start: null, select: null,
+});
 // 4 esquemas base p/ 3–4 jogadores (modos 3 e 4 têm esquemas SEPARADOS, p3 e p4, editáveis por jogador)
 export const KB_SCHEMES4 = [
-    { left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyZ'], action2: ['KeyX'], action4: ['KeyC'], action3: ['KeyV'] },
-    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'] },
-    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'] },
-    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'] },
+    { left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyZ'], action2: ['KeyX'], action4: ['KeyC'], action3: ['KeyV'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
+    { left: ['KeyJ'], right: ['KeyL'], up: ['KeyI'], down: ['KeyK'], action1: ['KeyM'], action2: ['Comma'], action4: ['Period'], action3: ['Semicolon', 'Slash'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
+    { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Home'], action2: ['End'], action4: ['PageUp'], action3: ['PageDown'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
+    { left: ['Numpad4'], right: ['Numpad6'], up: ['Numpad8'], down: ['Numpad5'], action1: ['Numpad2'], action2: ['Numpad0'], action4: ['Numpad3'], action3: ['NumpadDecimal'], ...SEM_ALCANCE_NO_TECLADO_PARTIDO },
 ];
+/**
+ * Cópia PROFUNDA e MUTÁVEL de uma tabela declarada. O remapeamento escreve dentro do esquema vivo, então ele
+ * não pode partilhar objeto com a tabela de `input/default-bindings`, que é congelada e é a declaração.
+ */
+const vivo = (t) => JSON.parse(JSON.stringify(t));
+/**
+ * ⚠️ AS DUAS TABELAS DE TECLADO PASSARAM A SER UMA (issue #118). O solo e a dupla já não são escritos aqui:
+ * são CÓPIAS VIVAS do que `input/default-bindings` declara, que é onde o ADR-0096 pôs a decisão.
+ *
+ * Antes eram duas listas paralelas com oito posições cada, e as oito «coincidiam» — menos uma. A `Space` do
+ * jogador 1 em dupla estava numa e não na outra, e o custo era concreto: `ui/webcam.ts` sintetiza `Space`
+ * para «olhar para cima = pular», então entrar um segundo jogador tirava o PULO de quem joga com os olhos e
+ * deixava o andar. Nada errava em voz alta. Derivar em vez de repetir torna essa divergência impossível de
+ * voltar a existir, em vez de a apanhar depois de acontecer.
+ */
 export const KB_DEFAULTS = {
-    // 1 jogador: WASD + setas; pulo J/Espaço; UJIK como na mão pequena do DOS. Sem Alt/AltGr/Ctrl/Shift.
-    solo: { left: ['KeyA', 'ArrowLeft'], right: ['KeyD', 'ArrowRight'], up: ['KeyW', 'ArrowUp'], down: ['KeyS', 'ArrowDown'],
-        action1: ['KeyU'], action2: ['KeyJ', 'Space'], action4: ['KeyI'], action3: ['KeyK'] },
-    p2: [{ left: ['KeyA'], right: ['KeyD'], up: ['KeyW'], down: ['KeyS'], action1: ['KeyU'], action2: ['KeyJ'], action4: ['KeyI'], action3: ['KeyK'] },
-        { left: ['ArrowLeft'], right: ['ArrowRight'], up: ['ArrowUp'], down: ['ArrowDown'], action1: ['Numpad8'], action2: ['Numpad5'], action4: ['Numpad9'], action3: ['Numpad6'] }],
-    p3: JSON.parse(JSON.stringify(KB_SCHEMES4.slice(0, 3))), // modo 3 jogadores (independente do 4)
-    p4: JSON.parse(JSON.stringify(KB_SCHEMES4)), // modo 4 jogadores
+    solo: vivo(KEYBOARD_SOLO),
+    p2: KEYBOARD_DUO.map(vivo),
+    p3: KB_SCHEMES4.slice(0, 3).map(vivo), // modo 3 jogadores (independente do 4)
+    p4: KB_SCHEMES4.map(vivo), // modo 4 jogadores
 };
 // dado salvo (parcial): sobrepõe os defaults; p34 é o formato ANTIGO (migra p/ p3+p4).
 // A FORMA vem de `vocabulary-migration`, que é quem a traduz — declarar aqui outra vez seria a

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

@@ -9,6 +9,14 @@ export interface KeydownEventLike {
     altKey: boolean;
     ctrlKey: boolean;
     preventDefault(): void;
+    /**
+     * O navegador viu a pessoa carregar? (ADR-0109) — OPCIONAL, e a opcionalidade é a decisão.
+     *
+     * ⚠️ Torná-lo obrigatório partiria todos os duplos de teste que já existem, e partiria-os por uma razão
+     * falsa: eles descrevem a decisão de teclado, que não depende disto. O que a ausência significa está
+     * escrito no `input/origem-sintetica` — «não afirmei nada», cuja resposta é `undefined` e não `'teclado'`.
+     */
+    isTrusted?: boolean;
 }
 /** `keyup` só precisa do código. */
 export interface KeyupEventLike {
@@ -174,6 +182,7 @@ export declare function isEasyShortcut(code: string, s: KeydownSnapshot): boolea
 export declare function titleNavOf(code: string, s: KeydownSnapshot, action2: boolean): TitleNav;
 import type { EventTargetLike } from './touch-bindings.js';
 import type { DomQuery } from '../core/dom-query.js';
+import type { Transporte } from './transporte-em-uso.js';
 export { hasNavIntent as hasTitleIntent } from './edges.js';
 /**
  * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
@@ -219,8 +228,24 @@ export interface KeydownCtx {
     getPlayers: () => readonly KeydownPlayer[];
     /** `kbRuntime.controlsState()` — memorizado do lado de lá; uma chamada por tecla, como no original. */
     getControls: () => ControlsSnapshot;
-    /** `keys` de input/state.ts: `const` mutado in place → entra por VALOR (é sempre o mesmo objeto). */
-    heldKeys: Set<string>;
+    /**
+     * O PAR DE `input/state`, E NÃO O CONJUNTO CRU (ADR-0109) — o mesmo corte que o `input/touch-bindings` fez.
+     *
+     * ⚠️ `ReadonlySet` e não `Set`, e a diferença É a razão de o par existir: LER o conjunto nunca foi o
+     * problema; ESCREVER nele apagava a origem. Com o tipo assim, uma escrita crua deixa de compilar — o crivo
+     * do inventário passa a ter o compilador do lado dele, em vez de ser a única coisa a segurar a linha.
+     */
+    readonly heldKeys: ReadonlySet<string>;
+    /** Uma tecla foi segurada, e sabe-se por quem. */
+    marcarTecla: (code: string, origem: Transporte) => void;
+    /**
+     * Uma tecla foi segurada e NÃO se sabe por quem — o evento sintético que ninguém assinou.
+     *
+     * ⚠️ Está no ctx a par das outras duas de propósito: se fosse importada, um consumidor não teria como ver
+     * que ela existe, e é justamente ele quem produz os eventos que caem aqui.
+     */
+    marcarTeclaSemOrigem: (code: string) => void;
+    soltarTecla: (code: string) => void;
     /** `let oneButton` do game.js (empatia motora) → getter. */
     isOneButton: () => boolean;
     actionOf: (code: string, playerIndex: number) => string | null;

package/dist-pkg/input/keydown.js

@@ -113,7 +113,9 @@ export function isJumpKey(code, s) {
  *  jogador. NÃO inclui os atalhos do Fácil (o original também não: por isso `easyKey` é somado à parte). */
 export function isGameKeyCode(code, s) {
     return s.controls.gameKeys.includes(code)
-        || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => arr.includes(code)));
+        // `arr &&` porque uma posição sem alcance é `null` desde a #118 — e `null.includes` seria uma exceção
+        // no caminho do teclado, ou seja, o jogo a parar de responder a qualquer tecla.
+        || s.players.some((p) => !!p.ctrl && Object.values(p.ctrl).some((arr) => !!arr && arr.includes(code)));
 }
 /** Os atalhos de acessibilidade do Fácil só existem SOLO (`numPlayers<=1`) e só para o Jogador 1. */
 export function isEasyShortcut(code, s) {
@@ -138,6 +140,10 @@ export function titleNavOf(code, s, action2) {
 }
 /** Alguma intenção foi expressa? Definição única em input/edges; aqui só o nome que este módulo sempre teve. */
 import { hasNavIntent as hasTitleIntent } from './edges.js';
+// ⚠️ IMPORTADA E NÃO INJECTADA, ao contrário dos três escritores logo abaixo, e a linha que separa os dois é
+// esta: `origemDoEvento` é uma função PURA do evento — não toca estado nenhum que o cartucho possua. Os
+// escritores tocam o `input/state`, que é mutado in-place e partilhado, e é por isso que continuam a entrar.
+import { origemDoEvento } from './origem-sintetica.js';
 export { hasNavIntent as hasTitleIntent } from './edges.js';
 /**
  * Quem é o dono do modal que esta tecla comanda? Devolve a POSIÇÃO no array, ou -1.
@@ -287,7 +293,7 @@ export function initKeydown(ctx) {
         };
     }
     /** A metade IMPURA: pega a decisão pronta e a carimba no mundo. */
-    function apply(d, code) {
+    function apply(d, code, origem) {
         switch (d.kind) {
             case 'overlay':
                 if (d.closeId)
@@ -354,8 +360,14 @@ export function initKeydown(ctx) {
                         p[edge] = true;
                 }
                 for (const k of d.releaseKeys)
-                    ctx.heldKeys.delete(k);
-                ctx.heldKeys.add(code);
+                    ctx.soltarTecla(k);
+                // ⚠️ A ORIGEM CHEGA DO EVENTO E NÃO É INVENTADA AQUI (ADR-0109). `origem` é `undefined` só para o
+                // evento sintético que ninguém assinou — e nesse caso a porta estreita APAGA a entrada anterior, em
+                // vez de deixar a tecla herdar de quem a segurou da última vez. Ver `marcarTeclaSemOrigem`.
+                if (origem)
+                    ctx.marcarTecla(code, origem);
+                else
+                    ctx.marcarTeclaSemOrigem(code);
                 return;
             }
         }
@@ -370,9 +382,11 @@ export function initKeydown(ctx) {
         const d = decideKeydown(e, snapshot());
         if (d.preventDefault)
             e.preventDefault();
-        apply(d, e.code);
+        apply(d, e.code, origemDoEvento(e));
     }
-    function onKeyup(e) { ctx.heldKeys.delete(e.code); }
+    // ⚠️ SOLTA NOS DOIS. Um `keys.delete` cru deixava a origem para trás, e um mapa que descreve teclas que já
+    // ninguém segura responde à alternância com o aparelho errado — sem erro, e só na aresta seguinte.
+    function onKeyup(e) { ctx.soltarTecla(e.code); }
     function attach() {
         ctx.win.addEventListener('keydown', onKeydown);
         ctx.win.addEventListener('keyup', onKeyup);

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/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;
+}