@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,29 +1,27 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Action } from './actions.js';
-import type { VisualState } from '../render/viz-axes.js';
+import type { VisualState } from './visual-state.js';
 /**
- * Ação → lista de códigos físicos (`KeyA`, `ArrowLeft`…). Fonte única: estava triplicado em input/.
+ * Action → list of physical codes (`KeyA`, `ArrowLeft`…). The single source: it was written three times in input/.
  *
- * ⚠️ FECHADO EM `Action` DESDE 2026-09-07 (issue #118, decisão do Dev), e era `Record<string, string[]>`.
- * Enquanto foi aberto, **faltar uma posição não dava erro de compilação** — e foi assim que o esquema de
- * dupla ficou com oito das quatorze, e que a `Space` do jogador 1 desapareceu sem que nada apitasse. O
- * defeito não era de digitação: era de o tipo aceitar um esquema incompleto como se fosse completo.
+ * ⚠️ CLOSED OVER `Action` (issue #118, the Dev's decision); it was `Record<string, string[]>`. While it was open,
+ * **a missing position was no compile error** — that is how a two-player scheme ended up with eight of the fourteen and
+ * player 1's `Space` vanished with nothing going off. The defect was not a typo: the type accepted an incomplete scheme
+ * as complete.
  *
- * ⚠️ E `null` NÃO É BURACO — é AUSÊNCIA DECLARADA, e é a metade que dá sentido a fechar o tipo. Um teclado
- * partido por quatro pode não ter lugar físico para ombros e gatilhos; dizer `null` afirma isso, e é o que o
- * aviso de alcance (`ui/reach-notice`, issue #112) lê para dizer à criança, ANTES de ela começar, quais das
- * ações do jogo o controlo dela não alcança. Inventar teclas para preencher seria mentir-lhe em silêncio.
+ * ⚠️ AND `null` IS NOT A HOLE — it is a DECLARED ABSENCE, the half that gives closing the type its meaning. A keyboard
+ * split four ways may have no physical room for shoulders and triggers; `null` says so, and it is what the reach notice
+ * (`ui/reach-notice`, issue #112) reads to tell the child, BEFORE they start, which of the game's actions their
+ * controls cannot reach. Inventing keys to fill it would lie to them in silence.
  *
- * Quem consome tem de tratar o `null`: `input/keyboard-runtime`, `input/touch-bindings` e
- * `ui/settings-controls` fazem-no, e é isso que impede um `null` de virar um `undefined.includes`.
+ * Consumers have to handle the `null`, and that is what keeps a `null` from becoming an `undefined.includes`.
  */
 export type KeyScheme = Record<Action, readonly string[] | null>;
-/** Lados da ventosa-aranha: direita, esquerda, teto, chão. */
+/** The sides a clinging player can stick to: right, left, ceiling, floor. */
 export type ClingSide = 'R' | 'L' | 'U' | 'D';
 /**
- * O sprite do jogador visto pelo jogo: posição, opacidade, escala e textura. Mesma forma que render/draw
- * declara como `PlayerSprite` — é um PIXI.Sprite reduzido ao que o jogo escreve nele, de propósito, para que
- * a lógica rode no project `node` com um sprite de mentira.
+ * The player's sprite as the game sees it: position, opacity, scale and texture. A PIXI.Sprite reduced to what the
+ * game writes on it, on purpose, so the logic runs in the `node` project with a fake sprite.
  */
 export interface PlayerSpriteLike {
     x: number;
@@ -36,13 +34,12 @@ export interface PlayerSpriteLike {
     texture: unknown;
 }
 /**
- * O JOGADOR. Os campos até `_swapSonar` são os que `game/player.makePlayer` cria — todos obrigatórios, porque
- * a fábrica sempre os escreve. Depois vêm os que outros subsistemas ACRESCENTAM em tempo de execução, e esses
- * são opcionais porque um jogador recém-criado genuinamente não os tem.
+ * THE PLAYER. The fields down to `_swapSonar` are the ones the player factory creates — all required, because the
+ * factory always writes them. After them come the ones other subsystems ADD at run time, optional because a freshly
+ * made player genuinely does not have them.
  *
- * A distinção não é cosmética: hoje `physics` exige `elevTarget` como opcional e `gamepad` exige `quit` como
- * obrigatório, e as duas leem o MESMO objeto. Escrever de que lado da linha cada campo cai é metade do valor
- * deste arquivo.
+ * The split is not cosmetic: two modules reading the SAME object used to disagree about which side of this line a
+ * field falls on. Writing it down is half the value of this file.
  */
 export interface Player {
     i: number;
@@ -54,7 +51,7 @@ export interface Player {
     onLadder: boolean;
     inWater: boolean;
     clinging: boolean;
-    /** Face à qual a ventosa-aranha está grudada; `null` quando não está grudado. */
+    /** The side the player is clinging to; `null` when not clinging. */
     clingN: ClingSide | null;
     flying: boolean;
     airTime: number;
@@ -67,7 +64,7 @@ export interface Player {
     groundIdle: number;
     flavor: number;
     flavorT: number;
-    /** Quadro corrente. `Frame` é `unknown` em render/player-anim — a textura é opaca para o jogo. */
+    /** The current frame. Opaque to the game — the texture is the renderer's business. */
     _tx: unknown;
     jumpBuffer: number;
     jumpChain: number;
@@ -85,45 +82,37 @@ export interface Player {
     activePower: string;
     hasKey: boolean;
     /**
-     * Esquema de teclas. `makePlayer` nasce com `null` e `assignControls` preenche no boot — por isso o `| null`.
-     * `game/physics` e `input/keyboard-runtime` declaram este campo como NÃO-nulo, o que é verdade no instante
-     * em que eles rodam mas não é verdade no tipo. Divergência REAL, deixada visível aqui de propósito em vez de
-     * apagada: quem estreitar precisa fazê-lo explicitamente, no ponto onde sabe que já foi atribuído.
+     * The key scheme. A player is born with `null` and `assignControls` fills it at boot — hence the `| null`. Modules
+     * that only run after boot may treat it as non-null, which is true at that instant but not in the type: a REAL
+     * divergence, left visible on purpose — whoever narrows it does so explicitly, where they know it was assigned.
      */
     ctrl: KeyScheme | null;
-    /** Índice do gamepad, ou -1 quando o jogador não tem controle físico. */
+    /** The gamepad index, or -1 when the player has no physical pad. */
     pad: number;
     /**
-     * O ESTADO VISUAL desta criança, em DOIS EIXOS mais a simulação (ADR-0076, issue #104).
+     * This child's VISUAL STATE, in TWO AXES plus the simulation (ADR-0076, issue #104).
      *
-     * ⚠️ `import type`, e a seta aponta para cima. `core/` não deveria importar de `render/`, e o tipo do
-     * ESTADO discutivelmente devia morar aqui em vez de lá. Fica assim de propósito e declarado: é só tipo,
-     * apagado em execução, sem aresta em runtime — e mover o módulo a meio da migração seria churn no ficheiro
-     * mais partilhado do repositório. Se `viz-axes` se dividir um dia, o `VisualState` vem para `core/` e as
-     * funções de renderização ficam lá.
+     * The shape lives in `core/visual-state`; `render/viz-axes` applies it (issue #167).
      */
     visual: VisualState;
     /**
-     * @deprecated ⚠️ O ESPELHO LEGADO, e ele morre nesta migração. Enquanto os dois existirem, `setPlayerViz`
-     * escreve os DOIS e um gate exige que nunca discordem — é o que deixa cada leitor migrar sozinho, com a
-     * árvore verde entre cada passo, em vez de uma passagem única onde não há onde parar.
+     * @deprecated ⚠️ THE LEGACY MIRROR, and it dies in this migration. While both exist, `setPlayerViz` writes BOTH and a
+     * gate requires they never disagree — that lets each reader migrate on its own, with the tree green between steps.
      *
-     * ⚠️ E ELE NÃO CONSEGUE EXPRIMIR O QUE A #104 EXISTE PARA PERMITIR: uma criança com `hc7` E `fix-deuter` ao
-     * mesmo tempo não tem chave única que a descreva. Por isso o espelho só sobrevive enquanto os controles
-     * ainda escrevem um valor de cada vez; assim que eles passam a escrever por eixo, ele deixa de poder
-     * acompanhar e sai.
+     * ⚠️ AND IT CANNOT EXPRESS WHAT #104 EXISTS TO ALLOW: a child with `hc7` AND a colour correction at once has no single
+     * key describing them. So the mirror survives only while the controls still write one value at a time.
      */
     viz: string;
     easy: boolean;
     toggleMove: boolean;
     /**
-     * A ALTERNÂNCIA DO BOTÃO DE CORRER (pedido do Dev): correr vira ESTADO em vez de "segurar".
+     * THE RUN-BUTTON TOGGLE (asked for by the Dev): running becomes a STATE instead of "holding".
      *
-     * Irmã de `toggleMove` e pelo mesmo motivo — quem não consegue manter pressionado andava sem segurar e
-     * continuava sem conseguir CORRER. Automática no controle de toque. Ver `game/run-toggle`.
+     * Sibling of `toggleMove` for the same reason — whoever cannot keep a button held could walk without holding and
+     * still could not RUN. Automatic on the touch pad.
      */
     toggleRun: boolean;
-    /** A trava da corrida: com `toggleRun`, é ela que diz se está correndo agora. Vida de RODADA. */
+    /** The run latch: with `toggleRun`, it says whether the player is running now. Lives for a ROUND. */
     runLatch: boolean;
     rmWalk: boolean;
     rmBreath: boolean;
@@ -134,60 +123,56 @@ export interface Player {
     _swapT: number;
     _swapSonar: boolean;
     sprite: PlayerSpriteLike | null;
-    /** ui/shell, input/gamepad, ui/hud: o jogador pediu para sair. */
+    /** The player asked to quit. */
     quit?: boolean;
-    /** game/session: entrou no meio da partida e aguarda a próxima rodada. */
+    /** Joined mid-game and waits for the next round. */
     waiting?: boolean;
-    /** game/level-geometry, game/physics: andar de destino do elevador em que está. */
+    /** The target floor of the lift the player is on. */
     elevTarget?: number | null;
-    /** game/physics: velocidade de queda memorizada para o som de impacto. */
+    /** The fall speed remembered for the landing sound. */
     _fallV?: number;
-    /** game/physics: distância pisada desde a última batida de bengala. */
+    /** The distance walked since the last cane tap. */
     caneDist?: number;
-    /** game/session, render/player-anim: usa a bengala de corrida (o cego só corre com ela). */
+    /** Uses the running cane (a blind player only runs with it). */
     runCane?: boolean;
-    /** render/fx → render/draw: fator de esmagamento (squash) e o temporizador que o decai (8 → 0).
-     *  Os dois ANDAM JUNTOS — `stepSquash` escreve os dois e `drawPlayers` lê os dois. Declarar só o `sq`, como
-     *  esta interface fazia até a conferência no navegador, é o erro de meia-dupla: o campo que sobra fica sem
-     *  tipo nenhum e ninguém percebe, porque metade da regra continua compilando. */
+    /** The squash factor and the timer that decays it (8 → 0). The two GO TOGETHER — one step writes both and the
+     *  drawing reads both. Declaring only `sq` is the half-pair mistake: the field left over has no type at all and
+     *  nobody notices, because half the rule still compiles. */
     sq?: number;
     sqT?: number;
-    /** render/player-anim → render/draw: o jogador está andando / correndo. Derivados por quadro a partir da
-     *  velocidade e do estado de contato; existem porque a BENGALA precisa saber (a de corrida só aparece
-     *  correndo, e correr exige `runCane`). Escritos pelo render, nunca pela fábrica. */
+    /** The player is walking / running. Derived each frame from speed and contact; they exist because the CANE needs to
+     *  know (the running cane only shows when running, and running needs `runCane`). Written by the renderer, never by
+     *  the factory. */
     walking?: boolean;
     running?: boolean;
-    /** game/quiz: vitórias na atividade de alfabetização, zeradas a cada nova partida. */
-    alfWins?: number;
-    /** ui/settings-audio, ui/pause-icons: saída de áudio própria; `null`/ausente = compartilhada. */
+    /** Wins in the literacy activity, reset at each new game. */
+    literacyWins?: number;
+    /** The player's own audio output; `null`/absent = shared. */
     audioSink?: string | null;
     /**
-     * platform/audio-nav: temporizador do sonar de parede.
+     * The wall-sonar timer, read by the platformer's `platform/audio-nav` (moved there in note CC).
      *
-     * ⚠️ `guideT` SAIU em 2026-09-07 (#84 item 2), e a ausência é a notícia: ele contava os 48 quadros entre
-     * dois bipes do guia, e não há mais bipe nenhum para temporizar. O que o substituiu — o grafo de áudio vivo
-     * — não é da entidade da engine e por isso não nasce aqui: mora em `PlayerAudioOut`, ao lado do `_ac`, pela
-     * mesma regra que o parágrafo acima explica.
+     * ⚠️ `guideT` is gone (#84 item 2): it counted the frames between two guide beeps, and there is no beep left to time.
+     * What replaced it — the live audio graph — is not the engine entity's and so is not born here: it lives in
+     * `PlayerAudioOut`, beside `_ac`, by the rule the paragraph above explains.
      */
     wnT?: number;
 }
 /**
- * Um jogador DEPOIS de `assignControls` — o `ctrl` deixou de ser `null`.
+ * A player AFTER `assignControls` — `ctrl` is no longer `null`.
  *
- * Existe para dar nome a uma invariante que hoje é assumida em silêncio: `game/physics` e
- * `input/keyboard-runtime` declaram `ctrl` como não-nulo porque, no instante em que rodam, ele já foi
- * atribuído. Isso é verdade e continua verdade — mas era uma afirmação escondida dentro de uma interface
- * redigitada, onde ninguém a lia como afirmação. Aqui ela tem nome, e quem a usa está dizendo "eu só rodo
- * depois do boot", que é uma frase verificável, em vez de simplesmente não mencionar o `null`.
+ * It names an invariant otherwise assumed in silence: modules that only run after boot treat `ctrl` as non-null. That
+ * is true — but it was an assertion hidden inside a retyped interface, where nobody read it as one. Here it has a name,
+ * and whoever uses it is saying "I only run after boot", a checkable sentence, instead of not mentioning the `null`.
  */
 export type ControlledPlayer = Player & {
     ctrl: KeyScheme;
 };
 /**
- * Atalho para as visões estreitas: `PlayerView<'x' | 'y'>` em vez de reescrever os campos.
+ * A shortcut for the narrow views: `PlayerView<'x' | 'y'>` instead of rewriting the fields.
  *
- * O ponto de não usar `Player` inteiro está no cabeçalho: o project `node` do Vitest monta jogadores de
- * mentira com só os campos que o módulo lê, e uma interface gorda obrigaria todo fixture a inventar 52.
- * Derivando, o módulo continua acoplado à sua fatia e o NOME e o TIPO de cada campo passam a ter fonte única.
+ * The point of not using the whole `Player` is in the header: the Vitest `node` project builds fake players with only
+ * the fields a module reads, and a fat interface would make every fixture invent all of them. Deriving keeps the module
+ * coupled to its slice while each field's NAME and TYPE have one source.
  */
 export type PlayerView<K extends keyof Player> = Pick<Player, K>;

package/dist-pkg/core/entity.js

@@ -1,38 +1,24 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/entity — O JOGADOR, escrito UMA vez. Passo 1 do ADR-0027, e o único que o ADR chama de pré-requisito
-// de todos os outros. Não move nada e não muda nada em tempo de execução: `tsc --noEmit` é o teste inteiro.
+// core/entity — THE PLAYER, written ONCE. Step 1 of ADR-0027, the one that record calls the prerequisite of all the
+// others. It moves nothing and changes nothing at run time: `tsc --noEmit` is its whole test.
 //
-// O PROBLEMA QUE ISTO RESOLVE. `core/state.players` é `unknown[]`. O tipo se perde exatamente na fronteira em
-// que a entidade atravessa o programa, então cada módulo que precisa de um jogador escreveu à mão a sua
-// própria visão estrutural e fez cast. São VINTE E TRÊS — o ADR-0027 estimou dez, contei uma a uma e são 23 —
-// e elas já não concordam entre si:
+// THE PROBLEM THIS SOLVES. `core/state.players` is `unknown[]`. The type is lost exactly at the boundary where the
+// entity crosses the program, so every module that needed a player wrote its own structural view by hand and cast.
+// There were twenty-three, and they no longer agreed: the same field required in one module and optional in another
+// for the SAME object, so a player was accepted by half the program and rejected by the other half. That is the
+// failure that already cost a broken climb in Easy mode, when three copies of the action→edge table diverged: a copy
+// nobody forces to agree, diverges.
 //
-//   · `quiz` tem QUATRO formas: `unknown` (physics, session, touch), `Quiz | null` (quiz),
-//     `{ kind: string } | null` (gamepad) e `{ kind?: string } | null` (keydown). O `kind` é obrigatório numa
-//     e opcional na outra, para o MESMO objeto.
-//   · `easy` é obrigatório em physics, gamepad e settings-motor; opcional em session, keydown, touch-bindings
-//     e draw. Um jogador sem `easy` é aceito por metade do programa e rejeitado pela outra.
-//   · `jumpEdge`, idem: obrigatório em physics/gamepad/attract, opcional em session/keydown/touch-bindings.
-//   · `quit` é obrigatório em gamepad e hud, opcional em session. `toggleMove` é obrigatório em
-//     settings-motor, opcional em pause-icons. `viz` é obrigatório em draw, opcional em pause-icons.
-//   · `KeyScheme` (= `Record<string, string[]>`) está declarado três vezes: em input/keyboard-runtime,
-//     input/keyboard e input/keydown.
+// HOW IT IS USED — and why modules must NOT import the whole `Player`. What makes the project testable in the Vitest
+// `node` project is that each module declares the MINIMAL slice it needs and the test builds a fake with only those
+// fields. Swapping the narrow views for one fat interface would destroy that: every fixture would have to invent every
+// field.
 //
-// Nada disso é hipótese sobre o futuro: é a mesma forma de falha que já custou uma escalada quebrada no modo
-// Fácil, quando três cópias da tabela ação→borda divergiram. Uma cópia que ninguém obriga a concordar diverge.
+// The way out is to derive instead of retyping: `Pick<Player, 'x' | 'y' | 'vx'>` instead of rewriting three fields.
+// The module stays coupled only to its slice and the test still builds only that — but each field's NAME and TYPE have
+// one source, and renaming a field breaks every consumer's compilation at the same instant.
 //
-// COMO ISTO É USADO — e por que os módulos NÃO devem importar `Player` inteiro. A propriedade que faz o
-// projeto testável no project `node` do Vitest é que cada módulo declara a fatia MÍNIMA de que precisa e o
-// teste monta um objeto de mentira com só aqueles campos. Trocar 23 visões estreitas por uma interface gorda
-// destruiria isso: todo fixture de teste passaria a ter de inventar 52 campos.
-//
-// A saída é derivar em vez de redigitar: `Pick<Player, 'x' | 'y' | 'vx'>` em vez de reescrever os três campos.
-// O módulo continua acoplado só à sua fatia; o teste continua montando só aquilo; mas o NOME e o TIPO de cada
-// campo passam a ter uma fonte única, e renomear um campo quebra a compilação de todos os consumidores no
-// mesmo instante, que é precisamente o que hoje não acontece.
-//
-// A FRONTEIRA DE CAMADA. `core/` não pode importar de `game/` nem de `render/` — seria inverter a dependência.
-// Por isso os campos que apontam para outras camadas entram aqui pelo MÍNIMO ESTRUTURAL: `core` sabe que o
-// jogador tem um quiz, não sabe o que é um quiz. Os tipos ricos (`Quiz` em game/quiz, `PlayerSprite` em
-// render/draw) são atribuíveis a estes, e é o compilador que garante isso no ponto de uso.
+// THE LAYER BOUNDARY. `core/` may not import upward (ADR-0173), so fields that point at other layers enter here as the
+// STRUCTURAL MINIMUM: the rich types (a sprite in `render/`) are assignable to these, and the compiler checks it where
+// they are used.
 export {};

package/dist-pkg/core/escape-html.d.ts

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Os CINCO caracteres, e cobre os dois contextos: elemento (`<` `>`) e ATRIBUTO (`"` `'`).
+ * The FIVE characters, covering both contexts: element (`<` `>`) and ATTRIBUTE (`"` `'`).
  *
- * O atributo é o que costuma faltar, e é o pior: dentro de um elemento uma aspa é inofensiva; dentro de
- * `aria-label="…"` ela FECHA o atributo e o que vem a seguir vira atributo — um `onmouseover` sem precisar de
- * uma única tag.
+ * The attribute is the one usually missing, and the worst: inside an element a quote is harmless; inside
+ * `aria-label="…"` it CLOSES the attribute and what follows becomes an attribute — an `onmouseover` without a single tag.
  *
- * ⚠️ O `&` É O PRIMEIRO, E A ORDEM É O DEFEITO CLÁSSICO DESTE AJUDANTE. Escapando-o por último, o `&` do
- * `&lt;` que acabou de ser produzido é escapado outra vez e a tela mostra `&lt;` literal. É silencioso porque
- * quem testa só com `<b>` nunca o vê: a saída ainda «parece» escapada.
+ * ⚠️ `&` GOES FIRST, AND THE ORDER IS THIS HELPER'S CLASSIC DEFECT. Escaped last, the `&` of the `&lt;` just produced is
+ * escaped again and the screen shows a literal `&lt;`. It is silent because a test with only `<b>` never sees it: the
+ * output still "looks" escaped.
  *
- * E ele escapa, não apaga. Apagar mudaria a palavra que a criança digitou, e uma atividade cujo texto muda
- * sozinho é um defeito diferente e igualmente sério.
+ * And it escapes, it does not delete. Deleting would change the word the child typed, and an activity whose text changes
+ * by itself is a different defect, and just as serious.
  */
-export declare function escaparHtml(s: string): string;
+export declare function escapeHtml(s: string): string;

package/dist-pkg/core/escape-html.js

@@ -1,31 +1,27 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/escape-html.ts — ESCAPAR TEXTO QUE VAI PARAR EM MARCAÇÃO. Módulo-folha: uma função, zero dependências.
+// core/escape-html.ts — ESCAPING TEXT THAT ENDS UP IN MARKUP. A leaf module: one function, no dependencies.
 //
-// ⚠️ NASCEU DENTRO DE `game/quiz.ts` E TEVE DE SAIR NO DIA SEGUINTE, o que vale registrar porque a razão não
-// é arrumação: `game/` é o CARTUCHO, e a issue #111 leva-o para um repositório próprio. O ajudante sairia com
-// ele, e o `consumer-quiz` — que é prova da ENGINE — nem sequer pode importar de `game/`, porque o
-// `engine-boundary` o proíbe. Um utilitário de segurança que vive do lado errado da fronteira é um utilitário
-// que o próximo consumidor reescreve, e duas versões de um escape divergem em silêncio.
+// ⚠️ It lives in the engine, not in a cartridge, because a security helper on the wrong side of a boundary is one the
+// next consumer rewrites — and two versions of an escape diverge in silence.
 //
-// ⚠️ E O ESCAPE É O SEGUNDO RECURSO, NÃO O PRIMEIRO. Onde o valor cabe num nó — `textContent`, `setAttribute`
-// —, é assim que ele entra, porque aí não há o que esquecer. Isto existe para o caso em que o texto está
-// dentro de um construtor denso de marcação, e nesse caso vem sempre acompanhado de um gate com conteúdo
-// hostil: um escape sem rasto é pior do que construir nós.
+// ⚠️ AND ESCAPING IS THE SECOND RESORT, NOT THE FIRST. Where the value fits a node — `textContent`, `setAttribute` —
+// that is how it goes in, because then there is nothing to forget. This exists for text inside a dense markup
+// builder, and there it always comes with a gate fed hostile content: an escape without a trace is worse than
+// building nodes.
 /**
- * Os CINCO caracteres, e cobre os dois contextos: elemento (`<` `>`) e ATRIBUTO (`"` `'`).
+ * The FIVE characters, covering both contexts: element (`<` `>`) and ATTRIBUTE (`"` `'`).
  *
- * O atributo é o que costuma faltar, e é o pior: dentro de um elemento uma aspa é inofensiva; dentro de
- * `aria-label="…"` ela FECHA o atributo e o que vem a seguir vira atributo — um `onmouseover` sem precisar de
- * uma única tag.
+ * The attribute is the one usually missing, and the worst: inside an element a quote is harmless; inside
+ * `aria-label="…"` it CLOSES the attribute and what follows becomes an attribute — an `onmouseover` without a single tag.
  *
- * ⚠️ O `&` É O PRIMEIRO, E A ORDEM É O DEFEITO CLÁSSICO DESTE AJUDANTE. Escapando-o por último, o `&` do
- * `&lt;` que acabou de ser produzido é escapado outra vez e a tela mostra `&lt;` literal. É silencioso porque
- * quem testa só com `<b>` nunca o vê: a saída ainda «parece» escapada.
+ * ⚠️ `&` GOES FIRST, AND THE ORDER IS THIS HELPER'S CLASSIC DEFECT. Escaped last, the `&` of the `&lt;` just produced is
+ * escaped again and the screen shows a literal `&lt;`. It is silent because a test with only `<b>` never sees it: the
+ * output still "looks" escaped.
  *
- * E ele escapa, não apaga. Apagar mudaria a palavra que a criança digitou, e uma atividade cujo texto muda
- * sozinho é um defeito diferente e igualmente sério.
+ * And it escapes, it does not delete. Deleting would change the word the child typed, and an activity whose text changes
+ * by itself is a different defect, and just as serious.
  */
-export function escaparHtml(s) {
+export function escapeHtml(s) {
     return String(s)
         .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
         .replaceAll('"', '&quot;').replaceAll("'", '&#39;');

package/dist-pkg/core/flash-threshold.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The grid: 64×64 cells of a 1024×768 reference. */
+export declare const COLUMNS = 16;
+export declare const ROWS = 12;
+export interface LuminanceFrame {
+    /** Milliseconds. */
+    readonly t: number;
+    /** Relative luminance 0..1 per cell, row by row, `COLUMNS * ROWS` long. */
+    readonly luminances: ArrayLike<number>;
+}
+export interface FlashVerdict {
+    readonly passes: boolean;
+    /** The most general flashes any 10° field showed within one second. */
+    readonly worstSecond: number;
+}
+/** Counts general flashes per 10° field and returns the worst second. */
+export declare function analyseFlashes(frames: readonly LuminanceFrame[]): FlashVerdict;

package/dist-pkg/core/flash-threshold.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/flash-threshold — THE GENERAL FLASH THRESHOLD OF WCAG 2.3.1, over a grid of relative luminance (study item B2).
+//
+// ADR-0020 names a FLASH_LIMIT pass and the engine limits nothing a cartridge flashes: it does not own the render. What it
+// can do is MEASURE what a game draws and say it. This file is the pure half — frames in, a verdict out, no DOM, no clock —
+// so the rule is tested by numbers written from the source; the sampler that reads a canvas lives with the root.
+//
+// 📌 THE SOURCE (read 2026-09-13), W3C Understanding SC 2.3.1, WCAG 2.2: a general flash is «a pair of opposing changes in
+// relative luminance of 10% or more of the maximum relative luminance (1.0) where the relative luminance of the darker
+// image is below 0.80»; the threshold passes with «no more than three … within any one-second period» or when the
+// concurrent area is «no more than … .006 steradians within any 10 degree visual field» (341×256 px at 1024×768; 25%).
+// ⚠️ NOT HERE: the red flash (CIE 1976 UCS chromaticity) — a verdict of «passes» from this file says nothing about red.
+// A LEAF: imports nothing.
+/** The grid: 64×64 cells of a 1024×768 reference. */
+export const COLUMNS = 16;
+export const ROWS = 12;
+/** The 10° field as whole cells: 5×4 = 320×256, the nearest rectangle to 341×256. */
+const WINDOW_C = 5;
+const WINDOW_L = 4;
+/** More than 25% of the field: 21 824 px of 87 296, 5.3 cells of 4 096 px — so 6 cells. */
+const CELLS_FOR_AREA = 6;
+const CHANGE = 0.1;
+const DARK_BELOW = 0.8;
+const MAX_PER_SECOND = 3;
+const CELLS = COLUMNS * ROWS;
+const WINDOWS = (COLUMNS - WINDOW_C + 1) * (ROWS - WINDOW_L + 1);
+/**
+ * Per cell, a TRANSITION is a move of 10% or more away from the last extreme, with the darker side below 0.80; a move
+ * further in the same direction extends the extreme instead of counting.
+ */
+function markCellTransitions(frame, s) {
+    for (let c = 0; c < CELLS; c++) {
+        s.transition[c] = 0;
+        const l = Number(frame.luminances[c] ?? 0);
+        const ref = s.reference[c];
+        if (Number.isNaN(ref)) {
+            s.reference[c] = l;
+            continue;
+        }
+        const way = Math.sign(l - ref);
+        if (way === s.direction[c]) {
+            s.reference[c] = l;
+            continue;
+        }
+        if (Math.abs(l - ref) >= CHANGE && Math.min(l, ref) < DARK_BELOW) {
+            s.transition[c] = way;
+            s.direction[c] = way;
+            s.reference[c] = l;
+        }
+    }
+}
+/** A field makes a transition when 6 of its cells make one in the same direction in the same frame. */
+function fieldTransition(transition, row, col) {
+    let wentUp = 0;
+    let wentDown = 0;
+    for (let dr = 0; dr < WINDOW_L; dr++) {
+        for (let dc = 0; dc < WINDOW_C; dc++) {
+            const way = transition[(row + dr) * COLUMNS + col + dc];
+            if (way > 0)
+                wentUp++;
+            else if (way < 0)
+                wentDown++;
+        }
+    }
+    return wentUp >= CELLS_FOR_AREA ? 1 : wentDown >= CELLS_FOR_AREA ? -1 : 0;
+}
+/** A FLASH is two opposing field transitions, and the pair then starts afresh. */
+function pairFieldTransitions(t, s) {
+    let j = 0;
+    for (let row = 0; row + WINDOW_L <= ROWS; row++) {
+        for (let col = 0; col + WINDOW_C <= COLUMNS; col++, j++) {
+            const way = fieldTransition(s.transition, row, col);
+            if (!way)
+                continue;
+            if (s.openHalf[j] !== 0 && s.openHalf[j] !== way) {
+                s.flashTimes[j].push(t);
+                s.openHalf[j] = 0;
+            }
+            else {
+                s.openHalf[j] = way;
+            }
+        }
+    }
+}
+/** The most flashes any one field showed «within any one-second period». */
+function worstSecond(flashTimes) {
+    let worst = 0;
+    for (const times of flashTimes) {
+        for (let i = 0, k = 0; i < times.length; i++) {
+            // less than a second apart; half a millisecond absorbs frame arithmetic
+            while (k < times.length && times[k] - times[i] < 1000 - 0.5)
+                k++;
+            worst = Math.max(worst, k - i);
+        }
+    }
+    return worst;
+}
+/** Counts general flashes per 10° field and returns the worst second. */
+export function analyseFlashes(frames) {
+    const s = {
+        reference: new Float64Array(CELLS).fill(Number.NaN),
+        direction: new Int8Array(CELLS),
+        transition: new Int8Array(CELLS),
+        openHalf: new Int8Array(WINDOWS),
+        flashTimes: Array.from({ length: WINDOWS }, () => []),
+    };
+    for (const frame of frames) {
+        markCellTransitions(frame, s);
+        pairFieldTransitions(frame.t, s);
+    }
+    const worst = worstSecond(s.flashTimes);
+    return { passes: worst <= MAX_PER_SECOND, worstSecond: worst };
+}

package/dist-pkg/core/game-speed.d.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE GAME SPEED STEPS (ADR-0180): 100% down to 50% in steps of 10%, Celeste's Assist Mode, the example the Game Accessibility
+ * Guidelines cite for «Include an option to adjust the game speed» (Basic). One control slows timers, reaction windows and the
+ * world's pace at once.
+ */
+export declare const GAME_SPEEDS: readonly number[];
+/** A value outside the steps is not a speed: a stored typo lands on 100%, never on zero or on a speed nobody chose. */
+export declare function isGameSpeed(v: number): number;
+/** One press: the next step down, wrapping from 50% back to 100%. */
+export declare function nextGameSpeed(v: number): number;

package/dist-pkg/core/game-speed.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE GAME SPEED STEPS (ADR-0180): 100% down to 50% in steps of 10%, Celeste's Assist Mode, the example the Game Accessibility
+ * Guidelines cite for «Include an option to adjust the game speed» (Basic). One control slows timers, reaction windows and the
+ * world's pace at once.
+ */
+export const GAME_SPEEDS = Object.freeze([1, 0.9, 0.8, 0.7, 0.6, 0.5]);
+/** A value outside the steps is not a speed: a stored typo lands on 100%, never on zero or on a speed nobody chose. */
+export function isGameSpeed(v) {
+    return GAME_SPEEDS.includes(v) ? v : 1;
+}
+/** One press: the next step down, wrapping from 50% back to 100%. */
+export function nextGameSpeed(v) {
+    const i = GAME_SPEEDS.indexOf(isGameSpeed(v));
+    return GAME_SPEEDS[(i + 1) % GAME_SPEEDS.length];
+}

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

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE ENGINE'S GENRE LIST — the Dev's transcription of the Wikipedia list of video game genres (ADR-0156 §1).
+ *
+ * Optional (ADR-0153): a cartridge MAY declare one, and nobody assigns one to a game (§5). The transcription is the
+ * decision and the page only its source, so families and genres are written as the Dev wrote them. A family name is not a
+ * declarable genre, except MMO, which the list gives as both. Not in the list, and so not declarable: the by-purpose genres
+ * and sandbox / open world (§4).
+ */
+export interface Genre {
+    readonly name: string;
+    readonly family: string;
+    /** Casino game is refused (§2); Horror game is to be avoided (§3). */
+    readonly mark?: 'refused' | 'avoid';
+}
+export declare const GENRES: readonly Genre[];
+/** Is a declared genre acceptable? EMPTY means conformant; any line refuses the boot (a malformed declaration). */
+export declare function genreProblems(genre: unknown): string[];
+/** The line `problems` carries for an accepted genre with a mark: Horror game plays, and the author reads why to avoid it. */
+export declare function genreWarning(genre: unknown): string | null;