@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/core/contract.js

@@ -1,200 +1,214 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/contract — OS SETE CAMPOS. A interface que o ADR-0030 escolheu como o eixo da engine.
+// core/contract — THE SEVEN FIELDS. The interface ADR-0030 chose as the engine's axis.
 //
-// ⚠️ ESTE FICHEIRO NÃO TINHA IMPORT NENHUM, e o único que ganhou é `import type` — apagado na compilação, logo
-// o módulo publicado continua sem dependência de execução. O que entra é o VOCABULÁRIO das catorze posições
-// (ADR-0074), e ele tinha de entrar: um campo que fala de mapeamento e escrevesse as suas próprias chaves
-// seria a segunda cópia da união que o `core/actions` existe para ser a primeira.
+// ⚠️ Its one import is `import type` — erased at compile time, so the published module keeps no run-time dependency.
+// What comes in is the VOCABULARY of the fourteen positions (ADR-0074), and it had to: a field about mapping that wrote
+// its own keys would be a second copy of the union `core/actions` exists to be the first of.
 //
-// ========================= O QUE ISTO É, E O QUE NÃO É =========================
-// Não é um framework nem uma classe-base. É a ÚNICA coisa que a pilha de acessibilidade sabe sobre um jogo.
-// O ADR-0027 mediu que as três funções que MAIS pareciam genéricas eram as três mais amarradas à plataforma —
-// `roleOf` era uma tabela de tiles, `caneProbe` usava `facing` e `BOX.w`, o sonar definia alvo como "moeda não
-// coletada deste jogador". Nenhuma delas estava errada; todas estavam ADIVINHANDO o jogo em vez de perguntar.
+// ========================= WHAT THIS IS, AND WHAT IT IS NOT =========================
+// Not a framework nor a base class. It is the ONLY thing the accessibility stack knows about a game. ADR-0027 measured
+// that the three functions that looked MOST generic were the three most tied to the platformer — the role table was a
+// tile table, the cane probe used facing and a hitbox, the sonar defined a target as "a coin this player has not taken".
+// None was wrong; all were GUESSING the game instead of asking.
 //
-// Estes sete campos são as perguntas. Um jogo que as responda ganha sonar, alto contraste, varredura, leitor de
-// tela e Libras sem escrever uma linha deles — que é o produto, e não "mais uma engine 2D" (ADR-0027).
+// These seven fields are the questions. A game that answers them gets sonar, high contrast, scanning, screen reader and
+// Libras without writing a line of them — which is the product, not "one more 2D engine" (ADR-0027).
 //
-// ========================= PURO, E DE PROPÓSITO =========================
-// Só TIPOS e funções puras. Zero dependências, zero I/O no import: é módulo-FOLHA, importável dos dois lados da
-// fronteira e do project `node`. Um contrato que precisasse de PIXI já teria escolhido o gênero.
+// ========================= PURE, ON PURPOSE =========================
+// Only TYPES and pure functions. No dependencies, no I/O at import: a LEAF module, importable from both sides of the
+// boundary and from the `node` project. A contract that needed PIXI would already have chosen the genre.
 //
-// ========================= COMO SE USA: FATIAS, NÃO O OBJETO GORDO =========================
-// Vale aqui a mesma regra de `core/entity`: quem consome declara a FATIA MÍNIMA de que precisa, com `Pick`, em
-// vez de receber a declaração inteira. O alto contraste quer `Pick<GameDeclaration, 'roleAt'>` e nada mais; o
-// HUD quer `'objective'`. Trocar 23 visões estreitas por uma interface gorda destruiria a testabilidade que o
-// projeto tem hoje — todo fixture passaria a inventar campos que o módulo não usa.
+// ========================= HOW IT IS USED: SLICES, NOT THE FAT OBJECT =========================
+// The rule of `core/entity` holds here too: a consumer declares the MINIMAL slice it needs, with `Pick`, instead of
+// receiving the whole declaration. High contrast wants `Pick<GameDeclaration, 'roleAt'>` and nothing else; the HUD wants
+// `'objective'`. A fat interface would destroy the project's testability — every fixture would invent fields the module
+// does not use.
 //
-// ========================= O QUE TEM EVIDÊNCIA E O QUE AINDA NÃO TEM =========================
-// Cinco campos nasceram de um consumidor REAL que hoje adivinha (marcados abaixo com "hoje quem adivinha").
-// DOIS não têm consumidor no código ainda — `tick` e `Announcement` — e estão aqui porque o ADR-0027 os nomeia
-// como o que decide varredura e WCAG 2.2.1. Estão marcados. Enquanto nenhum módulo os ler, são hipótese, e o
-// ADR-0030 registra que "o contrato basta" só vira resultado quando DOIS presets existirem.
-/** A dimensão que a topologia declara. `hotspots` não tem espaço, logo não tem dimensão. */
-export function dimension(t) { return t.kind === 'hotspots' ? 0 : t.size.length; }
-/** O eixo `i` de um ponto, para quem percorre dimensões em vez de as nomear. */
-function eixo(s, i) { return i === 0 ? s.x : i === 1 ? s.y : (s.z ?? 0); }
-/* ===================== CONFORMIDADE ===================== */
-/**
- * Uma declaração é bem-formada? Devolve a lista de problemas — VAZIA quer dizer conforme.
- *
- * 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".
- *
- * 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.
- */
-export function conformanceProblems(d) {
-    const p = [];
-    if (!d)
-        return ['declaration missing'];
-    // ⚠️ DUAS FALHAS DIFERENTES, E ELAS PRECISAM DE DUAS MENSAGENS. `topology` ausente é um campo que ninguém
-    // escreveu; `topology` que não é função é o campo escrito à moda antiga — um VALOR, que passava no
-    // TypeScript de quem não recompilou e morreria em produção com "topology is not a function". Dizer só
-    // "ausente" mandaria o autor procurar um campo que está lá, à vista.
-    const t = typeof d.topology === 'function' ? d.topology() : undefined;
+// ========================= EVIDENCE =========================
+// Each field was born from a REAL consumer that used to guess, and ADR-0030 records that "the contract is enough" only
+// becomes a result when TWO presets exist.
+/** Axis `i` of a point, for whoever walks dimensions instead of naming them. */
+function axis(s, i) { return i === 0 ? s.x : i === 1 ? s.y : (s.z ?? 0); }
+function topologyProblems(d) {
+    // ⚠️ TWO DIFFERENT FAILURES, AND THEY NEED TWO MESSAGES. A missing `topology` is a field nobody wrote; a `topology`
+    // that is not a function is the field written the old way — a VALUE, which passed the TypeScript of whoever had not
+    // recompiled and would die in production with "topology is not a function". Saying only "missing" would send the
+    // author looking for a field that is right there.
+    // Each answer excludes the others, so each one returns: the order is the rule, and the space is asked for only once it
+    // is known to be a function.
     if (d.topology === undefined || d.topology === null)
-        p.push('topology: missing');
-    else if (typeof d.topology !== 'function')
-        p.push('topology: must be a FUNCTION (it was a value until ADR-0084)');
-    else if (!t)
-        p.push('topology: the function returned nothing');
-    else if (t.kind === 'grid' || t.kind === 'continuous') {
-        // ⚠️ A DIMENSÃO É `size.length`, e é por isso que ela é conferida ANTES de tudo: um `size` vazio ou de
-        // quatro entradas não é uma medida ruim, é um espaço que `Spot` não sabe representar — e o erro apareceria
-        // longe daqui, como um eixo simplesmente ignorado.
-        if (!Array.isArray(t.size) || t.size.length < 2 || t.size.length > 3) {
-            p.push('topology.size: must be [w, h] or [w, h, d] - dimension is 2 or 3, and it is size.length');
-        }
-        else if (!t.size.every((n) => n > 0)) {
-            p.push('topology.size: every extent must be positive');
-        }
-        // `move` é o que decide a métrica. Ausente, a distância seria adivinhada — e adivinhar Chebyshev num
-        // quebra-cabeça deslizante sub-relata até 2×, que foi o achado §3 do ADR-0080.
-        if (t.move !== 'orthogonal' && t.move !== 'diagonal' && t.move !== 'free') {
-            p.push('topology.move: must be "orthogonal" (L1), "diagonal" (L8/Chebyshev) or "free" (L2) - it is the metric the sonar counts in');
-        }
-        // `frame` é em que PALAVRAS a direção é dita. Sem ele a engine escolheria pela criança, e num jogo de
-        // plataforma escolheria mal: norte e sul não querem dizer nada numa vista lateral.
-        if (t.frame !== 'compass' && t.frame !== 'clock') {
-            p.push('topology.frame: must be "compass" (board, top-down, map, 3D) or "clock" (2D side view)');
-        }
-        // `unit` é o que dá MÉTRICA a um espaço contínuo: sem ela, "a dois passos" não tem como ser dito.
-        if (t.kind === 'continuous' && !(t.unit > 0)) {
-            p.push('topology.continuous: unit must be positive (it is the metric the narration counts in)');
-        }
+        return ['topology: missing'];
+    if (typeof d.topology !== 'function')
+        return ['topology: must be a FUNCTION (it was a value until ADR-0084)'];
+    const t = d.topology();
+    if (!t)
+        return ['topology: the function returned nothing'];
+    if (t.kind === 'grid' || t.kind === 'continuous')
+        return [...sizeProblems(t), ...metricProblems(t), ...frameProblems(t)];
+    if (t.kind === 'hotspots')
+        return hotspotProblems(t);
+    return ['topology: unknown kind'];
+}
+// ⚠️ THE DIMENSION IS `size.length`, which is why it is checked BEFORE anything: an empty or four-entry `size` is not a
+// bad measurement, it is a space `Spot` cannot represent — and the error would show far from here, as an axis simply
+// ignored.
+function sizeProblems(t) {
+    if (!Array.isArray(t.size) || t.size.length < 2 || t.size.length > 3) {
+        return ['topology.size: must be [w, h] or [w, h, d] - dimension is 2 or 3, and it is size.length'];
     }
-    else if (t.kind === 'hotspots') {
-        if (!t.order?.length)
-            p.push('topology.hotspots: order is empty - there is nowhere to navigate');
-        else if (new Set(t.order).size !== t.order.length)
-            p.push('topology.hotspots: order has a repeated id');
+    return !t.size.every((n) => n > 0) ? ['topology.size: every extent must be positive'] : [];
+}
+function metricProblems(t) {
+    const p = [];
+    // `move` decides the metric. Absent, distance would be guessed — and guessing Chebyshev in a sliding puzzle
+    // under-reports up to 2×, finding §3 of ADR-0080.
+    if (t.move !== 'orthogonal' && t.move !== 'diagonal' && t.move !== 'free') {
+        p.push('topology.move: must be "orthogonal" (L1), "diagonal" (L8/Chebyshev) or "free" (L2) - it is the metric the sonar counts in');
     }
-    else
-        p.push('topology: unknown kind');
-    // ⚠️ TRÊS FALHAS DISTINTAS, e a terceira é a que este campo existe para tornar impossível: um jogo cujo
-    // mundo NÃO foi declarado. Antes deste campo, esquecer e escolher «não tenho espaço» produziam o mesmo
-    // silêncio — e o silêncio era resolvido pela engine a adivinhar que o mundo é a canvas.
-    if (d.world === undefined || d.world === null) {
-        p.push('world: missing - declare the element that IS the game, or {kind:"none"} if it has no space');
+    // `unit` is what gives a continuous space a METRIC: without it, "two steps away" cannot be said.
+    if (t.kind === 'continuous' && !(t.unit > 0)) {
+        p.push('topology.continuous: unit must be positive (it is the metric the narration counts in)');
     }
-    else if (typeof d.world !== 'function') {
-        p.push('world: must be a FUNCTION');
+    return p;
+}
+// `frame` is in what WORDS a direction is said. Without it the engine would choose for the child, and in a platformer it
+// would choose badly: north and south mean nothing in a side view.
+function frameProblems(t) {
+    return t.frame !== 'compass' && t.frame !== 'clock'
+        ? ['topology.frame: must be "compass" (board, top-down, map, 3D) or "clock" (2D side view)']
+        : [];
+}
+function hotspotProblems(t) {
+    if (!t.order?.length)
+        return ['topology.hotspots: order is empty - there is nowhere to navigate'];
+    return new Set(t.order).size !== t.order.length ? ['topology.hotspots: order has a repeated id'] : [];
+}
+function worldProblems(d) {
+    // ⚠️ THREE DISTINCT FAILURES, and the third is the one this field exists to make impossible: a game whose world was
+    // NOT declared. Before this field, forgetting and choosing "I have no space" produced the same silence — and the
+    // silence was resolved by the engine guessing that the world is the canvas.
+    if (d.world === undefined || d.world === null) {
+        return ['world: missing - declare the element that IS the game, or {kind:"none"} if it has no space'];
     }
-    else {
-        const w = d.world();
-        if (!w)
-            p.push('world: the function returned nothing');
-        else if (w.kind === 'element') {
-            if (!w.selector || !w.selector.trim())
-                p.push('world: kind "element" needs a non-empty selector');
-        }
-        else if (w.kind !== 'none')
-            p.push('world: unknown kind');
+    if (typeof d.world !== 'function')
+        return ['world: must be a FUNCTION'];
+    const w = d.world();
+    if (!w)
+        return ['world: the function returned nothing'];
+    if (w.kind === 'element') {
+        return !w.selector || !w.selector.trim() ? ['world: kind "element" needs a non-empty selector'] : [];
     }
-    // ⚠️ A MENSAGEM NOMEIA A SAÍDA, como as outras quatro fazem. Um jogo que não declara isto não recebe um
-    // padrão — recebe uma frase que diz o que perguntar a si próprio, porque a resposta é do jogo e de mais
-    // ninguém. (ADR-0104 §A.)
+    return w.kind !== 'none' ? ['world: unknown kind'] : [];
+}
+function holdsAtOnceProblems(d) {
+    // ⚠️ THE MESSAGE NAMES THE WAY OUT, like the others do. A game that does not declare this gets no default — it gets a
+    // sentence saying what to ask itself, because the answer is the game's and nobody else's. (ADR-0104 §A.)
     if (typeof d.holdsAtOnce !== 'function') {
-        // ⚠️ A MENSAGEM NÃO NOMEIA GÊNERO, e o gate de fronteira cobrou-o: a primeira escrita dizia «run+walk+jump
-        // is 3, a quiz is 1» e o `engine-boundary` reprovou a palavra «quiz» em linha de CÓDIGO da engine. Ele
-        // tinha razão, e a frase ficou melhor: descreve a FORMA da pergunta, que serve aos 300 jogos, em vez de
-        // dois exemplos que servem a dois.
-        p.push('holdsAtOnce: missing - declare how many positions are held AT ONCE (three if three fingers must press together, one if commands arrive one at a time)');
-    }
-    else {
-        const n = d.holdsAtOnce();
-        if (!Number.isInteger(n) || n < 1) {
-            // Zero não é «não usa controle»: um jogo que não segura posição nenhuma não é jogável, e devolver zero
-            // faria a aritmética do alcance passar por vacuidade — o mesmo defeito que o `reachable` recusa.
-            p.push('holdsAtOnce: must be an integer >= 1 - a game that holds nothing cannot be played');
-        }
-    }
-    // ⚠️ E ESTA É A OUTRA PERGUNTA, que o número acima parecia responder e não responde (ADR-0115). A mensagem
-    // diz o que a ausência CUSTA, e não só o que falta: sem ela, um jogo que nada segura oferece um controle de
-    // acessibilidade que não faz nada, e um que segura tudo pode não o oferecer a quem depende dele.
-    if (typeof d.seguraTeclas !== 'function') {
-        p.push('seguraTeclas: missing - declare whether any key is HELD in this game (latching is offered only where something can be held, and a game that holds nothing must not show a control that does nothing)');
+        // ⚠️ THE MESSAGE NAMES NO GENRE, and the boundary gate insisted: a first wording used a quiz as the example and the
+        // gate refused the word in a line of engine CODE. It was right, and the sentence got better: it describes the SHAPE
+        // of the question, which serves every game, instead of two examples that serve two.
+        return ['holdsAtOnce: missing - declare how many positions are held AT ONCE (three if three fingers must press together, one if commands arrive one at a time)'];
     }
-    else if (typeof d.seguraTeclas() !== 'boolean') {
-        // Um valor não-booleano seria truthy e ofereceria a alternância a toda a gente — o mesmo defeito
-        // silencioso que o `needsPointer` recusa logo abaixo, e pela mesma razão.
-        p.push('seguraTeclas: must return a boolean - a non-boolean is truthy and would offer latching in a game where nothing is held');
-    }
-    // ⚠️ OPCIONAL, MAS NÃO IMPUNE. Ausente é a resposta `false` e não é problema — ver a nota no campo. O que
-    // se recusa é declará-lo MAL: um `needsPointer: true` (valor em vez de função) seria sempre verdadeiro por
-    // ser um objecto, e um que devolvesse `'sim'` também. Nos dois casos o jogo julgaria ter declarado, o
-    // alcance leria uma coisa diferente do que ele quis dizer, e ninguém saberia — que é o defeito silencioso
-    // que esta função inteira existe para não deixar acontecer.
-    if (d.needsPointer !== undefined) {
-        if (typeof d.needsPointer !== 'function') {
-            // ⚠️ MENSAGENS SEM A PALAVRA `as`, e o motivo merece uma linha porque volta a morder: o detector de prosa
-            // pt-BR do `engine-i18n` casa palavras funcionais isoladas, e `as` é artigo plural em português. Uma
-            // mensagem INGLESA que diga «declare it as …» é contada como texto cru e faz o tecto do módulo subir.
-            // O cabeçalho daquele gate já admite a aproximação («senão 'mode' casa 'de'»); reescrever a frase custa
-            // nada e afrouxar o detector custaria a razão de ele existir.
-            p.push('needsPointer: must be a function - write `needsPointer: () => true`, because a game may draw in one phase and not in another');
-        }
-        else if (typeof d.needsPointer() !== 'boolean') {
-            p.push('needsPointer: must return a boolean - a non-boolean would be truthy and refuse devices this game can actually use');
-        }
-    }
-    // ⚠️ E O MESMO PARA O MAPEAMENTO, com uma razão própria: aqui um valor em vez de uma função não seria um
-    // erro barulhento, seria um mapeamento SILENCIOSAMENTE ignorado — a fábrica da engine ficava, e a criança
-    // jogava com um teclado que o autor do jogo julga ter mudado. E devolver algo que não é objecto nem `null`
-    // atravessaria o `Object.assign` sem escrever nada, que é a mesma ausência com outra roupa.
-    if (d.mapeamentoDoTeclado !== undefined) {
-        if (typeof d.mapeamentoDoTeclado !== 'function') {
-            p.push('mapeamentoDoTeclado: must be a function - write `mapeamentoDoTeclado: (jogadores, assento) => ({ action1: ["KeyQ"] })`, because the keyboard of two players is not the keyboard of one');
-        }
-        else {
-            const m = d.mapeamentoDoTeclado(1, 0);
-            if (m !== null && (typeof m !== 'object' || Array.isArray(m))) {
-                p.push('mapeamentoDoTeclado: must return an object or null - anything else is merged into nothing, and this game keeps the engine factory while its author believes otherwise');
-            }
-        }
+    const n = d.holdsAtOnce();
+    // Zero is not "uses no controls": a game that holds no position cannot be played, and returning zero would pass the
+    // reach arithmetic vacuously — the same defect `reachable` refuses.
+    return !Number.isInteger(n) || n < 1
+        ? ['holdsAtOnce: must be an integer >= 1 - a game that holds nothing cannot be played']
+        : [];
+}
+function latchingProblems(d) {
+    // ⚠️ AND THIS IS THE OTHER QUESTION, which the number above seemed to answer and does not (ADR-0115). The message says
+    // what the absence COSTS, not only what is missing: without it a game that holds nothing offers an accessibility
+    // control that does nothing, and one that holds everything may not offer it to whoever depends on it.
+    if (typeof d.holdsKeys !== 'function') {
+        return ['holdsKeys: missing - declare whether any key is HELD in this game (latching is offered only where something can be held, and a game that holds nothing must not show a control that does nothing)'];
     }
-    if (d.mapeamentoDoPad !== undefined) {
-        if (typeof d.mapeamentoDoPad !== 'function') {
-            p.push('mapeamentoDoPad: must be a function - write `mapeamentoDoPad: (jogadores, assento) => ({ action1: 3 })`, because two seats may want different arrangements');
-        }
-        else {
-            const m = d.mapeamentoDoPad(1, 0);
-            if (m !== null && (typeof m !== 'object' || Array.isArray(m))) {
-                p.push('mapeamentoDoPad: must return an object or null - anything else is merged into nothing, and this game keeps the engine factory while its author believes otherwise');
-            }
-        }
+    // A non-boolean would be truthy and offer the toggle to everyone — the same silent defect `needsPointer` refuses just
+    // below, for the same reason.
+    return typeof d.holdsKeys() !== 'boolean'
+        ? ['holdsKeys: must return a boolean - a non-boolean is truthy and would offer latching in a game where nothing is held']
+        : [];
+}
+function pointerProblems(d) {
+    // ⚠️ OPTIONAL, BUT NOT UNCHECKED. Absent is the answer `false` and no problem — see the note on the field. What is
+    // refused is declaring it WRONG: `needsPointer: true` (a value instead of a function) would always be truthy for
+    // being an object, and one returning a string too. Either way the game would believe it had declared, the reach would
+    // read something other than what it meant, and nobody would know — the silent defect this whole function exists to
+    // prevent.
+    if (d.needsPointer === undefined)
+        return [];
+    if (typeof d.needsPointer !== 'function') {
+        // ⚠️ MESSAGES WITHOUT THE WORD `as`, worth a line because it bites again: the raw-prose detector of `engine-i18n`
+        // matches isolated function words, and `as` is a plural article in Portuguese. An ENGLISH message saying
+        // "declare it as …" is counted as raw text and raises the module's ceiling. Rewording costs nothing; loosening the
+        // detector would cost the reason it exists.
+        return ['needsPointer: must be a function - write `needsPointer: () => true`, because a game may draw in one phase and not in another'];
     }
-    if (d.tick !== 'player' && d.tick !== 'clock')
-        p.push('tick: must be "player" or "clock"');
-    for (const f of ['roleAt', 'nameAt', 'focusOf', 'objectiveOf', 'targetsOf']) {
-        if (typeof d[f] !== 'function')
-            p.push(`${f}: missing`);
+    return typeof d.needsPointer() !== 'boolean'
+        ? ['needsPointer: must return a boolean - a non-boolean would be truthy and refuse devices this game can actually use']
+        : [];
+}
+/**
+ * A MAPPING DECLARED BY THE GAME, for the keyboard or the pad.
+ *
+ * 🔴 IT WAS THE SAME CHECK WRITTEN TWICE, and the two copies were not equally guarded: the keyboard's two decisions had
+ * cases and the pad's two were BLIND — asymmetric coverage is how a duplicate announces itself, because one copy gets
+ * attention and the other is assumed.
+ *
+ * ⚠️ Here a value instead of a function would not be a loud error, it would be a mapping SILENTLY ignored — the engine's
+ * factory would stay, and the child would play with controls the game's author believes they changed. And returning
+ * something that is neither an object nor `null` would pass through `Object.assign` writing nothing, the same absence in
+ * other clothes.
+ */
+function mappingProblems(field, declared, example, because) {
+    if (declared === undefined)
+        return [];
+    if (typeof declared !== 'function') {
+        return [`${field}: must be a function - write \`${field}: ${example}\`, because ${because}`];
     }
-    return p;
+    // The names of THIS annotation are mine and were born in English; the field's own (`players`, `seat`) became
+    // English with phase 7 of the English plan (ADR-0230).
+    const m = declared(1, 0);
+    return m !== null && (typeof m !== 'object' || Array.isArray(m))
+        ? [`${field}: must return an object or null - anything else is merged into nothing, and this game keeps the engine factory while its author believes otherwise`]
+        : [];
+}
+const keyboardMappingProblems = (d) => mappingProblems('keyboardMapping', d.keyboardMapping, '(players, seat) => ({ action1: ["KeyQ"] })', 'the keyboard of two players is not the keyboard of one');
+const padMappingProblems = (d) => mappingProblems('padMapping', d.padMapping, '(players, seat) => ({ action1: 3 })', 'two seats may want different arrangements');
+const tickProblems = (d) => (d.tick !== 'player' && d.tick !== 'clock' ? ['tick: must be "player" or "clock"'] : []);
+/** The five questions the engine asks the world. Each absent one is ONE problem, and the message says WHICH is missing. */
+const READERS = ['roleAt', 'nameAt', 'focusOf', 'objectiveOf', 'targetsOf'];
+const readerProblems = (d) => READERS.filter((f) => typeof d[f] !== 'function').map((f) => `${f}: missing`);
+/**
+ * 📌 THIS TABLE'S ORDER IS THE ORDER OF THE MESSAGES, and it matters to the reader: an author writing a preset gets the
+ * problems in the order the fields appear in the contract, not in the order this file grew.
+ */
+const FIELD_CHECKS = [
+    topologyProblems,
+    worldProblems,
+    holdsAtOnceProblems,
+    latchingProblems,
+    pointerProblems,
+    keyboardMappingProblems,
+    padMappingProblems,
+    tickProblems,
+    readerProblems,
+];
+/**
+ * Is a declaration well formed? Returns the list of problems — EMPTY means conformant.
+ *
+ * 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".
+ *
+ * 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 function conformanceProblems(d) {
+    if (!d)
+        return ['declaration missing'];
+    return FIELD_CHECKS.flatMap((check) => check(d));
 }
-/** 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 function speakableProblems(s) {
     if (!s)
         return ['name missing'];
@@ -208,32 +222,32 @@ export function speakableProblems(s) {
     return p;
 }
 /**
- * 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 function distance(t, a, b) {
-    // Lista: a distância é quantos itens separam um do outro. Não há eixo, logo não há regra de movimento.
+    // A list: the distance is how many items lie between. There is no axis, so there is no movement rule.
     if (t.kind === 'hotspots')
         return Math.abs(a.x - b.x);
     const d = [];
     for (let i = 0; i < t.size.length; i++)
-        d.push(Math.abs(eixo(a, i) - eixo(b, i)));
-    const bruta = t.move === 'orthogonal' ? d.reduce((s, v) => s + v, 0) // L¹: cada eixo custa por si
-        : t.move === 'diagonal' ? Math.max(...d) // L∞: a diagonal custa um passo
-            : Math.hypot(...d); // L²: a reta entre os dois
-    // Contínuo: dividida pela unidade — o resultado é "quantos passos", não "quantos pixels".
-    return t.kind === 'continuous' ? bruta / t.unit : bruta;
+        d.push(Math.abs(axis(a, i) - axis(b, i)));
+    const rawDistance = t.move === 'orthogonal' ? d.reduce((s, v) => s + v, 0) // L¹: each axis costs on its own
+        : t.move === 'diagonal' ? Math.max(...d) // L∞: a diagonal costs one step
+            : Math.hypot(...d); // L²: the straight line between them
+    // Continuous: divided by the unit — the result is "how many steps", not "how many pixels".
+    return t.kind === 'continuous' ? rawDistance / t.unit : rawDistance;
 }
 /**
- * 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 function bearing(t, from, to) {
     if (t.kind === 'hotspots')
@@ -241,22 +255,22 @@ export function bearing(t, from, to) {
     const dx = to.x - from.x;
     const dy = to.y - from.y;
     const dz = t.size.length > 2 ? (to.z ?? 0) - (from.z ?? 0) : 0;
-    const plano = Math.hypot(dx, dy);
-    // O eixo vertical do ESPAÇO ganha quando domina o plano — e ganha em palavras próprias, porque `up`/`down`
-    // já são AÇÕES em `core/actions`. Ver o comentário de `Heading`.
-    if (Math.abs(dz) > plano)
+    const plane = Math.hypot(dx, dy);
+    // SPACE's vertical axis wins when it dominates the plane — and wins in words of its own, because `up`/`down` are
+    // already ACTIONS in `core/actions`. See the comment on `Heading`.
+    if (Math.abs(dz) > plane)
         return { kind: 'compass', heading: dz > 0 ? 'zenith' : 'nadir' };
-    if (plano === 0)
-        return { kind: 'none' }; // mesmo lugar: não há direção que dizer, e inventar uma seria mentir
-    // `-dy` porque o norte é para CIMA e `y` cresce para baixo. Sem esta troca a rosa sai invertida, e o teste
-    // que a apanharia é o único que precisa de existir aqui.
-    const ang = Math.atan2(-dy, dx); // 0 = leste, cresce no sentido anti-horário
+    if (plane === 0)
+        return { kind: 'none' }; // the same place: there is no direction to say, and inventing one would lie
+    // `-dy` because north is UP and `y` grows downward. Without this swap the rose comes out inverted, and the test that
+    // would catch it is the only one that needs to exist here.
+    const ang = Math.atan2(-dy, dx); // 0 = east, growing anticlockwise
     if (t.frame === 'clock') {
-        // 12 horas é para CIMA e os ponteiros andam no sentido horário — daí `90 - graus`, e não `graus`.
-        const horario = ((90 - (ang * 180) / Math.PI) % 360 + 360) % 360;
-        const h = Math.round(horario / 30) % 12;
+        // 12 o'clock is UP and the hands move clockwise — hence `90 - degrees`, not `degrees`.
+        const clockwiseDegrees = ((90 - (ang * 180) / Math.PI) % 360 + 360) % 360;
+        const h = Math.round(clockwiseDegrees / 30) % 12;
         return { kind: 'clock', hour: h === 0 ? 12 : h };
     }
-    const ROSA = ['e', 'ne', 'n', 'nw', 'w', 'sw', 's', 'se'];
-    return { kind: 'compass', heading: ROSA[(Math.round(ang / (Math.PI / 4)) % 8 + 8) % 8] };
+    const COMPASS_ROSE = ['e', 'ne', 'n', 'nw', 'w', 'sw', 's', 'se'];
+    return { kind: 'compass', heading: COMPASS_ROSE[(Math.round(ang / (Math.PI / 4)) % 8 + 8) % 8] };
 }

package/dist-pkg/core/dom-query.d.ts

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * `document.querySelector`, na forma em que os módulos o recebem por INJEÇÃO — nunca importando `document`.
+ * `document.querySelector`, in the shape modules receive it by INJECTION — never importing `document`.
  *
- * O padrão é `HTMLElement` e não `Element` porque é o que os chamadores usam: `.hidden`, `.textContent`,
- * `.dataset`, `.focus()`. Quem precisa de outra coisa instancia — há um `$<SVGElement>` na árvore, e é por
- * causa dele que a RESTRIÇÃO continua sendo `Element`.
+ * The default is `HTMLElement` and not `Element` because that is what callers use: `.hidden`, `.textContent`,
+ * `.dataset`, `.focus()`. Whoever needs something else instantiates it — there is a `$<SVGElement>` in the tree, and
+ * it is why the CONSTRAINT stays `Element`.
  */
 export type DomQuery = <T extends Element = HTMLElement>(sel: string) => T | null;

package/dist-pkg/core/dom-query.js

@@ -1,25 +1,17 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/dom-query — O SELETOR DE DOM INJETADO, declarado UMA VEZ.
+// core/dom-query — THE INJECTED DOM SELECTOR, declared ONCE.
 //
-// ========================= POR QUE ESTE ARQUIVO EXISTE =========================
-// A mesma declaração de `DomQuery` — uma seta genérica sobre `Element`, devolvendo `T | null` — estava
-// escrita em DEZESSEIS módulos: `game/coin-spawning`, `game/quiz`, `input/gamepad`, `input/keydown`,
-// `input/touch`, `input/touch-bindings`, `ui/activities-menu`, `ui/hud`, `ui/map-hub`, `ui/menu-nav`,
-// `ui/settings-audio`, `ui/settings-controls`, `ui/settings-motor`, `ui/settings-typo`, `ui/shell` e
-// `ui/title`.
+// ========================= WHY THIS FILE EXISTS =========================
+// The same `DomQuery` declaration — a generic arrow over `Element`, returning `T | null` — was written in SIXTEEN
+// modules: ADR-0039's defect one step up (there a FIELD described twice, here a TYPE described sixteen times).
 //
-// Dezesseis cópias de uma verdade, que é o defeito do ADR-0039 um degrau acima: lá era um CAMPO descrito
-// duas vezes, aqui é um TIPO descrito dezesseis.
+// And, as copies do, they diverged. One declared it NON-generic. A generic function assigned to a non-generic
+// signature is instantiated at its CONSTRAINT, not its default: the real `$`, `<T extends Element = HTMLElement>`,
+// became `Element` — and `Element` has no `hidden`. Two type errors came from it, and neither mentioned a selector.
 //
-// E, como sempre acontece com cópia, elas divergiram. O `game/session` declarava a sua NÃO-genérica,
-// devolvendo um `SessionEl` estrutural. Uma função genérica atribuída a uma assinatura não-genérica é
-// instanciada pela RESTRIÇÃO e não pelo padrão: o `$` real, que é `<T extends Element = HTMLElement>`,
-// virava `Element` — e `Element` não tem `hidden`. Dois erros de tipo no `main.ts` nasciam daí, e nenhum
-// deles falava de seletor.
-//
-// ========================= POR QUE EM `core/` =========================
-// Porque é a camada que todos podem importar sem inverter nada — `game/`, `input/`, `render/` e `ui/`. E
-// não custa dependência nenhuma: o arquivo é SÓ TIPO, `import type` é apagado na compilação, e `Element` é
-// global de `lib.dom`, ligado no tsconfig. Nada aqui roda, então a propriedade de `core/` ser testável sem
-// navegador continua intacta.
+// ========================= WHY IN `core/` =========================
+// Because it is the layer everyone may import without inverting anything — `input/`, `render/` and `ui/` (ADR-0173).
+// And it costs no dependency: `Element` is a `lib.dom` global, and a type is erased at build.
+// 📌 It holds only the TYPE. The two global queries that lived here (`$`, `$$` over `globalThis.document`) left in
+// ADR-0232 D4: every module now queries the document it is GIVEN, and the root builds its `$` over the host's.
 export {};