@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,46 +1,42 @@
 // 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.
+// render/high-contrast — Direct Rendering: the accessibility high-contrast engine (ADR-0011) — outline + color-blocking
+// by role + a pushed-back background (desaturated/darkened), 3 contrast levels (3:1/4.5:1/7:1).
+// `createHighContrast(ctx)` returns worldToTextureDirect/directBgTexture/directSprite{Canvas,Texture} + the caches
+// (worldTexFor/spriteTexFor) + the role palette (persisted) — ONE instance per world, built by whoever HAS a world: the
+// root has none, so a game that draws one builds it (ADR-0232 D4, issue #207). INJECTED: the document the canvases are
+// made in, the grid's bounds (W/H), the tile lookup, the two outline levels (outlineFg/outlineBg, which the host changes)
+// and the NORMAL world canvas/texture (the scenery can swap it → getter). The "mode already applied" cache that the
+// host's static render pipeline uses to decide when to reapply textures per viewport is NOT here: it is not a
+// high-contrast cache, and several subsystems outside write into it.
+// See the ADR-0011 record (visual accessibility).
 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';
+import { KEYS } from '../platform/storage-keys.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)));
-        }
+/** The defaults with the stored colours laid over them, each clamped to 0–255; a malformed entry keeps its default. */
+function storedPalette(store) {
+    const palette = JSON.parse(JSON.stringify(HC_ROLE_DEF));
+    const s = store.getJSON(KEYS.hcrole, null);
+    if (!s || typeof s !== 'object')
+        return palette;
+    for (const k of Object.keys(palette)) {
+        const v = s[k];
+        if (Array.isArray(v) && v.length === 3)
+            palette[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").
+    return palette;
+}
+// off/mul = the platform map (more off = lighter → more contrast); bgMul = the background (lower = darker/pushed back).
+// Platform×background contrast ≈ 3 / 4.5 / 7 (see ADR-0011: 3:1 is the default, and 7:1 looks ugly).
 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) ===================== */
+/* ===================== desaturation/darkening (background/structure) ===================== */
 export function dimDesat(c, w, h, mul, blue, off) {
     off = off || 0;
     const img = c.getImageData(0, 0, w, h), d = img.data;
@@ -54,201 +50,210 @@ export function dimDesat(c, w, h, mul, blue, off) {
     }
     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;
+/** LADDER: black + rails and rungs in the role's colour → it reads as a ladder, not a solid band. */
+function drawLadder(c, X, Y, climb) {
+    c.fillStyle = '#0a0e14';
+    c.fillRect(X, Y, TILE, TILE);
+    c.fillStyle = 'rgb(' + climb.join(',') + ')';
+    c.fillRect(X + 1, Y, 2, TILE);
+    c.fillRect(X + TILE - 3, Y, 2, TILE); // side rails (the role's colour, customisable)
+    for (let ry = 2; ry < TILE - 1; ry += 5)
+        c.fillRect(X + 1, Y + ry, TILE - 2, 2); // rungs
 }
-/* ===================== 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)
+/** A tile repainted in its role's colour `rc`, by the brightness of each pixel (BT.601 luma); a hazard starts from brighter. */
+function repaintByRole(c, X, Y, role, rc) {
+    const 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);
+}
+/** Tiles 0 and 1 are this map's air (see the note in the loop below: a platformer's numbering, declared, not generalised). */
+const isAir = (t) => t === 0 || t === 1;
+/** The background outline: ONLY the outer perimeter — a block's edges that face the air —, not every block. */
+function outlineSecondPlane(c, hc, th) {
+    if (th <= 0)
+        return;
+    const air = (x, y) => isAir(hc.tileAt(x, y));
+    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), 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
+            if (air(x, y))
                 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 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);
         }
-    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);
+}
+/**
+ * Builds one world's high contrast and READS the stored role colours into its palette — at build, never at import
+ * (ADR-0232). The palette and the two texture caches live in this closure, so two worlds on one page share none of them.
+ */
+export function createHighContrast(ctx) {
+    const { store, doc } = ctx;
+    const role = storedPalette(store);
+    const saveRole = () => { store.setJSON(KEYS.hcrole, role); };
+    /* ===================== Direct Rendering: world + background + foreground sprites ===================== */
+    /** The world in high contrast: a desaturated/lightened base + repaint by role (with the ladder as a special case:
+     *  rails/rungs, not a solid band) + a background outline on the outer perimeter (walkable × not walkable). */
+    function worldToTextureDirect(srcCanvas, mode) {
+        const cfg = dcfg(mode);
+        const cv = makeCanvas(doc, 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: structure turns blue-grey (lighter = more contrast)
+        for (let y = 0; y < ctx.H; y++)
+            for (let x = 0; x < ctx.W; x++) {
+                const t = ctx.tileAt(x, y), r = ctx.roleOf(t);
+                if (!r)
+                    continue; // repaint non-structural tiles in the role's colour
+                // ⚠️ WHAT PLATFORMER IS LEFT HERE. The ladder is drawn with rails and rungs because a solid band does not READ as a
+                // ladder — an accessibility decision that would serve any game with something climbable. But the shape of the
+                // injected question ("does this tile draw as a ladder?" · "which painter does this role use?") has no evidence to
+                // choose it yet, and a consumer showed, in menu-nav, that the shape matters more than the existence of the
+                // injection. Declared instead of guessed.
+                if (t === 4)
+                    drawLadder(c, x * TILE, y * TILE, role.climb);
+                else
+                    repaintByRole(c, x * TILE, y * TILE, r, role[r]);
             }
+        outlineSecondPlane(c, ctx, ctx.outlineBg());
+        return tex(cv);
     }
-    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;
+    /** Background/decoration in high contrast: only desaturation/darkening (it steps back) — no repaint by role and no
+     *  outline. Used by render/viewports for decoration (treeTexFor) and parallax (parallaxTexFor). */
+    function directBgTexture(srcTex, mode) {
+        const cfg = dcfg(mode);
+        const cv = makeCanvas(doc, 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;
+    }
+    /** A foreground sprite (player/coin/power-up) in high contrast: it keeps the art's colour + a DARK outline (WCAG 2.4.7 —
+     *  it "jumps" off the pushed-back background). `mode` is unused (kept only for signature parity with the other 3
+     *  "direct*" functions — the dispatch by DIRECT_CFG[mode] already happened in the caller). fg=0 → no outline. */
+    function directSpriteCanvas(srcCanvas, mode) {
+        void mode;
+        const fg = ctx.outlineFg();
+        return fg > 0 ? outlineCanvas(srcCanvas, fg) : srcCanvas;
+    }
+    /** The PIXI.Texture variant of directSpriteCanvas (player: the source texture is already a PIXI.Texture, not a raw
+     *  canvas). `mode` likewise — unused, kept for signature parity. */
+    function directSpriteTexture(srcTex, mode) {
+        void mode;
+        const fg = ctx.outlineFg();
+        if (fg <= 0)
+            return srcTex;
+        const th = fg;
+        const cv = makeCanvas(doc, 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;
+            // ===================== THE CLIP COMES BEFORE THE OUTLINE =====================
+            // Reading the BASE and ignoring the `frame` draws, for a frame packed in an atlas, the whole atlas: every frame of the
+            // character at once, in a grid — the "kage bunshin" defect. It happened once the character's sprites were packed
+            // into an atlas, where only the frames that go through the seam fixer (idle/walk/run) become canvases of their own
+            // and jump, ladder, wall, ceiling, swim and flight are CLIPS.
+            //
+            // The seam fixer is asynchronous, so the idle frame showed it too: with high contrast on early, the outlined-frame
+            // cache memorises the atlas-based version and keeps it forever.
+            const f = srcTex.frame;
+            const needsClipping = !!f && (f.x !== 0 || f.y !== 0 || f.width !== s.width || f.height !== s.height);
+            let drawSource = s;
+            if (needsClipping && f) {
+                const rec = makeCanvas(doc, Math.max(1, f.width), Math.max(1, f.height));
+                const rc = rec.getContext('2d');
+                rc.imageSmoothingEnabled = false; // pixel art: resampling here would blur the outline the mode promises
+                rc.drawImage(s, f.x, f.y, f.width, f.height, 0, 0, f.width, f.height);
+                drawSource = rec;
+            }
+            // outlineCanvas only declares HTMLCanvasElement; the clip already returns a canvas, and an unclipped base is
+            // canvas-sourced on the paths that remain. The cast changes nothing at runtime.
+            const o = outlineCanvas(drawSource, 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;
+    }
+    /* ===================== lazy caches (world/sprites) + per-mode selector ===================== */
+    const worldTexHC = {};
+    /** The recoloured-sprite cache, keyed by `id|mode` — one cache for every sprite of this world, not one per game's coin. */
+    const spriteTexHC = {};
+    function worldTexFor(mode) {
+        if (DIRECT_CFG[mode]) {
+            if (!worldTexHC[mode])
+                worldTexHC[mode] = worldToTextureDirect(ctx.getWorldCanvasNormal(), mode);
+            return worldTexHC[mode];
         }
-        // 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 ctx.getWorldTexNormal();
     }
-    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;
+    /**
+     * Sprite `id`'s texture for `mode` (the same logic as `worldTexFor`, cached by `id|mode`).
+     *
+     * Outside the direct rendering modes it returns the normal texture the game declared — and it returns `undefined` for
+     * an id the game did not declare, instead of throwing: a missing sprite becomes "no texture" in the drawing, which is
+     * degradation; throwing here would take the whole frame down because of one item.
+     */
+    function spriteTexFor(id, mode) {
+        const src = ctx.sprites()[id];
+        if (!src)
+            return undefined;
+        if (DIRECT_CFG[mode]) {
+            const key = id + '|' + mode;
+            if (!spriteTexHC[key] && src.canvas)
+                spriteTexHC[key] = tex(directSpriteCanvas(src.canvas, mode));
+            return spriteTexHC[key] ?? src.tex;
+        }
+        return 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];
+    function clearWorldTexCache() { for (const k in worldTexHC)
+        delete worldTexHC[k]; }
+    /**
+     * With no argument it clears EVERYTHING; with an `id`, only that sprite's entries — what a game with many sprites will
+     * want, and what a cache keyed only by mode could not offer.
+     */
+    function clearSpriteTexCache(id) {
+        for (const k in spriteTexHC) {
+            if (id === undefined || k.startsWith(id + '|'))
+                delete spriteTexHC[k];
+        }
     }
+    return {
+        role, saveRole,
+        worldToTextureDirect, directBgTexture, directSpriteCanvas, directSpriteTexture,
+        worldTexFor, spriteTexFor, clearWorldTexCache, clearSpriteTexCache,
+    };
 }

package/dist-pkg/render/low-vision-drawing.d.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The simulations drawn rather than filtered. `haze` is also a filter under `createGame`, which draws only the other three. */
+export type LowVisionDrawing = 'haze' | 'tunnel' | 'macular' | 'diabetic';
+/** Draws simulation `lv` on a `w`×`h` context, over transparency. A key that is not a drawn simulation draws nothing. */
+export declare function drawLowVision(c: CanvasRenderingContext2D, lv: string, w: number, h: number): void;

package/dist-pkg/render/low-vision-drawing.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/low-vision-drawing — what a colour filter cannot make: the white film of cataract, the tunnel of glaucoma, the central
+// scotoma of macular degeneration and the scattered scotomas of diabetic retinopathy. They are a DRAWING over the world, not a
+// transformation of its colours.
+//
+// One drawing, two consumers: `render/viewports` stamps it into each viewport's texture, and `boot/create-game` lays it over
+// the declared world for the empathy panel (issue #182). Written once so the two cannot show different simulations under one name.
+/** Where the scattered scotomas of diabetic retinopathy sit, as fractions of the view: x, y and radius (of the width). */
+const SCATTERED_SPOTS = [[.22, .3, .1], [.64, .22, .075], [.8, .58, .11], [.4, .7, .085], [.16, .8, .07], [.54, .48, .06]];
+/** One radial gradient: its centre and radii, and its colour stops from the inside out. */
+function radial(c, [x0, y0, r0, x1, y1, r1], stops) {
+    const g = c.createRadialGradient(x0, y0, r0, x1, y1, r1);
+    for (const [at, colour] of stops)
+        g.addColorStop(at, colour);
+    return g;
+}
+/** Each drawn simulation, one row. A table and not a chain of `else if`: a fifth simulation is one more row. */
+const DRAWN = Object.freeze({
+    // a film over everything, translucent — the world shows through it, washed out
+    haze: (c, w, h) => { c.fillStyle = 'rgba(244,246,250,0.42)'; c.fillRect(0, 0, w, h); },
+    // the edges close in, the centre stays clear
+    tunnel: (c, w, h) => {
+        c.fillStyle = radial(c, [w / 2, h / 2, h * 0.12, w / 2, h / 2, h * 0.6], [[0, 'rgba(0,0,0,0)'], [.5, 'rgba(0,0,0,.55)'], [1, 'rgba(0,0,0,.99)']]);
+        c.fillRect(0, 0, w, h);
+    },
+    // the centre is gone, the edges stay
+    macular: (c, w, h) => {
+        c.fillStyle = radial(c, [w / 2, h / 2, 2, w / 2, h / 2, h * 0.34], [[0, 'rgba(12,12,15,.95)'], [.55, 'rgba(12,12,15,.5)'], [1, 'rgba(12,12,15,0)']]);
+        c.fillRect(0, 0, w, h);
+    },
+    // several dark spots, scattered, each in its own square
+    diabetic: (c, w, h) => {
+        for (const [fx, fy, fr] of SCATTERED_SPOTS) {
+            const x = fx * w, y = fy * h, r = fr * w;
+            c.fillStyle = radial(c, [x, y, 1, x, y, r], [[0, 'rgba(10,10,14,.95)'], [.5, 'rgba(10,10,14,.7)'], [1, 'rgba(10,10,14,0)']]);
+            c.fillRect(x - r, y - r, 2 * r, 2 * r);
+        }
+    },
+});
+/** Draws simulation `lv` on a `w`×`h` context, over transparency. A key that is not a drawn simulation draws nothing. */
+export function drawLowVision(c, lv, w, h) {
+    // an OWN key only: `toString` is on every object, and it is not a simulation
+    if (!Object.hasOwn(DRAWN, lv))
+        return;
+    DRAWN[lv](c, w, h);
+}

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

@@ -1,37 +1,49 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Store } from '../platform/storage.js';
 /**
  * 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).
+ * S-curve (quadratic) by `t`. NOT clamped — 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).
+ * Continuous `t` -> the i18n KEY of the screen-reader/UI label. NOT clamped (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;
+/** The document the `<filter>` node lives in — only what the shell touches. */
+export type LqDoc = Pick<Document, 'getElementById' | 'createElementNS' | 'body'>;
 export interface LqFilterCtx {
+    /** The document the SVG `<filter>` is created in and looked up from — passed, never the global one (ADR-0232). */
+    doc: LqDoc;
     /**
-     * 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.
+     * Recomposes the app's CSS filter after the amount changes — composed with the active colour/simulation filter, and
+     * with whatever texture-cache invalidation that triggers elsewhere. That composition belongs to other subsystems and
+     * stays with the host; this module only owns the amount + the SVG filter node.
      */
     onChange: () => void;
+    /**
+     * Where the amount is kept — the page's store, built by the root (ADR-0232, issue #207). Required: an enhancement read
+     * from nowhere starts OFF at every visit for the child with low vision who turned it on.
+     */
+    store: Pick<Store, 'getNum' | 'set'>;
+}
+/** One root's L→Q enhancement. */
+export interface LqFilter {
+    /** CSS `filter` fragment for the current amount ('' 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. */
+    filter(): string;
+    /** The current amount (0..1) — read by the visual-settings panel and the debug/`__incl` surface. */
+    t(): number;
+    /** Sets the amount (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 the host recompose the CSS filter. */
+    set(t: number): 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;
+/**
+ * Builds the enhancement and READS the stored amount — at build, never at import (ADR-0232). The amount lives in this
+ * closure: two roots on one page each keep their own.
+ */
+export declare function createLqFilter(ctx: LqFilterCtx): LqFilter;