@the-inclusionist/engine 6.36.1

package/dist-pkg/render/parallax.d.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { CenarioTema, TemaMorros, TemaPredios, FaixaDePredios } from './cenario-data.js';
+import type { CriarAzulejo } from './port.js';
+/** Uma camada de fundo: `factor` = quanto do movimento horizontal da câmera ela reproduz; `fy`, o vertical. */
+export interface CamadaParallax {
+    key: string;
+    factor: number;
+    fy: number;
+}
+export declare const PARALLAX: readonly CamadaParallax[];
+/** Índice da camada → número do arquivo PNG da Cidade (`c4.png`, `c3.png`, `c2.png`). */
+export declare const ARQUIVO_POR_CAMADA: readonly number[];
+/** Onde uma camada fica neste quadro. `x`/`y` = posição DENTRO do camera; `tileX`/`tileY` = rolagem da textura. */
+export interface PosicaoParallax {
+    x: number;
+    y: number;
+    tileX: number;
+    tileY: number;
+}
+/**
+ * A matemática do parallax, sem sprite nenhum.
+ *
+ * `x`/`y` = `camX`/`camY` porque o container `camera` está em `-camX`/`-camY`: a soma dá ZERO, e a camada
+ * fica parada na tela. É esse cancelamento que faz o fundo parecer fundo.
+ * `tileX`/`tileY` = `-cam * fator`: quanto MENOR o fator, menos a textura rola, mais distante a camada parece.
+ * Com `reduzido` (movimento reduzido — `rm.parallax`), a rolagem trava em zero e o fundo vira papel de
+ * parede; a contra-posição CONTINUA valendo, senão o fundo passaria a deslizar junto com o mundo — o oposto
+ * exato do que a opção existe para dar.
+ */
+export declare function posicoesParallax(camX: number, camY: number, camadas?: readonly CamadaParallax[], reduzido?: boolean): PosicaoParallax[];
+/** `tilePosition` de um `TilingSprite` — só o `set`, que é como o original o escreve. */
+interface PontoObservavel {
+    set(x: number, y: number): void;
+}
+/** O que tocamos de um `PIXI.TilingSprite`, e só isso. */
+export interface TilingSpriteLike {
+    x: number;
+    y: number;
+    texture: unknown;
+    tilePosition: PontoObservavel;
+    /**
+     * A ordem-z. Este módulo NÃO a lê — quem a escreve é a raiz de composição, ao encaixar as três camadas
+     * no registro canônico do ADR-0020. Está aqui porque a interface é EXPORTADA: ela não descreve só o que
+     * o parallax toca, descreve o que ele DEVOLVE, e o consumidor precisa deste campo para posicionar.
+     */
+    zIndex: number;
+}
+/** `camera` — só a inserção em posição de z fixa. */
+interface ContainerLike {
+    addChildAt(child: unknown, index: number): unknown;
+}
+/** `starsG`/`skyDecoG`/`fogG`: contra-posicionados junto com o parallax. */
+interface PosicionavelLike {
+    position: {
+        set(x: number, y: number): void;
+    };
+}
+export interface ParallaxCtx {
+    camera: ContainerLike;
+    criarAzulejo: CriarAzulejo<TilingSpriteLike>;
+    placeholderTex: (i: number) => unknown;
+    skyTex: (T: CenarioTema) => unknown;
+    /** themeHillsTexture — banda de morros. O `tema` escolhe a SILHUETA plantada em cima (árvores, cerca). */
+    hillsTex: (T: TemaMorros, near: boolean, tema: string) => unknown;
+    /** themeCitySkyTexture — céu + prédios distantes da Cidade, a única camada opaca dela. */
+    citySkyTex: (T: TemaPredios) => unknown;
+    /** themeSkylineTexture — uma faixa de prédios sobre transparência. */
+    skylineTex: (faixa: FaixaDePredios, semente: number) => unknown;
+    rm: {
+        parallax?: boolean;
+    };
+    getCenario: () => string;
+    getVizMode: () => string;
+    clearParallaxTexCache: () => void;
+    getDecorDeTela: () => ReadonlyArray<PosicionavelLike | null | undefined>;
+}
+export interface ParallaxApi {
+    layers: TilingSpriteLike[];
+    texNormal: unknown[];
+    updateParallax(camX: number, camY: number): void;
+    aplicarTemaParallax(theme: string, T: CenarioTema): void;
+}
+/** Cria as 3 camadas dentro do `camera` e devolve a API que as move e as veste. */
+export declare function createParallax(ctx: ParallaxCtx): ParallaxApi;
+export {};

package/dist-pkg/render/parallax.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/parallax — AS TRÊS CAMADAS DE FUNDO: onde cada uma fica, e de que tema ela é feita.
+//
+// Camada 1 do jogo é o tileset + o personagem. Atrás dele vêm três `TilingSprite`, e é isso que este módulo
+// governa: quanto cada uma se desloca quando a câmera anda (`updateParallax`), e qual textura cada uma veste
+// quando o cenário muda (`aplicarTemaParallax`). Nada mais — o tileset do mundo, o céu vivo da v3, o clima e a
+// Cidade têm cada um o seu módulo, e nenhum deles passa por aqui.
+//
+// ======================= A ENTREGA: A CONTA SAIU DE DENTRO DO EFEITO =======================
+// `updateParallax` era MATEMÁTICA PURA DISFARÇADA DE EFEITO. Dado (camX, camY) e os fatores de profundidade,
+// existe UMA posição determinada para cada camada — mas no monólito essa posição só existia como o lado
+// esquerdo de quatro atribuições dentro de um `for`, e a única forma de conferi-la era subir o jogo inteiro e
+// olhar. Aqui a conta é `posicoesParallax(camX, camY, camadas, reduzido)`, uma função pura que devolve
+// `{x, y, tileX, tileY}` por camada, e o `updateParallax` virou o carimbo dela nos sprites.
+//
+// O que essa separação torna verificável — e o que quebraria em SILÊNCIO sem ela:
+//  1. A CONTRA-POSIÇÃO. Os três sprites vivem DENTRO do container `camera` (têm de viver: é assim que também
+//     aparecem nas render-textures do multi-tela). O `camera` anda `-camX` a cada quadro; cada camada é posta
+//     em `+camX` para cancelar exatamente esse movimento e ficar PARADA na tela. É o cancelamento que faz o
+//     fundo parecer fundo. Inverta o sinal e o céu passa a correr com o dobro da velocidade do mundo, na
+//     direção errada — o jogo continua rodando, os testes de física continuam verdes, e só quem olhar percebe.
+//  2. A PROPORCIONALIDADE. O `tilePosition` de cada camada rola por `-camX * fator`. Camada mais distante
+//     (fator menor) se mexe MENOS. Ignorar o fator (ou trocá-lo entre duas camadas) achata a profundidade sem
+//     erro nenhum em lugar nenhum.
+//  3. O MOVIMENTO REDUZIDO. Com `rm.parallax` ligado (acessibilidade: gatilho vestibular), o `tilePosition`
+//     trava em zero — o fundo vira papel de parede — MAS a contra-posição continua valendo. Trocar essa ordem
+//     (travar `x`/`y` em vez do `tilePosition`) grudaria o fundo no mundo e produziria exatamente o
+//     deslizamento que a opção existe para eliminar, para a pessoa que pediu para não ver deslizamento.
+//
+// ======================= POR QUE A FRONTEIRA CAIU AQUI, E NÃO ANTES NEM DEPOIS =======================
+// ANTES (o dado dos temas) saiu para render/cenario-data.ts: as cores não são geometria de câmera, e são
+// lidas por scene-sky e pelo attract, que não têm nada a ver com rolagem. `PARALLAX` FICOU aqui, e não lá,
+// porque os fatores não variam por tema — são a definição de "o que é fundo" — e porque a conta que os
+// consome é a deste arquivo.
+// DEPOIS (a orquestração da troca de cenário) ficou em render/set-cenario.ts. `setCenario` faz TRÊS coisas:
+// repinta o fundo, RECONSTRÓI A TEXTURA DO MUNDO a partir dos PNG de tile do tema, e avisa a vida ambiente e
+// o alto contraste. Só a primeira é parallax. Trazer as outras duas para cá daria a este módulo a textura do
+// tileset — que não é fundo, é a Camada 1 — e o ciclo de vida do alto contraste. Por isso `aplicarTemaParallax`
+// mora aqui e é CHAMADO de lá: este módulo sabe vestir as três camadas e não sabe por quê.
+//
+// ======================= A PARTE IMPURA, E O QUE ELA GUARDA =======================
+// `aplicarTemaParallax` tem duas metades assimétricas, e a assimetria é o ponto:
+//  · Tema `v3` (Campo/Amanhecer/Noite/Floresta): as texturas são GERADAS na hora (render/scene-parallax), de
+//    forma síncrona. Não há espera, logo não há corrida.
+//  · Cidade (`v3:false`): as três texturas são PNG baixados, e chegam quando chegarem. Entre o pedido e a
+//    chegada a pessoa pode ter trocado de cenário de novo — por isso cada callback abre com
+//    `if (getCenario() !== theme) return`. Sem essa guarda, um PNG atrasado da Cidade sobrescreveria o céu do
+//    tema recém-escolhido. É a corrida mais fácil de introduzir e a mais difícil de reproduzir de mão, e é
+//    por ela, mais do que por qualquer outra coisa, que esta metade também entrou num módulo testável.
+// Nos dois caminhos a ordem é a mesma e importa: grava em `texNormal` → invalida o cache de recolor
+// (`clearParallaxTexCache`) → e SÓ pinta o sprite se o modo de visão for 'normal'. Nos modos acessíveis quem
+// pinta é render/viz-setters, lendo a textura crua que acabamos de gravar; pintar aqui atropelaria o recolor.
+//
+// ======================= INJEÇÃO, INTERFACE ESTRUTURAL E ORDEM DE BOOT =======================
+// Nada de `import * as PIXI`: declaramos só o que tocamos — um `TilingSprite` é, aqui, quatro campos
+// (`x`, `y`, `texture`, `tilePosition`) e um construtor de três argumentos. É o precedente de
+// render/scene-sky e render/viewports, e é o que deixa o módulo (e a factory INTEIRA, não só a parte pura)
+// rodar no project `node`, com sprites de mentira e um `Image` falso.
+// Pela mesma razão os três geradores de textura (`placeholderTex`/`skyTex`/`hillsTex`) entram INJETADOS em vez
+// de importados de render/scene-parallax: eles chamam `makeCanvas`, e importá-los aqui obrigaria todo teste da
+// factory a ter um `document`.
+//  · `rm` entra por VALOR: é `const` no game.js, mutado in place pelo painel de movimento reduzido (mesma
+//    decisão de render/draw.ts). Ler `rm.parallax` a cada quadro já vê o valor novo.
+//  · `getCenario`/`getVizMode` entram por GETTER: são as mega-variáveis de core/state.js, REATRIBUÍDAS.
+//  · `getDecorDeTela` é GETTER porque `starsG`/`skyDecoG`/`fogG` são declarados MUITO depois no game.js — o
+//    monólito protegia isso com `typeof starsG!=='undefined'`. Aqui o game.js passa `() => [starsG, skyDecoG,
+//    fogG]` (são `var`, logo içados) e a guarda por elemento fica deste lado.
+//  · `createParallax` DEVOLVE `layers` e `texNormal` em vez de recebê-los: o game.js os mantém como `const`
+//    desestruturados do retorno, e `texNormal` continua sendo o MESMO array que `initViewports` recebe por
+//    VALOR — `aplicarTemaParallax` troca os ELEMENTOS in place, nunca o array.
+//
+// ⚠️ ORDEM DE BOOT: `createParallax` tem de rodar logo depois de `camera` existir e ANTES de qualquer coisa que
+// dependa de `parallaxLayers` — o `camera.addChildAt(ts, i)` dá a ordem-z do fundo, e `starsG` é inserido
+// relativamente a `parallaxLayers[1]`. E tem de rodar ANTES do `setCenario` do boot, que é quem veste as
+// camadas com o tema salvo.
+//
+// SEM I/O NO IMPORT: o corpo do módulo declara `PARALLAX` e funções. Nenhum sprite é criado, nenhuma textura é
+// gerada e nenhuma imagem é pedida até `createParallax`/`aplicarTemaParallax` serem chamados.
+// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (D2-b).
+import { LOGICAL_W, LOGICAL_H } from '../core/constants.js';
+/* Parallax: 3 camadas de FUNDO atrás do tileset (Camada 1 = tileset+personagem).
+   Camada 4 (fator 0.10) é a mais distante e "quase não se mexe" — receberá a maior imagem possível do
+   PixelLab. Vivem DENTRO do camera (contra-posicionadas p/ ficarem fixas na tela) para também aparecerem nas
+   render-textures do multiplayer. tilePosition faz o scroll fracionado → ilusão de profundidade.
+   A ORDEM do array é a ordem-z: índice 0 no fundo. */
+export const PARALLAX = [
+    { key: 'sky', factor: 0.10, fy: 0 }, // Camada 4 — mais distante (céu/horizonte), maior imagem
+    { key: 'far', factor: 0.28, fy: 0 }, // Camada 3
+    { key: 'near', factor: 0.52, fy: 0 }, // Camada 2 — mais próxima do tileset
+];
+/** Índice da camada → número do arquivo PNG da Cidade (`c4.png`, `c3.png`, `c2.png`). */
+export const ARQUIVO_POR_CAMADA = [4, 3, 2];
+/**
+ * A matemática do parallax, sem sprite nenhum.
+ *
+ * `x`/`y` = `camX`/`camY` porque o container `camera` está em `-camX`/`-camY`: a soma dá ZERO, e a camada
+ * fica parada na tela. É esse cancelamento que faz o fundo parecer fundo.
+ * `tileX`/`tileY` = `-cam * fator`: quanto MENOR o fator, menos a textura rola, mais distante a camada parece.
+ * Com `reduzido` (movimento reduzido — `rm.parallax`), a rolagem trava em zero e o fundo vira papel de
+ * parede; a contra-posição CONTINUA valendo, senão o fundo passaria a deslizar junto com o mundo — o oposto
+ * exato do que a opção existe para dar.
+ */
+export function posicoesParallax(camX, camY, camadas = PARALLAX, reduzido = false) {
+    return camadas.map((p) => ({
+        x: camX,
+        y: camY,
+        tileX: reduzido ? 0 : -camX * p.factor,
+        tileY: reduzido ? 0 : -camY * p.fy,
+    }));
+}
+/* ===================== a montagem + o carimbo (impuro) ===================== */
+/** Cria as 3 camadas dentro do `camera` e devolve a API que as move e as veste. */
+export function createParallax(ctx) {
+    const layers = PARALLAX.map((_p, i) => {
+        const ts = ctx.criarAzulejo(ctx.placeholderTex(i), LOGICAL_W, LOGICAL_H);
+        ctx.camera.addChildAt(ts, i); // i=0 (sky) fica no fundo; depois far, near; tileset entra por cima
+        return ts;
+    });
+    // texturas normais (recoloridas p/ o fundo no alto contraste). Array `const` no game.js: os ELEMENTOS mudam.
+    const texNormal = layers.map((ts) => ts.texture);
+    function updateParallax(camX, camY) {
+        const pos = posicoesParallax(camX, camY, PARALLAX, !!ctx.rm.parallax);
+        for (let i = 0; i < layers.length; i++) {
+            const ts = layers[i], q = pos[i];
+            ts.x = q.x;
+            ts.y = q.y; // anula o camera → fixa na tela
+            ts.tilePosition.set(q.tileX, q.tileY); // rolagem fracionada → profundidade (0,0 no movimento reduzido)
+        }
+        // L6: decor de TELA da v3 (estrelas atrás dos morros · nuvens/pássaros à frente · névoa na frente de tudo).
+        // Guarda por elemento: no boot elas ainda não existem (eram o `typeof starsG!=='undefined'` do monólito).
+        for (const g of ctx.getDecorDeTela()) {
+            if (g)
+                g.position.set(camX, camY);
+        }
+    }
+    /** Grava a textura crua da camada `i`, invalida o recolor e — só no modo 'normal' — pinta o sprite. */
+    function vestir(i, t) {
+        texNormal[i] = t;
+        ctx.clearParallaxTexCache();
+        if (ctx.getVizMode() === 'normal')
+            layers[i].texture = t; // nos modos acessíveis quem pinta é viz-setters
+    }
+    /**
+     * TODA TROCA DE TEMA É SÍNCRONA AGORA (ADR-0042), e isso é mais que uma simplificação.
+     *
+     * Enquanto a Cidade vinha de PNG, este caminho era assíncrono e carregava a corrida junto: três `Image`
+     * baixando, e cada `onload` tendo de perguntar `getCenario() !== theme` antes de pintar, porque a criança
+     * podia ter trocado de cenário no meio. Isso sumiu com os arquivos — não há mais o que baixar, e portanto
+     * não há mais corrida que possa perder.
+     */
+    function aplicarTemaParallax(theme, T) {
+        const texs = T.fundo === 'predios'
+            ? [ctx.citySkyTex(T), ctx.skylineTex(T.predios[1], 977), ctx.skylineTex(T.predios[2], 131)]
+            : [ctx.skyTex(T), ctx.hillsTex(T, false, theme), ctx.hillsTex(T, true, theme)];
+        layers.forEach((_ts, i) => vestir(i, texs[i]));
+    }
+    return { layers, texNormal, updateParallax, aplicarTemaParallax };
+}

package/dist-pkg/render/player-anim.d.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { ControlledPlayer } from '../core/entity.js';
+/** Uma textura de quadro. Opaca de propósito: este módulo ESCOLHE quadros, nunca os desenha. */
+export type Frame = unknown;
+/** Uma "gracinha" de descanso (render/sprites.FLAVORS): `seq` indexa `tex`, `hold` é o nº de ticks por passo. */
+export interface FlavorLike {
+    seq: readonly number[];
+    hold: number;
+    tex: readonly Frame[];
+}
+/** O conjunto COMPLETO de quadros do personagem. Espelha os `TEX_*` de render/sprites, com nomes curtos. */
+export interface PlayerTextures {
+    idle: readonly Frame[];
+    walk: readonly Frame[];
+    run: readonly Frame[];
+    jumpUp: Frame;
+    jumpDown: Frame;
+    climb: readonly Frame[];
+    fly: Frame;
+    clingWall: readonly Frame[];
+    clingCeil: readonly Frame[];
+    swim: readonly Frame[];
+    swimIdle: readonly Frame[];
+    flavors: readonly FlavorLike[];
+}
+/** Os campos do jogador que a ANIMAÇÃO lê ou escreve. O objeto real (game/player.makePlayer) é superconjunto. */
+/**
+ * O jogador visto pela ANIMAÇÃO — derivado de core/entity. O que cada campo significa está documentado lá,
+ * uma vez; o que importa registrar AQUI é o que este módulo faz com eles:
+ *
+ *  · LÊ o que a física produziu: `vx`/`vy`, os três contatos, `clinging`/`clingN`/`flying` e `airTime`
+ *    (quadros desde que saiu do chão — a base do coyote-time). `runCane` decide se `running` pode ligar.
+ *  · LÊ as preferências de Movimento Reduzido: `rmWalk` congela TODA a locomoção num quadro único,
+ *    `rmBreath` congela a respiração do idle, `rmFlavor` desliga as gracinhas.
+ *  · ESCREVE os relógios: `anim` (respiração), `walkAnim` (o passo — NUNCA reseta, senão o ciclo de 8
+ *    reinicia), `climbFrame` (quadro CONGELADO da ventosa), `idleNow`/`idleTime`, `flavor`/`flavorT`,
+ *    `walking`/`running` (lidos pelo desenho da bengala em render/draw) e `_tx`, o quadro-base EM COR a
+ *    partir do qual o multi-tela recolore, por viewport.
+ *  · `ctrl`/`pad` entram só porque `held` precisa deles. `ControlledPlayer`: a animação roda em partida.
+ *
+ * `clingN` era `string | null` aqui e `ClingSide | null` na física — a mesma face da ventosa, uma tipada e
+ * a outra não. Derivar fecha isso sem discussão.
+ */
+export type AnimPlayer = Pick<ControlledPlayer, 'vx' | 'vy' | 'onGround' | 'onLadder' | 'inWater' | 'clinging' | 'clingN' | 'flying' | 'airTime' | 'runCane' | 'rmWalk' | 'rmBreath' | 'rmFlavor' | 'anim' | 'walkAnim' | 'climbFrame' | 'idleNow' | 'idleTime' | 'flavor' | 'flavorT' | 'walking' | 'running' | '_tx' | 'ctrl' | 'pad'>;
+/** Tudo que a escolha do quadro precisa e que não mora no jogador. */
+export interface PlayerAnimEnv {
+    dt: number;
+    dir: number;
+    wheelchair: boolean;
+    held(pl: AnimPlayer, act: string): boolean;
+    rnd(): number;
+    tex: PlayerTextures;
+}
+/**
+ * Coyote-time da ANIMAÇÃO (E16), em quadros. Existe para matar o flicker walk↔jump no pouso: `onGround`
+ * pisca por 1 quadro ao repousar, e sem essa folga o personagem alternava entre andar e pular ao aterrissar.
+ * É o coyote do RENDER e é independente do coyote da física (game/physics) — mudar um não muda o outro.
+ */
+export declare const COYOTE = 5;
+/**
+ * Escolhe o quadro do jogador para ESTE tick e adianta os relógios de animação.
+ *
+ * Cadeia de prioridade E17, do mais específico ao mais genérico — a ORDEM é a regra, não um detalhe:
+ *   ventosa → escada → água → voo → aéreo(pulo) → andando → idle
+ * Estar na água DENTRO de uma escada mostra escada; grudado na parede dentro d'água mostra ventosa.
+ *
+ * Também escreve em `pl` (ver AnimPlayer): `walking`/`running` (bengala), `idleNow`, os relógios e `_tx`.
+ *
+ * @returns o quadro escolhido (o mesmo valor que fica em `pl._tx`).
+ */
+export declare function choosePlayerFrame(pl: AnimPlayer, env: PlayerAnimEnv): Frame;

package/dist-pkg/render/player-anim.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/player-anim.ts — A ESCOLHA DO QUADRO do personagem: dado o estado do jogador, QUAL textura desenhar.
+// Extraída verbatim da segunda metade do `stepPlayer` do game.js (o trecho E15/E16/E17/E19/E20, de
+// `const COYOTE=5` até `pl._tx=tx`). Ela morava dentro da função de física por acidente histórico — mas não é
+// física: não move ninguém, não colide, não lê o mundo. É uma DECISÃO PURA a partir do estado já simulado,
+// e é por isso que ela é render e mora aqui, ao lado de render/sprites (quem cria as texturas) e de
+// render/viewports (quem as recolore por modo de visão).
+//
+// POR QUE A FRONTEIRA CAIU EXATAMENTE AQUI
+// O `stepPlayer` do monólito fazia quatro coisas em sequência: (1) física, (2) coleta de moeda/quiz,
+// (3) power-ups + chave/portão, (4) animação. A (1) já saiu para game/physics.ts (B1), que devolve
+// `{ran, dir}` — e `dir` existe justamente porque a animação lê a DIREÇÃO DO INPUT, não `vx` (a colisão zera
+// `vx` por quadros inteiros e isso reiniciava o ciclo de passos; só apareciam 2 dos 8 quadros). As (2) e (3)
+// são LÓGICA DE JOGO — dependem de `coins`, `powerups`, `gate`, do quiz e do HUD — e continuam no game.js;
+// não vieram junto de propósito, porque arrastá-las para cá traria de volta metade do monólito.
+// O corte começa em `const COYOTE=5` e termina em `pl._tx=tx`. A ÚLTIMA linha do original,
+// `if(pl.sprite) pl.sprite.texture=playerVizTex(tx, pl.viz)`, NÃO está aqui: ela toca um sprite do PIXI e o
+// recolor por modo de visão. Ela vive em render/draw.ts (`animatePlayer`), que é quem já lida com PIXI.
+// Assim este arquivo fica sem PIXI, sem DOM e sem estado de módulo — testável quadro a quadro no project
+// `node` do Vitest.
+//
+// O QUE É "PURO" AQUI (e o que não é)
+// A função é DETERMINÍSTICA dado `(pl, env)` e não faz I/O nenhum. Ela ESCREVE em `pl`, e isso é contrato,
+// não efeito colateral escondido: os relógios de animação (`anim`, `walkAnim`, `idleTime`, `flavorT`),
+// o quadro congelado da ventosa (`climbFrame`), o estado da gracinha (`flavor`) e as flags que o RESTO do
+// jogo lê (`walking`/`running`, que a bengala do modo cego consome em draw; `idleNow`; `_tx`, o quadro-base
+// em cor que o multi-tela recolore por viewport) moram no objeto do jogador desde o v3. Mover esses campos
+// para dentro do módulo criaria um segundo lugar de verdade sobre o jogador — o oposto do que a
+// modularização quer. O teste, por isso, sonda `pl` depois da chamada tanto quanto o valor de retorno.
+//
+// INJEÇÃO: `held` E `rnd` ENTRAM PELO `env`, NÃO POR IMPORT — e isso é um DESVIO CONSCIENTE do precedente de
+// game/physics.ts, que importa os dois. Lá a âncora de regressão são as 14 trajetórias-ouro, que exigem o
+// singleton de input e o RNG semeado reais; aqui não há trajetória-ouro nenhuma, e o valor da extração é
+// poder atravessar a cadeia de prioridade ramo a ramo. Com `held` injetado, um teste liga "Correr" sem
+// montar `keys`+`ctrl`+`padCur`; com `rnd` injetado, a gracinha sorteada é ESCOLHIDA em vez de descoberta.
+// O game.js passa exatamente os mesmos `held` (input/state) e `rnd` (core/rng), então a ordem de consumo da
+// semente — de que o attract-mode/replay depende — fica idêntica à do monólito.
+// As texturas também entram pelo `env` (`env.tex`): os `TEX_*` de render/sprites são bindings VIVOS que só
+// `initCharacterSprites()` preenche, e importá-los aqui amarraria o módulo ao boot do PIXI justamente na
+// parte que queremos testar sem ele. `ANIM` (as cadências) é constante pura → import normal.
+//
+// ARMADILHA DE ORDEM DE BOOT: nenhuma. O módulo não tem estado próprio nem toca nada no import.
+import { ANIM } from '../core/constants.js';
+/**
+ * Coyote-time da ANIMAÇÃO (E16), em quadros. Existe para matar o flicker walk↔jump no pouso: `onGround`
+ * pisca por 1 quadro ao repousar, e sem essa folga o personagem alternava entre andar e pular ao aterrissar.
+ * É o coyote do RENDER e é independente do coyote da física (game/physics) — mudar um não muda o outro.
+ */
+export const COYOTE = 5;
+/**
+ * Escolhe o quadro do jogador para ESTE tick e adianta os relógios de animação.
+ *
+ * Cadeia de prioridade E17, do mais específico ao mais genérico — a ORDEM é a regra, não um detalhe:
+ *   ventosa → escada → água → voo → aéreo(pulo) → andando → idle
+ * Estar na água DENTRO de uma escada mostra escada; grudado na parede dentro d'água mostra ventosa.
+ *
+ * Também escreve em `pl` (ver AnimPlayer): `walking`/`running` (bengala), `idleNow`, os relógios e `_tx`.
+ *
+ * @returns o quadro escolhido (o mesmo valor que fica em `pl._tx`).
+ */
+export function choosePlayerFrame(pl, env) {
+    const { dt, dir, tex, wheelchair } = env;
+    const held = env.held, rnd = env.rnd;
+    // E16: estado aéreo ESTÁVEL — subindo (vy<0) entra na hora; cair/sair de borda só após o coyote-time.
+    const grounded = pl.airTime <= COYOTE;
+    const airborne = !pl.clinging && ((pl.vy < 0 && !pl.onGround) || !grounded);
+    // 'moving' baseado no INPUT (direção segurada), NÃO em vx — a colisão zera vx por quadros e isso resetava
+    // o ciclo (só apareciam 2 dos 8 quadros). Assim os 8 quadros tocam contínuos.
+    const moving = (dir !== 0) && grounded && !pl.clinging;
+    pl.walking = moving && !pl.inWater && !pl.onLadder && !pl.flying; // p/ a bengala: só aparece andando
+    pl.running = pl.walking && held(pl, 'action1') && !!pl.runCane; // correndo: só com a bengala de corrida
+    pl.anim += dt; // idle (clock contínuo)
+    pl.walkAnim += dt; // clock do passo NUNCA reseta → ciclo de 8 sem reinício
+    const II = tex.idle;
+    const wcFreeze = wheelchair || !!pl.rmWalk; // cadeirante: pernas paradas — mesma via do movimento reduzido
+    let tx;
+    pl.idleNow = false;
+    if (pl.clinging) {
+        const ceil = (pl.clingN === 'U'); // E18f: teto e parede usam ciclos distintos
+        const CL = ceil ? tex.clingCeil : tex.clingWall;
+        if (!pl.rmWalk && (pl.vx !== 0 || pl.vy !== 0))
+            pl.climbFrame = (Math.floor(pl.walkAnim / ANIM.clingHold)) % CL.length; // só avança ao mover; parado MANTÉM o quadro
+        tx = CL[(pl.rmWalk ? 0 : (pl.climbFrame || 0)) % CL.length];
+    }
+    else if (pl.onLadder) {
+        const CB = tex.climb;
+        if (wheelchair) {
+            tx = II[0];
+        } // ELEVADOR cadeirante: pose PARADA (idle), não de escada
+        else {
+            const climbing = (pl.vy !== 0) && !pl.rmWalk;
+            tx = climbing ? CB[Math.floor(pl.walkAnim / ANIM.climbHold) % CB.length] : CB[0];
+        }
+    }
+    else if (pl.inWater) {
+        const stroking = ((dir !== 0) || held(pl, 'action2')) && !wcFreeze; // movendo = braçada; parado/congelado = pernas paradas
+        const SW = stroking ? tex.swim : tex.swimIdle;
+        tx = wcFreeze ? SW[0] : SW[Math.floor(pl.walkAnim / ANIM.swimHold) % SW.length];
+    }
+    else if (pl.flying) {
+        tx = tex.fly;
+    }
+    else if (airborne) {
+        if (wcFreeze)
+            tx = wheelchair ? II[0] : tex.jumpUp; // cadeirante caindo = pose neutra sentado; congelado = pulo num quadro
+        else
+            tx = pl.vy < 0 ? tex.jumpUp : tex.jumpDown; // subindo: pernas recolhidas / caindo: estendidas
+    }
+    else if (moving) {
+        if (wcFreeze) {
+            tx = II[0];
+        } // cadeirante/movimento reduzido: anda sem ciclo de passos
+        else {
+            const running = held(pl, 'action1'); // E19: correr ≠ andar — passada/cadência distintas
+            const M = running ? tex.run : tex.walk;
+            const hold = running ? ANIM.runHold : ANIM.walkHold;
+            tx = M[Math.floor(pl.walkAnim / hold) % M.length];
+        }
+    }
+    else {
+        pl.idleNow = true;
+        pl.idleTime += dt; // E20: parado → respira; após flavorDelay, uma gracinha
+        if (!pl.rmFlavor) { // gracinhas (toggle próprio — há quem se incomode)
+            if (pl.flavor < 0 && pl.idleTime > ANIM.flavorDelay) {
+                pl.flavor = Math.floor(rnd() * tex.flavors.length);
+                pl.flavorT = 0;
+            }
+            if (pl.flavor >= 0) {
+                const F = tex.flavors[pl.flavor];
+                const step = Math.floor(pl.flavorT / F.hold);
+                pl.flavorT += dt;
+                if (step >= F.seq.length) {
+                    pl.flavor = -1;
+                    pl.idleTime = 0;
+                }
+                else {
+                    tx = F.tex[F.seq[step]];
+                }
+            }
+        }
+        else
+            pl.flavor = -1;
+        if (pl.flavor < 0)
+            tx = pl.rmBreath ? II[0] : II[Math.floor(pl.anim / ANIM.idleHold) % II.length]; // respiração: congela ou cicla
+    }
+    if (!pl.idleNow) {
+        pl.idleTime = 0;
+        pl.flavor = -1;
+    } // saiu do idle → zera gracinha
+    pl._tx = tx; // quadro base (cor) p/ recolor por viewport
+    return tx;
+}

package/dist-pkg/render/port.d.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** O MÍNIMO de uma camada de desenho vetorial: limpar, preencher, retangular. */
+export interface Desenho {
+    clear(): this;
+    beginFill(color: number, alpha?: number): this;
+    drawRect(x: number, y: number, w: number, h: number): this;
+    endFill(): this;
+}
+/** Desenho que também traça linha — chuva, cabos, tracinhos de lava. */
+export interface DesenhoComLinha extends Desenho {
+    lineStyle(width: number, color?: number, alpha?: number): this;
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+}
+/** O que se pode esconder. Separado de `Desenho` porque nem toda camada é escondida por quem a desenha. */
+export interface Visivel {
+    visible: boolean;
+}
+/** Um contêiner do grafo de cena, do ponto de vista de quem só adiciona e remove filhos. */
+export interface Camada {
+    addChild(c: unknown): unknown;
+    removeChild(c: unknown): unknown;
+}
+/** O que tem textura trocável — o recolor do alto contraste escreve aqui. */
+export interface ComTextura {
+    texture: unknown;
+}
+/**
+ * DESENHAR UM OBJETO DENTRO DE UMA TEXTURA — a captura de tela de cada jogador no multi-tela.
+ *
+ * É uma FUNÇÃO e não um objeto `{ render(...) }`, e a diferença é o que faz a porta funcionar. Dois módulos
+ * declaravam `interface RendererLike { render(displayObject: unknown, options: { renderTexture: unknown }) }`
+ * — idênticos, e ambos recusados pelo PixiJS real: o `render` dele pede `IRenderableObject`, e `unknown` não
+ * é atribuível a isso. Por contravariância, quem DECLARA o parâmetro mais largo é quem não cabe.
+ *
+ * Pedir a CAPACIDADE resolve: o módulo diz o que quer que aconteça, e a raiz de composição — que é o único
+ * lugar onde o PixiJS já é conhecido — entrega a função. É o adaptador que o ADR-0035 prometeu, e a promessa
+ * só vira fato quando o pedido tem a forma de um verbo, não a de um objeto emprestado.
+ *
+ * ⚠️ `limpar` É OBRIGATÓRIO, e era opcional. Desenhar numa textura de render sem dizer se ela deve ser limpa
+ * antes é a diferença entre um quadro e um BORRÃO: sem limpar, cada quadro se acumula sobre o anterior e o
+ * personagem aparece várias vezes, em várias posições. Havia dois chamadores — um passava `false` de
+ * propósito (a passada extra de baixa visão, que compõe POR CIMA) e o outro não passava nada, deixando a
+ * decisão para um padrão que ninguém escreveu.
+ *
+ * Um padrão implícito aqui é caro de duas formas: ele muda com a versão do renderizador, e o sintoma dele é
+ * visual — nenhum teste de lógica o vê. Tornar o parâmetro obrigatório faz o compilador cobrar a intenção de
+ * cada chamador, uma vez, e para sempre.
+ */
+export type RenderizarEm = (objeto: unknown, alvo: unknown, limpar: boolean) => void;
+/**
+ * CRIAR UM SPRITE a partir de uma textura, e um AZULEJO a partir dela.
+ *
+ * Fábricas, não construtores — e pelo mesmo motivo do `RenderizarEm` acima. Três módulos pediam
+ * `interface SpriteCtor { new (tex: unknown): Sprite }`, e o `PIXI.Sprite` real não cabe: o construtor dele
+ * aceita `Texture | undefined`, e um parâmetro declarado `unknown` é MAIS LARGO — por contravariância, quem
+ * promete aceitar qualquer coisa é quem não pode receber um construtor que só aceita textura.
+ *
+ * Uma função apaga o problema: quem chama passa a textura que já tem, e quem compõe fecha a diferença uma
+ * vez. `T` é o que o módulo espera de volta — cada um sabe qual fatia do sprite ele vai tocar.
+ */
+export type CriarSprite<T> = (textura: unknown) => T;
+/** Idem para o azulejo do parallax, que também recebe largura e altura. */
+export type CriarAzulejo<T> = (textura: unknown, largura: number, altura: number) => T;
+/** E o desenho vetorial vazio (`new PIXI.Graphics()`), pela mesma razão. */
+export type CriarDesenho<T> = () => T;
+/**
+ * O QUE SE TINGE — um sprite do ponto de vista de quem só ESCREVE a cor nele.
+ *
+ * `tint: unknown`, e o `unknown` aqui é a coisa certa, não preguiça. Dois módulos declaravam
+ * `tint: number` — e o `PIXI.Sprite` real NÃO CABE nisso: o `tint` dele é `ColorSource`, que aceita
+ * número, texto (`'red'`), array e mais. `number` é um SUBTIPO estrito disso, e um módulo que não é
+ * dono do campo declarando algo MAIS ESTREITO que a verdade é exatamente o que o ADR-0039 proíbe:
+ * estreitar é o que quebra a atribuição.
+ *
+ * O supertipo verdadeiro que dá para provar sem importar PixiJS é `unknown`. O preço é conhecido e
+ * pequeno: quem escreve aqui não é mais conferido pelo compilador — mas as duas únicas escritas da
+ * árvore são constantes hexadecimais literais, e o `ColorSource` aceitaria todas elas de qualquer jeito.
+ */
+export interface Tingivel {
+    tint: unknown;
+}
+/** O que se descarta. `DisplayObject.destroy(options?)` do PixiJS satisfaz — o opcional não atrapalha. */
+export interface Descartavel {
+    destroy(): void;
+}
+/**
+ * Camada que também ESVAZIA, devolvendo o que saiu para quem precisa destruir os filhos removidos.
+ *
+ * Separada de `Camada` porque só um consumidor esvazia, e porque o retorno é a parte delicada: quem
+ * declarava `removeChildren(): CoinSprite[]` pedia de volta algo mais ESPECÍFICO do que o PixiJS
+ * entrega (`DisplayObject[]`) — e retorno é covariante, então o pedido específico é o que não cabe.
+ * `Descartavel` é o que o chamador de fato usa.
+ */
+export interface CamadaEsvaziavel extends Camada {
+    removeChildren(): Descartavel[];
+}
+/** O que tem filtro de GPU — a câmera e cada sprite de saída do multi-tela. */
+export interface ComFiltro {
+    filters: unknown;
+}
+/** Desenho que também traça CÍRCULO — a bolinha indicadora de cada viewport. */
+export interface DesenhoComCirculo extends DesenhoComLinha {
+    drawCircle(x: number, y: number, r: number): this;
+}
+/**
+ * APLICAR UM FILTRO CSS NO SOLO — o filtro global da tela, que compõe daltonismo, baixa visão,
+ * cegueira e o realce de luminância/quantização.
+ *
+ * Era `app: AppLike | null` com `AppLike { view?: { style: { filter: string } } }` — o módulo alcançava
+ * TRÊS níveis para dentro de um objeto que não é dele, e o `PIXI.Application` real não cabia: o `style`
+ * do `ICanvas` do PixiJS é `ICanvasStyle`, que sequer TEM `filter` (ele existe para a `OffscreenCanvas`,
+ * onde não há CSS). Em produção o `view` é um `HTMLCanvasElement` de verdade e o campo existe — mas isso
+ * é uma coisa que só a raiz de composição sabe, e é lá que a conversão pertence.
+ *
+ * Mesma lição do `RenderizarEm` e do `CriarSprite`: pedir o VERBO cabe onde emprestar o objeto não cabe.
+ */
+export type AplicarFiltroCss = (css: string, alcance: AlcanceDoFiltro) => void;
+/**
+ * ONDE o filtro de acessibilidade cai — e a distinção é de PRODUTO, decidida pelo Dev em 2026-08-26.
+ *
+ * O quadro é metade canvas e metade DOM, e filtro de PIXI não alcança DOM. Até aqui o filtro caía SÓ na
+ * canvas, e os menus ficavam crus: a criança daltônica recebia o jogo corrigido e as palavras não (issue
+ * #82). Mas a correção não é o único modo, e nem todos devem alcançar o menu:
+ *
+ *   · MELHORIA (`normal`, `hc-direto*`, `fix-*`) — existe para a criança ENXERGAR MELHOR. Tem de alcançar
+ *     tudo que ela lê, menus inclusive. É o caso que estava quebrado.
+ *   · EMPATIA (`sim-*`, `lv-*`, `blind`) — existe para um adulto SENTIR como é. Fica no mundo. O menu é o
+ *     instrumento de SAIR da simulação, e uma cegueira que apagasse o menu de pausa trancaria a criança
+ *     dentro dela.
+ *
+ * O catálogo já sabia disto antes de a regra ser escrita: `VIZ_MODES` traz `sim: true` exatamente nos nove
+ * modos de empatia, e `simulatesDisability(chave)` é a pergunta pronta. Nada de taxonomia nova.
+ */
+export type AlcanceDoFiltro = 'mundo' | 'mundo-e-menus';
+/**
+ * LIGAR/DESLIGAR O ALTO CONTRASTE NO DOM — a metade que o filtro não alcança.
+ *
+ * O alto contraste não é filtro de CSS: é Renderização Direta, e repinta as TEXTURAS da canvas. O DOM não
+ * tem textura, então não há o que propagar — há que escrever o equivalente, e ele mora no `style.css` sob
+ * `#dom-layer.hc`. Aqui só se diz SE está ligado; o desenho é do CSS, com as razões medidas (issue #83).
+ */
+export type AplicarAltoContrasteNoDom = (ligado: boolean) => void;

package/dist-pkg/render/port.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/port — A PORTA DO RENDERIZADOR (Fase D do plano, ADR-0035).
+//
+// ========================= O QUE ESTE ARQUIVO RESOLVE =========================
+// O ADR-0035 apostou a reversibilidade da escolha do renderizador num adaptador: os módulos não importam
+// PixiJS, recebem por injeção o que vão desenhar. A aposta foi cumprida pela metade — os módulos de fato não
+// importam PixiJS, mas cada um descreveu a forma do que recebe POR CONTA PRÓPRIA, e as descrições
+// divergiram.
+//
+// `Gfx` estava escrito CINCO vezes, em `render/scene-city`, `render/scene-sky`, `render/title-scene`,
+// `render/weather` e `game/traffic`, com quatro definições diferentes: umas com `clear(): void`, outras com
+// `clear(): Gfx`; uma com `visible`, outra com `lineStyle`/`moveTo`/`lineTo`. `Layer` e `SpriteCtor`, duas
+// vezes cada. `RendererLike`, `ContainerLike` e `GraphicsLike`, duas cada.
+//
+// É o mesmo defeito do `DomQuery` (dezesseis cópias) e do `KeyScheme` (seis), agora no renderizador: uma
+// verdade escrita em muitos lugares diverge, e a divergência aparece na raiz de composição — que é o único
+// ponto onde o PixiJS de verdade encontra todas elas ao mesmo tempo.
+//
+// ========================= O QUE A PORTA NÃO É =========================
+// NÃO é a implementação de `Scene`/`Handle` que a D14 do `demos` especifica. O plano é explícito: "não fazer
+// agora a implementação completa de `Scene`; só a porta, e só onde os módulos já estão". Isto aqui descreve
+// o que o renderizador ATUAL oferece, numa declaração só, de um jeito que o PixiJS satisfaz sem adaptador.
+// A `Scene` nasce depois, e nasce podendo reusar estes nomes.
+//
+// ========================= POR QUE OS RETORNOS ENCADEIAM =========================
+// `beginFill(…): this` e não `: void`. O PixiJS encadeia (`g.beginFill(c).drawRect(…).endFill()`), e três
+// dos cinco módulos já dependiam disso. `this` em vez do nome do tipo é o que permite uma interface derivada
+// continuar encadeando sem redeclarar cada método — foi o que fez as cinco cópias divergirem.
+export {};