@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,28 +1,40 @@
 // 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 {
+import { type LatchPlayer } from './latch-sync.js';
+import type { LatchStore } from './latch-store.js';
+import type { TransportName } from './transport-in-use.js';
+import type { LiveInput } from './state.js';
+export interface LatchedEdgeOptions {
     /**
-     * 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.
+     * The input state whose transport automaton records the edge — the root's (`Engine.input`, ADR-0232 D4). REQUIRED: an
+     * edge recorded in another root's state would move THAT root's latch, and this child's would never follow the device.
      */
-    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;
+    readonly input: Pick<LiveInput, 'playerEdge' | 'inputOf'>;
+    /**
+     * The page's store, built by the root (ADR-0232, issue #207). REQUIRED, and the reason is the one that once gave it a
+     * default: omitting it would make the child lose their stored choice — in silence, and only in that game. The compiler
+     * now refuses the omission instead of a default reaching the page's one `localStorage` underneath the host.
+     */
+    readonly store: LatchStore;
+    /** The factory default. `DEFAULTS.toggleMove`, not a hand-written `false`: there is ONE source (ADR-0029). */
+    readonly byDefault?: boolean;
+    /**
+     * DOES THE MOUNTED GAME HOLD ANY KEY NOW? — `GameDeclaration.holdsKeys` (ADR-0249), the latch's default on eyes, face,
+     * gestures and speech. A FUNCTION, called at every edge: a game changes its answer between stages (ADR-0084), and the
+     * next command must follow the stage it lands in. REQUIRED, like `holdsKeys` itself: `true` latches a quiz's every word,
+     * `false` stops a platform game's «direita» after one step, so no default is safe.
+     */
+    readonly holdsKeys: () => boolean;
 }
 /**
- * DEVOLVE O `arestaDoJogador` QUE TAMBÉM RESOLVE A ALTERNÂNCIA — para passar a `initKeydown` e a
- * `initTouchBindings` no lugar do cru.
+ * RETURNS THE `playerEdge` THAT ALSO RESOLVES THE TOGGLE. The root calls it from the virtual controller's `pressedBy`, the one
+ * door every transport's press goes through (ADR-0109 rule 3); a host without that door hands it to `initKeydown`,
+ * `initTouchBindings` and `initGamepad` in place of the raw one.
  *
- * ⚠️ 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.
+ * ⚠️ IT RESOLVES AGAINST `inputOf(player).inUse` AND NOT `origin`, a difference of design and not of behaviour: today the
+ * edge always sets in-use to the origin, so swapping one for the other is an EQUIVALENT mutation — recorded as such in the
+ * gate, instead of pretending coverage. What the choice buys is the future: the state machine decides which device is in
+ * use, and the day it gains a rule that REFUSES an edge (a webcam false positive being filtered, say) this line follows
+ * it without being edited. Reading `origin` would be a second answer to the question `input/transport-in-use` exists to
+ * answer.
  */
-export declare function criarArestaComAlternancia(getPlayers: () => readonly (JogadorDaAlternancia | null | undefined)[], opts?: ArestaComAlternanciaOpts): (jogador: number, origem: Transporte) => void;
+export declare function createLatchedEdge(getPlayers: () => readonly (LatchPlayer | null | undefined)[], opts: LatchedEdgeOptions): (player: number, origin: TransportName) => void;

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

@@ -1,45 +1,44 @@
 // 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).
+// input/latch-edge.ts — THE EDGE AND THE TOGGLE, IN ONE FUNCTION (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.
+// ========================= WHY THE PAIR CANNOT SPLIT =========================
+// Recording which device an edge came from and resolving that device's toggle are two halves of ONE event: the child
+// changed controls. Done in different places, the second can go missing — the kind of defect this project has paid for
+// several times: the state machine knows they picked up the pad, and the game keeps moving with the keyboard's toggle.
+// No error, and only the child notices.
 //
-// 📌 É 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`.
+// 📌 The same move as the menu navigation's "one function so the pair never splits", and the double write in
+// `ui/settings-mobility`.
 //
-// ⚠️ 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';
+// ⚠️ AND IT IS A FACTORY, NOT A NEW FIELD IN EVERY INPUT MODULE'S CONTEXT. The keyboard and touch transports already
+// receive `playerEdge(player, origin)`; this returns one with that same signature, so the wiring is right without either
+// of them knowing the toggle exists. A second required field in two contexts would be more public surface, one more
+// thing a cartridge can forget, and the same question asked twice.
+import { DEFAULTS } from '../core/setting-defaults.js';
+import { syncLatch } 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.
+ * RETURNS THE `playerEdge` THAT ALSO RESOLVES THE TOGGLE. The root calls it from the virtual controller's `pressedBy`, the one
+ * door every transport's press goes through (ADR-0109 rule 3); a host without that door hands it to `initKeydown`,
+ * `initTouchBindings` and `initGamepad` in place of the raw one.
  *
- * ⚠️ 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.
+ * ⚠️ IT RESOLVES AGAINST `inputOf(player).inUse` AND NOT `origin`, a difference of design and not of behaviour: today the
+ * edge always sets in-use to the origin, so swapping one for the other is an EQUIVALENT mutation — recorded as such in the
+ * gate, instead of pretending coverage. What the choice buys is the future: the state machine decides which device is in
+ * use, and the day it gains a rule that REFUSES an edge (a webcam false positive being filtered, say) this line follows
+ * it without being edited. Reading `origin` would be a second answer to the question `input/transport-in-use` exists to
+ * answer.
  */
-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];
+export function createLatchedEdge(getPlayers, opts) {
+    const latchStore = opts.store;
+    const { playerEdge, inputOf } = opts.input;
+    const fallback = opts.byDefault ?? DEFAULTS.toggleMove;
+    return (player, origin) => {
+        playerEdge(player, origin);
+        // 📌 THE PLAYER MAY NOT EXIST — a waiting screen, a seat not joined yet — and that does not make the edge invalid:
+        // the transport in use is a fact about the INPUT and is recorded all the same. What does not happen is the second
+        // half, because there is nowhere to write it.
+        const p = getPlayers()[player];
         if (p)
-            sincronizarAlternancia(p, armazem, jogador, entradaDe(jogador).emUso, padrao);
+            syncLatch(p, latchStore, player, inputOf(player).inUse, { byDefault: fallback, gameHoldsKeys: opts.holdsKeys() });
     };
 }

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

@@ -1,70 +1,71 @@
 // 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.
+ * The transports that emit ONE COMMAND AT A TIME, on which the latch's default is the game's `holdsKeys()` (ADR-0249).
  *
- * 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.
+ * The values are transport names, which stay Portuguese like the rest of that vocabulary (`teclado`, `toque`): they are
+ * stored, and renaming a stored value loses what the child saved.
  */
-export declare const UM_COMANDO_DE_CADA_VEZ: ReadonlySet<string>;
+export declare const ONE_COMMAND_AT_A_TIME: ReadonlySet<string>;
 /**
- * Neste transporte a alternância está sempre ligada?
+ * Does this transport's latch start where the GAME says (ADR-0249)?
  *
- * ⚠️ «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`.
+ * `true` on the four one-command transports: with nothing stored for them, the latch is the game's `holdsKeys()`. The
+ * option is offered on every transport alike; this answers only where the default comes from.
  */
-export declare function alternanciaSempreLigada(transporte: string): boolean;
+export declare function latchDefaultFromGame(transport: string): boolean;
 /**
- * A opção deve ser OFERECIDA para este transporte?
+ * The toggle's storage key, with the transport in its name.
  *
- * 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.
+ * ⚠️ A FUNCTION, and not concatenation at the call site, for the reason `platform/storage` gives for the per-player keys:
+ * as a function, no call site can write a crooked name. Not a hypothesis — the mobility panel once rewrote the per-player
+ * key by hand, with a comment beside it saying it matched storage's. Two copies of a name change one at a time.
  *
- * ⚠️ 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.
+ * `base` is `togglemove` or `togglerun`, the two names that already exist in the child's storage.
  */
-export declare function chaveDaAlternancia(base: string, jogador: number, transporte: string): string;
+export declare function latchKey(base: string, player: number, transport: string): string;
 /**
- * A chave ANTIGA, por jogador e sem transporte. Continua a ser lida, e nunca mais escrita.
+ * The OLD key, per player and without a transport. Still read, never written again.
+ *
+ * ⚠️ IT IS INHERITED BY THE KEYBOARD, THE PAD AND TOUCH, and the choice takes a sentence to explain. The old value was set
+ * by the child in some context, and there is no way to know which — the key did not record it, which is the defect. The
+ * ways out were three: lose their setting, guess a transport, or inherit for all. Inheriting is the only one that takes
+ * nothing from whoever depends on the setting, and the leak it keeps lasts only until the child touches the setting once
+ * on each device. Losing the setting would cost more, and to whoever can least afford it.
  *
- * ⚠️ 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.
+ * 📌 NOT BY THE FOUR ONE-COMMAND TRANSPORTS (ADR-0249): there the default is the game's answer, and a value the child set
+ * on the keyboard is not a choice about how a spoken word or a look should behave in this game.
  *
- * É 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».
+ * It is also the pattern this repository chose for this same value before: the old key stays where it is — it is the
+ * child's data, not mine to delete, and keeping it is what makes a way back possible.
  */
-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;
+export declare function legacyLatchKey(base: string, player: number): string;
+/** What is known when resolving a transport's toggle. */
+export interface LatchReading {
+    /** What is stored for THIS transport. `null` = never written. */
+    readonly fromTransport: boolean | null;
+    /** What is stored under the old key, without a transport. `null` = never written. */
+    readonly fromLegacy: boolean | null;
+    /** The factory default (`DEFAULTS.toggleMove` / `DEFAULTS.toggleRun`). */
+    readonly byDefault: boolean;
+    /**
+     * THE GAME'S ANSWER, NOW: `GameDeclaration.holdsKeys()` (ADR-0249). The default on the one-command transports.
+     *
+     * ⚠️ READ WHEN THE LATCH IS RESOLVED, not once at boot: a game changes it between stages (ADR-0084), and a latch resolved
+     * from a stale answer would keep a quiz stage latched because the stage before it held keys. REQUIRED, like `holdsKeys`
+     * itself: both values can be wrong, so there is no safe default to fall back on.
+     */
+    readonly gameHoldsKeys: boolean;
 }
+/** The two defaults a resolution needs from outside storage — the factory's and the game's. */
+export type LatchDefaults = Pick<LatchReading, 'byDefault' | 'gameHoldsKeys'>;
 /**
- * A alternância deste transporte, resolvida.
+ * This transport's toggle, resolved.
  *
- * A ordem é: transporte de um comando → SEMPRE ligada, e nem se lê o resto · valor deste transporte · valor
- * legado · padrão de fábrica.
+ * The order: this transport's stored value · on a one-command transport, the game's `holdsKeys()` · the legacy value ·
+ * the factory default.
  *
- * ⚠️ 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.
+ * ⚠️ THE STORED VALUE COMES FIRST ON EVERY TRANSPORT (ADR-0249): the child's choice for this device wins over any default,
+ * including the game's. And a stored `false` is a VALUE, not an absence — the `!== null` is what keeps a latch the child
+ * turned off from coming back by itself.
  */
-export declare function alternanciaDe(transporte: string, l: LeituraDaAlternancia): boolean;
+export declare function latchOf(transport: string, l: LatchReading): boolean;

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

@@ -1,110 +1,89 @@
 // 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).
+// input/latch-scope — THE TOGGLE BELONGS TO A TRANSPORT, not to the child (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.
+// ========================= THE DEFECT THIS FIXES, WHICH HAD NO NAME =========================
+// "Holding becomes toggling" was stored PER PLAYER — `incl_togglemove_p0` — that is: per person, and for every device
+// at once. A child who turns the toggle on for the on-screen pad, because nobody holds a virtual button comfortably,
+// turns it on for the keyboard too, where holding a key is exactly what they can do. They did not ask for that and
+// nothing tells them.
 //
-// ⚠️ 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.
+// ⚠️ AND THE REPOSITORY ALREADY KNEW THE DEFECT WITHOUT NAMING IT: the run toggle is born off at the factory and switches
+// itself on with the on-screen pad, which is CONTEXT and not choice. Context is exactly the word: the value depends on
+// the device the child is on. Keeping it per person forced a separate mark (ADR-0029) to tell "turned on because they
+// wanted" from "turned on because it is touch" — a mark compensating for a key in the wrong scope.
 //
-// O mapeamento de teclas já se guarda por transporte, e sempre se guardou. Esta é a mesma coisa.
+// The key mapping is already kept per transport, and always was. This is the same thing.
 //
-// ========================= 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.
+// ========================= ON FOUR TRANSPORTS THE GAME SETS THE DEFAULT (ADR-0249) =========================
+// Eyes, face, gestures and speech emit ONE COMMAND AT A TIME: a word or a look is a tap, never a hold. Whether that tap
+// should keep going is the GAME's to say — in a platform game «direita» keeps the character walking, in a quiz «abaixo»
+// moves the cursor once — and the game already says it: `GameDeclaration.holdsKeys()`. So on these four the latch STARTS
+// as the game answers, and the child's stored choice for that transport, when there is one, wins (ADR-0104 §C: a default
+// is not a lock). Keyboard, pad and touch keep the factory default and the legacy inheritance below.
 //
-// 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.
+// A leaf module: it imports nothing, not even the `platform/storage` whose keys it builds.
 /**
- * Os transportes que emitem UM COMANDO DE CADA VEZ, e em que a alternância está sempre ligada.
+ * The transports that emit ONE COMMAND AT A TIME, on which the latch's default is the game's `holdsKeys()` (ADR-0249).
  *
- * 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.
+ * The values are transport names, which stay Portuguese like the rest of that vocabulary (`teclado`, `toque`): they are
+ * stored, and renaming a stored value loses what the child saved.
  */
-export const UM_COMANDO_DE_CADA_VEZ = new Set(['olhos', 'rosto', 'gestos', 'fala']);
+export const ONE_COMMAND_AT_A_TIME = new Set(['olhos', 'rosto', 'gestos', 'fala']);
 /**
- * Neste transporte a alternância está sempre ligada?
+ * Does this transport's latch start where the GAME says (ADR-0249)?
  *
- * ⚠️ «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`.
+ * `true` on the four one-command transports: with nothing stored for them, the latch is the game's `holdsKeys()`. The
+ * option is offered on every transport alike; this answers only where the default comes from.
  */
-export function alternanciaSempreLigada(transporte) {
-    return UM_COMANDO_DE_CADA_VEZ.has(transporte);
+export function latchDefaultFromGame(transport) {
+    return ONE_COMMAND_AT_A_TIME.has(transport);
 }
 /**
- * A opção deve ser OFERECIDA para este transporte?
+ * The toggle's storage key, with the transport in its name.
  *
- * 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.
+ * ⚠️ A FUNCTION, and not concatenation at the call site, for the reason `platform/storage` gives for the per-player keys:
+ * as a function, no call site can write a crooked name. Not a hypothesis — the mobility panel once rewrote the per-player
+ * key by hand, with a comment beside it saying it matched storage's. Two copies of a name change one at a time.
  *
- * `base` é `togglemove` ou `togglerun`, os dois nomes que já existem no armazenamento da criança.
+ * `base` is `togglemove` or `togglerun`, the two names that already exist in the child's storage.
  */
-export function chaveDaAlternancia(base, jogador, transporte) {
-    return `incl_${base}_p${jogador}_${transporte}`;
+export function latchKey(base, player, transport) {
+    return `incl_${base}_p${player}_${transport}`;
 }
 /**
- * A chave ANTIGA, por jogador e sem transporte. Continua a ser lida, e nunca mais escrita.
+ * The OLD key, per player and without a transport. Still read, never written again.
+ *
+ * ⚠️ IT IS INHERITED BY THE KEYBOARD, THE PAD AND TOUCH, and the choice takes a sentence to explain. The old value was set
+ * by the child in some context, and there is no way to know which — the key did not record it, which is the defect. The
+ * ways out were three: lose their setting, guess a transport, or inherit for all. Inheriting is the only one that takes
+ * nothing from whoever depends on the setting, and the leak it keeps lasts only until the child touches the setting once
+ * on each device. Losing the setting would cost more, and to whoever can least afford it.
  *
- * ⚠️ 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.
+ * 📌 NOT BY THE FOUR ONE-COMMAND TRANSPORTS (ADR-0249): there the default is the game's answer, and a value the child set
+ * on the keyboard is not a choice about how a spoken word or a look should behave in this game.
  *
- * É 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».
+ * It is also the pattern this repository chose for this same value before: the old key stays where it is — it is the
+ * child's data, not mine to delete, and keeping it is what makes a way back possible.
  */
-export function chaveLegadaDaAlternancia(base, jogador) {
-    return `incl_${base}_p${jogador}`;
+export function legacyLatchKey(base, player) {
+    return `incl_${base}_p${player}`;
 }
 /**
- * A alternância deste transporte, resolvida.
+ * This transport's toggle, resolved.
  *
- * A ordem é: transporte de um comando → SEMPRE ligada, e nem se lê o resto · valor deste transporte · valor
- * legado · padrão de fábrica.
+ * The order: this transport's stored value · on a one-command transport, the game's `holdsKeys()` · the legacy value ·
+ * the factory default.
  *
- * ⚠️ 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.
+ * ⚠️ THE STORED VALUE COMES FIRST ON EVERY TRANSPORT (ADR-0249): the child's choice for this device wins over any default,
+ * including the game's. And a stored `false` is a VALUE, not an absence — the `!== null` is what keeps a latch the child
+ * turned off from coming back by itself.
  */
-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;
+export function latchOf(transport, l) {
+    if (l.fromTransport !== null)
+        return l.fromTransport;
+    if (latchDefaultFromGame(transport))
+        return l.gameHoldsKeys;
+    if (l.fromLegacy !== null)
+        return l.fromLegacy;
+    return l.byDefault;
 }

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

@@ -1,45 +1,41 @@
 // 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;
+import { type LatchReading, type LatchDefaults } from './latch-scope.js';
+/** The minimum of `platform/storage` this needs. Injected, so the gate needs no browser. */
+export interface LatchStore {
+    /** ⚠️ The RAW read, not `getBool`. See `readTriState`. */
+    get(key: string, fallback?: null): string | null;
+    set(key: string, value: string): void;
 }
 /**
- * TRÊS ESTADOS E NÃO DOIS: `true`, `false`, e NUNCA ESCRITO.
+ * THREE STATES, NOT TWO: `true`, `false`, and NEVER WRITTEN.
  *
- * 🔴 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.
+ * 🔴 THIS FUNCTION EXISTS SO `getBool` IS NOT USED, and the difference costs a child's setting. `getBool` collapses
+ * "never written" into `false`. With it, the per-transport value of a child who never touched this device would reach the
+ * rule as `false` — and the rule answers at the FIRST line that finds a value, so it would return `false` and **never
+ * consult the legacy key**, where the setting they already had lives.
  *
- * ⚠️ É 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.
+ * ⚠️ That is why `latch-scope` types both fields `boolean | null` and has a case of its own saying "a stored `false` is a
+ * VALUE, not an absence". This is the storage side of the same sentence.
  */
-export declare function lerTriEstado(armazem: ArmazemDaAlternancia, chave: string): boolean | null;
+export declare function readTriState(store: LatchStore, key: string): boolean | null;
 /**
- * A LEITURA COMPLETA que a regra pede, montada a partir do armazenamento.
+ * THE WHOLE READING the rule asks for, built from storage.
  *
- * `base` é `togglemove` ou `togglerun` — os dois nomes que já existem no armazenamento da criança.
+ * `base` is `togglemove` or `togglerun` — the two names that already exist in the child's storage. `defaults` carries what
+ * storage does not know: the factory default and the game's `holdsKeys()` answer now (ADR-0249).
  */
-export declare function leituraDaAlternancia(armazem: ArmazemDaAlternancia, base: string, jogador: number, transporte: string, padrao: boolean): LeituraDaAlternancia;
+export declare function readLatch(store: LatchStore, base: string, player: number, transport: string, defaults: LatchDefaults): LatchReading;
 /**
- * A ALTERNÂNCIA DESTE JOGADOR NESTE TRANSPORTE — a pergunta inteira, numa chamada.
+ * THIS PLAYER'S TOGGLE ON THIS TRANSPORT — the whole question, in one call.
  *
- * 📌 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.
+ * 📌 SWITCHING TRANSPORT SWITCHES THE ANSWER WITHOUT WRITING ANYTHING, clause 1 of ADR-0113 in code: the value belongs to
+ * the controls' mapping, like a caps lock, and changing controls is changing mapping.
  */
-export declare function alternanciaGuardada(armazem: ArmazemDaAlternancia, base: string, jogador: number, transporte: string, padrao: boolean): boolean;
+export declare function storedLatch(store: LatchStore, base: string, player: number, transport: string, defaults: LatchDefaults): boolean;
 /**
- * GRAVA A ESCOLHA DA CRIANÇA para o transporte em uso. Devolve se gravou.
+ * WRITES THE CHILD'S CHOICE for the transport in use — on EVERY transport (ADR-0249).
  *
- * ⚠️ 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.
+ * 📌 Eyes, face, gestures and speech included: their latch starts as the game answers `holdsKeys()`, and what is written
+ * here is the child changing that default for that device. The stored value is what `latchOf` reads first.
  */
-export declare function gravarAlternancia(escrever: (chave: string, ligada: boolean) => void, base: string, jogador: number, transporte: string, ligada: boolean): boolean;
+export declare function writeLatch(write: (key: string, isOn: boolean) => void, base: string, player: number, transport: string, isOn: boolean): void;