@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+import { type AnimPlayer, type Frame, type PlayerTextures } from './player-anim.js';
+import type { RenderizarEm } from './port.js';
+/** O que este módulo toca de um `PIXI.Graphics`. Superconjunto do `DrawGraphics` de wheelchair-sprites. */
+export interface GraphicsLike {
+    clear(): unknown;
+    lineStyle(width: number, color?: number, alpha?: number): unknown;
+    beginFill(color: number, alpha?: number): unknown;
+    endFill(): unknown;
+    drawRect(x: number, y: number, w: number, h: number): unknown;
+    moveTo(x: number, y: number): unknown;
+    lineTo(x: number, y: number): unknown;
+    drawCircle(x: number, y: number, r: number): unknown;
+}
+/** O sprite do personagem — só posição, escala, alpha, visibilidade e textura. */
+export interface PlayerSprite {
+    x: number;
+    y: number;
+    alpha: number;
+    visible: boolean;
+    scale: {
+        set(x: number, y: number): void;
+    };
+    texture: unknown;
+}
+/** `camera` (PIXI.Container): daqui só a posição importa; ela é passada opaca ao renderer. */
+export interface CameraLike {
+    x: number;
+    y: number;
+}
+/** `app.renderer` — só a passada em render-texture do caminho multi-tela. */
+/** O sprite de um item declarado: o mínimo que o desenho toca. */
+export interface ItemSprite {
+    visible: boolean;
+    alpha: number;
+}
+/**
+ * Um power-up, do ponto de vista do DESENHO: um sprite, e nada mais.
+ *
+ * Era `extends Powerup`, importado de `game/powerups` — e esse `import type` era a ÚLTIMA aresta deste módulo
+ * para o jogo. Tipo apagado em tempo de compilação não entra no pacote, é verdade; mas ele obriga o arquivo a
+ * existir para o `tsc`, e obriga QUALQUER jogo a ter um power-up com aquela forma. O desenho toca `sprite` e
+ * mais nada — declarar só isso é a fatia mínima, a mesma regra de `core/entity`.
+ */
+interface PowerupWithSprite {
+    sprite?: {
+        visible: boolean;
+    } | null;
+    /**
+     * ⚠️ `kind` NÃO é lido aqui — e entrou mesmo assim, em 2026-08-26. O desenho ENTREGA o power-up ao
+     * `powerupVisibleTo` injetado, e é ele que lê o `kind` (a chave do portão é global; o resto é por
+     * jogador). Uma fatia mínima descreve o que o módulo CONSOME; em posição de parâmetro ela precisa
+     * descrever também o que ele ENTREGA, senão o callback real não cabe no ctx.
+     *
+     * É a quinta vez que esta forma aparece na árvore — `held` em audio-nav, `setSquash` na física, o
+     * menu de pausa no gamepad, o `navPause` — e a lição é a mesma: repassar é uma exigência, não uma
+     * leitura. A fatia continua mínima: dois campos, e nenhum tipo de `game/` importado.
+     */
+    kind: string;
+}
+/** O jogador, do ponto de vista do DESENHO (a animação usa `AnimPlayer`, do qual este é superconjunto). */
+/**
+ * O jogador visto pelo DESENHO: tudo o que a animação lê, mais posição, dano e apresentação.
+ * `sq`/`sqT` são o squash&stretch (amplitude e relógio, escritos por render/fx.setSquash); `easy` desenha a
+ * hitbox de coleta tolerante translúcida; `viz` é o modo de visão, que recolore por viewport.
+ */
+export type DrawPlayer = AnimPlayer & PlayerView<'i' | 'x' | 'y' | 'facing' | 'hurtTimer' | 'sq' | 'sqT' | 'easy' | 'viz' | 'sprite'>;
+/** Flags de Movimento Reduzido que o DESENHO consulta (o objeto `rm` do game.js tem mais chaves). */
+export interface ReducedMotion {
+    items?: boolean;
+}
+export interface DrawCtx {
+    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
+     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
+     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    getNumPlayers: () => number;
+    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
+     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    getPlayers: () => readonly unknown[];
+    camera: CameraLike;
+    renderizarEm: RenderizarEm;
+    caneLayer: GraphicsLike;
+    chairLayer: GraphicsLike;
+    /**
+     * CAIXA DE COLISÃO do jogador (largura × altura, em px). ENTRA em vez de ser importada de `game/player`, e
+     * isso não é política nova: `render/scene-city`, `render/scene-sky` e `platform/audio-nav` já a recebem
+     * assim — este módulo é que tinha ficado para trás, sozinho na camada de render importando do jogo.
+     *
+     * Ela aparece em três lugares e sempre pela mesma razão: `pl.y` é o PÉ do jogador, e meia caixa acima é o
+     * meio do corpo. É conhecimento de gênero — um top-down não ancora no pé, um quiz não tem corpo — e por
+     * isso pertence a quem tem corpo, não a quem desenha.
+     */
+    BOX: {
+        w: number;
+        h: number;
+    };
+    easyHitbox: GraphicsLike;
+    getVpTex(): unknown[];
+    isWheelchair(): boolean;
+    getFxClock(): number;
+    getPowerups(): readonly PowerupWithSprite[];
+    /**
+     * Os sprites dos ITENS declarados, na ordem em que o jogo os declara. Era `getCoinSprites()`, importado de
+     * `game/coin-spawning` — o desenho sabia que os itens são moedas.
+     */
+    getItemSprites(): readonly (ItemSprite | null | undefined)[];
+    /** O item `j` aparece para o jogador `i`? Era `!cn.taken` — a regra "coletado some" é do jogo. */
+    itemVisibleTo(j: number, playerIndex: number): boolean;
+    /**
+     * O item `j` é DESTE jogador? Era `cn.owner === i`, e o que o desenho faz com a resposta é esmaecer o item
+     * alheio (lote C). A ideia de POSSE é do jogo: um cooperativo responde `true` sempre e ninguém esmaece nada.
+     */
+    itemOwnedBy(j: number, playerIndex: number): boolean;
+    /**
+     * O power-up `pu` aparece para o jogador `i`? Era `!puTaken(pu, i)`, que trazia a regra "chave é global,
+     * o resto é por jogador" — uma frase sobre ESTE jogo, dentro do desenho.
+     */
+    powerupVisibleTo(pu: PowerupWithSprite, playerIndex: number): boolean;
+    rm: ReducedMotion;
+    WORLD_PX_W(): number;
+    WORLD_PX_H(): number;
+    caneOn(pl: DrawPlayer): boolean;
+    updateParallax(camX: number, camY: number): void;
+    drawElevators(): void;
+    markSeen(camX: number, camY: number): void;
+    redrawMinimapIfDirty(): void;
+    drawMinimapPlayer(worldX: number, worldY: number): void;
+    applySharedTextures(viz: string): void;
+    renderVpOverlay(i: number, viz: string): void;
+    playerVizTex(base: Frame, viz: string): unknown;
+    updateGameHud(): void;
+    playerTextures(): PlayerTextures;
+    held(pl: AnimPlayer, act: string): boolean;
+}
+export interface DrawApi {
+    /** Enquadra `pl`, aplica clamp+tremor+arredondamento e reposiciona o parallax.
+     *  `i` é o índice do jogador, e existe porque CADA JOGADOR TEM A SUA CÂMERA (ver `camDe`). */
+    placeCam(pl: DrawPlayer, i?: number): {
+        camX: number;
+        camY: number;
+    };
+    /** Desenha o quadro inteiro (era `draw()` no game.js). */
+    drawFrame(): void;
+    /** Escolhe o quadro de animação de `pl` e o aplica no sprite (era a cauda do `stepPlayer`). */
+    animatePlayer(pl: DrawPlayer, dt: number, dir: number): Frame;
+}
+export declare function initDraw(ctx: DrawCtx): DrawApi;
+export {};

package/dist-pkg/render/draw.js

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/draw.ts — O QUADRO. Onde a câmera para e o que é carimbado nela, uma vez por tick, depois que
+// `update()` já simulou o mundo. Extraído verbatim do game.js (`placeCam` + `draw`), mais a aplicação da
+// textura escolhida no sprite do jogador (a última linha do antigo `stepPlayer`).
+//
+// O QUE ENTROU
+//   · `placeCam(pl)`     — a câmera: enquadra o jogador, CLAMPA nas bordas do mundo, aplica o tremor de tela
+//                          (render/fx.shakeAmp) RE-CLAMPANDO (senão o tremor mostraria o vazio fora do mapa),
+//                          arredonda para pixel inteiro (o jogo é 320×180: meio pixel é tremulação) e
+//                          reposiciona o parallax. Devolve `{camX,camY}` PRÉ-arredondamento, que é o que o
+//                          minimapa usa para marcar o que já foi visto.
+//   · `drawFrame()`      — o quadro inteiro: transform dos sprites de jogador (squash&stretch com easing,
+//                          ancorado nos pés + piscada de dano), elevadores, partículas, bengala, cadeira de
+//                          rodas, hitbox tolerante do modo Fácil, e ENTÃO um dos DOIS caminhos de câmera
+//                          (tela única direta vs. multi-tela com uma render-texture por viewport), clima e HUD.
+//   · `animatePlayer()`  — chama a decisão de quadro (render/player-anim) e a aplica no sprite, passando pelo
+//                          recolor do modo de visão (`playerVizTex`).
+//
+// POR QUE A FRONTEIRA CAIU AQUI
+// `placeCam` e `draw` são inseparáveis: os DOIS caminhos de câmera do `draw` chamam `placeCam`, e o de
+// multi-tela depende do efeito colateral dela (mover `camera` antes de cada `renderer.render`). Separá-los
+// só produziria dois módulos que se importam. Já `animatePlayer` veio junto por outro motivo: a escolha do
+// quadro é pura e mora em render/player-anim.ts, mas APLICÁ-LA toca um `PIXI.Sprite` e o cache de recolor de
+// render/viewports — exatamente o tipo de coisa que este módulo já faz. Deixá-la no game.js manteria lá uma
+// linha órfã de render dentro de uma função de lógica de jogo.
+//
+// O QUE FICOU DE FORA, E POR QUÊ
+//   · `configureRender()` — a MONTAGEM do multi-tela (criar/destruir as render-textures, os sprites de
+//     viewport, as molduras e as bolinhas). É ciclo de vida do render-graph, não desenho de quadro; e vive
+//     colada ao `app.renderer.resize` e ao HUD. Fica no game.js para uma rodada própria.
+//   · `updateParallax()` — mexe nos `TilingSprite` criados no game.js e na decor de tela da v3; entra
+//     injetada.
+//   · `applySharedTextures()` (render/viz-setters) e `renderVpOverlay()` (render/viewports) — já são módulos;
+//     entram injetados porque suas instâncias são criadas no game.js.
+//   · A coleta de moedas, os power-ups e o portão que precediam a animação no `stepPlayer`: são LÓGICA DE
+//     JOGO (dependem de `coins`, `powerups`, `gate`, quiz e HUD) e continuam no game.js.
+//
+// INJEÇÃO — a regra e as EXCEÇÕES conscientes
+// Vale a regra da casa: o que o game.js REATRIBUI entra por getter; o que é estável entra por valor. Daí
+// `getVpTex` (o `let vpTex` que `configureRender` troca a cada mudança de nº de telas), `isWheelchair`
+// (`let wheelchair`), `getFxClock` (`let fxClock`, o relógio do cintilar) e `getPowerups` (`let powerups`)
+// serem GETTERS. `rm` (o objeto de Movimento Reduzido) é `const` e mutado IN PLACE → entra por valor.
+//
+// EXCEÇÃO (desvio consciente da instrução de recorte, que pedia getters também para `numPlayers`, `coins` e
+// `players`): esses três são `export let` de core/state.ts, ou seja, BINDINGS VIVOS de ES Modules. Importá-los
+// aqui já entrega o valor atual a cada leitura — `setNumPlayersValue`/`setCoins` são vistos na hora, sem
+// getter. Getter aqui não acrescentaria correção, só uma indireção a mais e um ctx maior; e o precedente do
+// repositório é este (game/coin-spawning.ts importa `coins`+`setCoins` direto; game/physics.ts importa
+// `players`). A regra do getter vale para o que mora no ESCOPO PRIVADO do game.js, que módulo nenhum enxerga.
+//
+// PIXI POR INTERFACE ESTRUTURAL, não por `import * as PIXI` — mesmo precedente de render/viewports.ts e
+// render/scene-sky.ts. `camera`, `renderer`, as camadas de `Graphics` e os sprites entram como interfaces com
+// só os membros que este módulo toca, para o arquivo carregar no project `node` do Vitest.
+// Pelo mesmo motivo, os colaboradores que importam PIXI (game/level-geometry.drawElevators,
+// render/minimap.*) entram por closure em vez de import: o game.js já tem as camadas deles em mão.
+// São importados direto só os módulos-folha node-safe: constantes, RNG, render/fx, render/wheelchair-sprites,
+// render/viz-modes, game/powerups, game/coin-spawning e core/state.
+//
+// ORDEM DE BOOT: `initDraw` não faz I/O nem toca o render-graph — só fecha closures. Pode ser chamada em
+// qualquer ponto do game.js posterior às camadas de `Graphics`, à `camera` e ao `app`; o resto do ctx é
+// função e resolve tarde. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (C1).
+import { LOGICAL_W, LOGICAL_H, EASY } from '../core/constants.js';
+// A corrente da DECORACAO, nao a do jogo: uma particula sorteada aqui nao pode mover o sorteio
+// das moedas. Ver o cabecalho de core/rng.ts (issue #107).
+import { rngDecoracao } from '../core/rng.js';
+const rnd = rngDecoracao.rnd;
+import { JUICE, easeOut3, shakeAmp, drawFx } from './fx.js';
+import { criarCamera } from './camera.js';
+import { drawCane, drawRunCane, drawChair } from './wheelchair-sprites.js';
+import { VIZ_BY_KEY } from './viz-modes.js';
+// (`game/powerups` e `game/coin-spawning` SAÍRAM daqui no item 19 — ver o bloco "ITENS DECLARADOS" abaixo.)
+import { drawWeather } from './weather.js';
+import { choosePlayerFrame } from './player-anim.js';
+export function initDraw(ctx) {
+    /* ===================== câmera ===================== */
+    // A CONTA saiu para `render/camera` (item 22: M1 extraiu as fórmulas, M2 as embrulhou num OBJETO). Aqui
+    // ficou o CARIMBO dela no render-graph: o sorteio do tremor, a escrita no container e o aviso ao parallax.
+    //
+    // ========================= UMA CÂMERA POR JOGADOR, E POR QUÊ AGORA =========================
+    // O caminho multi-tela chama `placeCam(PLS[i])` para CADA jogador dentro do MESMO quadro. Com uma câmera
+    // só, a posição do jogador i entraria como ponto de partida da do jogador i+1. Hoje isso não daria em
+    // nada — com zona-morta 0×0 a câmera é sem memória e `seguir` equivale a `enquadrar`, letra por letra
+    // (`tests/camera.node.test.js` prende essa igualdade). No dia em que a zona deixar de ser zero, daria: as
+    // câmeras dos jogadores se puxariam. É mais barato separar antes de o defeito existir do que depois, e
+    // separar agora não muda um pixel do que a criança vê.
+    //
+    // ⚠️ `pular()` AINDA NÃO TEM CHAMADOR. Ele é para nascer/renascer/trocar de fase, e enquanto a zona é zero
+    // não faz falta nenhuma — `seguir` já centra. Quando o Dev escolher uma zona, o nascimento sem `pular`
+    // aparece como um deslize da câmera até o jogador no primeiro quadro da fase. Fica anotado aqui, e não
+    // fingido de resolvido.
+    const cams = new Map();
+    const camDe = (i) => {
+        let c = cams.get(i);
+        if (!c) {
+            c = criarCamera({ w: ctx.WORLD_PX_W(), h: ctx.WORLD_PX_H() }, { w: LOGICAL_W, h: LOGICAL_H });
+            cams.set(i, c);
+        }
+        // O mundo muda de tamanho ao trocar de fase, e a câmera não é avisada por ninguém — reprender todo quadro
+        // custa duas contas e dispensa um evento que hoje não existe.
+        else
+            c.redimensionar({ w: ctx.WORLD_PX_W(), h: ctx.WORLD_PX_H() }, { w: LOGICAL_W, h: LOGICAL_H });
+        return c;
+    };
+    function placeCam(pl, i = 0) {
+        const c = camDe(i);
+        // `pl.y` é o PÉ do jogador; o meio do corpo fica meia caixa acima. Esta conversão é a única coisa de
+        // PLATAFORMA que havia no enquadramento, e agora ela mora aqui, onde o corpo existe — e não na câmera.
+        c.seguir(pl.x, pl.y - ctx.BOX.h / 2);
+        const k = shakeAmp(); // JUICE: tremor decai linearmente (render/fx)
+        // Os dois sorteios ficam DENTRO do `if`, como no original: com `k === 0` ele não chamava `rnd()`, e
+        // chamá-lo duas vezes por quadro deslocaria o fluxo do gerador COMPARTILHADO — mesma semente, outro jogo.
+        const cam = k > 0 ? c.quadro(k, rnd() * 2 - 1, rnd() * 2 - 1) : c.base;
+        ctx.camera.x = -Math.round(cam.camX);
+        ctx.camera.y = -Math.round(cam.camY);
+        ctx.updateParallax(cam.camX, cam.camY);
+        return cam;
+    }
+    /* ===================== animação do personagem ===================== */
+    function animatePlayer(pl, dt, dir) {
+        const tx = choosePlayerFrame(pl, {
+            dt, dir, wheelchair: ctx.isWheelchair(), held: ctx.held, rnd, tex: ctx.playerTextures(),
+        });
+        // solo/default; no MP o drawFrame troca a textura por viewport (applySharedTextures)
+        if (pl.sprite)
+            pl.sprite.texture = ctx.playerVizTex(tx, pl.viz);
+        return tx;
+    }
+    /* ===================== o quadro ===================== */
+    function drawFrame() {
+        const PLS = ctx.getPlayers();
+        for (const pl of PLS) {
+            if (!pl.sprite)
+                continue;
+            pl.sprite.x = pl.x;
+            pl.sprite.y = pl.y + 1;
+            // JUICE: squash&stretch com easing, ancorado nos pés
+            const q = (JUICE.squash && !pl.rmWalk && (pl.sqT || 0) > 0) ? (pl.sq || 0) * easeOut3((pl.sqT || 0) / 8) : 0;
+            // sem escala procedural de respiração (parecia mastigar) — respiração é por FRAMES
+            pl.sprite.scale.set((pl.facing < 0 ? -1 : 1) * (1 - q * 0.7), 1 + q);
+            pl.sprite.alpha = pl.hurtTimer > 0 ? (Math.floor(pl.hurtTimer / 4) % 2 ? 0.4 : 1) : 1;
+        }
+        ctx.drawElevators(); // cadeirante: plataforma do elevador sob os pés (largo/fino)
+        drawFx(); // JUICE: partículas (poeira/brilhos) na camada acima dos players
+        const shimOn = JUICE.shimmer && !ctx.rm.items; // JUICE: cintilar dos itens (respeita Movimento Reduzido)
+        const fxClock = ctx.getFxClock();
+        // modo cego: bengala SÓ andando (corrida = bengala de roda); nada parado/nadando/voando/escada
+        ctx.caneLayer.clear();
+        for (const pl of PLS) {
+            if (!ctx.caneOn(pl) || !pl.sprite || !pl.sprite.visible)
+                continue;
+            if (pl.running)
+                drawRunCane(ctx.caneLayer, pl);
+            else if (pl.walking)
+                drawCane(ctx.caneLayer, pl);
+        }
+        // cadeirante: desenha a cadeira nos jogadores (exceto nadando/voando)
+        ctx.chairLayer.clear();
+        if (ctx.isWheelchair()) {
+            for (const pl of PLS) {
+                if (pl.sprite && pl.sprite.visible && !pl.inWater && !pl.flying)
+                    drawChair(ctx.chairLayer, pl);
+            }
+        }
+        // Fácil: hitbox de coleta tolerante (retângulo translúcido) — só para os jogadores em Fácil
+        ctx.easyHitbox.clear();
+        const pad = EASY.pad;
+        for (const pl of PLS) {
+            if (!pl.easy)
+                continue;
+            ctx.easyHitbox.lineStyle(1, 0xffffff, 0.45);
+            ctx.easyHitbox.beginFill(0xffffff, 0.10);
+            ctx.easyHitbox.drawRect(pl.x - ctx.BOX.w / 2 - pad, pl.y - ctx.BOX.h - pad, ctx.BOX.w + 2 * pad, ctx.BOX.h + 2 * pad);
+            ctx.easyHitbox.endFill();
+        }
+        if (ctx.getNumPlayers() <= 1) {
+            // O CINTILAR fica: é juice da engine (render/fx), e vale para moeda, estrela ou peça de tabuleiro.
+            const itens = ctx.getItemSprites();
+            for (let j = 0; j < itens.length; j++) {
+                const s = itens[j];
+                if (s)
+                    s.alpha = shimOn ? 0.8 + 0.2 * Math.sin(fxClock * 0.12 + j * 1.7) : 1;
+            }
+            const { camX, camY } = placeCam(PLS[0]);
+            ctx.markSeen(camX, camY);
+            ctx.redrawMinimapIfDirty();
+            ctx.drawMinimapPlayer(PLS[0].x, PLS[0].y - ctx.BOX.h / 2);
+        }
+        else {
+            // Otimização: se TODOS estão no mesmo modo (caso comum), troca as texturas UMA vez; senão, por viewport.
+            const v0 = PLS[0].viz, allSame = PLS.every((p) => p.viz === v0);
+            const anyOverlay = PLS.some((p) => { const m = VIZ_BY_KEY[p.viz]; return !!m && m.kind === 'lowvision'; });
+            if (allSame)
+                ctx.applySharedTextures(v0);
+            for (let i = 0, n = ctx.getNumPlayers(); i < n; i++) {
+                const viz = PLS[i].viz;
+                if (!allSame)
+                    ctx.applySharedTextures(viz); // só troca por viewport quando os modos diferem
+                const itens2 = ctx.getItemSprites();
+                for (let j = 0; j < itens2.length; j++) {
+                    const s = itens2[j];
+                    if (!s)
+                        continue;
+                    s.visible = ctx.itemVisibleTo(j, i);
+                    // Lote C: item alheio esmaecido — quem é "alheio" é o jogo que diz; JUICE: cintilar multiplicativo
+                    s.alpha = (ctx.itemOwnedBy(j, i) ? 1 : 0.4) * (shimOn ? 0.8 + 0.2 * Math.sin(fxClock * 0.12 + j * 1.7) : 1);
+                }
+                for (const pu of ctx.getPowerups()) {
+                    if (pu.sprite)
+                        pu.sprite.visible = ctx.powerupVisibleTo(pu, i);
+                }
+                placeCam(PLS[i], i);
+                ctx.renderizarEm(ctx.camera, ctx.getVpTex()[i], true); // LIMPA: cada quadro é um quadro, não um acúmulo
+                if (anyOverlay)
+                    ctx.renderVpOverlay(i, viz); // passada extra só se algum jogador está em baixa visão
+            }
+        }
+        drawWeather(); // chuva/clarão em tela-espaço, sobre tudo
+        ctx.updateGameHud(); // HUD por jogador (moedas + poder) em DOM sobreposto (alta definição)
+    }
+    return { placeCam, drawFrame, animatePlayer };
+}

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export interface Particle {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    life: number;
+    max: number;
+    color: number;
+    size: number;
+    g: number;
+}
+export interface JuiceFlags {
+    dust: boolean;
+    sparkle: boolean;
+    squash: boolean;
+    hitstop: boolean;
+    shake: boolean;
+    shimmer: boolean;
+}
+/** Juice toggles (persisted in localStorage; edited in the ?debug panel + Sensibilidade → Movimento). */
+export declare const JUICE: JuiceFlags;
+export declare function saveJuice(): void;
+/** Standard easing (squash recovery, particle fade). Shared → exported (game.js render reads it too). */
+export declare const easeOut3: (t: number) => number;
+/** Minimal PIXI.Graphics surface drawFx needs (kept structural so the module stays PIXI-free for node tests). */
+interface FxGraphics {
+    clear(): void;
+    beginFill(color: number, alpha?: number): unknown;
+    drawRect(x: number, y: number, w: number, h: number): unknown;
+    endFill(): unknown;
+}
+interface ReducedMotion {
+    particles?: boolean;
+    parallax?: boolean;
+}
+interface Squashable {
+    rmWalk?: boolean;
+    sq?: number;
+    sqT?: number;
+}
+export declare function initFx(deps: {
+    fxG: FxGraphics;
+    rm: ReducedMotion;
+    getPlayers: () => readonly unknown[];
+}): void;
+export declare function spawnParticle(x: number, y: number, vx: number, vy: number, life: number, color: number, size: number, grav?: number): void;
+export declare function puffDust(x: number, y: number, n: number): void;
+export declare function burstSparkle(x: number, y: number, color?: number, n?: number): void;
+export declare function addShake(mag: number, dur: number): void;
+export declare function addHitstop(t: number): void;
+export declare function setSquash(pl: Squashable, amt: number): void;
+/** Advance particles + decay shake/squash. (fxClock is stepped by game.js — see header.) */
+export declare function stepFx(dt: number): void;
+export declare function drawFx(): void;
+/** Decrement hit-stop and report whether the world is still frozen (game.js early-returns on true). */
+export declare function tickHitstop(dt: number): boolean;
+/** Current screen-shake amplitude (0 = none); the camera applies the random jitter. */
+export declare function shakeAmp(): number;
+export declare const getParticles: () => Particle[];
+export declare const getHitstopT: () => number;
+export declare const getShakeT: () => number;
+export {};

package/dist-pkg/render/fx.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/fx — Juice / micro-feedback (Estágio 4, Tier 2): particles (dust/sparkle), screen shake, hit-stop,
+// squash&stretch, + the JUICE toggles. Formulas are verbatim from game.js (behavior-preserving). The reduce-
+// motion flags (`rm`), the PIXI graphics layer (`fxG`) and the round's player list are INJECTED via initFx.
+// `fxClock` is NOT here — it is a general animation clock (coin shimmer reads it) and stays in game.js.
+// Shake/hit-stop state is read by the camera/update/__incl via getters. See docs/5-Refactoring/plano-modularizacao-mapa.md.
+// A corrente da DECORACAO, nao a do jogo: uma particula sorteada aqui nao pode mover o sorteio
+// das moedas. Ver o cabecalho de core/rng.ts (issue #107).
+import { rngDecoracao } from '../core/rng.js';
+const rnd = rngDecoracao.rnd;
+import * as store from '../platform/storage.js';
+/** Juice toggles (persisted in localStorage; edited in the ?debug panel + Sensibilidade → Movimento). */
+export const JUICE = (() => {
+    const d = { dust: true, sparkle: true, squash: true, hitstop: true, shake: true, shimmer: true };
+    const s = store.getJSON(store.KEYS.juice, null);
+    if (s && typeof s === 'object')
+        for (const k of Object.keys(d))
+            if (k in s)
+                d[k] = !!s[k];
+    return d;
+})();
+export function saveJuice() {
+    store.setJSON(store.KEYS.juice, JUICE);
+}
+/** Standard easing (squash recovery, particle fade). Shared → exported (game.js render reads it too). */
+export const easeOut3 = (t) => 1 - Math.pow(1 - t, 3);
+let particles = [];
+let hitstopT = 0, shakeT = 0, shakeDur = 1, shakeMag = 0;
+let fxG = null;
+let rm = {};
+// A LISTA DE JOGADORES entra por injeção desde 2026-08-26. Era `numPlayers`, um `let` de `core/state`
+// importado como binding vivo — e um `let` de módulo é compartilhado por qualquer segundo jogo que a
+// mesma página carregue (D13 do `demos`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
+// possui; o `let` que sobra guarda a função, não a lista.
+let getPlayers = () => [];
+export function initFx(deps) {
+    fxG = deps.fxG;
+    rm = deps.rm;
+    getPlayers = deps.getPlayers;
+}
+export function spawnParticle(x, y, vx, vy, life, color, size, grav) {
+    if (particles.length >= 160)
+        particles.shift();
+    particles.push({ x, y, vx, vy, life, max: life, color, size, g: grav || 0 });
+}
+export function puffDust(x, y, n) {
+    if (!JUICE.dust || rm.particles)
+        return;
+    for (let i = 0; i < n; i++)
+        spawnParticle(x + (rnd() - 0.5) * 8, y - 1 - rnd() * 2, (rnd() - 0.5) * 0.9, -0.2 - rnd() * 0.4, 14 + rnd() * 10, 0xcfc6b8, rnd() < 0.4 ? 2 : 1, 0.02);
+}
+export function burstSparkle(x, y, color, n) {
+    if (!JUICE.sparkle || rm.particles)
+        return;
+    const N = n || 8;
+    for (let i = 0; i < N; i++) {
+        const a = (i / N) * Math.PI * 2 + rnd() * 0.5, sp = 0.5 + rnd() * 0.9;
+        spawnParticle(x, y, Math.cos(a) * sp, Math.sin(a) * sp - 0.3, 18 + rnd() * 12, color || 0xffd23f, rnd() < 0.5 ? 2 : 1, 0.015);
+    }
+}
+export function addShake(mag, dur) {
+    if (!JUICE.shake || rm.parallax)
+        return;
+    shakeMag = Math.max(shakeMag, mag);
+    shakeDur = dur;
+    shakeT = Math.max(shakeT, dur);
+}
+export function addHitstop(t) {
+    if (!JUICE.hitstop)
+        return;
+    hitstopT = Math.max(hitstopT, t);
+}
+export function setSquash(pl, amt) {
+    if (!JUICE.squash || pl.rmWalk)
+        return;
+    pl.sq = Math.max(-0.28, Math.min(0.2, amt));
+    pl.sqT = 8;
+}
+/** Advance particles + decay shake/squash. (fxClock is stepped by game.js — see header.) */
+export function stepFx(dt) {
+    if (shakeT > 0)
+        shakeT = Math.max(0, shakeT - dt);
+    for (const pl of getPlayers())
+        if (pl.sqT && pl.sqT > 0)
+            pl.sqT = Math.max(0, pl.sqT - dt);
+    for (let i = particles.length - 1; i >= 0; i--) {
+        const p = particles[i];
+        p.life -= dt;
+        if (p.life <= 0) {
+            particles.splice(i, 1);
+            continue;
+        }
+        p.vy += p.g * dt;
+        p.x += p.vx * dt;
+        p.y += p.vy * dt;
+    }
+}
+export function drawFx() {
+    if (!fxG)
+        return;
+    fxG.clear();
+    for (const p of particles) {
+        const f = p.life / p.max;
+        fxG.beginFill(p.color, 0.9 * easeOut3(f));
+        fxG.drawRect(p.x - p.size / 2, p.y - p.size / 2, p.size, p.size);
+        fxG.endFill();
+    }
+}
+/** Decrement hit-stop and report whether the world is still frozen (game.js early-returns on true). */
+export function tickHitstop(dt) {
+    if (hitstopT > 0) {
+        hitstopT = Math.max(0, hitstopT - dt);
+        return true;
+    }
+    return false;
+}
+/** Current screen-shake amplitude (0 = none); the camera applies the random jitter. */
+export function shakeAmp() {
+    return shakeT > 0 && shakeMag > 0 ? shakeMag * (shakeT / shakeDur) : 0;
+}
+export const getParticles = () => particles;
+export const getHitstopT = () => hitstopT;
+export const getShakeT = () => shakeT;

package/dist-pkg/render/hc-role-data.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Papéis que `roleOf(tile)` sabe devolver — os que o repinte do alto contraste aplica direto no tile. */
+export type PaintableRole = 'hazard' | 'climb' | 'water';
+/** Todos os papéis customizáveis. `gate` não vem de `roleOf()`: é usado à parte pelo desenho do portão
+ *  trancado (game/level-geometry), mas o jogador escolhe a cor dele no mesmo painel. */
+export type HcRoleKey = PaintableRole | 'gate';
+/** Ordem canônica dos papéis — a ordem em que o painel desenha os seletores de cor. */
+export declare const HC_ROLE_KEYS: readonly HcRoleKey[];
+/**
+ * Cores padrão por papel (RGB 0-255). Color-blocking: perigo = laranja-quente, escalável/interativo
+ * (escada/trampolim) = ciano, água = azul, portão = magenta. A estrutura (pedra/parede) fica no cinza-azulado
+ * do nível e por isso não é um papel. Customizável e persistido — ver `HC_ROLE` em render/high-contrast.
+ */
+export declare const HC_ROLE_DEF: Record<HcRoleKey, [number, number, number]>;

package/dist-pkg/render/hc-role-data.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/hc-role-data — os PAPÉIS SEMÂNTICOS do color-blocking, num só lugar.
+//
+// Existiam duas listas dos mesmos quatro papéis: `RoleKey`/`ROLE_KEYS` em ui/settings-visual (que desenha um
+// seletor de cor por papel) e `PaintableRole`/`HcRoleKey` em render/high-contrast (que repinta os tiles). Nada
+// ligava as duas, e a falha era silenciosa: um quinto papel adicionado ao render ganharia cor e não ganharia
+// seletor, sem erro de tipo em lugar nenhum — o painel simplesmente não ofereceria como customizar.
+//
+// Este módulo é FOLHA de propósito: zero dependências. Ele é importado tanto pelo render quanto pela UI, e um
+// arquivo de dados sem dependência nenhuma pode ser importado dos dois lados sem arrastar o pipeline de
+// renderização para dentro de um painel de configuração (nem o contrário).
+//
+// O que NÃO mora aqui: os rótulos em pt-BR dos papéis, que são apresentação e ficam em ui/settings-visual.
+// Eles são digitados por `HcRoleKey`, então continuam obrigados a cobrir exatamente estes quatro papéis.
+/** Ordem canônica dos papéis — a ordem em que o painel desenha os seletores de cor. */
+export const HC_ROLE_KEYS = ['hazard', 'climb', 'water', 'gate'];
+/**
+ * Cores padrão por papel (RGB 0-255). Color-blocking: perigo = laranja-quente, escalável/interativo
+ * (escada/trampolim) = ciano, água = azul, portão = magenta. A estrutura (pedra/parede) fica no cinza-azulado
+ * do nível e por isso não é um papel. Customizável e persistido — ver `HC_ROLE` em render/high-contrast.
+ */
+export const HC_ROLE_DEF = {
+    hazard: [255, 110, 45], climb: [55, 225, 205], water: [70, 140, 255], gate: [194, 58, 212],
+};