@the-inclusionist/engine 6.36.1

package/dist-pkg/render/set-cenario.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/set-cenario — TROCAR DE CENÁRIO: a única porta por onde o jogo muda de mundo visual.
+//
+// `setCenario(tema)` é chamado de quatro lugares muito diferentes — o splash (a criança escolhe antes de
+// começar), a demonstração automática (game/attract.ts sorteia), o console de testes (`window.__incl`) e o
+// BOOT (restauração do tema salvo em `incl_cenario`) — e sempre faz a mesma sequência de cinco passos. Esta
+// função é ORQUESTRAÇÃO: ela não desenha nada, não gera textura nenhuma e não sabe fórmula alguma. Ela decide
+// QUEM é avisado, EM QUE ORDEM, e o que fazer quando a resposta demora.
+//
+// ======================= POR QUE ISTO É UM MÓDULO, E NÃO FIAÇÃO NO game.js =======================
+// A tentação era deixá-la no monólito como cola: quase toda linha dela chama alguém de fora, e o contexto
+// injetado aqui é largo. Três coisas decidiram o contrário, e nenhuma delas é estética:
+//
+//  1. A GUARDA DE CORRIDA. Os tiles do tema (`tile_fill.png`/`tile_surface.png`) chegam quando chegarem, e
+//     entre o pedido e a chegada a pessoa pode ter trocado de cenário de novo — no splash isso é UM segundo
+//     de distância, e na demonstração automática o troca-troca é o comportamento normal. Por isso o `.then`
+//     abre com `if (getCenario() !== theme) return`: um tileset atrasado do Campo não pode repintar o chão da
+//     Floresta. É a espécie de defeito que aparece uma vez a cada cem trocas, some quando alguém vai olhar, e
+//     não tem como ser reproduzido de mão com confiança. Fora de um módulo, ele não tem como ter teste.
+//  2. A ORDEM DOS AVISOS. `setCenarioValue` (core/state.js — valor, persistência e evento) vem ANTES de
+//     qualquer trabalho de textura, e é isso que faz a guarda de corrida do item 1 funcionar: quem compara
+//     `getCenario() !== theme` está comparando com o valor que ESTA chamada gravou. Inverter as duas linhas
+//     não quebra nada visível e desarma a guarda inteira, silenciosamente.
+//  3. A VALIDAÇÃO. "Tema desconhecido → 'cidade'" é a rede que segura um `incl_cenario` de uma versão antiga
+//     (e o boot ainda migra a chave 'noite' → 'espaco', do lado do game.js). Ela virou
+//     `normalizarCenario` em render/cenario-data.ts, com o comportamento atual PREGADO por teste, defeito de
+//     herança de protótipo incluído — ver o cabeçalho de lá.
+//
+// ======================= OS CINCO PASSOS, E POR QUE NESTA ORDEM =======================
+//   1. valida o tema           → `normalizarCenario`
+//   2. grava e persiste        → `setCenarioValue` (core/state.js). ANTES do resto: arma as guardas de corrida.
+//   3. veste o FUNDO           → `aplicarTemaParallax` (render/parallax.ts) — síncrono nos temas v3, PNG na Cidade
+//   4. pede os TILES do tema   → assíncrono; ao chegar, refaz a textura do MUNDO e reaplica os modos de visão
+//   5. avisa quem depende      → vida ambiente da Cidade (síncrono) e alto contraste (síncrono)
+// O passo 5 roda ANTES de o passo 4 terminar, e isso é de propósito: a vida ambiente e o recolor não esperam
+// download nenhum. O passo 4 reaplica o recolor DE NOVO quando os tiles chegam, porque aí a textura do mundo
+// mudou — os dois `reapplyVizAll` não são duplicação, são dois momentos.
+//
+// ======================= O QUE FICOU DE FORA, E POR QUÊ =======================
+//  · O DADO dos temas → render/cenario-data.ts (folha, sem dependência). Importado aqui, não injetado: é um
+//    módulo sem efeito nenhum, então importá-lo não cria risco de ordem de boot.
+//  · A geometria e a pintura das 3 camadas de fundo → render/parallax.ts. Este módulo só chama
+//    `aplicarTemaParallax` e não sabe o que é `tilePosition`.
+//  · As FÓRMULAS de céu/morros/placeholder → render/scene-parallax.ts (desde o Estágio 4).
+//  · O BUILDER da textura do mundo (`worldCanvas`) → render/world-tex.ts. Aqui só entra o resultado.
+//  · A migração da chave antiga ('noite' → 'espaco') e o `try/catch` do boot FICAM no game.js: são política de
+//    persistência e rede de segurança do arranque, não regra de cenário.
+//  · `worldCanvasNormal`/`worldTexNormal` continuam sendo `let` do game.js — são lidos por
+//    render/high-contrast (por getter) e pelo render estático. Este módulo os ESCREVE por um único
+//    `setWorldTextures(canvas, textura)`, para que a dupla nunca fique meio trocada.
+//
+// ======================= ⚠️ A ARMADILHA DE BOOT DESTA REGIÃO =======================
+// O `setCenario` do boot é chamado MUITO cedo — logo depois de `initViewports`, e antes de metade do jogo
+// existir. O monólito o embrulha num `try/catch` que cai para 'cidade' EM SILÊNCIO, e é por isso que uma
+// dependência ausente aqui não vira erro: vira "o tema que a criança escolheu não voltou, e ninguém sabe por
+// quê". Todas as dependências que ainda não existem naquele instante entram por GETTER ou por CALLBACK, nunca
+// por valor, exatamente para que a montagem do ctx não toque em `const` em TDZ:
+//   · `isVizReady`/`reapplyVizAll` — `vizReady` só vira `true` lá no fim do boot; no arranque as duas voltas
+//     de `reapplyVizAll` são puladas, e quem pinta é o `else if (worldSprite)` do passo 4.
+//   · `getWorldSprite` — o sprite do mundo nasce DEPOIS deste ponto no game.js. Só é tocado dentro do `.then`,
+//     que é assíncrono, mas o getter garante que a montagem do ctx não o dereferencie.
+//   · `isVidaReady`/`applyCenarioVida` — `sceneCity` nasce centenas de linhas depois; `_vidaReady` é `false`
+//     no boot justamente para que esta chamada seja pulada, e o game.js chama `applyCenarioVida()` uma vez, à
+//     mão, quando a cena da cidade fica pronta.
+//   · `clearWorldTexCache` vem de render/high-contrast, que é um módulo de verdade e já existe no import.
+//
+// SEM I/O NO IMPORT, e agora sem I/O NENHUM: `carregarTilesDoTema` (a carga assíncrona dos PNG de tile, com a
+// guarda de corrida que ela exigia) foi APAGADA no item 17 — os tiles da Cidade viraram dados em
+// `render/city-tiles`. O corpo do módulo não pede nada, e a troca de cenário virou síncrona.
+// Ver docs/5-Refactoring/plano-modularizacao-mapa.md (D2-b).
+import { CENARIOS, normalizarCenario } from './cenario-data.js';
+export function createSetCenario(ctx) {
+    function setCenario(theme) {
+        const tema = normalizarCenario(theme);
+        ctx.setCenarioValue(tema); // ANTES do trabalho de textura: é o valor com que as guardas de corrida comparam
+        const T = CENARIOS[tema];
+        ctx.aplicarTemaParallax(tema, T); // as 3 camadas de fundo (render/parallax.ts)
+        // TILES do tema: SÍNCRONOS. v3: blocos Clarity SEM recolor (o `worldCanvas` cai no desenho da v3 com null).
+        //
+        // A GUARDA DE CORRIDA MORREU JUNTO COM A CORRIDA. Havia um `if (getCenario() !== tema) return` aqui, e ele
+        // estava certo enquanto os tiles chegavam por `Promise`: trocar de cenário durante o download deixava a
+        // resposta antiga pintar por cima da nova. Sem download não há "durante", e guarda contra corrida que não
+        // existe mais é código que só pode confundir quem o ler depois.
+        const tiles = ctx.getTiles(tema);
+        const cv = ctx.worldCanvas(tiles), t = ctx.tex(cv);
+        ctx.setWorldTextures(cv, t);
+        ctx.clearWorldTexCache();
+        if (ctx.isVizReady())
+            ctx.reapplyVizAll();
+        else {
+            const sprite = ctx.getWorldSprite(); // no boot o recolor ainda não existe: pinta o sprite direto
+            if (sprite)
+                sprite.texture = t;
+        }
+        // (o Cenário saiu do menu de pausa — a escolha é do J1 no splash, antes de começar)
+        if (ctx.isVidaReady())
+            ctx.applyCenarioVida(); // liga/desliga carros/deco da cidade e semeia o tema
+        if (ctx.isVizReady())
+            ctx.reapplyVizAll(); // reaplica o cenário recolorido (só após o init montar tudo)
+        // incl_cenario é persistido por setCenarioValue (core/state.js)
+    }
+    return { setCenario };
+}

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

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export declare function spriteToCanvas(art: string[]): HTMLCanvasElement;
+export declare function outlineCanvas(src: HTMLCanvasElement, thick: number): HTMLCanvasElement;

package/dist-pkg/render/sprite-fx.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/sprite-fx.ts — helpers de canvas p/ SPRITES/silhuetas, sobre render/canvas.ts. Módulo-folha (só makeCanvas):
+//  • spriteToCanvas: pinta arte ASCII 16×32 (1 char = 1 px) pela paleta unificada APP.
+//  • outlineCanvas: contorno ESCURO único atrás da arte (1º plano do alto contraste) — silhueta deslocada em anel
+//    + arte por cima (sem cortar vãos internos). APP / _silhouette / OUTLINE_DARK são privados. (Fase 2.21)
+import { makeCanvas } from './canvas.js';
+// Paleta UNIFICADA (E15) — luz de cima-esquerda, contorno escuro. H cabelo · S pele · D pele-sombra · K contorno/olho
+// · W branco · R camisa · T camisa-sombra · B calça · P calça-sombra.
+const APP = { H: '#403020', S: '#c08070', D: '#9a5f50', K: '#1a1420', W: '#e8eef0', R: '#3090d0', T: '#2566a0', B: '#303050', P: '#20203a' };
+export function spriteToCanvas(art) {
+    const cv = makeCanvas(16, 32), c = cv.getContext('2d');
+    for (let y = 0; y < 32; y++) {
+        const row = art[y];
+        if (!row)
+            continue;
+        for (let x = 0; x < 16; x++) {
+            const ch = row[x];
+            if (ch === '.' || !ch)
+                continue;
+            c.fillStyle = APP[ch] || '#f0f';
+            c.fillRect(x, y, 1, 1);
+        }
+    }
+    return cv;
+}
+const OUTLINE_DARK = '#0a0a08'; // contorno escuro (José refará o gráfico visando 3:1 depois)
+function _silhouette(src, color) { const cv = makeCanvas(src.width, src.height), c = cv.getContext('2d'); c.drawImage(src, 0, 0); c.globalCompositeOperation = 'source-in'; c.fillStyle = color; c.fillRect(0, 0, cv.width, cv.height); return cv; }
+// Contorno ESCURO único: preserva a arte (contorno ATRÁS, arte por cima → só aparece nas bordas externas, sem cortar vãos).
+export function outlineCanvas(src, thick) {
+    const cv = makeCanvas(src.width, src.height), c = cv.getContext('2d');
+    const dark = _silhouette(src, OUTLINE_DARK), r = thick >= 2 ? 2 : 1;
+    for (let dx = -r; dx <= r; dx++)
+        for (let dy = -r; dy <= r; dy++) {
+            if (!dx && !dy)
+                continue;
+            c.drawImage(dark, dx, dy);
+        } // anel escuro
+    c.drawImage(src, 0, 0);
+    return cv; // arte por cima → sem corte interno
+}

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

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { tex } from './canvas.js';
+type Tex = ReturnType<typeof tex>;
+/** Alto-contraste plumbing this module needs but does not own — game.js keeps the mutable source of truth
+ *  (world/coin/tree/parallax texture pipelines share the same DIRECT_CFG/directSpriteCanvas; `disp` also
+ *  serves quiz rendering outside textures). Call once at boot, before the first letterTexture/pupTexFor. */
+export interface TexturesCtx {
+    /**
+     * IDS DAS FORMAS a pré-desenhar. Eram importados de `game/activity-content` (as dez formas da atividade de
+     * soma e subtração) — uma aresta de importação da ENGINE para o JOGO por causa de UMA linha do `initTextures`.
+     *
+     * O ADR-0027 conta essas arestas porque elas decidem o que um pacote arrasta: um módulo de render que importa
+     * conteúdo de matemática não se empacota sem levar o currículo junto. E o custo escondido era maior que a
+     * aresta — esta era também a única razão de `render/viz-setters` arrastar `game/`, por transitividade.
+     *
+     * Só os IDS, e não a lista de formas: este módulo desenha por id (`shapeTexture(id)`) e nunca leu o nome em
+     * português. Pedir a estrutura inteira seria pedir mais do que se usa, que é como uma aresta volta.
+     */
+    shapes: readonly string[];
+    /**
+     * OS PODERES a pré-desenhar, com a arte pronta. Mesma razão de `shapes`, um passo adiante: além da lista,
+     * entra o CANVAS de cada um — porque o ícone de voo, o de ventosa e o da bengala de corrida são arte deste
+     * jogo, e não geometria que a engine saiba desenhar sozinha.
+     *
+     * Era `PUP_KINDS` cravado aqui + `import { powerupCanvas } from './props.js'`. A arte mudou de camada no
+     * item 19 (`game/props`), e esta era a única aresta que a mudança criaria — some por injeção, e não por
+     * mudança de endereço.
+     */
+    powerups: readonly {
+        readonly kind: string;
+        readonly canvas: HTMLCanvasElement;
+    }[];
+    disp: (s: string) => string;
+    directCfg: Record<string, {
+        off: number;
+        mul: number;
+        bgMul: number;
+    }>;
+    directSpriteCanvas: (src: HTMLCanvasElement, mode: string) => HTMLCanvasElement;
+}
+/** Vertex list for the polygon shapes (PURE — no canvas). null = drawn via an arc/ellipse/rect primitive instead. */
+export declare function shapePoints(id: string, cx: number, cy: number, r: number): [number, number][] | null;
+/** 16×16 icon for a soma/subtração shape id (cyan fill + dark outline). */
+export declare function shapeTexture(id: string): Tex;
+/** Cache keyed by shape id — filled by initTextures (the injected id list never changes at runtime). */
+export declare const SHAPE_TEX: Record<string, Tex>;
+/** 16×16 rounded-square tile with a single letter (uses the injected `disp`, which honors letterCase). */
+export declare function letterTexture(ch: string): Tex;
+/** Normal-mode cache — filled by initTextures. */
+export declare const PUP_TEX: Record<string, Tex>;
+/** Power-up texture for `mode` (normal or alto-contraste-direto). Cached per mode×kind. */
+export declare function pupTexFor(kind: string, mode: string): Tex;
+/** Drops the alto-contraste power-up cache — game.js's _rebakeDirect clears world/coin/pup/player caches
+ *  together whenever outline thickness or role colors change. Call it from there instead of touching a private. */
+export declare function resetPupTexCache(): void;
+/** Fills SHAPE_TEX/PUP_TEX (+ wires the alto-contraste deps). Call ONCE at boot, before the first rebuildCoins/
+ *  rebuildExtras — mirrors game.js's old eager `const SHAPE_TEX=...; SOMASUB_SHAPES.forEach(...)` / PUP_CANVAS
+ *  forEach, just deferred past import time so this module stays side-effect-free to import (node tests included). */
+export declare function initTextures(ctx: TexturesCtx): void;
+export declare const PIP_W = 24, PIP_H = 32;
+export declare const PIP_PAL: string[];
+export declare const PIP_IDLE: string[];
+export declare const PIP_WALK: string[][];
+/** Valid palette digit (7 = transparent background, skipped); robust to short/ragged rows. */
+export declare const isPix: (ch: string) => boolean;
+export declare function indexedToCanvas(rows: string[]): HTMLCanvasElement;
+export declare function silhouetteCanvasIdx(rows: string[]): HTMLCanvasElement;
+export declare const PLAYER_IDLE: string[];
+export declare const PLAYER_WALK: string[];
+export declare const PLAYER_CLIMB: string[];
+export declare const PLAYER_HURT: string[];
+/** Verbatim reproduction of game.js's old eager `const TEX={idle:tex(spriteToCanvas(PLAYER_IDLE)),...}` — never
+ *  auto-run (see header note above). Unused today; kept callable in case a future caller resurfaces. */
+export declare function buildLegacyPlayerTex(): Record<string, Tex>;
+export {};

package/dist-pkg/render/textures.js

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/textures — procedural texture generators for in-world GLYPHS: soma/subtração SHAPES, sílabas LETTERS,
+// and power-up ICONS (+ their alto-contraste variant). Verbatim from game.js (behavior-preserving). `disp`
+// (letterCase-aware) and the DIRECT_CFG/directSpriteCanvas alto-contraste plumbing are SHARED with other texture
+// pipelines (world/coin/tree/parallax) that stay in game.js — INJECTED via initTextures, never read from a
+// global. Caches are filled BY initTextures (not at import time) so importing this module stays I/O-free, same
+// discipline as render/sprites.ts (Fase 2.24). See docs/5-Refactoring/plano-modularizacao-mapa.md.
+import { makeCanvas, tex } from './canvas.js';
+import { spriteToCanvas } from './sprite-fx.js';
+let disp = (s) => String(s).toLowerCase(); // safe pre-init default (matches letterCase='lower')
+let directCfg = {};
+let directSpriteCanvas = (src) => src; // safe pre-init default (fg=0 → sem contorno)
+/* ===================== soma/subtração: formas ===================== */
+/** Vertex list for the polygon shapes (PURE — no canvas). null = drawn via an arc/ellipse/rect primitive instead. */
+export function shapePoints(id, cx, cy, r) {
+    switch (id) {
+        case 'triangulo': return [[cx, cy - r], [cx + r, cy + r], [cx - r, cy + r]];
+        case 'losango': return [[cx, cy - r], [cx + r, cy], [cx, cy + r], [cx - r, cy]];
+        case 'paralelogramo': return [[cx - r + 3, cy - r * 0.6], [cx + r, cy - r * 0.6], [cx + r - 3, cy + r * 0.6], [cx - r, cy + r * 0.6]];
+        case 'trapezio': return [[cx - r * 0.5, cy - r * 0.7], [cx + r * 0.5, cy - r * 0.7], [cx + r, cy + r * 0.7], [cx - r, cy + r * 0.7]];
+        case 'pentagono': return Array.from({ length: 5 }, (_, i) => { const a = -Math.PI / 2 + i * 2 * Math.PI / 5; return [cx + r * Math.cos(a), cy + r * Math.sin(a)]; });
+        case 'hexagono': return Array.from({ length: 6 }, (_, i) => { const a = i * 2 * Math.PI / 6; return [cx + r * Math.cos(a), cy + r * Math.sin(a)]; });
+        default: return null;
+    }
+}
+/** 16×16 icon for a soma/subtração shape id (cyan fill + dark outline). */
+export function shapeTexture(id) {
+    const cv = makeCanvas(16, 16), c = cv.getContext('2d');
+    c.fillStyle = '#7fdcff';
+    c.strokeStyle = '#04121a';
+    c.lineWidth = 1.5;
+    const cx = 8, cy = 8, r = 6;
+    c.beginPath();
+    const pts = shapePoints(id, cx, cy, r);
+    if (pts) {
+        pts.forEach(([x, y], i) => c[i ? 'lineTo' : 'moveTo'](x, y));
+        c.closePath();
+    }
+    else
+        switch (id) {
+            case 'circulo':
+                c.arc(cx, cy, r, 0, 7);
+                break;
+            case 'oval':
+                c.ellipse(cx, cy, r, r * 0.66, 0, 0, 7);
+                break;
+            case 'quadrado':
+                c.rect(cx - r, cy - r, 2 * r, 2 * r);
+                break;
+            case 'retangulo':
+                c.rect(cx - r, cy - r * 0.6, 2 * r, r * 1.2);
+                break;
+            default: c.arc(cx, cy, r, 0, 7);
+        }
+    c.fill();
+    c.stroke();
+    return tex(cv);
+}
+/** Cache keyed by shape id — filled by initTextures (the injected id list never changes at runtime). */
+export const SHAPE_TEX = {};
+/* ===================== sílabas: letra ===================== */
+/** 16×16 rounded-square tile with a single letter (uses the injected `disp`, which honors letterCase). */
+export function letterTexture(ch) {
+    const cv = makeCanvas(16, 16), c = cv.getContext('2d');
+    c.fillStyle = '#ffd23f';
+    c.strokeStyle = '#1a1400';
+    c.lineWidth = 1.5;
+    c.beginPath();
+    if (c.roundRect)
+        c.roundRect(2, 2, 12, 12, 3);
+    else
+        c.rect(2, 2, 12, 12);
+    c.fill();
+    c.stroke();
+    c.fillStyle = '#1a1400';
+    c.font = 'bold 11px system-ui,sans-serif';
+    c.textAlign = 'center';
+    c.textBaseline = 'middle';
+    c.fillText(disp(ch), 8, 9);
+    return tex(cv);
+}
+/* ===================== power-ups: ícone (+ alto contraste) ===================== */
+//
+// A LISTA E A ARTE ENTRAM JUNTAS, e nenhuma das duas mora aqui (item 19). Era
+//     const PUP_KINDS = ['superjump', 'ultrajump', 'turbo', 'fly', 'wallcling', 'key', 'runcane'] as const;
+// mais `import { powerupCanvas } from './props.js'` — os sete poderes DESTE jogo e o desenho deles, dentro de
+// um módulo de render. É o mesmo defeito que `SHAPE_TEX` tinha e pelo qual `shapes` já entra por ctx: um
+// segundo jogo herdava sete ícones que não são dele e não tinha como não herdar.
+//
+// A diferença em relação a `shapes` vale nota: das formas, a engine recebe só os IDS e DESENHA (`shapeTexture`
+// é geometria — polígono, arco, retângulo — e serve a qualquer jogo). Dos power-ups ela recebe o CANVAS
+// PRONTO, porque uma ventosa, uma asa e uma bengala de corrida não são geometria: são arte, e arte é do jogo.
+const PUP_CANVAS = {};
+/** Normal-mode cache — filled by initTextures. */
+export const PUP_TEX = {};
+const _pupTexHC = {}; // {mode:{kind:tex}} — outlined alto-contraste variant
+/** Power-up texture for `mode` (normal or alto-contraste-direto). Cached per mode×kind. */
+export function pupTexFor(kind, mode) {
+    const hc = (_pupTexHC[mode] = _pupTexHC[mode] || {});
+    if (directCfg[mode]) {
+        if (!hc[kind])
+            hc[kind] = tex(directSpriteCanvas(PUP_CANVAS[kind], mode));
+        return hc[kind];
+    }
+    return PUP_TEX[kind];
+}
+/** Drops the alto-contraste power-up cache — game.js's _rebakeDirect clears world/coin/pup/player caches
+ *  together whenever outline thickness or role colors change. Call it from there instead of touching a private. */
+export function resetPupTexCache() {
+    for (const k in _pupTexHC)
+        delete _pupTexHC[k];
+}
+/** Fills SHAPE_TEX/PUP_TEX (+ wires the alto-contraste deps). Call ONCE at boot, before the first rebuildCoins/
+ *  rebuildExtras — mirrors game.js's old eager `const SHAPE_TEX=...; SOMASUB_SHAPES.forEach(...)` / PUP_CANVAS
+ *  forEach, just deferred past import time so this module stays side-effect-free to import (node tests included). */
+export function initTextures(ctx) {
+    disp = ctx.disp;
+    directCfg = ctx.directCfg;
+    directSpriteCanvas = ctx.directSpriteCanvas;
+    // LIMPA ANTES DE ENCHER. Enquanto as formas eram uma tabela FIXA importada, o cache só podia ser preenchido
+    // com o mesmo conteúdo e a diferença nunca apareceu — a função é chamada uma vez no boot. Com a lista
+    // INJETADA, "encher" tinha de deixar de significar "acrescentar": um segundo consumidor que inicializasse
+    // com as formas dele herdaria as nossas por cima, e o sintoma seria texturas de matemática num jogo que não
+    // tem matemática. Achado por um teste meu que afirmava a coisa errada e reprovou por isso.
+    for (const k of Object.keys(SHAPE_TEX))
+        delete SHAPE_TEX[k];
+    for (const id of ctx.shapes)
+        SHAPE_TEX[id] = shapeTexture(id);
+    // Mesma regra de limpar-antes-de-encher, pelo mesmo motivo do bloco acima: com a lista INJETADA, um segundo
+    // consumidor herdaria os poderes do primeiro por cima dos dele.
+    for (const k of Object.keys(PUP_CANVAS))
+        delete PUP_CANVAS[k];
+    for (const k of Object.keys(PUP_TEX))
+        delete PUP_TEX[k];
+    for (const p of ctx.powerups) {
+        PUP_CANVAS[p.kind] = p.canvas;
+        PUP_TEX[p.kind] = tex(p.canvas);
+    }
+}
+/* ===================== personagem: arte indexada (DEFERRED — não é código morto) =====================
+   FASE ATUAL: o jogo usa o PIXEL ART do PixelLab DIRETO (PNG nativo por quadro, render/sprites.ts — Fase 2.24).
+   A conversão deste personagem PROCEDURAL SEMÂNTICO/indexado (PIP_* abaixo) para a arte real do jogo "fica para
+   uma fase posterior" — comentário original de game.js, preservado aqui junto do código. ZERO chamadores hoje
+   (indexedToCanvas/silhouetteCanvasIdx não são invocadas por ninguém) — isso é trabalho ESTACIONADO de propósito,
+   não descartado. Ver docs/plano-arte-procedural.md. */
+export const PIP_W = 24, PIP_H = 32;
+export const PIP_PAL = ['#fcd7ab', '#e2aa86', '#9d6e62', '#5d2e22', '#472a1e', '#231c1c', '#1e1011', '#ff00ff', '#050809', '#010909'];
+export const PIP_IDLE = ['.....99444446666888.....', '...9444444444444448.....', '..924444444444444488....', '.9422442444444444439....', '.94424222442424495338...', '894444444424224495348...', '964664444444444915548...', '966664455444449101658...', '966666595689998000859...', '966659986991891000859...', '96656919911011009819....', '.99969111890000910119...', '990099198999008998819...', '902281890990001920929...', '91133119889000089099....', '.911111121500003409.....', '....991100003330009.....', '.....9821000000009......', '.....999821111198.......', '....92223999998429......', '...9022222399823229.....', '...99888822222283829....', '...91118892222281008....', '..9910000182224910089...', '.939211001844449300829..', '.9335821139999999229329.', '92355589985335229999939.', '939955955255552589..99..', '99..99952555958129......', '.....928899.9925489.....', '....991999..99554339....', '........................'];
+export const PIP_WALK = [
+    ['.....5566655...........', '...69344433365666......', '..533344434444336......', '.66224444444443466.....', '.54324444443444436.....', '6644442234424499346....', '66466433422323999444...', '66666344434434929445...', '66666448944939313935...', '66666659969856121945...', '66666889992191000945...', '6699681601102018929....', '6921981999900040026....', '9013891806960689926....', '903382190550009905.....', '.41231100220002306.....', '...592100000220006.....', '.....921100000006......', '.....56661111186.......', '....9622269999825......', '....9522222992525......', '....9968862222989......', '....8910062222929......', '.....810082222828......', '.....8100922229919.....', '.....9100996699914.....', '.....6200092559916.....', '.....5100094558988.....', '.....98112989689.......', '.....99889899119.......', '.....9558...95554......', '.....94444.............'],
+    ['.....6656655...........', '...68443344466665......', '..933444444444336......', '.98224444443344466.....', '.63424444443444435.....', '6544442244424499446....', '65366434422413695444...', '66566444434433618445...', '66666449944939213845...', '65656869969946122945...', '66666889992191000845...', '6588690911101019919....', '6900881998600080026....', '6012891509950499926....', '813362191860005805.....', '.51131100230002306.....', '...992100000220019.....', '.....921100000008......', '.....98951111189.......', '....8422299989924......', '...99411222992925......', '...89996992222999......', '...99910082222999......', '....981009222299.......', '.....81009222299.......', '.....89206198999.......', '......9200095499.......', '.....54622292499.......', '.....9556999659........', '.....999999.1198.......', '.....9349...64444......', '.....83455.............'],
+    ['.....6665656...........', '...96444444466665......', '..633444443444446......', '.55324444443444466.....', '.64424444333444435.....', '6644432244222369334....', '66466433422413699444...', '66666444444444929634...', '66566339944948813934...', '66666649969958121635...', '66666999992081000945...', '6699681922101016629....', '6921991989800081016....', '8002961505950499625....', '903361160550005506.....', '.50131110440003306.....', '...861100000330004.....', '.....961200000115......', '.....59891111189.......', '....9222266989926......', '...99222222992629......', '...99999992222999......', '...99920060022999......', '....99200610229........', '....992229222299.......', '.....992200999999......', '.....999200925999......', '.....55822292598.......', '....95599999969........', '....985589992289.......', '....9489...933223......', '....94469..............'],
+    ['.....5665566...........', '...98444443366666......', '..644444444444446......', '.96224444444444456.....', '.63313444443443436.....', '6543332243424469434....', '65466434422324499434...', '66666334444444939444...', '66665349944936312934...', '66666859958968122934...', '66666999992081000934...', '6686691611101009625....', '6922991989800060015....', '9013991508960699825....', '903381190650006506.....', '.51221110420002406.....', '...992200000220006.....', '.....931100000116......', '......9991111169.......', '.....522299899315......', '...89222222992225......', '...99888922222866......', '...99200942222929......', '....8100992222829......', '....810099222298166....', '....810899998899216....', '....810099925999216....', '....91006454459895.....', '....91216355928........', '.....99959992158.......', '......8689.943444......', '......94465............'],
+    ['.....6665655...........', '...56444444356665......', '..633333344443446......', '.86314444443444466.....', '.83423434433434445.....', '6633432243423399434....', '66456434422413899434...', '66566434434434828636...', '66566349944949213935...', '66666659969968111636...', '66666989982091000645...', '6699691922201018829....', '6811991999900081016....', '6002961505960499625....', '603361160560005506.....', '.51131100440002206.....', '...981100000230015.....', '.....961100000116......', '.....99991111189.......', '....9222296966825......', '...89222222992625......', '...99998922222996......', '...99200932222826......', '....62009922229138.....', '....810099222299169....', '....910699898899206....', '....810099525599219....', '....91008545559988.....', '....82119946529........', '.....99899991169.......', '......9555.833323......', '......95555............'],
+    ['.....6556656...........', '...56443344456566......', '..833444444443336......', '.56224444444443466.....', '.64324434343444435.....', '6644442244424499349....', '65466444422313695444...', '66566344444333619446...', '66666439944939223945...', '65665669969949121945...', '66666899982190000845...', '6699690911101019919....', '6911991996600081026....', '8113891609960499925....', '913381191980005606.....', '.51131100430002306.....', '...992100000220019.....', '.....821100000006......', '.....99961111196.......', '....9222269899924......', '...99222222992625......', '...99998922222995......', '...89100922222929......', '....92008822229215.....', '....920089222299139....', '....620099988999108....', '....610009523399129....', '....91000855249998.....', '....9922299989998......', '.....899999.81198......', '.....99559..943445.....', '.....995548............'],
+];
+/** Valid palette digit (7 = transparent background, skipped); robust to short/ragged rows. */
+export const isPix = (ch) => ch >= '0' && ch <= '9' && ch !== '7';
+export function indexedToCanvas(rows) {
+    const cv = makeCanvas(PIP_W, PIP_H), c = cv.getContext('2d');
+    for (let y = 0; y < PIP_H; y++) {
+        const r = rows[y];
+        if (!r)
+            continue;
+        for (let x = 0; x < PIP_W; x++) {
+            const ch = r[x];
+            if (!isPix(ch))
+                continue;
+            c.fillStyle = PIP_PAL[+ch];
+            c.fillRect(x, y, 1, 1);
+        }
+    }
+    return cv;
+}
+export function silhouetteCanvasIdx(rows) {
+    const cv = makeCanvas(PIP_W, PIP_H), c = cv.getContext('2d');
+    c.fillStyle = '#ffe600';
+    for (let y = 0; y < PIP_H; y++) {
+        const r = rows[y];
+        if (!r)
+            continue;
+        for (let x = 0; x < PIP_W; x++) {
+            if (isPix(r[x]))
+                c.fillRect(x, y, 1, 1);
+        }
+    }
+    return cv;
+}
+/* ===================== personagem: sprite indexado ANTIGO (achado, não é o mesmo caso do PIP_*) =====================
+   ACHADO — relatado, não consertado: TEX + PLAYER_IDLE/WALK/CLIMB/HURT abaixo já tinham ZERO chamadores no
+   game.js original (nenhuma referência além da própria definição de TEX) — diferente do bloco PIP_* acima, este
+   não carrega comentário de "fase posterior"; é vestígio pré-PixelLab, plenamente substituído pelo pipeline PNG
+   (render/sprites.ts: TEX_IDLE/TEX_WALK/TEX_CLIMB/…, Fase 2.24). Preservado verbatim (a tarefa pede não apagar);
+   TEX passou de constante eager para função sob demanda (buildLegacyPlayerTex) só para este módulo poder ser
+   importado sem `document` (disciplina de render/sprites.ts) — comportamento IDÊNTICO se algum dia for chamada. */
+export const PLAYER_IDLE = [
+    '................', '................', '.....HHHHHH.....', '....HHHHHHHH....',
+    '....HHSSSSHH....', '....HSSSSSSH....', '....HSKSSKSH....', '....HSSSSSSH....',
+    '....HSSWWSSH....', '....HSSSSSSH....', '.....HSSSSH.....', '......SSSS......',
+    '.....RRRRRR.....', '....RRRRRRRR....', '...RRRRRRRRRR...', '..SRRRRRRRRRRS..',
+    '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '...RRRRRRRRRR...',
+    '...RRRRRRRRRR...', '....RRRRRRRR....', '....BBBBBBBB....', '....BBBBBBBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '...KKKK..KKKK...', '...KKKK..KKKK...',
+];
+export const PLAYER_WALK = [
+    '................', '................', '.....HHHHHH.....', '....HHHHHHHH....',
+    '....HHSSSSHH....', '....HSSSSSSH....', '....HSKSSKSH....', '....HSSSSSSH....',
+    '....HSSWWSSH....', '....HSSSSSSH....', '.....HSSSSH.....', '......SSSS......',
+    '.....RRRRRR.....', '....RRRRRRRR....', '...RRRRRRRRRR...', '..SRRRRRRRRRRS..',
+    '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '...RRRRRRRRRR...',
+    '...RRRRRRRRRR...', '....RRRRRRRR....', '....BBBBBBBB....', '...BBBB..BBB....',
+    '..BBB....BBB....', '.BBB.....BBB....', 'KKKK.....KKKK...', '................',
+    '................', '................', '................', '................',
+];
+export const PLAYER_CLIMB = [
+    '................', '................', '.....HHHHHH.....', '....HHHHHHHH....',
+    '....HHHHHHHH....', '....HHHHHHHH....', '....HHHHHHHH....', '....HHHHHHHH....',
+    '....HHHHHHHH....', '....HHHHHHHH....', '.....HHHHHH.....', '......SSSS......',
+    '.....RRRRRR.....', '....RRRRRRRR....', '...RRRRRRRRRR...', '..SRRRRRRRRRRS..',
+    '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '..SRRRRRRRRRRS..', '...RRRRRRRRRR...',
+    '...RRRRRRRRRR...', '....RRRRRRRR....', '....BBBBBBBB....', '....BBBBBBBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '...KKKK..KKKK...', '...KKKK..KKKK...',
+];
+export const PLAYER_HURT = [
+    '................', '................', '.....HHHHHH.....', '....HHHHHHHH....',
+    '....HHSSSSHH....', '....HSSSSSSH....', '....HSWWWWSH....', '....HSWKKWSH....',
+    '....HSSSSSSH....', '....HSKKKKSH....', '.....HSSSSH.....', '......SSSS......',
+    '.....RRRRRR.....', '....RRRRRRRR....', '...RRRRRRRRRR...', '..SRRRRRRRRRRS..',
+    '..SRRRRRRRRR.S..', '..SRRRRRRRR.SS..', '...RRRRRRRRSS...', '...RRRRRRRRRR...',
+    '...RRRRRRRRRR...', '....RRRRRRRR....', '....BBBBBBBB....', '....BBBBBBBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....', '....BBB..BBB....',
+    '....BBB..BBB....', '....BBB..BBB....', '...KKKK..KKKK...', '...KKKK..KKKK...',
+];
+/** Verbatim reproduction of game.js's old eager `const TEX={idle:tex(spriteToCanvas(PLAYER_IDLE)),...}` — never
+ *  auto-run (see header note above). Unused today; kept callable in case a future caller resurfaces. */
+export function buildLegacyPlayerTex() {
+    return { idle: tex(spriteToCanvas(PLAYER_IDLE)), walk: tex(spriteToCanvas(PLAYER_WALK)), climb: tex(spriteToCanvas(PLAYER_CLIMB)), hurt: tex(spriteToCanvas(PLAYER_HURT)) };
+}

package/dist-pkg/render/title-scene.d.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Desenho } from './port.js';
+type Gfx = Desenho;
+export interface TitleSceneCtx {
+    /** The PIXI.Graphics layer this scene draws into (created + z-ordered in game.js). */
+    titleG: Gfx;
+    /** Live screen size (pass `app.screen` — width/height read fresh on every draw()). */
+    screen: {
+        width: number;
+        height: number;
+    };
+    /** Reduced-motion flags; only `.parallax` (reduced parallax/animation) matters here. */
+    getRm: () => {
+        parallax?: boolean;
+    };
+}
+export interface TitleScene {
+    /** Redraws the title backdrop for the current frame (clears `titleG` first). */
+    draw: () => void;
+}
+/** The 4 title-screen clouds' logical (unscaled) positions — v3 exact. */
+export interface TitleCloudDef {
+    cx: number;
+    cy: number;
+}
+export declare const TITLE_CLOUDS: readonly TitleCloudDef[];
+/** Horizon row (sky/grass split), in screen pixels. */
+export declare function titleHorizonY(H: number): number;
+/** Sky gradient color for scanline `y` (0-indexed from the top), given the horizon row count. RGB
+ * interpolation rgb(26→58, 26→76, 58→180) — exact v3 formula, packed as 0xRRGGBB. */
+export declare function titleSkyRowColor(y: number, horizon: number): number;
+/** This frame's cloud-drift offset: frozen at 0 under reduced motion, else sub-pixel accumulation of the
+ * per-draw frame counter (titleT/6) — corrects #21a (no more Math.floor → no "jumps 1px every 6 frames"). */
+export declare function titleCloudDriftOffset(titleT: number, reducedMotion: boolean): number;
+/** Screen-space x of one title cloud, with whole-body wrap (#21b: the 28px-wide cloud only re-enters once it
+ * has left the screen entirely). */
+export declare function titleCloudX(cx: number, k: number, off: number, W: number): number;
+export interface TitleGrassRow {
+    xStart: number;
+    xStep: number;
+    y: number;
+}
+/** The 3 staggered dotted-grass rows below the horizon — v3 exact. */
+export declare function titleGrassRows(k: number, horizon: number): TitleGrassRow[];
+export declare function createTitleScene(ctx: TitleSceneCtx): TitleScene;
+export {};

package/dist-pkg/render/title-scene.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/title-scene — title-screen BACKDROP: sky gradient + 4 drifting clouds + dotted grass, drawn into
+// `titleG` (v3.1.100 formulas, verbatim). Extracted from game.js's drawTitleScene(). The `titleG` PIXI.Graphics
+// layer is CREATED in game.js (`app.stage.addChildAt(titleG, app.stage.getChildIndex(weatherLayer))`) — its
+// z-order is soldered into the render-graph assembly there, same precedent as render/scene-sky.ts — and is
+// INJECTED here; only the drawing logic moves. cloudWrapX (sub-pixel, whole-body wrap, bug #21) is imported
+// straight from render/scene-sky.ts rather than re-implemented — it is already a leaf pure function there.
+import { LOGICAL_H } from '../core/constants.js';
+import { cloudWrapX } from './scene-sky.js';
+export const TITLE_CLOUDS = [
+    { cx: 40, cy: 30 }, { cx: 180, cy: 52 }, { cx: 265, cy: 22 }, { cx: 110, cy: 72 },
+];
+/** Horizon row (sky/grass split), in screen pixels. */
+export function titleHorizonY(H) {
+    return Math.round(H * 0.735);
+}
+/** Sky gradient color for scanline `y` (0-indexed from the top), given the horizon row count. RGB
+ * interpolation rgb(26→58, 26→76, 58→180) — exact v3 formula, packed as 0xRRGGBB. */
+export function titleSkyRowColor(y, horizon) {
+    const f = y / horizon;
+    const r = Math.round(26 + 32 * f), g = Math.round(26 + 50 * f), b = Math.round(58 + 122 * f);
+    return (r << 16) | (g << 8) | b;
+}
+/** This frame's cloud-drift offset: frozen at 0 under reduced motion, else sub-pixel accumulation of the
+ * per-draw frame counter (titleT/6) — corrects #21a (no more Math.floor → no "jumps 1px every 6 frames"). */
+export function titleCloudDriftOffset(titleT, reducedMotion) {
+    return reducedMotion ? 0 : titleT / 6;
+}
+/** Screen-space x of one title cloud, with whole-body wrap (#21b: the 28px-wide cloud only re-enters once it
+ * has left the screen entirely). */
+export function titleCloudX(cx, k, off, W) {
+    return cloudWrapX(cx * k - off, -28 * k, W + 28 * k);
+}
+/** The 3 staggered dotted-grass rows below the horizon — v3 exact. */
+export function titleGrassRows(k, horizon) {
+    return [
+        { xStart: 0, xStep: 3 * k, y: horizon },
+        { xStart: 1 * k, xStep: 4 * k, y: horizon + 3 * k },
+        { xStart: 2 * k, xStep: 5 * k, y: horizon + 6 * k },
+    ];
+}
+// ---------------------------------------------------------------------------------------------
+// PIXI-facing (thin) — requires the injected `titleG` layer
+// ---------------------------------------------------------------------------------------------
+export function createTitleScene(ctx) {
+    let titleT = 0; // frame counter (module-local state, mirrors the old closure-level `let titleT=0`)
+    function drawCloud(g, cx, cy, k, off, W) {
+        const x = titleCloudX(cx, k, off, W), s = k;
+        g.beginFill(0xf6f5f0)
+            .drawRect(x, cy * s, 28 * s, 6 * s)
+            .drawRect(x + 6 * s, (cy - 4) * s, 16 * s, 6 * s)
+            .drawRect(x + 2 * s, (cy + 6) * s, 24 * s, 4 * s)
+            .endFill();
+    }
+    function draw() {
+        const g = ctx.titleG;
+        g.clear();
+        const W = ctx.screen.width, H = ctx.screen.height, k = H / LOGICAL_H;
+        const HOR = titleHorizonY(H);
+        for (let y = 0; y < HOR; y++)
+            g.beginFill(titleSkyRowColor(y, HOR)).drawRect(0, y, W, 1).endFill();
+        titleT++;
+        const off = titleCloudDriftOffset(titleT, !!ctx.getRm().parallax);
+        for (const c of TITLE_CLOUDS)
+            drawCloud(g, c.cx, c.cy, k, off, W);
+        g.beginFill(0x3f7d20).drawRect(0, HOR, W, H - HOR).endFill();
+        g.beginFill(0x2d5b16);
+        for (const row of titleGrassRows(k, HOR)) {
+            for (let x = row.xStart; x < W; x += row.xStep)
+                g.drawRect(x, row.y, k, k);
+        }
+        g.endFill();
+    }
+    return { draw };
+}