@the-inclusionist/engine 6.36.1

package/dist-pkg/render/high-contrast.d.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type HcRoleKey, type PaintableRole } from './hc-role-data.js';
+export type { PaintableRole, HcRoleKey } from './hc-role-data.js';
+export { HC_ROLE_KEYS, HC_ROLE_DEF } from './hc-role-data.js';
+export declare const HC_ROLE: Record<HcRoleKey, [number, number, number]>;
+/** Persiste HC_ROLE (chamado por setRoleColor/resetRoleColors no game.js). Migrado de localStorage direto → store. */
+export declare function saveHcRole(): void;
+export interface DirectCfg {
+    off: number;
+    mul: number;
+    bgMul: number;
+}
+export declare const DIRECT_CFG: Record<string, DirectCfg>;
+export declare function dcfg(mode: string): DirectCfg;
+export declare function dimDesat(c: CanvasRenderingContext2D, w: number, h: number, mul: number, blue: number, off?: number): void;
+export interface HighContrastCtx {
+    W: number;
+    H: number;
+    outlineFg: () => number;
+    outlineBg: () => number;
+    getWorldCanvasNormal: () => HTMLCanvasElement;
+    getWorldTexNormal: () => unknown;
+    /**
+     * OS SPRITES QUE O JOGO QUER RECOLORIDOS, POR ID. A engine cacheia por `(id, modo)` e nunca sabe o que o id
+     * significa — pode ser uma moeda, uma sílaba, uma peça de tabuleiro.
+     *
+     * Era um par cravado, `coinCanvasNormal` + `coinTexNormal`, e o nome era a dívida: a API do cache de alto
+     * contraste tinha a forma de UM sprite de UM jogo. Um segundo jogo que quisesse recolorir a peça dele não
+     * tinha por onde — teria de chamar a peça de "moeda", ou de reimplementar o cache.
+     *
+     * Função e não valor porque o canvas de um sprite pode ser reescrito no boot (o mesmo motivo do
+     * `getWorldCanvasNormal`), e um valor lido uma vez congelaria o do primeiro instante.
+     */
+    sprites: () => Record<string, {
+        canvas: HTMLCanvasElement | null;
+        tex: unknown;
+    }>;
+    /**
+     * TILE → PAPEL SEMÂNTICO, e é o consumidor quem sabe. `null` = estrutura (sem repintura).
+     *
+     * Era uma tabela fixa AQUI DENTRO — `9` perigo, `4|5|10` escalável, `3` água — e o ADR-0027 a nomeia como o
+     * acoplamento nº 1 da base: quatro linhas das quais TODO o alto contraste dependia. Elas diziam, pela
+     * estrutura, que "perigo é o tile 9" era verdade da engine. É verdade DESTE MAPA. Um segundo jogo com outra
+     * numeração pintava o chão de laranja e a lava de cinza — sem erro, sem teste vermelho, para quem menos
+     * pode conferir isso olhando.
+     *
+     * A tabela do jogo de plataforma mora em `game/tile-roles`. Trocar de tabela é trocar de jogo, e é só isso.
+     */
+    roleOf: (t: number) => PaintableRole | null;
+}
+export declare function initHighContrast(c: HighContrastCtx): void;
+/** Mundo em alto contraste: base dessaturada/clareada + repintura por papel (com escada como caso especial:
+ *  trilhos/degraus, não faixa sólida) + contorno de 2º plano no perímetro externo (navegável × não-navegável). */
+export declare function worldToTextureDirect(srcCanvas: HTMLCanvasElement, mode: string): unknown;
+/** Superfície mínima de PIXI.Texture que directBgTexture/directSpriteTexture tocam (resource.source pode ser
+ *  canvas OU imagem — parallax de tema "cidade" carrega PNG via PIXI.Texture.from(img)). Estrutural (como o
+ *  FxGraphics de render/fx.ts) para não arrastar os tipos de união de Resource do PIXI aqui dentro. */
+interface DirectTexSource {
+    orig: {
+        width: number;
+        height: number;
+    };
+    /**
+     * O RECORTE do quadro dentro da base. Passou a existir aqui com o atlas (item 22): antes toda textura de
+     * personagem era uma tela própria e base e recorte coincidiam. Opcional porque `directBgTexture` recebe
+     * texturas que de fato ocupam a base inteira (parallax, árvore) e não precisa dele.
+     */
+    frame?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    baseTexture: {
+        valid: boolean;
+        resource?: {
+            source?: (HTMLCanvasElement | HTMLImageElement) | null;
+        } | null;
+        once(event: 'loaded', cb: () => void): void;
+    };
+}
+/** Fundo/decoração em alto contraste: só dessaturação/escurecimento (recua) — sem repintura por papel nem
+ *  contorno. Usada por game.js para árvores (treeTexFor) e parallax (parallaxTexFor). */
+export declare function directBgTexture(srcTex: DirectTexSource, mode: string): unknown;
+/** Sprite de 1º plano (player/moeda/power-up) em alto contraste: mantém a cor da arte + contorno ESCURO
+ *  (WCAG 2.4.7 — "salta" do fundo recuado). `mode` não é usado (mantido só p/ paridade de assinatura com as
+ *  outras 3 funções "direct*" — o dispatch por DIRECT_CFG[mode] já aconteceu no chamador). fg=0 → sem contorno. */
+export declare function directSpriteCanvas(srcCanvas: HTMLCanvasElement, mode: string): HTMLCanvasElement;
+/** Variante PIXI.Texture de directSpriteCanvas (player: a textura de origem já é uma PIXI.Texture, não um
+ *  canvas cru). `mode` idem — não usado, mantido por paridade de assinatura. */
+export declare function directSpriteTexture(srcTex: DirectTexSource, mode: string): unknown;
+/** Textura do MUNDO para `mode` (normal → a textura viva; hc-* → Renderização Direta, cacheada). */
+export declare function worldTexFor(mode: string): unknown;
+/**
+ * Textura do sprite `id` para `mode` (mesma lógica de `worldTexFor`, cache por `id|modo`).
+ *
+ * Fora dos modos de renderização direta devolve a textura normal declarada pelo jogo — e devolve `undefined`
+ * para um id que o jogo não declarou, em vez de lançar: um sprite ausente vira "sem textura" no desenho, que
+ * é degradação; lançar aqui derrubaria o quadro inteiro por causa de um item.
+ */
+export declare function spriteTexFor(id: string, mode: string): unknown;
+/** Invalida o cache de mundo (tema/cenário mudou → worldCanvasNormal é outro canvas). */
+export declare function clearWorldTexCache(): void;
+/**
+ * Invalida o cache de sprites (cor de papel mudou → `_rebakeDirect` no game.js). Sem argumento limpa TUDO;
+ * com um `id`, só as entradas daquele sprite — o que um jogo com muitos sprites vai querer, e o que um cache
+ * chaveado só por modo não conseguia oferecer.
+ */
+export declare function clearSpriteTexCache(id?: string): void;

package/dist-pkg/render/high-contrast.js

@@ -0,0 +1,254 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/high-contrast — Renderização Direta (Estágio 4, Tier 2): o motor de alto contraste de acessibilidade
+// (ADR-0011) — outline + color-blocking por papel + fundo recuado (dessaturado/escurecido), 3 níveis de
+// contraste (3:1/4,5:1/7:1). worldToTextureDirect/directBgTexture/directSprite{Canvas,Texture} + os caches
+// _worldTexHC/_coinTexHC (worldTexFor/coinTexFor) + a paleta HC_ROLE (persistida) vivem aqui. INJETADO via
+// initHighContrast: os limites do grid (W/H), os dois níveis de contorno (outlineFg/outlineBg — mutados por
+// setOutlineFg/setOutlineBg no game.js) e os canvases/texturas NORMAIS do mundo/moeda (mundo é `let` e muda de
+// cenário → getter; moeda nunca é reatribuída → valor direto). `_lastSharedViz` FICA no game.js: não é cache de
+// alto contraste, é o cache de "modo já aplicado" que TODO o pipeline de render estático (mundo/parallax/moedas/
+// power-ups/portão) usa para decidir quando reaplicar texturas por viewport — 7 subsistemas fora daqui escrevem
+// nele. `_pupTexHC`/`_playerDirect` (power-ups/player) também ficam no game.js: consomem directSpriteCanvas/
+// directSpriteTexture DAQUI mas não estão na lista de extração desta onda.
+// Ver docs/2-Architecture/adr/ADR-0011-visual-accessibility.yaml + docs/5-Refactoring/plano-modularizacao-mapa.md.
+import { makeCanvas, tex } from './canvas.js';
+import { outlineCanvas } from './sprite-fx.js';
+import { TILE } from '../core/constants.js';
+import { tileAt } from '../core/collision.js';
+import { HC_ROLE_DEF } from './hc-role-data.js';
+import * as store from '../platform/storage.js';
+export { HC_ROLE_KEYS, HC_ROLE_DEF } from './hc-role-data.js';
+export const HC_ROLE = (() => {
+    const d = JSON.parse(JSON.stringify(HC_ROLE_DEF));
+    const s = store.getJSON(store.KEYS.hcrole, null);
+    if (s && typeof s === 'object') {
+        for (const k of Object.keys(d)) {
+            const v = s[k];
+            if (Array.isArray(v) && v.length === 3)
+                d[k] = v.map((n) => Math.max(0, Math.min(255, n | 0)));
+        }
+    }
+    return d;
+})();
+/** Persiste HC_ROLE (chamado por setRoleColor/resetRoleColors no game.js). Migrado de localStorage direto → store. */
+export function saveHcRole() { store.setJSON(store.KEYS.hcrole, HC_ROLE); }
+// off/mul = mapa da plataforma (mais off = mais clara → mais contraste); bgMul = fundo (menor = mais escuro/
+// recuado). Contraste plataforma×fundo ≈ 3 / 4,5 / 7 (ver ADR-0011: 3:1 é o default, "7:1 fica feio").
+export const DIRECT_CFG = {
+    'hc-direto': { off: 55, mul: 0.5, bgMul: 0.30 },
+    'hc-direto-45': { off: 66, mul: 0.5, bgMul: 0.28 },
+    'hc-direto-7': { off: 100, mul: 0.48, bgMul: 0.13 },
+};
+export function dcfg(mode) { return DIRECT_CFG[mode] || DIRECT_CFG['hc-direto']; }
+/* ===================== dessaturação/escurecimento (fundo/estrutura) ===================== */
+export function dimDesat(c, w, h, mul, blue, off) {
+    off = off || 0;
+    const img = c.getImageData(0, 0, w, h), d = img.data;
+    for (let i = 0; i < d.length; i += 4) {
+        if (d[i + 3] < 8)
+            continue;
+        const l = 0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2], g = off + l * mul;
+        d[i] = Math.min(255, g) | 0;
+        d[i + 1] = Math.min(255, g * 1.02) | 0;
+        d[i + 2] = Math.min(255, g * blue) | 0;
+    }
+    c.putImageData(img, 0, 0);
+}
+let ctx = null;
+export function initHighContrast(c) { ctx = c; }
+function requireCtx() {
+    if (!ctx)
+        throw new Error('render/high-contrast: initHighContrast(ctx) ainda não foi chamado');
+    return ctx;
+}
+/* ===================== Renderização Direta: mundo + fundo + sprites de 1º plano ===================== */
+/** Mundo em alto contraste: base dessaturada/clareada + repintura por papel (com escada como caso especial:
+ *  trilhos/degraus, não faixa sólida) + contorno de 2º plano no perímetro externo (navegável × não-navegável). */
+export function worldToTextureDirect(srcCanvas, mode) {
+    const hc = requireCtx();
+    const cfg = dcfg(mode);
+    const cv = makeCanvas(srcCanvas.width, srcCanvas.height), c = cv.getContext('2d');
+    c.drawImage(srcCanvas, 0, 0);
+    dimDesat(c, cv.width, cv.height, cfg.mul, 1.22, cfg.off); // base: estrutura vira cinza-azulado (mais clara = mais contraste)
+    for (let y = 0; y < hc.H; y++)
+        for (let x = 0; x < hc.W; x++) {
+            const t = tileAt(x, y), role = hc.roleOf(t);
+            if (!role)
+                continue; // repinta tiles não-estruturais pela cor do papel
+            const X = x * TILE, Y = y * TILE;
+            // ⚠️ O QUE SOBRA DE PLATAFORMA AQUI. A escada é desenhada com trilhos e degraus porque uma faixa sólida
+            // não LÊ como escada — decisão de acessibilidade, que serviria a qualquer jogo com algo escalável. Mas a
+            // forma da pergunta injetada ("este tile se desenha como escada?" · "que pintor este papel usa?") ainda
+            // não tem evidência que a escolha, e foi um consumidor que mostrou, no menu-nav, que a forma importa mais
+            // que a existência da injeção. Declarado em vez de adivinhado. Ver game/tile-roles.
+            if (t === 4) { // ESCADA: preto + trilhos e degraus ciano → lê como escada (não faixa verde sólida)
+                c.fillStyle = '#0a0e14';
+                c.fillRect(X, Y, TILE, TILE);
+                c.fillStyle = 'rgb(' + HC_ROLE.climb.join(',') + ')';
+                c.fillRect(X + 1, Y, 2, TILE);
+                c.fillRect(X + TILE - 3, Y, 2, TILE); // trilhos laterais (cor do papel, customizável)
+                for (let ry = 2; ry < TILE - 1; ry += 5)
+                    c.fillRect(X + 1, Y + ry, TILE - 2, 2); // degraus
+                continue;
+            }
+            const rc = HC_ROLE[role], img = c.getImageData(X, Y, TILE, TILE), d = img.data, lo = role === 'hazard' ? 0.58 : 0.44;
+            for (let i = 0; i < d.length; i += 4) {
+                if (d[i + 3] < 8)
+                    continue;
+                const g = (0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2]) / 255, f = lo + (1 - lo) * g;
+                d[i] = Math.min(255, rc[0] * f) | 0;
+                d[i + 1] = Math.min(255, rc[1] * f) | 0;
+                d[i + 2] = Math.min(255, rc[2] * f) | 0;
+            }
+            c.putImageData(img, X, Y);
+        }
+    const th = hc.outlineBg(); // contorno de 2º plano: SÓ o perímetro externo (bordas voltadas ao ar) — não em cada bloco
+    if (th > 0) {
+        const air = (x, y) => { const t = tileAt(x, y); return t === 0 || t === 1; };
+        c.fillStyle = 'rgba(200,222,255,0.97)';
+        for (let y = 0; y < hc.H; y++)
+            for (let x = 0; x < hc.W; x++) {
+                const t = tileAt(x, y);
+                if (t === 0 || t === 1)
+                    continue;
+                const X = x * TILE, Y = y * TILE;
+                if (air(x, y - 1))
+                    c.fillRect(X, Y, TILE, th);
+                if (air(x, y + 1))
+                    c.fillRect(X, Y + TILE - th, TILE, th);
+                if (air(x - 1, y))
+                    c.fillRect(X, Y, th, TILE);
+                if (air(x + 1, y))
+                    c.fillRect(X + TILE - th, Y, th, TILE);
+            }
+    }
+    return tex(cv);
+}
+/** Fundo/decoração em alto contraste: só dessaturação/escurecimento (recua) — sem repintura por papel nem
+ *  contorno. Usada por game.js para árvores (treeTexFor) e parallax (parallaxTexFor). */
+export function directBgTexture(srcTex, mode) {
+    const cfg = dcfg(mode);
+    const cv = makeCanvas(Math.max(1, srcTex.orig.width), Math.max(1, srcTex.orig.height)), dst = tex(cv);
+    const paint = () => {
+        const s = srcTex.baseTexture.resource && srcTex.baseTexture.resource.source;
+        if (!s || !s.width)
+            return;
+        cv.width = s.width;
+        cv.height = s.height;
+        const c = cv.getContext('2d');
+        c.clearRect(0, 0, cv.width, cv.height);
+        c.drawImage(s, 0, 0);
+        dimDesat(c, cv.width, cv.height, cfg.bgMul, 1.2);
+        dst.update();
+    };
+    if (srcTex.baseTexture.valid)
+        paint();
+    else
+        srcTex.baseTexture.once('loaded', paint);
+    return dst;
+}
+/** Sprite de 1º plano (player/moeda/power-up) em alto contraste: mantém a cor da arte + contorno ESCURO
+ *  (WCAG 2.4.7 — "salta" do fundo recuado). `mode` não é usado (mantido só p/ paridade de assinatura com as
+ *  outras 3 funções "direct*" — o dispatch por DIRECT_CFG[mode] já aconteceu no chamador). fg=0 → sem contorno. */
+export function directSpriteCanvas(srcCanvas, mode) {
+    void mode;
+    const fg = requireCtx().outlineFg();
+    return fg > 0 ? outlineCanvas(srcCanvas, fg) : srcCanvas;
+}
+/** Variante PIXI.Texture de directSpriteCanvas (player: a textura de origem já é uma PIXI.Texture, não um
+ *  canvas cru). `mode` idem — não usado, mantido por paridade de assinatura. */
+export function directSpriteTexture(srcTex, mode) {
+    void mode;
+    const fg = requireCtx().outlineFg();
+    if (fg <= 0)
+        return srcTex;
+    const th = fg;
+    const cv = makeCanvas(Math.max(1, srcTex.orig.width), Math.max(1, srcTex.orig.height)), dst = tex(cv);
+    const paint = () => {
+        const s = srcTex.baseTexture.resource && srcTex.baseTexture.resource.source;
+        if (!s || !s.width)
+            return;
+        // ===================== O RECORTE VEM ANTES DO CONTORNO =====================
+        // Aqui morava o "kage bunshin". Esta função lia a BASE e ignorava o `frame`, e havia um comentário
+        // explicando por que isso era seguro: "só é chamada p/ texturas de player (sempre canvas-sourced)". A
+        // afirmação era verdadeira e VIROU FALSA — o item 22 empacotou os sprites num atlas de 256×207, e desde
+        // então só os quadros que passam pelo tapa-costuras (idle/andar/correr) viram tela própria. Pulo, escada,
+        // parede, teto, nado e voo são RECORTE dentro do atlas, e contornar a base deles desenhava o atlas
+        // inteiro: todos os quadros do personagem de uma vez, em grade.
+        //
+        // O tapa-costuras é assíncrono, e por isso o idle também aparecia: com alto contraste ligado cedo, o
+        // cache `_playerDirect` memoriza a versão baseada no atlas e a guarda para sempre.
+        const f = srcTex.frame;
+        const precisaRecortar = !!f && (f.x !== 0 || f.y !== 0 || f.width !== s.width || f.height !== s.height);
+        let fonte = s;
+        if (precisaRecortar && f) {
+            const rec = makeCanvas(Math.max(1, f.width), Math.max(1, f.height));
+            const rc = rec.getContext('2d');
+            rc.imageSmoothingEnabled = false; // pixel art: reamostrar aqui borraria o contorno que o modo promete
+            rc.drawImage(s, f.x, f.y, f.width, f.height, 0, 0, f.width, f.height);
+            fonte = rec;
+        }
+        // outlineCanvas só declara HTMLCanvasElement; o recorte já devolve canvas, e a base sem recorte é
+        // canvas-sourced pelos caminhos que restam. O cast preserva o runtime idêntico ao original.
+        const o = outlineCanvas(fonte, th);
+        cv.width = o.width;
+        cv.height = o.height;
+        const c = cv.getContext('2d');
+        c.clearRect(0, 0, cv.width, cv.height);
+        c.drawImage(o, 0, 0);
+        dst.update();
+    };
+    if (srcTex.baseTexture.valid)
+        paint();
+    else
+        srcTex.baseTexture.once('loaded', paint);
+    return dst;
+}
+/* ===================== caches preguiçosos (mundo/moeda) + seletor por modo ===================== */
+const _worldTexHC = {};
+/** Cache de sprite recolorido, chaveado por `id|modo`. Era `_coinTexHC[modo]` — um cache por jogo. */
+const _spriteTexHC = {};
+/** Textura do MUNDO para `mode` (normal → a textura viva; hc-* → Renderização Direta, cacheada). */
+export function worldTexFor(mode) {
+    const hc = requireCtx();
+    if (DIRECT_CFG[mode]) {
+        if (!_worldTexHC[mode])
+            _worldTexHC[mode] = worldToTextureDirect(hc.getWorldCanvasNormal(), mode);
+        return _worldTexHC[mode];
+    }
+    return hc.getWorldTexNormal();
+}
+/**
+ * Textura do sprite `id` para `mode` (mesma lógica de `worldTexFor`, cache por `id|modo`).
+ *
+ * Fora dos modos de renderização direta devolve a textura normal declarada pelo jogo — e devolve `undefined`
+ * para um id que o jogo não declarou, em vez de lançar: um sprite ausente vira "sem textura" no desenho, que
+ * é degradação; lançar aqui derrubaria o quadro inteiro por causa de um item.
+ */
+export function spriteTexFor(id, mode) {
+    const hc = requireCtx();
+    const src = hc.sprites()[id];
+    if (!src)
+        return undefined;
+    if (DIRECT_CFG[mode]) {
+        const chave = id + '|' + mode;
+        if (!_spriteTexHC[chave] && src.canvas)
+            _spriteTexHC[chave] = tex(directSpriteCanvas(src.canvas, mode));
+        return _spriteTexHC[chave] ?? src.tex;
+    }
+    return src.tex;
+}
+/** Invalida o cache de mundo (tema/cenário mudou → worldCanvasNormal é outro canvas). */
+export function clearWorldTexCache() { for (const k in _worldTexHC)
+    delete _worldTexHC[k]; }
+/**
+ * Invalida o cache de sprites (cor de papel mudou → `_rebakeDirect` no game.js). Sem argumento limpa TUDO;
+ * com um `id`, só as entradas daquele sprite — o que um jogo com muitos sprites vai querer, e o que um cache
+ * chaveado só por modo não conseguia oferecer.
+ */
+export function clearSpriteTexCache(id) {
+    for (const k in _spriteTexHC) {
+        if (id === undefined || k.startsWith(id + '|'))
+            delete _spriteTexHC[k];
+    }
+}

package/dist-pkg/render/lq-filter.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * 17-sample `feFuncR/G/B` table for tableValues, blending contrast-stretch (linear, α=1.3, μ=0.5) with an
+ * S-curve (quadratic) by `t`. NOT clamped — mirrors game.js's lqCurve verbatim (callers clamp `t` upstream).
+ */
+export declare function lqCurve(t: number): string;
+/**
+ * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped — mirrors game.js's lqName verbatim
+ * (t<=0 and t>=1-ish inputs fall through to the end labels naturally).
+ *
+ * Returns a key rather than resolved text for two reasons. This module is a render leaf and stays free of the
+ * i18n dependency; and its parameter is already called `t`, so importing i18n's `t` here would shadow it — a
+ * rename to dodge a name clash is a worse reason to change a signature than the boundary itself.
+ */
+export declare function lqName(t: number): string;
+/** Reads (or lazily creates) the shared `<filter id="lq-enh">` SVG node, appended once to `document.body`. */
+export declare function ensureLqFilter(): SVGFilterElement;
+/** CSS `filter` fragment for the current lqT ('' when off) — ensures the SVG node exists BEFORE returning the
+ * `url()` reference (a dangling reference would hide the canvas). Composed by callers with viz-mode filters. */
+export declare function lqFilter(): string;
+/** Current lqT (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
+export declare function getLqT(): number;
+export interface LqFilterCtx {
+    /**
+     * Recomposes the app's CSS filter after lqT changes. In game.js this is either a full `applyVizGlobal()`
+     * re-apply (single-player: also touches viz-mode texture caches, `_lastSharedViz`) or a direct
+     * `app.view.style.filter = ...` write composed with the active viz-mode filter (multiplayer). That
+     * composition — and the texture-cache invalidation it triggers elsewhere — belongs to other subsystems and
+     * stays in game.js; this module only owns lqT + the SVG filter node.
+     */
+    onChange: () => void;
+}
+/** Wires the injected recompose callback. Call once during game.js boot. */
+export declare function initLqFilter(ctx: LqFilterCtx): void;
+/** Sets lqT (clamped to 0..1), persists it, updates the live SVG table (if the filter is already on-screen),
+ * then calls the injected `onChange` to let game.js recompose the CSS filter. Mirrors game.js's setLq. */
+export declare function setLq(t: number): void;

package/dist-pkg/render/lq-filter.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/lq-filter.ts — Realce de contraste Linear→Quadrático (baixa visão, PESQUISA-ALTO-CONTRASTE §2.3).
+// Curva de tom POR PIXEL na tela inteira, composta via SVG feComponentTransfer (17 amostras, sRGB) no CSS
+// filter do canvas. `lqCurve`/`lqName` são puros (project node); `ensureLqFilter`/`setLq` são a casca fina que
+// cria o nó SVG e escreve no DOM. Recompor o CSS filter final (junto com os modos de cor) fica em game.js via
+// `onChange` injetado — não duplica _lastSharedViz/_rebakeDirect (outros subsistemas). Extraído verbatim.
+import * as store from '../platform/storage.js';
+const FILTER_ID = 'lq-enh';
+function clamp01(t) {
+    return Math.max(0, Math.min(1, t));
+}
+/**
+ * 17-sample `feFuncR/G/B` table for tableValues, blending contrast-stretch (linear, α=1.3, μ=0.5) with an
+ * S-curve (quadratic) by `t`. NOT clamped — mirrors game.js's lqCurve verbatim (callers clamp `t` upstream).
+ */
+export function lqCurve(t) {
+    const N = 17, a = 1.3, out = [];
+    for (let i = 0; i < N; i++) {
+        const x = i / (N - 1);
+        const lin = Math.min(1, Math.max(0, a * (x - 0.5) + 0.5));
+        const quad = x < 0.5 ? 2 * x * x : 1 - 2 * (1 - x) * (1 - x);
+        out.push(((1 - t) * lin + t * quad).toFixed(4));
+    }
+    return out.join(' ');
+}
+/**
+ * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped — mirrors game.js's lqName verbatim
+ * (t<=0 and t>=1-ish inputs fall through to the end labels naturally).
+ *
+ * Returns a key rather than resolved text for two reasons. This module is a render leaf and stays free of the
+ * i18n dependency; and its parameter is already called `t`, so importing i18n's `t` here would shadow it — a
+ * rename to dodge a name clash is a worse reason to change a signature than the boundary itself.
+ */
+export function lqName(t) {
+    return t <= 0 ? 'lq.off' : t < 0.34 ? 'lq.linear' : t < 0.67 ? 'lq.mixed' : 'lq.quadratic';
+}
+// ---------- Thin DOM shell ----------
+/** Current L→Q amount (0..1), persisted in platform/storage under `KEYS.lq` ('incl_lq'). Module-local state. */
+let lqT = clamp01(store.getNum(store.KEYS.lq, 0));
+/** Reads (or lazily creates) the shared `<filter id="lq-enh">` SVG node, appended once to `document.body`. */
+export function ensureLqFilter() {
+    const existing = document.getElementById(FILTER_ID);
+    if (existing)
+        return existing;
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('width', '0');
+    svg.setAttribute('height', '0');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.style.position = 'absolute';
+    const f = document.createElementNS(NS, 'filter');
+    f.id = FILTER_ID;
+    f.setAttribute('color-interpolation-filters', 'sRGB');
+    const ct = document.createElementNS(NS, 'feComponentTransfer');
+    ['feFuncR', 'feFuncG', 'feFuncB'].forEach((ch) => {
+        const fn = document.createElementNS(NS, ch);
+        fn.setAttribute('type', 'table');
+        fn.setAttribute('tableValues', lqCurve(lqT));
+        ct.appendChild(fn);
+    });
+    f.appendChild(ct);
+    svg.appendChild(f);
+    document.body.appendChild(svg);
+    return f;
+}
+/** CSS `filter` fragment for the current lqT ('' when off) — ensures the SVG node exists BEFORE returning the
+ * `url()` reference (a dangling reference would hide the canvas). Composed by callers with viz-mode filters. */
+export function lqFilter() {
+    if (lqT <= 0)
+        return '';
+    ensureLqFilter();
+    return `url(#${FILTER_ID})`;
+}
+/** Current lqT (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
+export function getLqT() {
+    return lqT;
+}
+let onChange = () => { };
+/** Wires the injected recompose callback. Call once during game.js boot. */
+export function initLqFilter(ctx) {
+    onChange = ctx.onChange;
+}
+/** Sets lqT (clamped to 0..1), persists it, updates the live SVG table (if the filter is already on-screen),
+ * then calls the injected `onChange` to let game.js recompose the CSS filter. Mirrors game.js's setLq. */
+export function setLq(t) {
+    lqT = clamp01(t);
+    store.set(store.KEYS.lq, lqT);
+    if (lqT > 0) {
+        const f = ensureLqFilter();
+        const tv = lqCurve(lqT);
+        f.querySelectorAll('feFuncR,feFuncG,feFuncB').forEach((fn) => fn.setAttribute('tableValues', tv));
+    }
+    onChange();
+}

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

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import * as PIXI from 'pixi.js';
+export declare function initMinimap(stage: PIXI.Container, W: number, H: number): void;
+export declare function markSeen(camX: number, camY: number): void;
+export declare function redrawMinimapIfDirty(): void;
+export declare function drawMinimapPlayer(worldX: number, worldY: number): void;
+export declare function resetMinimap(): void;
+export declare function setMinimapCorner(touch: boolean): void;
+export declare function setMinimapVisible(v: boolean): void;
+export declare function getMinimap(): PIXI.Container | null;
+export declare function minimapSeenCount(): number;

package/dist-pkg/render/minimap.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/minimap.ts — minimapa com FOG-OF-WAR (Estágio 4, Tier 1). Um container PixiJS no canto do stage: fundo
+// + tiles JÁ VISTOS (revelados pela câmera) + ponto do jogador. O que já foi visto persiste até o fim da fase.
+// initMinimap cria os objetos (import PURO — nada de PIXI no import); markSeen revela; redrawMinimapIfDirty
+// repinta só quando mudou; drawMinimapPlayer põe o ponto; resetMinimap re-escurece (fim de fase). Cor do tile
+// vem de core/collision (tileAt/isSolidType). Deps: PIXI (npm), constants (TILE/LOGICAL_*), collision.
+import * as PIXI from 'pixi.js';
+import { LOGICAL_W, LOGICAL_H, TILE } from '../core/constants.js';
+import { tileAt, isSolidType } from '../core/collision.js';
+const MM_SCALE = 0.8, MM_PAD = 4;
+let _minimap = null;
+let _mmTiles = null, _mmPlayer = null;
+let _seen = [];
+let _dirty = false;
+let _W = 0, _H = 0, _mmW = 0, _mmH = 0;
+// Cria o container + graphics no stage e a grade de "visto" (W×H). Chamado uma vez no boot do game.js.
+export function initMinimap(stage, W, H) {
+    _W = W;
+    _H = H;
+    _mmW = W * MM_SCALE;
+    _mmH = H * MM_SCALE;
+    _minimap = new PIXI.Container();
+    _minimap.x = MM_PAD;
+    _minimap.y = LOGICAL_H - _mmH - MM_PAD;
+    _minimap.alpha = 0.92;
+    stage.addChild(_minimap);
+    const mmBg = new PIXI.Graphics();
+    mmBg.beginFill(0x05070f, 0.72);
+    mmBg.drawRect(-1, -1, _mmW + 2, _mmH + 2);
+    mmBg.endFill();
+    _mmTiles = new PIXI.Graphics();
+    _mmPlayer = new PIXI.Graphics();
+    _minimap.addChild(mmBg, _mmTiles, _mmPlayer);
+    _seen = Array.from({ length: H }, () => new Uint8Array(W));
+    _dirty = false;
+}
+// Marca como visto todos os tiles dentro da janela da câmera (camX,camY = canto sup-esq do viewport, em px).
+export function markSeen(camX, camY) {
+    const tx0 = Math.max(0, (camX / TILE) | 0), tx1 = Math.min(_W - 1, ((camX + LOGICAL_W) / TILE) | 0);
+    const ty0 = Math.max(0, (camY / TILE) | 0), ty1 = Math.min(_H - 1, ((camY + LOGICAL_H) / TILE) | 0);
+    for (let ty = ty0; ty <= ty1; ty++)
+        for (let tx = tx0; tx <= tx1; tx++)
+            if (!_seen[ty][tx]) {
+                _seen[ty][tx] = 1;
+                _dirty = true;
+            }
+}
+// Repinta os tiles vistos SÓ se algo novo foi revelado (barato: o fog muda pouco por frame). Cor por tipo.
+export function redrawMinimapIfDirty() {
+    if (!_dirty || !_mmTiles)
+        return;
+    _mmTiles.clear();
+    for (let ty = 0; ty < _H; ty++)
+        for (let tx = 0; tx < _W; tx++) {
+            if (!_seen[ty][tx])
+                continue;
+            const t = tileAt(tx, ty);
+            const col = isSolidType(t) ? 0x9a93b5 : (t === 3 ? 0x2f6fae : (t === 9 ? 0xff5b3a : 0x232038)); // sólido / água / lava / ar
+            _mmTiles.beginFill(col, 1);
+            _mmTiles.drawRect(tx * MM_SCALE, ty * MM_SCALE, MM_SCALE + 0.4, MM_SCALE + 0.4);
+            _mmTiles.endFill();
+        }
+    _dirty = false;
+}
+// Ponto do jogador (worldX,worldY em px do mundo; o game.js passa o centro do corpo).
+export function drawMinimapPlayer(worldX, worldY) {
+    if (!_mmPlayer)
+        return;
+    _mmPlayer.clear();
+    _mmPlayer.beginFill(0xffd23f, 1);
+    _mmPlayer.drawRect((worldX / TILE) * MM_SCALE - 1, (worldY / TILE) * MM_SCALE - 1, 2.6, 2.6);
+    _mmPlayer.endFill();
+}
+// Fim de fase: o fog-of-war volta a escurecer (o mapa some até ser revisto).
+export function resetMinimap() { _seen.forEach((r) => r.fill(0)); _dirty = true; }
+// Reposiciona o minimapa: no toque vai p/ o canto sup-dir (não briga com os controles); senão inf-esq.
+export function setMinimapCorner(touch) {
+    if (!_minimap)
+        return;
+    if (touch) {
+        _minimap.x = LOGICAL_W - _mmW - MM_PAD;
+        _minimap.y = MM_PAD;
+    }
+    else {
+        _minimap.x = MM_PAD;
+        _minimap.y = LOGICAL_H - _mmH - MM_PAD;
+    }
+}
+export function setMinimapVisible(v) { if (_minimap)
+    _minimap.visible = v; } // some no título / no multiplayer
+export function getMinimap() { return _minimap; } // p/ o __incl (debug/teste)
+export function minimapSeenCount() { let n = 0; for (const r of _seen)
+    for (const v of r)
+        n += v; return n; } // stat de fog revelado