@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Gênero gramatical do nome. `n` = neutro/indefinido (o pt-BR usa o masculino como default nesse caso). */
+export type Gender = 'm' | 'f' | 'n';
+/** Um nome que pode ser FALADO (leitor de tela) e SINALIZADO (Libras, que traduz o mesmo texto). */
+export interface Speakable {
+    /** O nome, na língua da interface. Conteúdo de currículo NÃO se traduz — ver o pilar 3 do ADR-0010. */
+    readonly text: string;
+    readonly gender: Gender;
+    readonly plural: boolean;
+}
+/**
+ * COMO SE CONTA UM PASSO — e é isto que decide a métrica, que não é a mesma em todo tabuleiro.
+ *
+ * ⚠️ A grade tinha UMA métrica fixa (Chebyshev), com a razão escrita ao lado: *"numa grade, a diagonal custa um
+ * passo, e é assim que quem joga conta"*. Verdade onde a diagonal é legal. **Falsa num quebra-cabeça
+ * deslizante**, onde nada anda na diagonal: uma peça duas à direita e duas abaixo está a 2 por Chebyshev e a
+ * QUATRO movimentos de distância. O sonar sub-relatava até 2× — e sub-relatar distância a quem não vê a tela
+ * não é imprecisão, é mandar a criança para o lado errado com confiança.
+ *
+ * `grid` nunca foi UMA coisa. Quem declara a grade declara também como se anda nela.
+ */
+export type MoveRule = 'orthogonal' | 'diagonal' | 'free';
+/**
+ * EM QUE PALAVRAS SE DIZ UMA DIREÇÃO. Não é preferência de quem ouve: é propriedade do ESPAÇO do jogo.
+ *
+ *   `compass`  norte · sul · leste · oeste (+ zênite e nadir) — tabuleiro, top-down, mapa, 3D
+ *   `clock`    «às 2 horas», «às 10 horas» — PLATAFORMA 2D, vista lateral
+ *
+ * ⚠️ Num jogo de plataforma, norte e sul não querem dizer nada: a criança não está a olhar um mapa, está a
+ * olhar de lado. O relógio é o referencial que essa vista já usa, e dá 12 posições onde a rosa dá 8.
+ *
+ * ⚠️ E O RELÓGIO PRESSUPÕE LER RELÓGIO ANALÓGICO, num público que inclui alfabetização. Não é motivo para o
+ * recusar — é motivo para o rótulo FALADO ser testado com criança (issue #7) antes de se declarar bom.
+ */
+export type Frame = 'compass' | 'clock';
+export type Topology = 
+/**
+ * Grade discreta. A distância é em CÉLULAS, e a métrica sai de `move`.
+ * `size` é `[colunas, linhas]` ou `[colunas, linhas, camadas]`.
+ */
+{
+    readonly kind: 'grid';
+    readonly size: readonly number[];
+    readonly move: MoveRule;
+    readonly frame: Frame;
+}
+/**
+ * Espaço contínuo. A distância é em UNIDADES do mundo; `unit` diz quanto vale um "passo" para quem narra.
+ * `size` é `[largura, altura]` ou `[largura, altura, profundidade]`.
+ */
+ | {
+    readonly kind: 'continuous';
+    readonly size: readonly number[];
+    readonly unit: number;
+    readonly move: MoveRule;
+    readonly frame: Frame;
+}
+/** Sem espaço: uma lista ORDENADA de alvos. A distância é a diferença de índice, e não há direção. */
+ | {
+    readonly kind: 'hotspots';
+    readonly order: readonly string[];
+};
+/**
+ * Uma posição, na métrica da topologia declarada. Em `hotspots`, `x` é o índice e `y` é ignorado.
+ *
+ * ⚠️ ASSIMETRIA DELIBERADA COM `size`, e vale dizer por quê. A EXTENSÃO é um vetor porque a dimensão varia e
+ * `size.length` é o único lugar onde ela mora — sem isso, "tem profundidade?" viraria `depth !== undefined`
+ * espalhado por cada consumidor. O PONTO tem eixos com nome porque é lido em código a toda hora: `alvo.at.x`
+ * diz o que é, `alvo.at[0]` obriga a lembrar. Dimensão é 2 ou 3 e a conformidade recusa o resto, o que fecha
+ * a assimetria: não há `size` que `Spot` não consiga representar.
+ */
+export interface Spot {
+    readonly x: number;
+    readonly y: number;
+    readonly z?: number;
+}
+/** A dimensão que a topologia declara. `hotspots` não tem espaço, logo não tem dimensão. */
+export declare function dimension(t: Topology): number;
+export type Role = 'hazard' | 'climb' | 'water' | 'goal' | 'gate' | 'key' | 'structure' | 'free';
+/**
+ * ⚠️ `zenith` E `nadir` ENTRARAM PORQUE `up`/`down` JÁ QUEREM DIZER DUAS COISAS. `ACTIONS` (core/actions) tem
+ * `up` e `down` como AÇÕES DE CONTROLE — o que a criança carrega —, e o eixo vertical do ESPAÇO é outra coisa
+ * inteiramente. Enquanto o mundo era plano a ambiguidade não custava nada; num espaço de três dimensões
+ * custaria o pior tipo de defeito, o que se lê certo e faz outra coisa. Palavras próprias, antes de o 3D chegar.
+ */
+export type Heading = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw' | 'zenith' | 'nadir' | 'none';
+/**
+ * PARA ONDE FICA UM PONTO VISTO DE OUTRO, já no referencial que a topologia declara.
+ *
+ * ⚠️ NÃO É O `heading` DO FOCO, e a diferença é o defeito que isto conserta. `Focus.heading` é para onde a
+ * criança está VIRADA; isto é para onde está o ALVO. O sonar precisa do segundo e calculava-o à mão a partir
+ * de `x` cru, com zona morta de ±4, dizendo `left`/`right`/`ahead` — três palavras onde o contrato tem oito, e
+ * MISTURANDO REFERENCIAIS: *esquerda/direita* é relativo à tela, *à frente* é relativo ao corpo. Uma criança
+ * cega que ouve as duas na mesma frase não tem como saber de qual origem cada uma fala.
+ */
+export type Bearing = {
+    readonly kind: 'compass';
+    readonly heading: Heading;
+} | {
+    readonly kind: 'clock';
+    readonly hour: number;
+} | {
+    readonly kind: 'none';
+};
+export interface Focus {
+    /** Quem está com o foco. Um id do jogo — a engine não o interpreta, só o carrega. */
+    readonly id: string;
+    readonly at: Spot;
+    readonly heading: Heading;
+}
+export interface Objective {
+    /** O que se está juntando/resolvendo: "moedas", "palavras", "contas". */
+    readonly name: Speakable;
+    readonly have: number;
+    readonly need: number;
+}
+export type TickOwner = 'player' | 'clock';
+export type Announcement = {
+    readonly kind: 'state';
+    readonly name: Speakable;
+} | {
+    readonly kind: 'event';
+    readonly name: Speakable;
+    readonly urgent: boolean;
+};
+/**
+ * O que a criança vê como sendo o jogo.
+ *
+ * ⚠️ `none` NÃO É UM PADRÃO, É UMA ESCOLHA ESCRITA. Existe para atividade sem espaço — uma tela de pintura
+ * livre, autoria, um formulário —, onde não há «mundo» para simular nem alvo para sonar. O Dev nomeou o caso:
+ * *"atividades como paint não são exatamente jogos, mas podem ser feitas com a engine e sonar não vai
+ * funcionar muito bem"*.
+ *
+ * ⚠️ E O QUE ELE NÃO PODE SER É O QUE ACONTECE QUANDO ALGUÉM ESQUECE. Um jogo de DOM puro não é «um jogo onde
+ * empatia não faz sentido»: o xadrez às cegas é a prova empírica de que faz. `none` é para quem DECLARA que
+ * não tem espaço, e a ausência do campo é reprovada — hoje as duas coisas produzem o mesmo silêncio.
+ */
+export type WorldScope = 
+/** O seletor do elemento que é o mundo. A engine aplica ali o que é do mundo, e só ali. */
+{
+    readonly kind: 'element';
+    readonly selector: string;
+}
+/** Sem espaço. Empatia e sonar NÃO são oferecidos — e a tela de seleção diz isso antes de a criança começar. */
+ | {
+    readonly kind: 'none';
+};
+/**
+ * O que um jogo entrega à engine. `tick` é dado; TODO O RESTO é função, porque a resposta muda com a posição,
+ * o jogador e o instante.
+ *
+ * ⚠️ NÃO IMPORTE ISTO INTEIRO num módulo consumidor. Use `Pick<GameDeclaration, 'roleAt'>` e afins — a regra é
+ * a de `core/entity`, e é o que mantém os fixtures de teste pequenos.
+ */
+export interface GameDeclaration {
+    /**
+     * A forma do espaço AGORA.
+     *
+     * ⚠️ ERA UM VALOR ATÉ 2026-09-06, e a assimetria já tinha sido remendada em dois lugares antes de alguém a
+     * nomear: a porta do sonar sempre pediu `topology: () => Topology` (`platform/audio-sonar.ts`), e
+     * `boot/create-game` fazia a ponte com `() => o.declaration.topology` — uma função que devolve uma
+     * constante. O `game-15puzzle` (3×3/4×4/5×5) precisou de um getter para caber no tipo, e um getter que
+     * satisfaz uma interface é COINCIDÊNCIA DO TypeScript, não contrato: nada avisava o próximo autor de que
+     * era o esperado, e `conformanceProblems` lia uma vez só — quem memorizasse a topologia ficava defasado
+     * em silêncio. Remendo que aparece duas vezes é o contrato a pedir para mudar. ADR-0084.
+     */
+    topology(): Topology;
+    /**
+     * QUAL ELEMENTO É O MUNDO. Ver o bloco 8 acima para o defeito que este campo conserta.
+     *
+     * ⚠️ OBRIGATÓRIO, e a obrigatoriedade é a decisão. A proposta original era um campo opcional com padrão;
+     * o Dev recusou, e a razão é o BLINDFOLD CHESS: xadrez às cegas existe, logo um jogo de DOM puro não é um
+     * jogo onde empatia não faz sentido — é um jogo onde ela exige mais de quem o programa. Um padrão deixaria
+     * o esquecimento passar como se fosse escolha.
+     */
+    world(): WorldScope;
+    readonly tick: TickOwner;
+    /** O papel do que está em `at`. É o campo 2, e é o que substitui `roleOf`. */
+    roleAt(at: Spot): Role;
+    /** Como se chama o que está em `at`. Sem isto não há leitor de tela nem Libras. */
+    nameAt(at: Spot): Speakable | null;
+    /** Quem tem o foco agora, e para onde aponta. `null` = ninguém (menu fechado, rodada não começou). */
+    focusOf(playerIndex: number): Focus | null;
+    /** O que a rodada pede deste jogador. */
+    objectiveOf(playerIndex: number): Objective;
+    /**
+     * ONDE estão os alvos ainda válidos deste jogador — a segunda metade do campo 5.
+     *
+     * É o que substitui o `getCoins()` do sonar: em vez de a engine varrer um array de moedas e filtrar por
+     * `taken`/`owner`, o jogo devolve os pontos que ainda contam para ESTE jogador. Um quiz devolve o índice da
+     * pergunta em aberto; uma plataforma devolve as moedas não coletadas; um Sokoban devolve as caixas fora do
+     * lugar. A engine só compara distâncias, e é por isso que o sonar passa a servir a qualquer gênero.
+     *
+     * Vazio é resposta legítima e significa "não há para onde apontar" — não é erro.
+     */
+    targetsOf(playerIndex: number): readonly Spot[];
+}
+/**
+ * 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 declare function conformanceProblems(d: Partial<GameDeclaration> | null | undefined): string[];
+/** Um nome falável bem-formado? Texto vazio é o defeito silencioso: o leitor de tela simplesmente cala. */
+export declare function speakableProblems(s: Speakable | null | undefined): string[];
+/**
+ * Distância entre dois pontos NA MÉTRICA declarada — a que o jogo declarou em `move`, e em quantas dimensões
+ * ele declarou em `size`. É o que o sonar precisa e antes calculava em pixels.
+ *
+ * ⚠️ 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.
+ */
+export declare function distance(t: Topology, a: Spot, b: Spot): number;
+/**
+ * PARA ONDE FICA `to` VISTO DE `from`, já nas palavras que a topologia declarou.
+ *
+ * ⚠️ 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.
+ */
+export declare function bearing(t: Topology, from: Spot, to: Spot): Bearing;

package/dist-pkg/core/contract.js

@@ -0,0 +1,184 @@
+// 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.
+//
+// ========================= 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.
+//
+// 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).
+//
+// ========================= 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.
+//
+// ========================= 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.
+//
+// ========================= 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;
+    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)');
+        }
+    }
+    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');
+    }
+    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');
+    }
+    else if (typeof d.world !== 'function') {
+        p.push('world: must be a FUNCTION');
+    }
+    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 (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 p;
+}
+/** Um nome falável bem-formado? Texto vazio é o defeito silencioso: o leitor de tela simplesmente cala. */
+export function speakableProblems(s) {
+    if (!s)
+        return ['name missing'];
+    const p = [];
+    if (!s.text.trim())
+        p.push('text: empty - the screen reader would fall silent');
+    if (s.gender !== 'm' && s.gender !== 'f' && s.gender !== 'n')
+        p.push('gender: must be m, f or n');
+    if (typeof s.plural !== 'boolean')
+        p.push('plural: must be a boolean');
+    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.
+ *
+ * ⚠️ 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.
+ */
+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.
+    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;
+}
+/**
+ * PARA ONDE FICA `to` VISTO DE `from`, já nas palavras que a topologia declarou.
+ *
+ * ⚠️ 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.
+ */
+export function bearing(t, from, to) {
+    if (t.kind === 'hotspots')
+        return { kind: 'none' };
+    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)
+        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 (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;
+        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] };
+}

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

@@ -0,0 +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`.
+ *
+ * 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`.
+ */
+export type DomQuery = <T extends Element = HTMLElement>(sel: string) => T | null;

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

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/dom-query — O SELETOR DE DOM INJETADO, declarado UMA VEZ.
+//
+// ========================= 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`.
+//
+// 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.
+//
+// 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.
+export {};

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

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Ação → lista de códigos físicos (`KeyA`, `ArrowLeft`…). Fonte única: estava triplicado em input/. */
+export type KeyScheme = Record<string, string[]>;
+/** Lados da ventosa-aranha: direita, esquerda, teto, chão. */
+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.
+ */
+export interface PlayerSpriteLike {
+    x: number;
+    y: number;
+    alpha: number;
+    visible: boolean;
+    scale: {
+        set(x: number, y: number): void;
+    };
+    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.
+ *
+ * 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.
+ */
+export interface Player {
+    i: number;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    onGround: boolean;
+    onLadder: boolean;
+    inWater: boolean;
+    clinging: boolean;
+    /** Face à qual a ventosa-aranha está grudada; `null` quando não está grudado. */
+    clingN: ClingSide | null;
+    flying: boolean;
+    airTime: number;
+    facing: number;
+    anim: number;
+    walkAnim: number;
+    climbFrame: number;
+    idleNow: boolean;
+    idleTime: number;
+    groundIdle: number;
+    flavor: number;
+    flavorT: number;
+    /** Quadro corrente. `Frame` é `unknown` em render/player-anim — a textura é opaca para o jogo. */
+    _tx: unknown;
+    jumpBuffer: number;
+    jumpChain: number;
+    waterStroke: number;
+    walkDir: number;
+    hurtTimer: number;
+    jumpEdge: boolean;
+    runEdge: boolean;
+    swapEdge: boolean;
+    specialEdge: boolean;
+    leftEdge: boolean;
+    rightEdge: boolean;
+    collected: number;
+    owned: string[];
+    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.
+     */
+    ctrl: KeyScheme | null;
+    /** Índice do gamepad, ou -1 quando o jogador não tem controle físico. */
+    pad: number;
+    viz: string;
+    easy: boolean;
+    toggleMove: boolean;
+    /**
+     * A ALTERNÂNCIA DO BOTÃO DE CORRER (pedido do Dev): correr vira ESTADO em vez de "segurar".
+     *
+     * 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`.
+     */
+    toggleRun: boolean;
+    /** A trava da corrida: com `toggleRun`, é ela que diz se está correndo agora. Vida de RODADA. */
+    runLatch: boolean;
+    rmWalk: boolean;
+    rmBreath: boolean;
+    rmFlavor: boolean;
+    stepT: number;
+    guardT: number;
+    _swapDown: boolean;
+    _swapT: number;
+    _swapSonar: boolean;
+    sprite: PlayerSpriteLike | null;
+    /** ui/shell, input/gamepad, ui/hud: o jogador pediu para sair. */
+    quit?: boolean;
+    /** game/session: entrou no meio da partida e aguarda a próxima rodada. */
+    waiting?: boolean;
+    /** game/level-geometry, game/physics: andar de destino do elevador em que está. */
+    elevTarget?: number | null;
+    /** game/physics: velocidade de queda memorizada para o som de impacto. */
+    _fallV?: number;
+    /** game/physics: distância pisada desde a última batida de bengala. */
+    caneDist?: number;
+    /** game/session, render/player-anim: usa a bengala de corrida (o cego só corre com ela). */
+    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. */
+    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. */
+    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. */
+    audioSink?: string | null;
+    /** platform/audio-nav: temporizadores do sonar de parede e do guia. */
+    wnT?: number;
+    guideT?: number;
+}
+/**
+ * Um jogador DEPOIS de `assignControls` — o `ctrl` deixou de ser `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`.
+ */
+export type ControlledPlayer = Player & {
+    ctrl: KeyScheme;
+};
+/**
+ * Atalho para as visões estreitas: `PlayerView<'x' | 'y'>` em vez de reescrever os campos.
+ *
+ * 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.
+ */
+export type PlayerView<K extends keyof Player> = Pick<Player, K>;

package/dist-pkg/core/entity.js

@@ -0,0 +1,38 @@
+// 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.
+//
+// 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:
+//
+//   · `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.
+//
+// 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.
+//
+// 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.
+export {};

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

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Os CINCO caracteres, e cobre os dois contextos: elemento (`<` `>`) e ATRIBUTO (`"` `'`).
+ *
+ * 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.
+ *
+ * ⚠️ 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.
+ *
+ * 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.
+ */
+export declare function escaparHtml(s: string): string;