@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,100 +1,153 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** As quatorze posições que a engine conhece. Nenhuma delas é uma palavra que uma criança leia. */
+/** The fourteen positions the engine knows. None of them is a word a child reads. */
 export declare const ACTIONS: readonly ["up", "down", "left", "right", "action1", "action2", "action3", "action4", "leftShoulder", "leftTrigger", "rightShoulder", "rightTrigger", "start", "select"];
 export type Action = (typeof ACTIONS)[number];
-/** As quatro direções, que todo transporte tem de alcançar. */
+/** The four directions, which every transport has to reach. */
 export declare const DIRECTIONS: readonly ["up", "down", "left", "right"];
 /**
- * Os oito verbos, em DUAS metades que se nomeiam por critérios diferentes, e isso é decisão e não descuido:
+ * The eight verbs, in TWO halves named by different criteria, and that is a decision, not carelessness:
  *
- * · `action1`..`action4` — o losango. NUMERADOS, porque quatro posições em cruz não têm nomes que
- *   atravessem gêneros: o que uma plataforma chama de pulo, um quiz chama de confirmar.
- * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NOMEADOS pela anatomia da mão: dois
- *   dedos por mão, um por cima do outro. ADR-0086.
+ * · `action1`..`action4` — the diamond. NUMBERED, because four positions in a cross have no names that cross genres:
+ *   what a platformer calls jump, a quiz calls confirm.
+ * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NAMED by the hand's anatomy: two fingers per
+ *   hand, one above the other. ADR-0086.
  *
- * ⚠️ NÃO HÁ HIERARQUIA ENTRE ELES no contrato. A ordem é a de apresentação — no assistente do gamepad, na
- * tela de remapeamento — e não uma escala de importância: um jogo pode usar `rightShoulder` e nenhuma outra.
+ * ⚠️ THERE IS NO HIERARCHY BETWEEN THEM in the contract. The order is that of presentation — in the gamepad wizard, on
+ * the remap screen — and not a scale of importance: a game may use `rightShoulder` and nothing else.
  */
 export declare const VERBS: readonly ["action1", "action2", "action3", "action4", "leftShoulder", "leftTrigger", "rightShoulder", "rightTrigger"];
 /**
- * As duas de SISTEMA. Não pertencem ao mundo do jogo: `start` pausa e retoma, `select` abre o que é da sessão.
+ * The two SYSTEM ones. They do not belong to the game's world: `start` pauses and resumes, `select` opens what belongs
+ * to the session.
  *
- * ⚠️ E É POR ISSO QUE A ENGINE PODE NOMEÁ-LAS e não pode nomear as outras. O ADR-0074 proíbe um nome abstrato
- * chegar a uma pessoa porque `action1` não diz nada a ninguém — mas «start» e «select» são o que está escrito
- * no próprio controle desde 1983, e a criança lê a legenda antes de ler a nossa.
+ * ⚠️ AND THAT IS WHY THE ENGINE MAY NAME THEM and may not name the others. ADR-0074 forbids an abstract name reaching a
+ * person because `action1` says nothing to anyone — but "start" and "select" are what has been printed on the pad
+ * itself since 1983, and the child reads that legend before ours.
  */
 export declare const SYSTEM: readonly ["start", "select"];
-/** O que a criança lê e ouve para uma posição: o nome, e a frase que o explica quando ela pergunta. */
+/**
+ * What the child reads and hears for a position: the name, and the sentence that explains it when they ask — RESOLVED, in
+ * the page's language. The engine builds these from the game's KEYS (`wordsOf`) each time it draws; a game declares keys.
+ */
 export interface ActionWord {
-    /** «Pular», «Confirmar», «Colocar peça». NUNCA `action2` — nome abstrato que chega a uma pessoa é defeito. */
+    /** "Jump", "Confirm", "Place piece". NEVER `action2` — an abstract name reaching a person is a defect. */
     readonly label: string;
     /**
-     * A versão CURTA, para onde não cabe a longa. Cai em `label` quando ausente.
+     * The SHORT version, for where the long one does not fit. Falls back to `label` when absent.
      *
-     * ⚠️ NÃO É PREFERÊNCIA DE ESTILO: É LARGURA MEDIDA. A legenda do título põe a palavra debaixo de um glifo,
-     * numa fileira de quatro, e `ui/shell` já trazia a nota de que ali não cabe o «Correr / interagir» que a
-     * lista de remapeamento usa — por isso o dicionário tinha DUAS famílias de chaves para as mesmas quatro
-     * ações, `act.*` e `legend.*`. A distinção é do jogo, não da engine, então atravessa com as palavras.
+     * ⚠️ NOT A STYLE PREFERENCE: MEASURED WIDTH. A legend puts the word under a glyph, in a row of four, where the longer
+     * remap-screen wording does not fit — which is why the dictionary once had TWO families of keys for the same four
+     * actions. The distinction is the game's, not the engine's, so it crosses with the words.
      *
-     * ⚠️ E O RECUO PARA `label` DEGRADA VISUALMENTE, não funcionalmente: um jogo que não declare `short` vê a
-     * palavra longa espremida, e não uma legenda vazia. Escolhido assim porque uma legenda muda é pior do que
-     * uma legenda apertada — a primeira some para quem usa leitor de tela, a segunda não.
+     * ⚠️ AND THE FALLBACK TO `label` DEGRADES VISUALLY, not functionally: a game that declares no `short` gets the long
+     * word squeezed, not an empty legend. Chosen because a mute legend is worse than a tight one — the first vanishes for
+     * a screen reader user, the second does not.
      */
     readonly short?: string;
-    /** Opcional, para a tela de remapeamento: o que este botão faz, numa frase. */
+    /** Optional, for the remap screen: what this button does, in one sentence. */
     readonly hint?: string;
 }
 /**
- * O vocabulário de UM jogo: para cada posição que ele usa, a palavra dele.
+ * What a game DECLARES for a position: the KEYS of its words in its own dictionary (`CreateGameOptions.dictionaries`).
+ *
+ * 🔴 KEYS AND NOT WORDS (ADR-0232 D3, erratum of 2026-09-25). A word handed over at boot is in the boot language forever:
+ * 📏 measured, a preset built with `t` in Portuguese still read «Acima» after `setLocale('en')`. A key is resolved by the
+ * root's translator each time the engine draws or speaks it, so changing the language changes every word at once
+ * (ADR-0225), and the game never needs to know how (ADR-0216).
+ */
+export interface ActionKeys {
+    /** The key of the name: «Jump», «Confirm». A key the game's dictionaries lack leaves the position unnamed, and `problems` says so. */
+    readonly labelKey: string;
+    /** The key of the SHORT name, for a legend under a glyph. Falls back to the name when absent. */
+    readonly shortKey?: string;
+    /** The key of the sentence that says what this button does, for the help and the remap screen. */
+    readonly hintKey?: string;
+}
+/**
+ * The vocabulary of ONE game: for each position it uses, the keys of its words.
+ *
+ * ⚠️ PARTIAL ON PURPOSE. A game declares ONLY the positions it uses. Requiring all fourteen would make a quiz invent a
+ * name for a trigger it does not have, and an invented name ends up on a remap screen in front of a child.
+ */
+export type ActionPreset = Partial<Readonly<Record<Action, ActionKeys>>>;
+/** A preset RESOLVED into words, in the page's language — what the engine's surfaces read (`wordsOf`). */
+export type ActionWords = Partial<Readonly<Record<Action, ActionWord>>>;
+/** The positions this preset names, in the canonical order of `ACTIONS`. */
+export declare function presetActions(p: ActionPreset | ActionWords): Action[];
+/**
+ * THE GAME'S KEYS, RESOLVED NOW — called at every drawing, never kept (ADR-0232 D3 erratum).
  *
- * ⚠️ PARCIAL DE PROPÓSITO. Um jogo declara SÓ as posições que usa. Exigir as quatorze obrigaria um quiz a
- * inventar nome para um gatilho que ele não tem, e um nome inventado acaba numa tela de remapeamento à
- * frente de uma criança.
+ * A position whose NAME resolves to nothing is left out, so every surface treats it as unnamed — the rule `labellerFrom`
+ * already applies: an absence is one step fewer, never a mute step, and never the key itself on screen.
  */
-export type ActionPreset = Partial<Readonly<Record<Action, ActionWord>>>;
-/** As posições que este preset nomeia, na ordem canônica de `ACTIONS`. */
-export declare function presetActions(p: ActionPreset): Action[];
+export declare function wordsOf(p: ActionPreset, word: (key: string) => string | null): ActionWords;
 /**
- * A pergunta que a engine faz ao jogo quando precisa MOSTRAR uma ação: «como é que isto se chama?».
+ * The question the engine asks the game when it has to SHOW an action: "what is this called?".
  *
- * É a fronteira do corte em forma de função. A engine sabe que existe uma posição; só o jogo sabe a palavra,
- * e é esta função que atravessa.
+ * It is the cut's boundary in the shape of a function. The engine knows a position exists; only the game knows the
+ * word, and this function is what crosses.
  */
 export type ActionLabeller = (a: Action) => string;
 /**
- * Constrói o tradutor a partir de um preset.
+ * Builds the translator from a preset.
  *
- * ⚠️ E O QUE ELE FAZ COM UMA AÇÃO SEM NOME É A DECISÃO INTEIRA. Devolver `action7` seria pôr um nome abstrato
- * à frente de uma criança, que o ADR-0074 chama de defeito em tantas palavras. Devolver vazio calaria o leitor
- * de tela, que é o defeito silencioso que `speakableProblems` já persegue noutro sítio.
+ * ⚠️ AND WHAT IT DOES WITH AN UNNAMED ACTION IS THE WHOLE DECISION. Returning `action7` would put an abstract name in
+ * front of a child, which ADR-0074 calls a defect in so many words. Returning empty would silence the screen reader,
+ * the silent defect `speakableProblems` already chases elsewhere.
  *
- * Devolve `null`, e quem chama decide: o assistente de controle NÃO PERGUNTA por uma ação que o jogo não
- * nomeia — se o jogo não a usa, não há o que mapear. Uma ausência vira menos um passo, nunca um passo mudo.
+ * It returns `null`, and the caller decides: the pad wizard DOES NOT ASK for an action the game does not name — if the
+ * game does not use it, there is nothing to map. An absence becomes one step fewer, never a mute step. (`SYSTEM` is the
+ * exception there: the wizard asks START and SELECT in its own words, since no preset may name them — ADR-0144 erratum.)
  */
-export declare function labellerFrom(p: ActionPreset): (a: Action) => string | null;
+export declare function labellerFrom(p: ActionWords): (a: Action) => string | null;
 /**
- * O mesmo, na versão CURTA — para a legenda do título, onde a palavra vive debaixo de um glifo.
+ * The same, in the SHORT version — for a legend, where the word lives under a glyph.
  *
- * ⚠️ RECUA PARA `label`, e o recuo é a decisão: uma legenda apertada é pior que uma bonita e melhor que uma
- * vazia. Vazia sumiria também para quem usa leitor de tela, que é o custo que não se aceita aqui.
+ * ⚠️ IT FALLS BACK TO `label`, and the fallback is the decision: a tight legend is worse than a neat one and better than
+ * an empty one. Empty would also vanish for a screen reader user, which is the cost not accepted here.
  */
-export declare function shortLabellerFrom(p: ActionPreset): (a: Action) => string | null;
+export declare function shortLabellerFrom(p: ActionWords): (a: Action) => string | null;
 /**
- * Um preset é bem-formado? Devolve os problemas — VAZIA quer dizer conforme.
+ * Is a preset well formed? Returns the problems — EMPTY means conformant.
  *
- * ⚠️ O QUE ELE APANHA É O RÓTULO VAZIO, e é o mesmo defeito silencioso de `speakableProblems` em
- * `core/contract`: um `label` em branco não quebra nada, não avisa ninguém, e deixa a tela de remapeamento
- * com uma linha muda — que para quem usa leitor de tela é um botão que existe e não tem nome.
+ * ⚠️ WHAT IT CATCHES IS THE EMPTY KEY, the same silent defect as `speakableProblems` in `core/contract`: a blank
+ * `labelKey` breaks nothing, warns nobody, and leaves the remap screen with a mute row — for a screen reader user, a button
+ * that exists and has no name. Whether the key is IN the game's dictionaries is the root's question (`ui/declared-words`).
  */
 export declare function presetProblems(p: ActionPreset | null | undefined): string[];
-/** É uma ação conhecida? Guarda de fronteira para dado que veio de fora (mapa salvo, remapeamento). */
+/**
+ * `start` IS THE PAUSE'S, AND A GAME DOES NOT TAKE IT (ADR-0144 §4). Returns the reason, or `null`.
+ *
+ * ⚠️ THIS IS THE ONE CLAUSE OF THAT RECORD THAT ADDS A RESTRICTION instead of reusing something that was
+ * already there, and it is written down — rather than discovered in a conflict — because the record asked
+ * for exactly that. Since ADR-0122 the pause is not declinable, and `start` is the only position that
+ * reaches it: a game that claimed it for something else would be declining the pause by the back door, and
+ * the child would get four settings panels that are mounted, in the document, and unreachable.
+ *
+ * 📌 SEPARATE FROM `presetProblems`, and on purpose. That one answers «is this preset well formed?» and
+ * nobody calls it yet (issue for the wiring); this one is a PRE-CONDITION the boot refuses on, which is a
+ * different rubric — a malformed label degrades a remap screen, a stolen `start` removes the pause.
+ *
+ * 📌 `select` has its own sibling below, since ADR-0155 made it the door to the pause menus. Until then it stayed
+ * free on purpose: refusing it would have been deciding, in advance, something nobody had decided.
+ */
+export declare function startClaimProblem(p: ActionPreset | null | undefined): string | null;
+/**
+ * `select` OPENS THE PAUSE MENUS, AND A GAME DOES NOT TAKE IT EITHER (ADR-0155 §4). Returns the reason, or `null`.
+ *
+ * ⚠️ The same argument as `start`, one door over: START is now the quick pause and SELECT the six-item card, so
+ * a game claiming `select` would leave quitting, the number of players and the inclusion settings unreachable.
+ * 📏 Measured when written: no game repository declares `select` in a preset.
+ */
+export declare function selectClaimProblem(p: ActionPreset | null | undefined): string | null;
+/** Is it a known action? A boundary guard for data that came from outside (a saved map, a remap). */
 export declare function isAction(x: unknown): x is Action;
 /**
- * Uma declaração de ações usadas por um jogo é bem-formada? Devolve os problemas — VAZIA quer dizer conforme.
+ * Is a declaration of the actions a game uses well formed? Returns the problems — EMPTY means conformant.
  *
- * ⚠️ EXIGIR AS QUATRO DIREÇÕES SERIA ERRADO, e a tentação é grande: um quiz navega por `up`/`down` e não usa
- * `left`/`right`; um jogo de um botão não usa nenhuma. Quem decide o conjunto é o jogo. O que esta função
- * confere é que o conjunto é NOMEÁVEL e não está vazio — um jogo sem ação nenhuma não tem como ser jogado, e
- * hoje isso falharia em silêncio no primeiro transporte que tentasse ligar-se a nada.
+ * ⚠️ REQUIRING THE FOUR DIRECTIONS WOULD BE WRONG, and the temptation is strong: a quiz walks by `up`/`down` and uses
+ * no `left`/`right`; a one-button game uses none. The game decides the set. What this checks is that the set is
+ * NAMEABLE and not empty — a game with no action cannot be played, and that would otherwise fail in silence in the
+ * first transport that tried to bind to nothing.
  */
 export declare function actionSetProblems(used: readonly string[] | null | undefined): string[];

package/dist-pkg/core/actions.js

@@ -1,79 +1,95 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/actions — AS QUATORZE AÇÕES ABSTRATAS. A fonte única do vocabulário de entrada da engine.
+// core/actions — THE FOURTEEN ABSTRACT ACTIONS. The single source of the engine's input vocabulary.
 //
-// ========================= O QUE ISTO É =========================
-// O ADR-0074 decidiu que a engine conhece POSIÇÕES, não verbos, e que o JOGO fornece as palavras. Este módulo
-// é a lista dessas posições e nada mais: zero dependências, zero I/O, importável dos dois lados da fronteira.
+// ========================= WHAT THIS IS =========================
+// ADR-0074 decided that the engine knows POSITIONS, not verbs, and that the GAME supplies the words. This module is
+// the list of those positions and nothing else: no dependencies, no I/O, importable from both sides of the boundary.
+// It was written before the transports migrated to it (issue #103), so the migration had a destination instead of
+// inventing one.
 //
-// ⚠️ ATÉ AQUI A LISTA SÓ EXISTIA NUM REGISTRO. O código continua com os oito nomes de plataforma
-// (`jump`, `run`, `swap`, `especial`) espalhados por `input/gamepad`, `input/edges`, `input/devices` e
-// `input/keydown` — a migração é a issue #103 e não aconteceu. Este módulo é o alvo dela: um sítio para onde
-// os transportes passam a apontar, escrito antes para que a migração tenha destino em vez de o inventar.
+// ========================= WHY FOURTEEN AND NOT NINE =========================
+// ADR-0074 recorded nine and wrote, among its own drawbacks, that nine is a CEILING a genre may want to exceed and
+// that the record must say what happens then. The Dev exceeded it, asking for five more for richer games.
 //
-// ========================= POR QUE QUATORZE E NÃO NOVE =========================
-// O ADR-0074 registrou nove e escreveu, entre as suas próprias desvantagens, que «nove é um TETO que um gênero
-// pode querer exceder, e o registro tem de dizer o que acontece». O Dev excedeu-o em 2026-09-06, pedindo mais
-// cinco para jogos mais elaborados. O ADR-0085 é o que acontece.
+// ⚠️ AND THE FOUR NEW ONES ARE `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NOT
+// `action5`..`action8`. I argued for numbers and the Dev decided against, for a reason ADR-0086 records: `action7` is
+// unreadable where someone programs, and a vocabulary nobody can read aloud is not abstraction, it is cipher.
 //
-// ⚠️ E OS QUATRO NOVOS CHAMAM-SE `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NÃO
-// `action5`..`action8`. Eu argumentei pelos números e o Dev decidiu contra, em 2026-09-06, com uma razão que
-// o ADR-0086 registra: `action7` é ilegível no ponto onde alguém programa, e um vocabulário que ninguém
-// consegue ler em voz alta não é abstração, é cifra. O ADR-0085 dizia o contrário; foi supersedido, não
-// emendado.
+// ⚠️ AND THE OBJECTION STAYS WRITTEN, because it does not vanish when the decision went the other way: shoulder and
+// trigger are a GAMEPAD's shape. On a keyboard `leftTrigger` is a key; on touch, a slot; for a speech recogniser, a
+// word. ADR-0086 answers that the shape is ANATOMICAL before it is a gamepad's — two fingers per hand, one above the
+// other — and that this crosses transports better than a number does. Whoever disagrees should read both records.
 //
-// ⚠️ E A OBJEÇÃO CONTINUA ESCRITA, porque ela não some por a decisão ter sido outra: ombro e gatilho são
-// FORMA DE GAMEPAD. Num teclado, `leftTrigger` é a tecla Y; num toque, um slot; num reconhecedor de fala, uma
-// palavra. O ADR-0086 responde que a forma é ANATÔMICA antes de ser de gamepad — dois dedos por mão, um por
-// cima do outro — e que isso atravessa transportes melhor do que um número atravessa. Quem discordar leia os
-// dois registros, que é para isso que eles existem.
-//
-// `start` e `select` mantêm nome pelo critério que já valia para `start`: são FUNÇÃO, não posição — o que é
-// do sistema e não do mundo do jogo.
-/** As quatorze posições que a engine conhece. Nenhuma delas é uma palavra que uma criança leia. */
+// `start` and `select` keep names by the criterion that already held for `start`: they are a FUNCTION, not a
+// position — what belongs to the system and not to the game's world.
+/** The fourteen positions the engine knows. None of them is a word a child reads. */
 export const ACTIONS = [
     'up', 'down', 'left', 'right',
     'action1', 'action2', 'action3', 'action4',
     'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
     'start', 'select',
 ];
-/** As quatro direções, que todo transporte tem de alcançar. */
+/** The four directions, which every transport has to reach. */
 export const DIRECTIONS = ['up', 'down', 'left', 'right'];
 /**
- * Os oito verbos, em DUAS metades que se nomeiam por critérios diferentes, e isso é decisão e não descuido:
+ * The eight verbs, in TWO halves named by different criteria, and that is a decision, not carelessness:
  *
- * · `action1`..`action4` — o losango. NUMERADOS, porque quatro posições em cruz não têm nomes que
- *   atravessem gêneros: o que uma plataforma chama de pulo, um quiz chama de confirmar.
- * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NOMEADOS pela anatomia da mão: dois
- *   dedos por mão, um por cima do outro. ADR-0086.
+ * · `action1`..`action4` — the diamond. NUMBERED, because four positions in a cross have no names that cross genres:
+ *   what a platformer calls jump, a quiz calls confirm.
+ * · `leftShoulder`, `leftTrigger`, `rightShoulder`, `rightTrigger` — NAMED by the hand's anatomy: two fingers per
+ *   hand, one above the other. ADR-0086.
  *
- * ⚠️ NÃO HÁ HIERARQUIA ENTRE ELES no contrato. A ordem é a de apresentação — no assistente do gamepad, na
- * tela de remapeamento — e não uma escala de importância: um jogo pode usar `rightShoulder` e nenhuma outra.
+ * ⚠️ THERE IS NO HIERARCHY BETWEEN THEM in the contract. The order is that of presentation — in the gamepad wizard, on
+ * the remap screen — and not a scale of importance: a game may use `rightShoulder` and nothing else.
  */
 export const VERBS = [
     'action1', 'action2', 'action3', 'action4',
     'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
 ];
 /**
- * As duas de SISTEMA. Não pertencem ao mundo do jogo: `start` pausa e retoma, `select` abre o que é da sessão.
+ * The two SYSTEM ones. They do not belong to the game's world: `start` pauses and resumes, `select` opens what belongs
+ * to the session.
  *
- * ⚠️ E É POR ISSO QUE A ENGINE PODE NOMEÁ-LAS e não pode nomear as outras. O ADR-0074 proíbe um nome abstrato
- * chegar a uma pessoa porque `action1` não diz nada a ninguém — mas «start» e «select» são o que está escrito
- * no próprio controle desde 1983, e a criança lê a legenda antes de ler a nossa.
+ * ⚠️ AND THAT IS WHY THE ENGINE MAY NAME THEM and may not name the others. ADR-0074 forbids an abstract name reaching a
+ * person because `action1` says nothing to anyone — but "start" and "select" are what has been printed on the pad
+ * itself since 1983, and the child reads that legend before ours.
  */
 export const SYSTEM = ['start', 'select'];
-/** As posições que este preset nomeia, na ordem canônica de `ACTIONS`. */
+/** The positions this preset names, in the canonical order of `ACTIONS`. */
 export function presetActions(p) {
     return ACTIONS.filter((a) => p[a] !== undefined);
 }
+/** Resolves one declared key through `word`; a key that is not text resolves to nothing. */
+const resolved = (word, key) => (typeof key === 'string' && key.trim() ? word(key) : null);
+/**
+ * THE GAME'S KEYS, RESOLVED NOW — called at every drawing, never kept (ADR-0232 D3 erratum).
+ *
+ * A position whose NAME resolves to nothing is left out, so every surface treats it as unnamed — the rule `labellerFrom`
+ * already applies: an absence is one step fewer, never a mute step, and never the key itself on screen.
+ */
+export function wordsOf(p, word) {
+    const words = {};
+    for (const a of presetActions(p)) {
+        const keys = p[a];
+        const label = resolved(word, keys.labelKey);
+        if (!label)
+            continue;
+        const short = resolved(word, keys.shortKey);
+        const hint = resolved(word, keys.hintKey);
+        words[a] = { label, ...(short ? { short } : {}), ...(hint ? { hint } : {}) };
+    }
+    return words;
+}
 /**
- * Constrói o tradutor a partir de um preset.
+ * Builds the translator from a preset.
  *
- * ⚠️ E O QUE ELE FAZ COM UMA AÇÃO SEM NOME É A DECISÃO INTEIRA. Devolver `action7` seria pôr um nome abstrato
- * à frente de uma criança, que o ADR-0074 chama de defeito em tantas palavras. Devolver vazio calaria o leitor
- * de tela, que é o defeito silencioso que `speakableProblems` já persegue noutro sítio.
+ * ⚠️ AND WHAT IT DOES WITH AN UNNAMED ACTION IS THE WHOLE DECISION. Returning `action7` would put an abstract name in
+ * front of a child, which ADR-0074 calls a defect in so many words. Returning empty would silence the screen reader,
+ * the silent defect `speakableProblems` already chases elsewhere.
  *
- * Devolve `null`, e quem chama decide: o assistente de controle NÃO PERGUNTA por uma ação que o jogo não
- * nomeia — se o jogo não a usa, não há o que mapear. Uma ausência vira menos um passo, nunca um passo mudo.
+ * It returns `null`, and the caller decides: the pad wizard DOES NOT ASK for an action the game does not name — if the
+ * game does not use it, there is nothing to map. An absence becomes one step fewer, never a mute step. (`SYSTEM` is the
+ * exception there: the wizard asks START and SELECT in its own words, since no preset may name them — ADR-0144 erratum.)
  */
 export function labellerFrom(p) {
     return (a) => {
@@ -82,57 +98,92 @@ export function labellerFrom(p) {
     };
 }
 /**
- * O mesmo, na versão CURTA — para a legenda do título, onde a palavra vive debaixo de um glifo.
+ * The same, in the SHORT version — for a legend, where the word lives under a glyph.
  *
- * ⚠️ RECUA PARA `label`, e o recuo é a decisão: uma legenda apertada é pior que uma bonita e melhor que uma
- * vazia. Vazia sumiria também para quem usa leitor de tela, que é o custo que não se aceita aqui.
+ * ⚠️ IT FALLS BACK TO `label`, and the fallback is the decision: a tight legend is worse than a neat one and better than
+ * an empty one. Empty would also vanish for a screen reader user, which is the cost not accepted here.
  */
 export function shortLabellerFrom(p) {
     return (a) => {
         const w = p[a];
         if (!w)
             return null;
-        const curto = w.short && w.short.trim() ? w.short : w.label;
-        return curto && curto.trim() ? curto : null;
+        const short = w.short && w.short.trim() ? w.short : w.label;
+        return short && short.trim() ? short : null;
     };
 }
 /**
- * Um preset é bem-formado? Devolve os problemas — VAZIA quer dizer conforme.
+ * Is a preset well formed? Returns the problems — EMPTY means conformant.
  *
- * ⚠️ O QUE ELE APANHA É O RÓTULO VAZIO, e é o mesmo defeito silencioso de `speakableProblems` em
- * `core/contract`: um `label` em branco não quebra nada, não avisa ninguém, e deixa a tela de remapeamento
- * com uma linha muda — que para quem usa leitor de tela é um botão que existe e não tem nome.
+ * ⚠️ WHAT IT CATCHES IS THE EMPTY KEY, the same silent defect as `speakableProblems` in `core/contract`: a blank
+ * `labelKey` breaks nothing, warns nobody, and leaves the remap screen with a mute row — for a screen reader user, a button
+ * that exists and has no name. Whether the key is IN the game's dictionaries is the root's question (`ui/declared-words`).
  */
 export function presetProblems(p) {
     if (!p)
         return ['preset: missing'];
     const problemas = [];
-    const nomeadas = presetActions(p);
-    if (nomeadas.length === 0)
+    const named = presetActions(p);
+    if (named.length === 0)
         problemas.push('preset: names no action - the child would see an unlabelled control');
-    for (const chave of Object.keys(p)) {
-        if (!isAction(chave))
-            problemas.push(`preset: ${chave} is not an action`);
+    for (const key of Object.keys(p)) {
+        if (!isAction(key))
+            problemas.push(`preset: ${key} is not an action`);
     }
-    for (const a of nomeadas) {
+    for (const a of named) {
         const w = p[a];
-        if (!w || !w.label || !w.label.trim()) {
-            problemas.push(`preset: ${a} has an empty label - the remap screen would show a nameless button`);
+        if (!w || typeof w.labelKey !== 'string' || !w.labelKey.trim()) {
+            problemas.push(`preset: ${a} has an empty labelKey - the remap screen would show a nameless button`);
         }
     }
     return problemas;
 }
-/** É uma ação conhecida? Guarda de fronteira para dado que veio de fora (mapa salvo, remapeamento). */
+/**
+ * `start` IS THE PAUSE'S, AND A GAME DOES NOT TAKE IT (ADR-0144 §4). Returns the reason, or `null`.
+ *
+ * ⚠️ THIS IS THE ONE CLAUSE OF THAT RECORD THAT ADDS A RESTRICTION instead of reusing something that was
+ * already there, and it is written down — rather than discovered in a conflict — because the record asked
+ * for exactly that. Since ADR-0122 the pause is not declinable, and `start` is the only position that
+ * reaches it: a game that claimed it for something else would be declining the pause by the back door, and
+ * the child would get four settings panels that are mounted, in the document, and unreachable.
+ *
+ * 📌 SEPARATE FROM `presetProblems`, and on purpose. That one answers «is this preset well formed?» and
+ * nobody calls it yet (issue for the wiring); this one is a PRE-CONDITION the boot refuses on, which is a
+ * different rubric — a malformed label degrades a remap screen, a stolen `start` removes the pause.
+ *
+ * 📌 `select` has its own sibling below, since ADR-0155 made it the door to the pause menus. Until then it stayed
+ * free on purpose: refusing it would have been deciding, in advance, something nobody had decided.
+ */
+export function startClaimProblem(p) {
+    if (!p || p.start === undefined)
+        return null;
+    return 'preset: «start» is the position that opens the pause (ADR-0144 §4) and a game may not claim it; '
+        + 'use one of the eight verb positions instead (action1..action4, leftShoulder, leftTrigger, rightShoulder, rightTrigger)';
+}
+/**
+ * `select` OPENS THE PAUSE MENUS, AND A GAME DOES NOT TAKE IT EITHER (ADR-0155 §4). Returns the reason, or `null`.
+ *
+ * ⚠️ The same argument as `start`, one door over: START is now the quick pause and SELECT the six-item card, so
+ * a game claiming `select` would leave quitting, the number of players and the inclusion settings unreachable.
+ * 📏 Measured when written: no game repository declares `select` in a preset.
+ */
+export function selectClaimProblem(p) {
+    if (!p || p.select === undefined)
+        return null;
+    return 'preset: «select» is the position that opens the pause menus (ADR-0155 §4) and a game may not claim it; '
+        + 'use one of the eight verb positions instead (action1..action4, leftShoulder, leftTrigger, rightShoulder, rightTrigger)';
+}
+/** Is it a known action? A boundary guard for data that came from outside (a saved map, a remap). */
 export function isAction(x) {
     return typeof x === 'string' && ACTIONS.includes(x);
 }
 /**
- * Uma declaração de ações usadas por um jogo é bem-formada? Devolve os problemas — VAZIA quer dizer conforme.
+ * Is a declaration of the actions a game uses well formed? Returns the problems — EMPTY means conformant.
  *
- * ⚠️ EXIGIR AS QUATRO DIREÇÕES SERIA ERRADO, e a tentação é grande: um quiz navega por `up`/`down` e não usa
- * `left`/`right`; um jogo de um botão não usa nenhuma. Quem decide o conjunto é o jogo. O que esta função
- * confere é que o conjunto é NOMEÁVEL e não está vazio — um jogo sem ação nenhuma não tem como ser jogado, e
- * hoje isso falharia em silêncio no primeiro transporte que tentasse ligar-se a nada.
+ * ⚠️ REQUIRING THE FOUR DIRECTIONS WOULD BE WRONG, and the temptation is strong: a quiz walks by `up`/`down` and uses
+ * no `left`/`right`; a one-button game uses none. The game decides the set. What this checks is that the set is
+ * NAMEABLE and not empty — a game with no action cannot be played, and that would otherwise fail in silence in the
+ * first transport that tried to bind to nothing.
  */
 export function actionSetProblems(used) {
     const p = [];
@@ -140,9 +191,9 @@ export function actionSetProblems(used) {
         return ['action set: missing'];
     if (used.length === 0)
         return ['action set: empty - a game with no action cannot be played'];
-    const desconhecidas = used.filter((a) => !isAction(a));
-    if (desconhecidas.length)
-        p.push(`action set: unknown action(s) ${desconhecidas.join(', ')}`);
+    const unknown = used.filter((a) => !isAction(a));
+    if (unknown.length)
+        p.push(`action set: unknown action(s) ${unknown.join(', ')}`);
     if (new Set(used).size !== used.length)
         p.push('action set: has a repeated action');
     return p;

package/dist-pkg/core/calm-mode.d.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The calm cycle: 0 = normal · 1 = quiet (reduces) · 2 = silent (switches off). */
+export declare const CALM_NAMES: readonly string[];
+/** The audio categories calm mode governs. The others are left intact on purpose (see the header). */
+export declare const CALM_AUDIO_CATS: readonly string[];
+/** One step of the cycle. */
+export declare const nextCalmMode: (cur: number) => number;
+/**
+ * The stored level, sanitised, with the caller's fallback.
+ *
+ * ⚠️ Data from the browser is data from OUTSIDE: an invented level would pick `CALM_NAMES[3]`, which is `undefined`, and the
+ * announcement to the screen reader would come out empty — the child who depends on it would hear silence and not know which
+ * level she is in.
+ */
+export declare function sanitiseTeaLevel(raw: number, fallback: number): number;
+/**
+ * What the level does to ONE audio category.
+ *
+ * 📌 The clamp of level 1 is DESTRUCTIVE, and it is in plain sight for that reason: it writes 0.3 over the volume the child
+ * chose, and going back to level 0 returns the stored value, not the one she had before. Extracted so that this can be
+ * measured by a case.
+ */
+export declare function calmAudioPlan(calmMode: number, vol: number): {
+    on: boolean;
+    vol: number;
+};
+/** What the level does to the two reduced-motion flags. */
+export declare function calmMotionPlan(calmMode: number): {
+    sceneReduced: boolean;
+    charFrozen: boolean;
+};

package/dist-pkg/core/calm-mode.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/calm-mode — SENSORY COMFORT IN THREE LEVELS, and what each one silences (ADR-0028; issue #203).
+//
+// 🔴 WHY THIS LEFT `ui/pause-icons`: that module had reached 695 lines of code and 127 decision nodes (ADR-0221), and this
+// group is not about ICONS. It is about what a child who cannot bear noise needs the engine to silence — the icon is one of
+// the surfaces she asks through; the panel row is another. A module that answers «what does level 2 do to the audio?» should
+// not require reading a file about the accessibility bar to be found.
+//
+// ⚠️ A LEAF MODULE: zero imports, zero DOM, zero storage. Everything here is a question with an answer — which is what makes
+// the destructive clamp of level 1 testable without mounting anything.
+//
+// 📌 WHAT IT NEVER TOUCHES, and it is the decision that defines it: TTS, sonar, ledge guard and guide. The calm level is about
+// NOISE, not about losing navigation — a child in silent mode still needs to hear where she is.
+/** The calm cycle: 0 = normal · 1 = quiet (reduces) · 2 = silent (switches off). */
+export const CALM_NAMES = ['calm.off', 'calm.quiet', 'calm.silent'];
+/** The audio categories calm mode governs. The others are left intact on purpose (see the header). */
+export const CALM_AUDIO_CATS = ['ambient', 'music', 'earcons', 'interact'];
+/** One step of the cycle. */
+export const nextCalmMode = (cur) => (cur + 1) % CALM_NAMES.length;
+/**
+ * The stored level, sanitised, with the caller's fallback.
+ *
+ * ⚠️ Data from the browser is data from OUTSIDE: an invented level would pick `CALM_NAMES[3]`, which is `undefined`, and the
+ * announcement to the screen reader would come out empty — the child who depends on it would hear silence and not know which
+ * level she is in.
+ */
+export function sanitiseTeaLevel(raw, fallback) {
+    return Number.isInteger(raw) && raw >= 0 && raw < CALM_NAMES.length ? raw : fallback;
+}
+/**
+ * What the level does to ONE audio category.
+ *
+ * 📌 The clamp of level 1 is DESTRUCTIVE, and it is in plain sight for that reason: it writes 0.3 over the volume the child
+ * chose, and going back to level 0 returns the stored value, not the one she had before. Extracted so that this can be
+ * measured by a case.
+ */
+export function calmAudioPlan(calmMode, vol) {
+    if (calmMode === 0)
+        return { on: true, vol };
+    if (calmMode === 1)
+        return { on: true, vol: Math.min(vol, 0.3) };
+    return { on: false, vol };
+}
+/** What the level does to the two reduced-motion flags. */
+export function calmMotionPlan(calmMode) {
+    return { sceneReduced: calmMode >= 1, charFrozen: calmMode === 2 };
+}