@the-inclusionist/engine 6.36.1

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

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/scene-sky — céu de tela: deriva de nuvens (math pura + bug #21) + trilha viva da v3 (nuvens/pássaros do mundo,
+// estrelas/névoa, grama/minhocas/vagalumes/borboletas). Extraído do game.js (#43). As 6 CAMADAS (skyLayer/starsG/
+// skyDecoG/fogG/grassG/themeFxG) continuam sendo CRIADAS no game.js — a ordem-z delas está soldada na montagem do
+// render-graph (parallax/worldSprite/lifeLayer/carLayer) — e são INJETADAS aqui; movemos só a LÓGICA. Fórmulas copiadas
+// verbatim da v3.1.100. Injeção por closure. Ver docs/5-Refactoring/plano-modularizacao-mapa.md (#43).
+/**
+ * Posição horizontal de uma nuvem à deriva, com wrap SUB-PIXEL e pelo CORPO INTEIRO. Corrige #21:
+ * (a) NÃO arredonda → deriva suave mesmo a <1px/frame; (b) só reentra quando a nuvem inteira saiu.
+ * @param phase distância de deriva acumulada (float; cresce → direita, decresce → esquerda)
+ * @param enterAt x de (re)entrada — passe `-larguraDaNuvem` p/ reentrar TOTALMENTE fora da tela
+ * @param span período do wrap — passe `larguraDaTela + larguraDaNuvem` p/ só reentrar depois de sair inteira
+ */
+export function cloudWrapX(phase, enterAt, span) {
+    return ((phase % span) + span) % span + enterAt;
+}
+/** Largura e altura do cúmulo base, antes de `esc`. Quem mede cobertura precisa das duas. */
+export const NUVEM_W = 26, NUVEM_H = 13;
+/** Quantas fileiras a manta fechada tem. É o que a faz cobrir do topo ao horizonte em vez de só o topo. */
+const FILEIRAS = 3;
+/**
+ * Onde estão as `n` nuvens de tela neste instante.
+ *
+ * Os fatores 37, 13, 7 e 5 são PRIMOS COM 3 de propósito: a fileira é `i % 3`, e qualquer variação tirada de
+ * `i` com um fator múltiplo de 3 sairia CONSTANTE dentro de uma fileira — a fileira 0, que é a que se vê no
+ * tempo bom, teria todas as nuvens do mesmo tamanho, à mesma velocidade e na mesma altura. Já aconteceu.
+ *
+ * @param t relógio de efeitos (0 congela a deriva — movimento reduzido)
+ * @param vw largura do viewport
+ * @param n quantas nuvens no total (a fileira 0, ~n/3, é a que aparece no tempo bom)
+ * @param junta 0 = poucas e altas (o pôr do sol aparece) · 1 = as três fileiras cobrindo o céu inteiro
+ */
+export function nuvensDeTela(t, vw, n, junta) {
+    const j = Math.max(0, Math.min(1, junta)), nuvens = [];
+    for (let i = 0; i < n; i++) {
+        const sp = 0.05 + ((i * 7) % 4) * 0.021; // velocidades diferentes: elas se alcançam e se abrem
+        const esc = (1.15 + ((i * 37) % 5) * 0.18) * (1 + 0.6 * j); // crescem ao fechar até uma encostar na outra
+        const larg = NUVEM_W * esc;
+        const x = cloudWrapX(t * sp + (i * (vw + larg)) / Math.max(1, n), -larg, vw + larg);
+        const aberto = 4 + ((i * 37) % 26); // altura de repouso: a faixa alta do céu
+        const fechado = (i % FILEIRAS) * 27 + ((i * 13) % 7); // altura de manta: a fileira desta nuvem
+        // A fileira 0 é permanente; as outras entram entre 0,15 e 0,65 de aglomeração — antes da chuva, portanto.
+        const surge = i % FILEIRAS === 0 ? 1 : Math.max(0, Math.min(1, (j - 0.15) / 0.5));
+        nuvens.push({ x, y: (1 - j) * aberto + j * fechado, esc, alpha: (0.72 + 0.28 * j) * surge });
+    }
+    return nuvens;
+}
+/**
+ * Um cúmulo em retângulos: laje de base e três lóbulos de alturas diferentes. Retângulos e não arcos porque é
+ * o que o `Gfx` do PIXI oferece aqui e porque é o que combina com o resto — a nuvem é pixel art, não um
+ * desenho vetorial reduzido. `[x, y, w, h]` no espaço da nuvem base (NUVEM_W×NUVEM_H), multiplicado por `esc`.
+ */
+const CUMULO = [
+    [0, 8, 26, 4], [2, 5, 9, 3], [3, 3, 6, 2], [4, 2, 4, 1],
+    [9, 4, 9, 4], [11, 2, 6, 2], [12, 1, 4, 1],
+    [17, 5, 7, 3], [18, 3, 4, 2],
+];
+/** A sombra sob a base — uma linha só. Na Floresta ela é alaranjada: a luz baixa bate por baixo. */
+const CUMULO_SOMBRA = [1, 12, 24, 1];
+export function createSceneSky(ctx) {
+    const clouds = [];
+    let birds = [];
+    let _birdT = 500;
+    // seedClouds v3: 7 nuvens à deriva no céu do MUNDO (skyLayer)
+    for (let i = 0; i < 7; i++) {
+        const s = ctx.criarSprite(ctx.CLOUD_TEX[i % 2]);
+        s.alpha = 0.5 + ((i * 37) % 30) / 100;
+        s.x = (i * 173) % ctx.WORLD_PX_W;
+        s.y = 8 + ((i * 61) % Math.floor(ctx.WORLD_PX_H * 0.30));
+        s._v = 0.02 + ((i * 13) % 10) / 300;
+        ctx.skyLayer.addChild(s);
+        clouds.push(s);
+    }
+    function stepSky(dt) {
+        if (ctx.getRm().decor) {
+            if (birds.length) {
+                birds.forEach((b) => { ctx.skyLayer.removeChild(b.s); b.s.destroy(); });
+                birds = [];
+            }
+            return;
+        }
+        for (const c of clouds) {
+            c.x += (c._v || 0) * dt;
+            if (c.x > ctx.WORLD_PX_W + 50)
+                c.x = -50;
+        }
+        if (birds.length < 3 && ++_birdT >= 520) {
+            _birdT = ctx.randInt(0, 300);
+            const dir = ctx.rnd() < 0.5 ? 1 : -1;
+            const s = ctx.criarSprite(ctx.BIRD_TEX[0]);
+            s.scale.x = dir;
+            s.x = dir > 0 ? -10 : ctx.WORLD_PX_W + 10;
+            s.y = 12 + ctx.rnd() * ctx.WORLD_PX_H * 0.25;
+            ctx.skyLayer.addChild(s);
+            birds.push({ s, dir, f: 0, t: 0 });
+        }
+        for (let i = birds.length - 1; i >= 0; i--) {
+            const b = birds[i];
+            b.s.x += b.dir * 0.7 * dt;
+            b.t += dt;
+            if (b.t >= 8) {
+                b.t = 0;
+                b.f = 1 - b.f;
+                b.s.texture = ctx.BIRD_TEX[b.f];
+            }
+            if (b.s.x < -16 || b.s.x > ctx.WORLD_PX_W + 16) {
+                ctx.skyLayer.removeChild(b.s);
+                b.s.destroy();
+                birds.splice(i, 1);
+            }
+        }
+    }
+    function drawV3Cloud(g, x, y, col) {
+        g.beginFill(ctx.hexN(col[0])).drawRect(x, y + 6, 24, 6).drawRect(x + 2, y + 4, 8, 4).drawRect(x + 3, y + 2, 6, 2)
+            .drawRect(x + 8, y + 2, 12, 6).drawRect(x + 10, y, 8, 2).drawRect(x + 16, y + 4, 8, 4).endFill();
+        g.beginFill(ctx.hexN(col[1])).drawRect(x + 1, y + 11, 22, 1).endFill();
+    }
+    function drawCumulo(g, nv, col) {
+        const e = nv.esc, R = (r) => {
+            g.drawRect(Math.round(nv.x + r[0] * e), Math.round(nv.y + r[1] * e), Math.round(r[2] * e), Math.round(r[3] * e));
+        };
+        g.beginFill(ctx.hexN(col[0]), nv.alpha);
+        for (const r of CUMULO)
+            R(r);
+        g.endFill();
+        g.beginFill(ctx.hexN(col[1]), nv.alpha);
+        R(CUMULO_SOMBRA);
+        g.endFill();
+    }
+    function drawV3Grass(g, tx, ty, fl, t) {
+        const TILE = ctx.TILE, x = tx * TILE, y = ty * TILE, wind = ctx.getRm().decor ? 0 : Math.sin(t * 0.045 + tx * 0.6);
+        g.beginFill(ctx.hexN(fl.base)).drawRect(x, y, TILE, 2).endFill();
+        g.beginFill(ctx.hexN(fl.top)).drawRect(x, y, TILE, 1).endFill();
+        const seed = (tx * 1103515245 + 12345) >>> 0;
+        for (let i = 0; i < 6; i++) {
+            const bx = (seed >> (i * 4)) & 15, bh = 2 + ((seed >> (i * 4 + 4)) & 1);
+            g.beginFill(ctx.hexN((i & 1) ? fl.bDk : fl.bLt));
+            for (let h = 0; h < bh; h++) {
+                const dx = Math.round(wind * (h / Math.max(1, bh - 1)) * 1.5);
+                g.drawRect(x + bx + dx, y - 1 - h, 1, 1);
+            }
+            g.endFill();
+        }
+        if ((seed >> 9) % 7 === 0) {
+            const fx = x + 4 + (seed % 7), sh = 4, cy = y - sh - 2;
+            g.beginFill(ctx.hexN(fl.bDk));
+            let topDx = 0;
+            for (let h = 0; h < sh; h++) {
+                topDx = Math.round(wind * (h / sh) * 2.4);
+                g.drawRect(fx + topDx, y - 1 - h, 1, 1);
+            }
+            g.endFill();
+            const bxC = fx + topDx;
+            g.beginFill(ctx.hexN(fl.petals[(seed >>> 17) % fl.petals.length])).drawRect(bxC - 1, cy + 1, 3, 1).drawRect(bxC, cy, 1, 3).endFill(); // >>> (v3 usava >> e o canvas engolia o índice; PIXI lança)
+            g.beginFill(ctx.hexN(fl.center)).drawRect(bxC, cy + 1, 1, 1).endFill();
+        }
+    }
+    function stepV3Decor() {
+        const T = ctx.CENARIOS[ctx.getCenario()] || {};
+        ctx.starsG.clear();
+        ctx.skyDecoG.clear();
+        ctx.nuvemG.clear();
+        ctx.fogG.clear();
+        ctx.grassG.clear();
+        ctx.themeFxG.clear();
+        ctx.themeFxBackG.clear();
+        // A pergunta é "este tema tem decoração viva?", e ela se responde OLHANDO A DECORAÇÃO. Antes era
+        // `!T.v3`, que respondia "este tema não é a Cidade" — o mesmo resultado por acidente, enquanto a Cidade
+        // era o único tema sem céu vivo. Um tema de fundo raster COM borboletas quebrava aquilo; este não.
+        if (!T.decor?.length || ctx.DIRECT_CFG[ctx.getVizMode()])
+            return; // alto contraste dispensa decor
+        const t = ctx.getFxClock(), d = T.decor || [], vw = ctx.LOGICAL_W, vh = ctx.LOGICAL_H, reduzido = !!ctx.getRm().decor;
+        // TELA: estrelas (sparkles v3) — cintilam a ~0,3Hz
+        if (!reduzido && d.includes('sparkles')) {
+            const top = Math.max(1, Math.floor(vh * 0.7));
+            for (let i = 0; i < 22; i++) {
+                const a = 0.3 + 0.35 * Math.sin(t * 0.03 + i * 1.3);
+                if (a <= 0.05)
+                    continue;
+                ctx.starsG.beginFill(0xffffff, a).drawRect((i * 73) % vw, (i * 49) % top, 1, 1).endFill();
+            }
+        }
+        // TELA: nuvens. Dois caminhos, e a diferença é DADO, não gosto:
+        //  · tema com `nuvens: N` (hoje só a Floresta) — manta viva de N cúmulos que fecha e abre com a chuva;
+        //  · os outros três — as 3 lajes da v3, derivas 0.08/0.05/0.11, VERBATIM. Não passaram por aqui de graça:
+        //    o Dev pediu o céu novo para a Floresta, e mudar a aparência dos outros três de carona seria alargar
+        //    o pedido por conta própria. Quando ele quiser, é trocar um número na tabela de cenários.
+        if (d.includes('nuvens') && T.cloud && T.nuvens) {
+            const col = T.cloud, junta = reduzido ? 0 : ctx.getAglomeracao();
+            // `nuvemG` e não `skyDecoG`: a manta fica ATRÁS das bandas de morro (ver a nota no ctx).
+            for (const nv of nuvensDeTela(reduzido ? 0 : t, vw, T.nuvens, junta))
+                drawCumulo(ctx.nuvemG, nv, col);
+        }
+        else if (d.includes('nuvens') && T.cloud) {
+            const col = T.cloud, defs = [{ y: 6, sp: 0.08, off: 0 }, { y: 20, sp: 0.05, off: 130 }, { y: 12, sp: 0.11, off: 250 }];
+            for (const c0 of defs) {
+                const x = cloudWrapX((reduzido ? 0 : t) * c0.sp + c0.off, -44, vw + 64);
+                drawV3Cloud(ctx.skyDecoG, x, c0.y, col);
+            }
+        }
+        if (!reduzido && d.includes('passaros')) {
+            ctx.skyDecoG.beginFill(0x282837, 0.7);
+            for (let i = 0; i < 3; i++) {
+                const bx = ((t * (0.25 + i * 0.07) + i * 90) % (vw + 20)) - 10, by = 14 + i * 9 + Math.sin(t * 0.04 + i) * 2, f = Math.sin(t * 0.2 + i) > 0 ? 1 : 2;
+                const X = Math.round(bx), Y = Math.round(by);
+                ctx.skyDecoG.drawRect(X - 2, Y + f, 2, 1).drawRect(X + 1, Y + f, 2, 1).drawRect(X, Y, 1, 1);
+            }
+            ctx.skyDecoG.endFill();
+        }
+        // TELA: névoa do amanhecer (3 camadas onduladas) — v3 exato, na FRENTE
+        if (d.includes('nevoa')) {
+            const base = Math.floor(vh * 0.72);
+            const Ls = [{ y: base, drift: 0.30, amp: 3, op: 0.06, freq: 0.080 }, { y: base + 6, drift: 0.55, amp: 4, op: 0.08, freq: 0.060 }, { y: base + 13, drift: 0.85, amp: 5, op: 0.10, freq: 0.050 }];
+            for (const L of Ls) {
+                ctx.fogG.beginFill(0xdee2ec, L.op);
+                for (let x = 0; x < vw; x += 2) {
+                    const top = L.y + Math.round(L.amp * Math.sin((x + (reduzido ? 0 : t) * L.drift) * L.freq));
+                    ctx.fogG.drawRect(x, top, 2, vh - top);
+                }
+                ctx.fogG.endFill();
+            }
+        }
+        // MUNDO (culled por jogador, dedupe): grama em TODA superfície + minhocas/vagalumes/borboletas
+        const fl = ctx.THEME_FLORA[ctx.getCenario()], seen = new Set();
+        for (const pl of ctx.getPlayers()) {
+            if (pl.quit)
+                continue;
+            const camX = Math.max(0, Math.min(pl.x - vw / 2, ctx.WORLD_PX_W - vw)), camY = Math.max(0, Math.min((pl.y - ctx.BOX.h / 2) - vh / 2, ctx.WORLD_PX_H - vh));
+            // Margem de recorte = 3 tiles em TODAS as direções: cobre a flutuação da fauna (borboleta sobe ~34px ≈ 2 tiles,
+            // deriva ~19px) E reduz pop-in do decor na beirada ao mover a câmera → mais fluido (José). (#69)
+            const tx0 = Math.max(0, Math.floor(camX / ctx.TILE) - 3), tx1 = Math.min(ctx.WORLD_W - 1, Math.floor((camX + vw) / ctx.TILE) + 3);
+            const ty0 = Math.max(0, Math.floor(camY / ctx.TILE) - 3), ty1 = Math.min(ctx.WORLD_H - 1, Math.floor((camY + vh) / ctx.TILE) + 3);
+            for (let tx = tx0; tx <= tx1; tx++) {
+                for (let ty = ty0; ty <= ty1; ty++) {
+                    const st = ctx.tileAt(tx, ty); // flora/fauna SÓ em PEDRA(2)/parede(6) — nunca em trampolim(5), lava(9) ou escada(4). #69
+                    if (!((st === 2 || st === 6) && !ctx.solidAt(tx, ty - 1) && ctx.tileAt(tx, ty - 1) !== 3 && ctx.tileAt(tx, ty - 1) !== 9))
+                        continue;
+                    const k = tx + ',' + ty;
+                    if (seen.has('g' + k))
+                        continue;
+                    seen.add('g' + k);
+                    // densidade: só uma FRAÇÃO das superfícies recebe flora (getGrassDensity), escolhidas por hash+semente da fase.
+                    if (fl && ((tx * 668265263 ^ ty * 2246822519 ^ ctx.getDecorSeed()) >>> 0) % 1000 < ctx.getGrassDensity() * 1000)
+                        drawV3Grass(ctx.grassG, tx, ty, fl, t);
+                    // #69: fauna distribuída POR SUPERFÍCIE (hash de tx,ty), não "1 por coluna no topo" — aparece em todas as
+                    // alturas, inclusive perto do player em corredores baixos / junto à lava (antes ancorava só na superfície + alta).
+                    if (d.includes('minhocas') && ((tx * 668265263 ^ ty * 374761393) >>> 0) % 6 === 0 && !seen.has('w' + k)) {
+                        seen.add('w' + k); // ~1/6 das superfícies
+                        ctx.themeFxG.beginFill(0xc47b8a);
+                        const bx = tx * ctx.TILE + 5, by = ty * ctx.TILE + 4;
+                        for (let s2 = 0; s2 < 5; s2++)
+                            ctx.themeFxG.drawRect(bx + s2, by + Math.round(reduzido ? 0 : Math.sin(t * 0.15 + tx * 0.7 + s2 * 0.8)), 1, 1);
+                        ctx.themeFxG.endFill();
+                    }
+                    const bh = (tx * 374761393 ^ ty * 668265263) >>> 0; // hash por superfície (cor + lado + gate)
+                    if (!reduzido && d.includes('borboletas') && bh % 7 === 0 && !seen.has('b' + k)) {
+                        seen.add('b' + k); // ~1/7 das superfícies
+                        const cols = [0xff8c42, 0xffd166, 0xef476f, 0xfca5d4, 0xf4a261, 0xe9c46a];
+                        const groundY = ty * ctx.TILE, wx = tx * ctx.TILE + 8 + 14 * Math.sin(t * 0.015 + tx + ty) + 5 * Math.cos(t * 0.04 + tx);
+                        const rise = 8 + 26 * (0.5 + 0.5 * Math.sin(t * 0.012 + tx * 1.3 + ty)), wy = groundY - rise + 4 * Math.sin(t * 0.05 + tx);
+                        const flap = Math.abs(Math.sin(t * 0.4 + tx * 0.7 + ty)), w = 1 + Math.round(flap * 2), X = Math.round(wx), Y = Math.round(wy);
+                        const bfg = (bh & 1) ? ctx.themeFxG : ctx.themeFxBackG; // metade ATRÁS / metade À FRENTE do player — #69
+                        bfg.beginFill(cols[bh % cols.length]).drawRect(X - w, Y, w, 2).drawRect(X + 2, Y, w, 2).endFill();
+                        bfg.beginFill(0x3a2a1a).drawRect(X, Y, 2, 2).endFill();
+                    }
+                    // (sem break: grama em TODAS as superfícies expostas da coluna, não só a mais alta — senão some perto do player. #69)
+                }
+            }
+            if (!reduzido && d.includes('vagalumes')) {
+                const cell = 64; // drawFireflies v3: grade hash fixa no mundo, só no ar
+                const cx0 = Math.floor(camX / cell) - 1, cx1 = Math.floor((camX + vw) / cell) + 1, cy0 = Math.floor(camY / cell) - 1, cy1 = Math.floor((camY + vh) / cell) + 1;
+                for (let cyi = cy0; cyi <= cy1; cyi++)
+                    for (let cxi = cx0; cxi <= cx1; cxi++) {
+                        const h = ((cxi * 73856093) ^ (cyi * 19349663)) >>> 0;
+                        if (h % 3 !== 0)
+                            continue;
+                        const k = 'f' + cxi + ',' + cyi;
+                        if (seen.has(k))
+                            continue;
+                        seen.add(k);
+                        const ph = ((h >> 4) % 628) / 100;
+                        const wx = cxi * cell + 8 + (h % (cell - 16)) + 8 * Math.sin(t * 0.013 + ph), wy = cyi * cell + 8 + ((h >> 9) % (cell - 16)) + 6 * Math.cos(t * 0.017 + ph * 1.3);
+                        const a = 0.45 + 0.45 * Math.sin(t * 0.05 + ph);
+                        if (a <= 0.06)
+                            continue;
+                        if (ctx.solidAt(Math.floor(wx / ctx.TILE), Math.floor(wy / ctx.TILE)))
+                            continue;
+                        ctx.themeFxBackG.beginFill(0xfff096, a * 0.35).drawRect(wx - 1, wy - 1, 3, 3).endFill(); // vaga-lumes ao FUNDO (atrás do player) — #69
+                        ctx.themeFxBackG.beginFill(0xffffbe, a).drawRect(wx, wy, 1, 1).endFill();
+                    }
+            }
+        }
+    }
+    return { stepSky, stepV3Decor, getClouds: () => clouds, getBirds: () => birds };
+}

package/dist-pkg/render/screen-pipeline.d.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { CriarSprite, CriarDesenho, ComFiltro, DesenhoComCirculo } from './port.js';
+/** Retângulo em pixels lógicos. */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Onde uma tela fica e o que se desenha em volta dela. */
+export interface ViewportPlacement {
+    /** Canto superior esquerdo do sprite da tela, no canvas. */
+    x: number;
+    y: number;
+    /** Retângulo da moldura (meio pixel para dentro, 1px menor nos dois lados — ver o cabeçalho). */
+    frame: Rect;
+    /** Âncora da bolinha indicadora do modo de visão (canto superior DIREITO da tela, para dentro). */
+    dot: {
+        x: number;
+        y: number;
+    };
+}
+/** O plano completo de render para `n` jogadores. */
+export interface ScreenPlan {
+    /** `true` = caminho de TELA ÚNICA: a câmera vai direto no stage, sem render-texture nenhuma. */
+    single: boolean;
+    cols: number;
+    rows: number;
+    /** Tamanho a que o renderer é redimensionado. */
+    canvas: {
+        w: number;
+        h: number;
+    };
+    /** Uma entrada por tela — VAZIO no caminho de tela única, que não tem viewport. */
+    viewports: ViewportPlacement[];
+}
+/** Cor da moldura de tela (o mesmo cinza-azulado da borda do canvas em tela única). */
+export declare const FRAME_COLOR = 13489906;
+/** Opacidade da moldura. */
+export declare const FRAME_ALPHA = 0.95;
+/** Espessura da moldura, em pixels LÓGICOS (escala junto com o canvas). */
+export declare const FRAME_WIDTH = 1;
+/** Recuo da bolinha indicadora a partir da borda direita da tela. */
+export declare const DOT_INSET_X = 9;
+/** Recuo da bolinha indicadora a partir do topo da tela. */
+export declare const DOT_INSET_Y = 9;
+/**
+ * A geometria de render para `n` jogadores, sem tocar em nada.
+ *
+ * `n <= 1` devolve `single: true` e NENHUM viewport: em tela única a câmera é filha do stage e o PIXI desenha
+ * direto no canvas — não há render-texture, nem moldura, nem bolinha (o indicador de modo de visão de tela
+ * única é outro, no DOM).
+ *
+ * `w`/`h` são parâmetros com o pixel canônico (320×180, ADR-0010) por padrão — não para o jogo trocá-los, mas
+ * para a conta ser conferível com números pequenos no teste.
+ */
+export declare function planScreens(n: number, w?: number, h?: number): ScreenPlan;
+/** O que se toca de um `PIXI.BaseTexture`: só o modo de escala (NEAREST = pixel art sem borrar). */
+interface BaseTextureLike {
+    scaleMode: number;
+}
+/** O que se toca de uma `PIXI.RenderTexture`: o baseTexture e o descarte (`true` = destrói a base junto). */
+export interface RenderTextureLike {
+    baseTexture: BaseTextureLike;
+    destroy(destroyBase?: boolean): void;
+}
+/** `PIXI.RenderTexture` como FÁBRICA — é `RenderTexture.create({width,height})`, não um construtor. */
+export interface RenderTextureFactory {
+    create(opts: {
+        width: number;
+        height: number;
+    }): RenderTextureLike;
+}
+/** O mínimo de um objeto de cena posicionável e descartável. */
+export interface DisplayLike {
+    x: number;
+    y: number;
+    visible: boolean;
+    destroy(): void;
+}
+/** `PIXI.Sprite` — aqui ele só nasce de uma render-texture e é posicionado.
+ *  O `filters` NÃO é tocado aqui: quem põe filtro de GPU por tela é `render/viz-setters`, e é para lá que
+ *  estes sprites vão (`getVpSpr`). A INVERSÃO DA FATIA MÍNIMA de novo — em posição de entrega, a fatia que
+ *  vale é a de quem RECEBE, não a de quem lê. Ver o cabeçalho de `render/port`. */
+export type SpriteLike = DisplayLike & ComFiltro;
+/** `PIXI.Graphics` — a moldura desenha; as bolinhas só são posicionadas (quem as pinta é viz-setters).
+ *  E é por serem pintadas LÁ que a declaração inclui o desenho inteiro: as bolinhas saem daqui por
+ *  `getVpDots` e o `viz-setters` chama `clear`/`beginFill`/`drawCircle` nelas. */
+export interface GraphicsLike extends DisplayLike, DesenhoComCirculo {
+}
+/** `PIXI.Container` no papel de pai de cena. */
+export interface ContainerLike {
+    addChild(child: unknown): unknown;
+    addChildAt(child: unknown, index: number): unknown;
+    removeChild(child: unknown): unknown;
+}
+/** A câmera, vista daqui: só a sua PATERNIDADE importa (filha do stage ou órfã). */
+export interface CameraLike {
+    parent: ContainerLike | null;
+}
+/** `app.renderer` — daqui só se redimensiona o canvas. */
+export interface ResizableRenderer {
+    resize(w: number, h: number): void;
+}
+export interface ScreenPipelineCtx {
+    RenderTexture: RenderTextureFactory;
+    /** Fábricas, não construtores (Fase D): `new (texture: unknown)` não recebe o `PIXI.Sprite` real, cujo
+     *  construtor só aceita `Texture`. Ver `CriarSprite` no cabeçalho de `render/port`. */
+    criarSprite: CriarSprite<SpriteLike>;
+    criarDesenho: CriarDesenho<GraphicsLike>;
+    NEAREST: number;
+    stage: ContainerLike;
+    renderer: ResizableRenderer;
+    camera: CameraLike;
+    getNumPlayers: () => number;
+    getVpTex: () => RenderTextureLike[];
+    setVpTex: (a: RenderTextureLike[]) => void;
+    getVpSpr: () => SpriteLike[];
+    setVpSpr: (a: SpriteLike[]) => void;
+    getVpFrames: () => GraphicsLike | null;
+    setVpFrames: (g: GraphicsLike | null) => void;
+    getVpDots: () => GraphicsLike[];
+    setVpDots: (a: GraphicsLike[]) => void;
+    setMinimapVisible: (on: boolean) => void;
+    buildGameHud: () => void;
+    applyVpFilters: () => void;
+    updateVpDots: () => void;
+}
+export interface ScreenPipelineApi {
+    /** Remonta o pipeline de render para o nº de jogadores ATUAL. Idempotente: destrói o conjunto anterior. */
+    configureRender(): void;
+}
+export declare function initScreenPipeline(ctx: ScreenPipelineCtx): ScreenPipelineApi;
+export {};

package/dist-pkg/render/screen-pipeline.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/screen-pipeline — QUANTAS TELAS EXISTEM, ONDE ELAS FICAM, E O QUE CADA UMA GANHA DE OBJETO PIXI.
+//
+// Este módulo é o antigo `configureRender()` do main.js. Ele roda toda vez que o número de jogadores muda
+// (`setNumPlayers`) e no reinício da rodada (`restartGame`), e é a única função do jogo que troca a TOPOLOGIA
+// do render: de "uma câmera desenhada direto no stage" para "N render-textures, uma por jogador, cada uma
+// virando um sprite posicionado na grade" — e de volta.
+//
+// ======================= É ENGINE, E NÃO DESTE JOGO =======================
+// "N jogadores em telas SEPARADAS, sem split-screen" é o pilar 7 do ADR-0010: vale para os 35+ jogos da
+// coleção EdSP, não só para *The Inclusionist*. Um segundo jogo reusaria isto INTEIRO — nada aqui sabe o que
+// é uma moeda, um power-up, um portão ou uma área secreta. O que o módulo conhece é: um stage, um renderer,
+// uma câmera, e a conta de `core/screens.ts`. Por isso ele mora em `render/`, ao lado de `render/viewports.ts`,
+// e por isso todo o resto (o HUD, os filtros de a11y, as bolinhas) entra por INJEÇÃO, como callback — quem
+// troca o pipeline não precisa saber o que mais o jogo quer refazer quando o pipeline troca.
+//
+// ======================= POR QUE UM ARQUIVO IRMÃO, E NÃO DENTRO DE render/viewports.ts =======================
+// Os dois falam de "viewport", mas respondem a perguntas diferentes, e a diferença é justamente a fronteira:
+//   · `render/viewports.ts` é a FÁBRICA DE IMAGEM — dado um MODO de visão acessível, como o pixel sai
+//     (matriz de daltonismo, névoa de catarata, contorno do alto contraste). Ele CONSOME `vpTex` por getter e
+//     nunca o cria. É uma pergunta sobre COR e FILTRO.
+//   · aqui é a TOPOLOGIA — quantas render-textures existem, de que tamanho é o canvas, onde cada sprite fica,
+//     onde a moldura é traçada, onde a bolinha indicadora é ancorada. É uma pergunta sobre GEOMETRIA e CICLO
+//     DE VIDA (destruir o conjunto anterior antes de montar o novo).
+// Fundir os dois daria um módulo cujo `ctx` teria ~25 campos e cujo nome só poderia ser "coisas de viewport",
+// que é um tema, não uma responsabilidade — exatamente o argumento do cabeçalho de `input/touch-bindings.ts`.
+// Há ainda um motivo mecânico: `viewports.ts` é quem LÊ `vpTex` (`getVpTex()`); este módulo é quem o
+// REATRIBUI. Deixar leitor e escritor no mesmo arquivo apagaria a única pista de que aquele array troca de
+// identidade a cada mudança de nº de telas — e é essa troca que obriga metade dos getters do projeto.
+// O elo real entre os dois é estreito e explícito: `applyVpFilters()` e `updateVpDots()`, dois callbacks de
+// ré-aplicação chamados no fim do caminho multi-tela.
+//
+// ======================= A PARTE PURA: PLANEJAR ≠ CONSTRUIR =======================
+// O bloco original trançava a conta da grade com as chamadas do PIXI. Aqui a conta saiu inteira para
+// `planScreens(n)`, que devolve, sem tocar em nada: o tamanho do canvas, e para cada tela a sua posição, o
+// retângulo da moldura e a âncora da bolinha. `configureRender()` vira execução de um plano.
+// É `planScreens` que carrega as três regras que ninguém enxergava no meio dos `new PIXI.Sprite`:
+//   · a grade vem de `core/screens.ts` (`screenGrid`) — a MESMA fonte do layout, do HUD e do CRT. A cópia que
+//     vivia aqui era a quinta, e era a DIVERGENTE (`cols = n<=2 ? n : 2`, sem a guarda de `n<=1`);
+//   · com 3 telas, a terceira é CENTRALIZADA na linha de baixo — `x = (LOGICAL_W*cols - LOGICAL_W)/2`;
+//   · a moldura é traçada em meio pixel (`+0.5`) e 1px menor nos dois lados, senão a linha de 1px lógico sai
+//     borrada ou comida pela borda do canvas quando a escala inteira multiplica tudo.
+//
+// ======================= O QUE FICOU DE FORA =======================
+//  · `buildGameHud`, `applyVpFilters`, `updateVpDots` e `setMinimapVisible` são CALLBACKS. O HUD é DOM
+//    sobreposto (ui/hud.ts), os filtros são política de a11y (render/viz-setters.ts) e o minimapa é outro
+//    subsistema; este módulo só sabe QUANDO eles precisam rodar de novo, não COMO.
+//  · quem cria `camera` e solda o z-order dela continua sendo o main.js. Daqui só se move a câmera entre
+//    "filha do stage" (tela única) e "órfã, desenhada à mão nas render-textures" (multi-tela).
+//  · o LAÇO de render por viewport (quem chama `renderer.render(camera,{renderTexture:vpTex[i]})` a cada
+//    quadro) é de `render/draw.ts`. Aqui se monta a infraestrutura; lá ela é usada.
+//
+// ======================= ARMADILHAS DE ORDEM DE BOOT =======================
+//  · `applyVpFilters` e `updateVpDots` são `const` desestruturados de `initVizSetters`, ~300 linhas ABAIXO do
+//    ponto onde este init cabe. Por isso entram no `ctx` como SETAS PREGUIÇOSAS (`() => applyVpFilters()`):
+//    passá-los por valor derrubaria o boot na TDZ. Isso é seguro porque `configureRender` NUNCA é chamado
+//    durante o boot — só por `setNumPlayers`/`restartGame` (game/session.ts), que só rodam a partir de um
+//    clique ou do início de partida, muito depois do módulo inteiro ter avaliado.
+//  · `vpTex`/`vpSpr`/`vpFrames`/`vpDots` são `let` do main.js que ESTE módulo reatribui, e que outros três
+//    módulos leem por getter (`viewports`, `viz-setters`, `draw`). Por isso o `ctx` traz o par getter+setter
+//    de cada um, em vez de o módulo ser dono dos arrays: se ele fosse dono, o main.js teria de trocar os
+//    quatro getters que já distribuiu, e a religação deixaria de ser local.
+//  · SEM I/O no import: nada de `document`, nada de canvas no corpo. `planScreens` é aritmética pura e roda no
+//    project `node`; tudo que toca PIXI só acontece dentro de `configureRender()`.
+//
+// PIXI entra por INTERFACE ESTRUTURAL, e não por `import * as PIXI` — mesmo precedente de render/viewports,
+// render/scene-sky e game/traffic. Aqui o motivo é mais forte do que o de costume: este é o módulo que mais
+// mexe em tipos concretos do engine (`RenderTexture`, `Sprite`, `Graphics`, `SCALE_MODES`), e é exatamente
+// isso que o obrigaria a arrastar 445KB de PixiJS para dentro do project `node` do Vitest se importasse.
+import { LOGICAL_W, LOGICAL_H } from '../core/constants.js';
+import { screenGrid } from '../core/screens.js';
+/** Cor da moldura de tela (o mesmo cinza-azulado da borda do canvas em tela única). */
+export const FRAME_COLOR = 0xcdd6f2;
+/** Opacidade da moldura. */
+export const FRAME_ALPHA = 0.95;
+/** Espessura da moldura, em pixels LÓGICOS (escala junto com o canvas). */
+export const FRAME_WIDTH = 1;
+/** Recuo da bolinha indicadora a partir da borda direita da tela. */
+export const DOT_INSET_X = 9;
+/** Recuo da bolinha indicadora a partir do topo da tela. */
+export const DOT_INSET_Y = 9;
+/**
+ * A geometria de render para `n` jogadores, sem tocar em nada.
+ *
+ * `n <= 1` devolve `single: true` e NENHUM viewport: em tela única a câmera é filha do stage e o PIXI desenha
+ * direto no canvas — não há render-texture, nem moldura, nem bolinha (o indicador de modo de visão de tela
+ * única é outro, no DOM).
+ *
+ * `w`/`h` são parâmetros com o pixel canônico (320×180, ADR-0010) por padrão — não para o jogo trocá-los, mas
+ * para a conta ser conferível com números pequenos no teste.
+ */
+export function planScreens(n, w = LOGICAL_W, h = LOGICAL_H) {
+    const { cols, rows } = screenGrid(n); // fonte única: core/screens.ts (era a 5ª cópia, e a divergente)
+    if (n <= 1)
+        return { single: true, cols, rows, canvas: { w, h }, viewports: [] };
+    const viewports = [];
+    for (let i = 0; i < n; i++) {
+        let x = (i % cols) * w;
+        const y = Math.floor(i / cols) * h;
+        if (n === 3 && i === 2)
+            x = (w * cols - w) / 2; // 3 telas: a 3ª centralizada na linha de baixo
+        viewports.push({
+            x, y,
+            frame: { x: x + 0.5, y: y + 0.5, w: w - 1, h: h - 1 },
+            dot: { x: x + w - DOT_INSET_X, y: y + DOT_INSET_Y },
+        });
+    }
+    return { single: false, cols, rows, canvas: { w: w * cols, h: h * rows }, viewports };
+}
+export function initScreenPipeline(ctx) {
+    function configureRender() {
+        // 1) descarte do conjunto anterior — SEMPRE, inclusive ao voltar para tela única, senão as render-textures
+        //    da configuração passada ficariam na GPU sem ninguém para desenhá-las.
+        ctx.getVpSpr().forEach((s) => s.destroy());
+        ctx.setVpSpr([]);
+        ctx.getVpTex().forEach((t) => t.destroy(true));
+        ctx.setVpTex([]);
+        const frames = ctx.getVpFrames();
+        if (frames) {
+            frames.destroy();
+            ctx.setVpFrames(null);
+        }
+        ctx.getVpDots().forEach((g) => g.destroy());
+        ctx.setVpDots([]);
+        const plan = planScreens(ctx.getNumPlayers());
+        // 2) tela única: a câmera volta a ser filha do stage (no fundo de tudo) e o PIXI desenha direto no canvas.
+        if (plan.single) {
+            if (ctx.camera.parent !== ctx.stage)
+                ctx.stage.addChildAt(ctx.camera, 0);
+            ctx.setMinimapVisible(true);
+            ctx.renderer.resize(plan.canvas.w, plan.canvas.h);
+            ctx.buildGameHud();
+            return;
+        }
+        // 3) multi-tela: a câmera SAI da cena — passa a ser desenhada à mão, uma vez por viewport, dentro da
+        //    render-texture de cada jogador (o laço em si é de render/draw.ts).
+        if (ctx.camera.parent)
+            ctx.camera.parent.removeChild(ctx.camera);
+        ctx.setMinimapVisible(false); // minimapa é de tela única (não cabe replicado em 4 telas de 320×180)
+        ctx.renderer.resize(plan.canvas.w, plan.canvas.h);
+        const vpTex = [], vpSpr = [];
+        for (const vp of plan.viewports) {
+            const rt = ctx.RenderTexture.create({ width: LOGICAL_W, height: LOGICAL_H });
+            rt.baseTexture.scaleMode = ctx.NEAREST; // pixel art: ampliar sem interpolar
+            const s = ctx.criarSprite(rt);
+            s.x = vp.x;
+            s.y = vp.y;
+            ctx.stage.addChild(s);
+            vpTex.push(rt);
+            vpSpr.push(s);
+        }
+        ctx.setVpTex(vpTex);
+        ctx.setVpSpr(vpSpr);
+        // moldura: uma linha por tela, num único Graphics (separa e enquadra como a borda da tela única)
+        const vpFrames = ctx.criarDesenho();
+        for (const vp of plan.viewports) {
+            vpFrames.lineStyle(FRAME_WIDTH, FRAME_COLOR, FRAME_ALPHA);
+            vpFrames.drawRect(vp.frame.x, vp.frame.y, vp.frame.w, vp.frame.h);
+        }
+        ctx.stage.addChild(vpFrames);
+        ctx.setVpFrames(vpFrames);
+        // bolinhas indicadoras do modo de visão: ACIMA de tudo e FORA da render-texture, portanto fora do filtro
+        // do viewport — é por isso que elas continuam visíveis no modo cegueira (ver updateVpDots em viz-setters).
+        ctx.setVpDots(plan.viewports.map((vp) => {
+            const g = ctx.criarDesenho();
+            g.x = vp.dot.x;
+            g.y = vp.dot.y;
+            g.visible = false;
+            ctx.stage.addChild(g);
+            return g;
+        }));
+        ctx.buildGameHud();
+        ctx.applyVpFilters();
+        ctx.updateVpDots();
+    }
+    return { configureRender };
+}

package/dist-pkg/render/set-cenario.d.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type CenarioTema } from './cenario-data.js';
+import type { Tileset } from './world-tex.js';
+/** `HTMLImageElement`, reduzido ao que o carregamento usa. */
+/** O tileset de um tema: interior + topo. Corresponde ao `Tileset` de render/world-tex. */
+/**
+ * Os dois tiles do tema. `Tileset` vem de `render/world-tex`, que é o dono — ele os desenha, e por isso
+ * sabe que são `CanvasImageSource`. A versão que estava aqui dizia `unknown` nos dois campos: uma
+ * descrição que apenas SE PARECE com a real, que é o que o ADR-0039 proíbe. O `unknown` não protegia
+ * nada — só empurrava a conversão para quem recebesse.
+ */
+export type TilesDoTema = Tileset;
+/** `worldSprite` — só a troca de textura. */
+interface SpriteComTextura {
+    texture: unknown;
+}
+/**
+ * Baixa `tile_fill.png` + `tile_surface.png` do tema. Resolve com os dois, ou com `null` se QUALQUER um falhar.
+ *
+ * Verbatim do `loadTileImages` do monólito, `fail` inclusive: quando uma das imagens erra, o `res(null)` sai na
+ * hora e a outra, ao chegar, encontra `fail` ligado e não resolve por cima. A promessa nunca REJEITA — tema sem
+ * arte é um caminho normal (a Cidade não tem tileset próprio), não um erro, e uma rejeição aqui derrubaria a
+ * troca de cenário inteira. Nunca pendura: os dois lados de cada imagem estão cobertos.
+ */
+export interface SetCenarioCtx {
+    setCenarioValue: (theme: string) => void;
+    getCenario: () => string;
+    aplicarTemaParallax: (theme: string, T: CenarioTema) => void;
+    /**
+     * Os tiles do tema, SÍNCRONOS. Eram dois PNG baixados por `carregarTilesDoTema`; hoje a Cidade os desenha
+     * (render/city-tiles) e os outros temas devolvem `null`, que é o caminho dos blocos v3 — o mesmo `null` de
+     * antes, agora imediato em vez de prometido.
+     */
+    getTiles: (tema: string) => TilesDoTema | null;
+    /** Builder da canvas do nível. `HTMLCanvasElement` e não `unknown`: é o que o `render/world-tex`
+     *  devolve, e o `unknown` só adiava a conversão até o `main.ts`, onde ela virava erro (ADR-0039). */
+    worldCanvas: (tiles: TilesDoTema | null) => HTMLCanvasElement;
+    tex: (canvas: HTMLCanvasElement) => unknown;
+    clearWorldTexCache: () => void;
+    /** Escreve `worldCanvasNormal`/`worldTexNormal` (os dois `let` do composition root), sempre em par. A
+     *  TEXTURA segue `unknown` de propósito — é objeto do PixiJS, e este módulo roda no project `node`. */
+    setWorldTextures: (canvas: HTMLCanvasElement, textura: unknown) => void;
+    isVizReady: () => boolean;
+    reapplyVizAll: () => void;
+    getWorldSprite: () => SpriteComTextura | null | undefined;
+    isVidaReady: () => boolean;
+    applyCenarioVida: () => void;
+}
+export interface SetCenarioApi {
+    /** Troca o cenário. Valida, persiste, repinta o fundo, refaz o mundo e avisa quem depende. */
+    setCenario(theme: string): void;
+}
+export declare function createSetCenario(ctx: SetCenarioCtx): SetCenarioApi;
+export {};