@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/core/contract.d.ts

@@ -1,43 +1,42 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Action } from './actions.js';
-/** Gênero gramatical do nome. `n` = neutro/indefinido (o pt-BR usa o masculino como default nesse caso). */
+/** The name's grammatical gender. `n` = neuter/unknown (Portuguese uses the masculine as the default then). */
 export type Gender = 'm' | 'f' | 'n';
-/** Um nome que pode ser FALADO (leitor de tela) e SINALIZADO (Libras, que traduz o mesmo texto). */
+/** A name that can be SPOKEN (screen reader) and SIGNED (Libras, which translates the same text). */
 export interface Speakable {
-    /** O nome, na língua da interface. Conteúdo de currículo NÃO se traduz — ver o pilar 3 do ADR-0010. */
+    /** The name, in the interface's language. Curriculum content is NOT translated — see pillar 3 of ADR-0010. */
     readonly text: string;
     readonly gender: Gender;
     readonly plural: boolean;
 }
 /**
- * COMO SE CONTA UM PASSO — e é isto que decide a métrica, que não é a mesma em todo tabuleiro.
+ * HOW A STEP IS COUNTED — and that is what decides the metric, which is not the same on every board.
  *
- * ⚠️ A grade tinha UMA métrica fixa (Chebyshev), com a razão escrita ao lado: *"numa grade, a diagonal custa um
- * passo, e é assim que quem joga conta"*. Verdade onde a diagonal é legal. **Falsa num quebra-cabeça
- * deslizante**, onde nada anda na diagonal: uma peça duas à direita e duas abaixo está a 2 por Chebyshev e a
- * QUATRO movimentos de distância. O sonar sub-relatava até 2× — e sub-relatar distância a quem não vê a tela
- * não é imprecisão, é mandar a criança para o lado errado com confiança.
+ * ⚠️ The grid had ONE fixed metric (Chebyshev), on the reasoning that on a grid a diagonal costs one step. True where the
+ * diagonal is legal. **False in a sliding puzzle**, where nothing moves diagonally: a piece two right and two down is 2
+ * away by Chebyshev and FOUR moves away. The sonar under-reported up to 2× — and under-reporting distance to someone who
+ * cannot see the screen is not imprecision, it is sending the child the wrong way with confidence.
  *
- * `grid` nunca foi UMA coisa. Quem declara a grade declara também como se anda nela.
+ * `grid` was never ONE thing. Whoever declares a grid declares how one walks on it.
  */
 export type MoveRule = 'orthogonal' | 'diagonal' | 'free';
 /**
- * EM QUE PALAVRAS SE DIZ UMA DIREÇÃO. Não é preferência de quem ouve: é propriedade do ESPAÇO do jogo.
+ * IN WHAT WORDS A DIRECTION IS SAID. Not the listener's preference: a property of the game's SPACE.
  *
- *   `compass`  norte · sul · leste · oeste (+ zênite e nadir) — tabuleiro, top-down, mapa, 3D
- *   `clock`    «às 2 horas», «às 10 horas» — PLATAFORMA 2D, vista lateral
+ *   `compass`  north · south · east · west (+ zenith and nadir) — board, top-down, map, 3D
+ *   `clock`    "at 2 o'clock", "at 10 o'clock" — a 2D PLATFORMER, side view
  *
- * ⚠️ Num jogo de plataforma, norte e sul não querem dizer nada: a criança não está a olhar um mapa, está a
- * olhar de lado. O relógio é o referencial que essa vista já usa, e dá 12 posições onde a rosa dá 8.
+ * ⚠️ In a platformer north and south mean nothing: the child is not looking at a map, they are looking from the side.
+ * The clock is the frame that view already uses, and gives 12 positions where the rose gives 8.
  *
- * ⚠️ E O RELÓGIO PRESSUPÕE LER RELÓGIO ANALÓGICO, num público que inclui alfabetização. Não é motivo para o
- * recusar — é motivo para o rótulo FALADO ser testado com criança (issue #7) antes de se declarar bom.
+ * ⚠️ AND THE CLOCK ASSUMES READING AN ANALOGUE CLOCK, for an audience that includes early literacy. Not a reason to
+ * refuse it — a reason for the SPOKEN label to be tested with children (issue #7) before it is declared good.
  */
 export type Frame = 'compass' | 'clock';
 export type Topology = 
 /**
- * Grade discreta. A distância é em CÉLULAS, e a métrica sai de `move`.
- * `size` é `[colunas, linhas]` ou `[colunas, linhas, camadas]`.
+ * A discrete grid. Distance is in CELLS, and the metric comes from `move`.
+ * `size` is `[columns, rows]` or `[columns, rows, layers]`.
  */
 {
     readonly kind: 'grid';
@@ -46,8 +45,8 @@ export type Topology =
     readonly frame: Frame;
 }
 /**
- * Espaço contínuo. A distância é em UNIDADES do mundo; `unit` diz quanto vale um "passo" para quem narra.
- * `size` é `[largura, altura]` ou `[largura, altura, profundidade]`.
+ * Continuous space. Distance is in world UNITS; `unit` says what a "step" is worth to the narrator.
+ * `size` is `[width, height]` or `[width, height, depth]`.
  */
  | {
     readonly kind: 'continuous';
@@ -56,43 +55,43 @@ export type Topology =
     readonly move: MoveRule;
     readonly frame: Frame;
 }
-/** Sem espaço: uma lista ORDENADA de alvos. A distância é a diferença de índice, e não há direção. */
+/** No space: an ORDERED list of targets. Distance is the difference of index, and there is no direction. */
  | {
     readonly kind: 'hotspots';
     readonly order: readonly string[];
 };
 /**
- * Uma posição, na métrica da topologia declarada. Em `hotspots`, `x` é o índice e `y` é ignorado.
+ * A position, in the declared topology's metric. In `hotspots`, `x` is the index and `y` is ignored.
  *
- * ⚠️ ASSIMETRIA DELIBERADA COM `size`, e vale dizer por quê. A EXTENSÃO é um vetor porque a dimensão varia e
- * `size.length` é o único lugar onde ela mora — sem isso, "tem profundidade?" viraria `depth !== undefined`
- * espalhado por cada consumidor. O PONTO tem eixos com nome porque é lido em código a toda hora: `alvo.at.x`
- * diz o que é, `alvo.at[0]` obriga a lembrar. Dimensão é 2 ou 3 e a conformidade recusa o resto, o que fecha
- * a assimetria: não há `size` que `Spot` não consiga representar.
+ * ⚠️ A DELIBERATE ASYMMETRY WITH `size`. The EXTENT is a vector because the dimension varies and `size.length` is the
+ * one place it lives — otherwise "does it have depth?" would become `depth !== undefined` in every consumer. The POINT
+ * has named axes because code reads it all the time: `target.at.x` says what it is, `target.at[0]` makes you remember.
+ * The dimension is 2 or 3 and conformance refuses the rest, which closes the asymmetry: there is no `size` `Spot`
+ * cannot represent.
  */
 export interface Spot {
     readonly x: number;
     readonly y: number;
     readonly z?: number;
 }
-/** A dimensão que a topologia declara. `hotspots` não tem espaço, logo não tem dimensão. */
+/** The dimension the topology declares. `hotspots` has no space, so no dimension. */
 export declare function dimension(t: Topology): number;
 export type Role = 'hazard' | 'climb' | 'water' | 'goal' | 'gate' | 'key' | 'structure' | 'free';
 /**
- * ⚠️ `zenith` E `nadir` ENTRARAM PORQUE `up`/`down` JÁ QUEREM DIZER DUAS COISAS. `ACTIONS` (core/actions) tem
- * `up` e `down` como AÇÕES DE CONTROLE — o que a criança carrega —, e o eixo vertical do ESPAÇO é outra coisa
- * inteiramente. Enquanto o mundo era plano a ambiguidade não custava nada; num espaço de três dimensões
- * custaria o pior tipo de defeito, o que se lê certo e faz outra coisa. Palavras próprias, antes de o 3D chegar.
+ * ⚠️ `zenith` AND `nadir` EXIST BECAUSE `up`/`down` ALREADY MEAN TWO THINGS. `ACTIONS` (core/actions) has `up` and
+ * `down` as CONTROL ACTIONS — what the child presses — and the vertical axis of SPACE is something else entirely. On a
+ * flat world the ambiguity cost nothing; in three dimensions it would cost the worst kind of defect, one that reads right
+ * and does something else. Words of their own, before 3D arrives.
  */
 export type Heading = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw' | 'zenith' | 'nadir' | 'none';
 /**
- * PARA ONDE FICA UM PONTO VISTO DE OUTRO, já no referencial que a topologia declara.
+ * WHERE A POINT LIES AS SEEN FROM ANOTHER, already in the frame the topology declares.
  *
- * ⚠️ NÃO É O `heading` DO FOCO, e a diferença é o defeito que isto conserta. `Focus.heading` é para onde a
- * criança está VIRADA; isto é para onde está o ALVO. O sonar precisa do segundo e calculava-o à mão a partir
- * de `x` cru, com zona morta de ±4, dizendo `left`/`right`/`ahead` — três palavras onde o contrato tem oito, e
- * MISTURANDO REFERENCIAIS: *esquerda/direita* é relativo à tela, *à frente* é relativo ao corpo. Uma criança
- * cega que ouve as duas na mesma frase não tem como saber de qual origem cada uma fala.
+ * ⚠️ NOT THE FOCUS'S `heading`, and the difference is the defect this fixes. `Focus.heading` is where the child is
+ * FACING; this is where the TARGET is. The sonar needs the second and used to compute it by hand from a raw `x`, saying
+ * `left`/`right`/`ahead` — three words where the contract has eight, and MIXING FRAMES: left/right is relative to the
+ * screen, ahead is relative to the body. A blind child hearing both in one sentence cannot know which origin each one
+ * speaks from.
  */
 export type Bearing = {
     readonly kind: 'compass';
@@ -104,13 +103,13 @@ export type Bearing = {
     readonly kind: 'none';
 };
 export interface Focus {
-    /** Quem está com o foco. Um id do jogo — a engine não o interpreta, só o carrega. */
+    /** Who has the focus. A game id — the engine does not interpret it, only carries it. */
     readonly id: string;
     readonly at: Spot;
     readonly heading: Heading;
 }
 export interface Objective {
-    /** O que se está juntando/resolvendo: "moedas", "palavras", "contas". */
+    /** What is being gathered/solved: "coins", "words", "sums". */
     readonly name: Speakable;
     readonly have: number;
     readonly need: number;
@@ -125,202 +124,183 @@ export type Announcement = {
     readonly urgent: boolean;
 };
 /**
- * O que a criança vê como sendo o jogo.
+ * What the child sees as being the game.
  *
- * ⚠️ `none` NÃO É UM PADRÃO, É UMA ESCOLHA ESCRITA. Existe para atividade sem espaço — uma tela de pintura
- * livre, autoria, um formulário —, onde não há «mundo» para simular nem alvo para sonar. O Dev nomeou o caso:
- * *"atividades como paint não são exatamente jogos, mas podem ser feitas com a engine e sonar não vai
- * funcionar muito bem"*.
+ * ⚠️ `none` IS NOT A DEFAULT, IT IS A WRITTEN CHOICE. It exists for an activity without space — free painting,
+ * authoring, a form — where there is no world to simulate over and no target for a sonar. The Dev named the case:
+ * «atividades como paint não são exatamente jogos, mas podem ser feitas com a engine e sonar não vai funcionar muito
+ * bem».
  *
- * ⚠️ E O QUE ELE NÃO PODE SER É O QUE ACONTECE QUANDO ALGUÉM ESQUECE. Um jogo de DOM puro não é «um jogo onde
- * empatia não faz sentido»: o xadrez às cegas é a prova empírica de que faz. `none` é para quem DECLARA que
- * não tem espaço, e a ausência do campo é reprovada — hoje as duas coisas produzem o mesmo silêncio.
+ * ⚠️ AND WHAT IT CANNOT BE IS WHAT HAPPENS WHEN SOMEONE FORGETS. A pure-DOM game is not a game where empathy makes no
+ * sense: blindfold chess is the empirical proof that it does. `none` is for whoever DECLARES they have no space, and the
+ * field's absence is refused — otherwise both would produce the same silence.
  */
 export type WorldScope = 
-/** O seletor do elemento que é o mundo. A engine aplica ali o que é do mundo, e só ali. */
+/** The selector of the element that is the world. The engine applies what belongs to the world there, and only there. */
 {
     readonly kind: 'element';
     readonly selector: string;
 }
-/** Sem espaço. Empatia e sonar NÃO são oferecidos — e a tela de seleção diz isso antes de a criança começar. */
+/** No space. Empathy and sonar are NOT offered — and the selection screen says so before the child starts. */
  | {
     readonly kind: 'none';
 };
 /**
- * O que um jogo entrega à engine. `tick` é dado; TODO O RESTO é função, porque a resposta muda com a posição,
- * o jogador e o instante.
+ * What a game hands the engine. `tick` is data; EVERYTHING ELSE is a function, because the answer changes with the
+ * position, the player and the instant.
  *
- * ⚠️ NÃO IMPORTE ISTO INTEIRO num módulo consumidor. Use `Pick<GameDeclaration, 'roleAt'>` e afins — a regra é
- * a de `core/entity`, e é o que mantém os fixtures de teste pequenos.
+ * ⚠️ DO NOT IMPORT THIS WHOLE into a consuming module. Use `Pick<GameDeclaration, 'roleAt'>` and the like — the rule of
+ * `core/entity`, which keeps test fixtures small.
  */
 export interface GameDeclaration {
     /**
-     * A forma do espaço AGORA.
+     * The shape of the space NOW.
      *
-     * ⚠️ ERA UM VALOR ATÉ 2026-09-06, e a assimetria já tinha sido remendada em dois lugares antes de alguém a
-     * nomear: a porta do sonar sempre pediu `topology: () => Topology` (`platform/audio-sonar.ts`), e
-     * `boot/create-game` fazia a ponte com `() => o.declaration.topology` — uma função que devolve uma
-     * constante. O `game-15puzzle` (3×3/4×4/5×5) precisou de um getter para caber no tipo, e um getter que
-     * satisfaz uma interface é COINCIDÊNCIA DO TypeScript, não contrato: nada avisava o próximo autor de que
-     * era o esperado, e `conformanceProblems` lia uma vez só — quem memorizasse a topologia ficava defasado
-     * em silêncio. Remendo que aparece duas vezes é o contrato a pedir para mudar. ADR-0084.
+     * ⚠️ It was a value, and the asymmetry had been patched in two places before anyone named it: the sonar's port always
+     * asked for a function, and the root bridged it with a function returning a constant. A sliding puzzle whose board
+     * size changes needed a getter to fit the type — and a getter that satisfies an interface is a TypeScript
+     * COINCIDENCE, not a contract: nothing told the next author it was expected, and conformance read it once, so whoever
+     * memorised the topology went stale in silence. A patch that shows up twice is the contract asking to change.
+     * ADR-0084.
      */
     topology(): Topology;
     /**
-     * QUAL ELEMENTO É O MUNDO. Ver o bloco 8 acima para o defeito que este campo conserta.
+     * WHICH ELEMENT IS THE WORLD. See block 8 above for the defect this field fixes.
      *
-     * ⚠️ OBRIGATÓRIO, e a obrigatoriedade é a decisão. A proposta original era um campo opcional com padrão;
-     * o Dev recusou, e a razão é o BLINDFOLD CHESS: xadrez às cegas existe, logo um jogo de DOM puro não é um
-     * jogo onde empatia não faz sentido — é um jogo onde ela exige mais de quem o programa. Um padrão deixaria
-     * o esquecimento passar como se fosse escolha.
+     * ⚠️ REQUIRED, and requiring it is the decision. The original proposal was an optional field with a default; the Dev
+     * refused, and the reason is BLINDFOLD CHESS: it exists, so a pure-DOM game is not one where empathy makes no sense —
+     * it is one where it asks more of whoever programs it. A default would let forgetting pass as a choice.
      */
     world(): WorldScope;
     /**
-     * QUANTAS POSIÇÕES ESTE JOGO PRECISA DE SEGURAR AO MESMO TEMPO. Correr + andar + pular são TRÊS; um quiz é
-     * UM. (ADR-0104 §A.)
+     * HOW MANY POSITIONS THIS GAME NEEDS HELD AT THE SAME TIME. Run + walk + jump is THREE; a quiz is ONE. (ADR-0104 §A.)
      *
-     * ⚠️ É UM EIXO DIFERENTE DE «QUANTAS AÇÕES», e é por não serem o mesmo que existia um ponto cego onde o
-     * aviso nunca disparava. Medido: a plataforma declara NOVE ações e o controle de tela tem NOVE lugares,
-     * então o `alcance().ok` era verdadeiro e o cartão da #112 nunca aparecia — mas correr, andar e pular ao
-     * mesmo tempo são três dedos, e num telemóvel de dois a criança simplesmente não consegue, sem nada em
-     * lado nenhum a dizer porquê. Alcançar uma ação e segurá-la junto com outra são perguntas distintas.
+     * ⚠️ A DIFFERENT AXIS FROM "HOW MANY ACTIONS", and because they are not the same there was a blind spot where the
+     * warning never fired: a game declaring nine actions on a pad with nine places reached them all, so the reach notice
+     * never appeared — but running, walking and jumping at once is three fingers, and on a two-finger phone the child
+     * simply cannot, with nothing anywhere saying why. Reaching an action and holding it with another are two questions.
      *
-     * ⚠️ OBRIGATÓRIO, e a obrigatoriedade É a decisão, na frase do Dev: «os 300 jogos precisam declarar sim!
-     * Não declarar é ter a acessibilidade programada no controle pro sorte». Um campo opcional é respondido
-     * por SILÊNCIO, e aqui o silêncio decide pela criança — decide-o quem não pensou no assunto. Trezentos
-     * jogos a responder deliberadamente é o custo; acessibilidade por sorte é a alternativa.
+     * ⚠️ REQUIRED, and requiring it IS the decision, in the Dev's words: «os 300 jogos precisam declarar sim! Não declarar
+     * é ter a acessibilidade programada no controle pro sorte». An optional field is answered by SILENCE, and here the
+     * silence decides for the child — decided by whoever did not think about it.
      *
-     * FUNÇÃO e não valor, pela mesma razão que a `topology`: um jogo com fases troca de exigência entre elas —
-     * uma fase a pé pede três, a mesma fase num veículo pode pedir uma. Um valor memorizado ficaria defasado
-     * em silêncio, que é o defeito que o ADR-0084 nomeou.
+     * A FUNCTION and not a value, like `topology`: a game with stages changes its demand between them — on foot it asks
+     * for three, in a vehicle perhaps one. A memorised value would go stale in silence, the defect ADR-0084 named.
      */
     holdsAtOnce(): number;
     /**
-     * ESTE JOGO SEGURA ALGUMA TECLA? — e a resposta não é derivável de mais nada. (ADR-0115.)
+     * DOES THIS GAME HOLD ANY KEY? — and the answer cannot be derived from anything else. (ADR-0115.)
      *
-     * 🔴 A ALTERNÂNCIA EXISTE PARA UMA CRIANÇA CONCRETA: quem não consegue MANTER uma tecla premida carrega uma
-     * vez para andar e outra para parar. Num jogo onde nada se segura — um quiz, um tabuleiro, um puzzle de
-     * peças — não há nada a travar, e o controle passa a ser uma opção que **não faz nada**. A criança abre o
-     * menu de acessibilidade, liga o ajuste de que depende, e não acontece nada: ela aprende que o ajuste está
-     * partido. É o botão morto que o ADR-0106 §5 proíbe.
+     * 🔴 THE TOGGLE EXISTS FOR A CONCRETE CHILD: whoever cannot KEEP a key pressed taps once to walk and again to stop. In
+     * a game where nothing is held — a quiz, a board, a tile puzzle — there is nothing to latch, and the setting becomes
+     * an option that **does nothing**. The child opens the accessibility menu, turns on the setting they depend on, and
+     * nothing happens: they learn the setting is broken. It is the dead button ADR-0106 §5 forbids.
      *
-     * ⚠️ E O `holdsAtOnce` ACIMA NÃO RESPONDE ISTO, o que foi o achado que obrigou a este campo: ele conta
-     * POSIÇÕES SIMULTÂNEAS e recusa zero, porque zero faria a aritmética do alcance passar por vacuidade. O
-     * `consumer-quiz` declara **1 sem segurar coisa nenhuma**. «Um de cada vez» e «um SEGURADO» são o mesmo
-     * número, e toda decisão a jusante vinha a ler um número que responde a outra pergunta.
+     * ⚠️ AND `holdsAtOnce` ABOVE DOES NOT ANSWER THIS, which is the finding that forced this field: it counts SIMULTANEOUS
+     * positions and refuses zero, because zero would pass the reach arithmetic vacuously. The demo quiz declares **1
+     * while holding nothing at all**. "One at a time" and "one HELD" are the same number, and every decision downstream
+     * was reading a number that answers another question.
      *
-     * ⚠️ OBRIGATÓRIO, e a obrigatoriedade É a decisão — a mesma do `holdsAtOnce`, pela mesma frase do Dev:
-     * «não declarar é ter a acessibilidade programada no controle pro sorte». Um campo opcional faria um jogo
-     * que ESQUECE a linha perder a alternância em silêncio, e quem paga é a criança com dificuldade motora.
+     * ⚠️ REQUIRED, and requiring it IS the decision — the same as `holdsAtOnce`, by the same words of the Dev. An optional
+     * field would let a game that FORGETS the line lose the toggle in silence, and the child with a motor difficulty pays.
      *
-     * 📌 FUNÇÃO e não valor, pelo ADR-0084: um jogo muda de exigência entre fases. A pé segura-se uma direcção;
-     * o mesmo jogo dentro de um veículo pode não segurar nada.
+     * 📌 A FUNCTION and not a value, by ADR-0084: a game changes its demand between stages. On foot one holds a direction;
+     * the same game in a vehicle may hold nothing.
      */
-    seguraTeclas(): boolean;
+    holdsKeys(): boolean;
     /**
-     * ESTE JOGO PRECISA DE UM PONTEIRO — posição contínua? (ADR-0112.)
+     * DOES THIS GAME NEED A POINTER — a continuous position? (ADR-0112.)
      *
-     * Um jogo de desenho precisa; um quiz não. Declarar faz um aparelho sem ponteiro RECUSAR-SE antes de a
-     * criança começar, em vez de ela descobrir a meio do primeiro traço.
+     * A drawing game does; a quiz does not. Declaring it makes a device without a pointer REFUSE before the child starts,
+     * instead of them finding out halfway through the first stroke.
      *
-     * ⚠️ OPCIONAL, E A DIFERENÇA PARA O `holdsAtOnce` LOGO ACIMA É DELIBERADA — copiar a obrigatoriedade dele
-     * seria aplicar uma regra cuja premissa não se sustenta aqui. O `holdsAtOnce` é obrigatório porque não tem
-     * padrão seguro E porque falha INVISIVELMENTE a quem escreve o jogo: ele tem teclado completo, o jogo corre,
-     * e quem descobre o defeito é a criança no telemóvel de dois dedos. Este tem padrão seguro (`false`) e falha
-     * VISIVELMENTE — um jogo de desenho que se esqueça de o declarar é inoperável no próprio aparelho de quem o
-     * escreve, porque ele também precisaria do ponteiro para o experimentar.
+     * ⚠️ OPTIONAL, AND THE DIFFERENCE FROM `holdsAtOnce` JUST ABOVE IS DELIBERATE — copying its requirement would apply a
+     * rule whose premise does not hold here. `holdsAtOnce` is required because it has no safe default AND fails INVISIBLY to
+     * whoever writes the game: they have a full keyboard, the game runs, and the child on a two-finger phone is who finds
+     * the defect. This one has a safe default (`false`) and fails VISIBLY — a drawing game that forgets to declare it is
+     * unusable on its own author's device, because they would need the pointer to try it.
      *
-     * Obrigar trezentos jogos a escrever `needsPointer: () => false` cobraria o preço do `holdsAtOnce` sem o
-     * motivo dele.
-     *
-     * FUNÇÃO e não valor, pela mesma razão das outras: uma actividade pode desenhar numa fase e não noutra.
+     * A FUNCTION and not a value, like the others: an activity may draw in one stage and not in another.
      */
     needsPointer?(): boolean;
     /**
-     * O MAPEAMENTO DE TECLADO QUE ESTE JOGO QUER — por número de jogadores e por assento (ADR-0115).
-     *
-     * A precedência é a que o registo pede, e ela cabe entre duas linhas que já existiam no `input/keyboard`:
-     * **fábrica da engine → padrão do JOGO → remapeamento da CRIANÇA.** Devolver `null` (ou não declarar) deixa
-     * a fábrica da engine intacta, que é o comportamento de sempre.
+     * THE KEYBOARD MAPPING THIS GAME WANTS — by number of players and by seat (ADR-0115).
      *
-     * PARCIAL de propósito: um jogo que só queira trocar o `action1` troca o `action1`. A fusão já existe — é o
-     * `Object.assign` que sobrepõe o dado guardado —, então esta é mais uma camada no mesmo sítio e não uma
-     * segunda forma de fundir.
+     * The precedence is the one the record asks for: **the engine's factory → the GAME's default → the CHILD's remap.**
+     * Returning `null` (or not declaring it) leaves the engine's factory untouched, which is the behaviour it always had.
      *
-     * ⚠️ OPCIONAL, e aqui, ao contrário do `seguraTeclas`, o silêncio tem um lado seguro: sem declaração o jogo
-     * fica com a fábrica da engine, que é jogável e é o que ele já tem hoje. Não há lado errado na ausência.
+     * PARTIAL on purpose: a game that only wants to change `action1` changes `action1`. The merge already exists — the
+     * `Object.assign` that lays the stored data on top — so this is one more layer in the same place, not a second way to
+     * merge.
      *
-     * ⚠️ E LEVA O ASSENTO porque o teclado de dois jogadores não é o de um: as setas mudam de dono, e um padrão
-     * que não soubesse o assento daria as mesmas teclas a duas crianças. `jogadores` é 1, 2, 3 ou 4; `assento` é
-     * o índice dentro desse arranjo.
+     * ⚠️ OPTIONAL, and here, unlike `holdsKeys`, silence has a safe side: with no declaration the game keeps the engine's
+     * factory, which is playable and is what it has today.
      *
-     * 📌 O irmão do CONTROLE é o campo logo abaixo, e chegou um commit depois: o obstáculo era que o assento
-     * ainda não se conhecia no ponto em que a tabela de botões é lida, e a saída foi subi-lo no laço.
+     * ⚠️ AND IT TAKES THE SEAT because a two-player keyboard is not a one-player one: the arrows change owner, and a
+     * default that did not know the seat would give two children the same keys. `players` is 1, 2, 3 or 4; `seat` is the
+     * index within that arrangement.
      */
-    mapeamentoDoTeclado?(jogadores: number, assento: number): Partial<Record<Action, readonly string[] | null>> | null;
+    keyboardMapping?(players: number, seat: number): Partial<Record<Action, readonly string[] | null>> | null;
     /**
-     * O MAPEAMENTO DE BOTÕES QUE ESTE JOGO QUER NO CONTROLE — mesma pergunta, outro aparelho (ADR-0115).
+     * THE BUTTON MAPPING THIS GAME WANTS ON A PAD — the same question, another device (ADR-0115).
      *
-     * Índices de botão da Gamepad API «standard», parciais: `{ action1: 3 }` troca só essa. `null` num botão diz
-     * «esta posição não existe neste jogo», que é diferente de a deixar na fábrica.
+     * Button indices of the "standard" Gamepad API, partial: `{ action1: 3 }` changes just that one. `null` on a button
+     * says "this position does not exist in this game", which differs from leaving it at the factory.
      *
-     * ⚠️ A PRECEDÊNCIA TEM UMA DIFERENÇA DE SÍTIO QUE VALE SABER: no teclado, o que a criança remapeou é uma
-     * camada POR CIMA desta; no controle, o mapa que ela gravou no assistente é um RAMO inteiro — se ele existe,
-     * este padrão não é consultado. Nos dois casos ela ganha, que é o que importa.
+     * ⚠️ THE PRECEDENCE SITS IN A DIFFERENT PLACE, worth knowing: on the keyboard, the child's remap is a layer ON TOP of
+     * this; on a pad, the map they recorded in the wizard is a whole BRANCH — if it exists, this default is not consulted.
+     * Either way the child wins, which is what matters.
      *
-     * 📌 E leva o assento pela mesma razão do teclado, ainda que por um caminho diferente: dois controles são
-     * dois aparelhos, mas o JOGO pode querer arranjos distintos por assento (o guarda-redes e o atacante não
-     * fazem o mesmo).
+     * 📌 It takes the seat for the keyboard's reason, by another path: two pads are two devices, but the GAME may want
+     * different arrangements per seat (a goalkeeper and a striker do not do the same thing).
      */
-    mapeamentoDoPad?(jogadores: number, assento: number): Partial<Record<Action, number | null>> | null;
+    padMapping?(players: number, seat: number): Partial<Record<Action, number | null>> | null;
     readonly tick: TickOwner;
-    /** O papel do que está em `at`. É o campo 2, e é o que substitui `roleOf`. */
+    /** The role of what is at `at`. Field 2, and what replaces a table of tile numbers. */
     roleAt(at: Spot): Role;
-    /** Como se chama o que está em `at`. Sem isto não há leitor de tela nem Libras. */
+    /** What the thing at `at` is called. Without it there is no screen reader and no Libras. */
     nameAt(at: Spot): Speakable | null;
-    /** Quem tem o foco agora, e para onde aponta. `null` = ninguém (menu fechado, rodada não começou). */
+    /** Who has the focus now, and where it points. `null` = nobody (menu closed, round not started). */
     focusOf(playerIndex: number): Focus | null;
-    /** O que a rodada pede deste jogador. */
+    /** What the round asks of this player. */
     objectiveOf(playerIndex: number): Objective;
     /**
-     * ONDE estão os alvos ainda válidos deste jogador — a segunda metade do campo 5.
+     * WHERE this player's still-valid targets are — the second half of field 5.
      *
-     * É o que substitui o `getCoins()` do sonar: em vez de a engine varrer um array de moedas e filtrar por
-     * `taken`/`owner`, o jogo devolve os pontos que ainda contam para ESTE jogador. Um quiz devolve o índice da
-     * pergunta em aberto; uma plataforma devolve as moedas não coletadas; um Sokoban devolve as caixas fora do
-     * lugar. A engine só compara distâncias, e é por isso que o sonar passa a servir a qualquer gênero.
+     * Instead of the engine sweeping an array of coins and filtering by owner and taken, the game returns the spots that
+     * still count for THIS player. A quiz returns the open question's index; a platformer, the coins not taken; a
+     * Sokoban, the boxes out of place. The engine only compares distances, which is why the sonar serves any genre.
      *
-     * Vazio é resposta legítima e significa "não há para onde apontar" — não é erro.
+     * Empty is a legitimate answer and means "there is nowhere to point" — not an error.
      */
     targetsOf(playerIndex: number): readonly Spot[];
 }
 /**
- * Uma declaração é bem-formada? Devolve a lista de problemas — VAZIA quer dizer conforme.
+ * Is a declaration well formed? Returns the list of problems — EMPTY means conformant.
  *
- * Existe porque um preset é uma promessa, e promessa sem verificação é comentário. O ADR-0030 diz que um
- * pacote de gênero "ou satisfaz os sete campos ou não satisfaz"; isto é o "ou não".
+ * It exists because a preset is a promise, and a promise without a check is a comment. ADR-0030 says a genre package
+ * "either satisfies the seven fields or does not"; this is the "does not".
  *
- * Confere FORMA, não verdade: que a topologia tenha medida positiva, que as funções existam, que o objetivo
- * não peça um alvo impossível. Não tem como conferir se `roleAt` devolve o papel CERTO — isso é o teste do
- * preset, não deste módulo.
+ * It checks SHAPE, not truth: that the topology has a positive measure, that the functions exist. It cannot check
+ * whether `roleAt` returns the RIGHT role — that is the preset's own test, not this module's.
  */
 export declare function conformanceProblems(d: Partial<GameDeclaration> | null | undefined): string[];
-/** Um nome falável bem-formado? Texto vazio é o defeito silencioso: o leitor de tela simplesmente cala. */
+/** Is a speakable name well formed? Empty text is the silent defect: the screen reader simply goes quiet. */
 export declare function speakableProblems(s: Speakable | null | undefined): string[];
 /**
- * Distância entre dois pontos NA MÉTRICA declarada — a que o jogo declarou em `move`, e em quantas dimensões
- * ele declarou em `size`. É o que o sonar precisa e antes calculava em pixels.
+ * The distance between two spots IN THE DECLARED METRIC — the one the game declared in `move`, over as many dimensions
+ * as it declared in `size`. It is what the sonar needs and used to compute in pixels.
  *
- * ⚠️ A GRADE ERA SEMPRE CHEBYSHEV, e isso custava até 2× de erro num quebra-cabeça deslizante. As três regras
- * não são gosto: são o que "um passo" significa em cada jogo, e o sonar fala em passos.
+ * ⚠️ THE GRID WAS ALWAYS CHEBYSHEV, which cost up to 2× error in a sliding puzzle. The three rules are not taste: they
+ * are what "one step" means in each game, and the sonar speaks in steps.
  */
 export declare function distance(t: Topology, a: Spot, b: Spot): number;
 /**
- * PARA ONDE FICA `to` VISTO DE `from`, já nas palavras que a topologia declarou.
+ * WHERE `to` LIES AS SEEN FROM `from`, already in the words the topology declared.
  *
- * ⚠️ DOIS EIXOS COM CONVENÇÕES DIFERENTES, e o silêncio sobre isto seria o defeito. `y` CRESCE PARA BAIXO —
- * é a coordenada da tela, herdada da canvas e de todo o código que já existe, não uma escolha desta função.
- * `z` CRESCE PARA CIMA, e essa é escolha: nada a força, e num espaço de três dimensões «zênite» só pode
- * querer dizer o lado para onde a criança olharia levantando a cabeça. Um jogo 3D tem de saber os dois.
+ * ⚠️ TWO AXES WITH DIFFERENT CONVENTIONS, and silence about it would be the defect. `y` GROWS DOWNWARD — the screen's
+ * coordinate, inherited from the canvas and all existing code, not a choice of this function. `z` GROWS UPWARD, and
+ * that is a choice: nothing forces it, and in three dimensions "zenith" can only mean the side the child would look at
+ * by raising their head. A 3D game has to know both.
  */
 export declare function bearing(t: Topology, from: Spot, to: Spot): Bearing;