@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/render/cvd-matrices.js

@@ -1,36 +1,35 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/cvd-matrices — as SEIS matrizes de daltonismo (3 SIMULAÇÕES Machado 2009 sev. 1.0 + 3 CORREÇÕES
-// C = I + M_err·(I − Sim), M_err de Fidaner et al.), num só lugar. Módulo-folha: ZERO dependências.
+// render/cvd-matrices — the SIX colour-blindness matrices (3 SIMULATIONS, Machado 2009 severity 1.0 + 3 CORRECTIONS
+// C = I + M_err·(I − Sim), M_err from Fidaner et al.), in one place. A leaf module: ZERO dependencies.
 //
-// A DUPLICAÇÃO QUE ESTE MÓDULO CURA (a sétima do refactor). Os mesmos 120 números existiam escritos DUAS
-// vezes, em linguagens diferentes:
-//   · `<feColorMatrix values="…">` em app/index.html — caminho de TELA ÚNICA (`filter: url(#cvd-…)` na
-//     <canvas>); render/viz-modes só guarda o `url(#cvd-deuter)`, nunca os números.
-//   · `PIXI.ColorMatrixFilter` dentro de `pixiFilterFor` no game.js — caminho MULTI-TELA (filtro GPU por
-//     viewport, um modo por jogador).
-// Batiam por sorte: nada ligava as duas cópias. Se divergissem, o sintoma seria SILENCIOSO e de
-// ACESSIBILIDADE — a MESMA pessoa daltônica veria cores diferentes em tela única e em multi-tela, sem erro,
-// sem log, sem teste vermelho. Agora os dois caminhos leem daqui: `render/viewports` monta o
-// ColorMatrixFilter com estes arrays, e `installCvdFilters()` GERA os seis `<filter>` do index.html no boot
-// a partir dos mesmos arrays (o HTML só guarda o `<defs id="cvd-defs">` vazio que os recebe).
+// THE DUPLICATION THIS MODULE CURES. The same 120 numbers were once written TWICE, in different languages: as
+// `<feColorMatrix values="…">` in a page's HTML — the SINGLE-SCREEN path (`filter: url(#cvd-…)` on the <canvas>) — and
+// as a `PIXI.ColorMatrixFilter` — the MULTI-SCREEN path (a GPU filter per viewport, one mode per player). Nothing tied
+// the two copies. Had they drifted, the symptom would be SILENT and about ACCESSIBILITY — the SAME colour-blind person
+// would see different colours on one screen and on several, with no error, no log, no red test. Now both paths read
+// from here: `render/viewports` builds the ColorMatrixFilter from these arrays, and `installCvdFilters()` GENERATES the
+// six `<filter>`s at boot from the same arrays, into the empty host the root is given (`host.cvdHost`).
 //
-// Este é um módulo-folha de propósito (mesmo formato de render/hc-role-data): um arquivo de dados sem
-// dependência nenhuma pode ser lido tanto pelo pipeline de render quanto pelo boot do documento sem arrastar
-// PixiJS para dentro do HTML nem o DOM para dentro do render.
+// A leaf module on purpose (the same shape as render/hc-role-data): a data file with no dependency can be read both by
+// the render pipeline and by the document's boot without dragging PixiJS into the HTML or the DOM into the renderer.
 //
-// LAYOUT: 20 números = 4 linhas de 5 (R, G, B, A), em ordem de linha. É EXATAMENTE o mesmo layout nos dois
-// destinos — `feColorMatrix type="matrix"` e `PIXI.ColorMatrixFilter#matrix` — por isso o array serve aos
-// dois sem conversão. Aplicados em sRGB nos dois caminhos (aproximação padrão da web; ver a decisão 2 da
-// pesquisa). Fonte primária e a conferência valor a valor: docs/research/PESQUISA-DALTONIZACAO.md.
-/** Ordem canônica: as três simulações (o que a pessoa vê) antes das três correções (o que a ajuda a ver). */
+// LAYOUT: 20 numbers = 4 rows of 5 (R, G, B, A), in row order. It is EXACTLY the same layout at both destinations —
+// `feColorMatrix type="matrix"` and `PIXI.ColorMatrixFilter#matrix` — so the array serves both with no conversion.
+// Applied in sRGB on both paths (the web's standard approximation; see the research's decision 2). Primary source and
+// the value-by-value check: docs/research/RESEARCH-DALTONIZATION.md.
+/**
+ * Canonical order: the three simulations (what the person sees) before the three corrections (what helps them see).
+ * It is also THE list of colour-vision modes the rest of the engine asks about — `onlyColourVision` (render/viz-axes)
+ * reads it for the scanline that stays under them (ADR-0241).
+ */
 export const CVD_KEYS = ['sim-protan', 'sim-deuter', 'sim-tritan', 'fix-protan', 'fix-deuter', 'fix-tritan'];
 /**
- * As matrizes, 4×5 em ordem de linha. Linha A = `0 0 0 1 0` em todas: nenhum dos seis modos mexe em alfa.
+ * The matrices, 4×5 in row order. Row A = `0 0 0 1 0` in all of them: none of the six modes touches alpha.
  *
- * SIMULAÇÃO (Machado, Oliveira & Fernandes 2009, severidade 1.0 — valores conferidos na página dos autores,
- * UFRGS). CORREÇÃO (daltonização canônica): a linha R é identidade — não adianta modular o canal que a pessoa
- * não distingue — e o erro é reinjetado em G e B, onde há discriminação; a soma de cada linha é 1, então
- * branco e cinzas ficam preservados.
+ * SIMULATION (Machado, Oliveira & Fernandes 2009, severity 1.0 — values checked on the authors' page, UFRGS).
+ * CORRECTION (canonical daltonisation): the R row is identity — there is no point modulating the channel the person
+ * cannot tell apart — and the error is reinjected into G and B, where there is discrimination; each row sums to 1, so
+ * white and greys are preserved.
  */
 export const CVD_MATRIX = {
     'sim-protan': [0.152286, 1.052583, -0.204868, 0, 0, 0.114503, 0.786281, 0.099216, 0, 0, -0.003882, -0.048116, 1.051998, 0, 0, 0, 0, 0, 1, 0],
@@ -41,31 +40,31 @@ export const CVD_MATRIX = {
     'fix-tritan': [1, 0, 0, 0, 0, -0.100459, 1.122915, -0.022457, 0, 0, -0.183603, -0.637643, 1.821245, 0, 0, 0, 0, 0, 1, 0],
 };
 /**
- * Modo → id do `<filter>` SVG. Os ids são API PÚBLICA deste módulo: `VIZ_FILTER` (render/viz-modes) pede o
- * filtro pelo `url(#…)`, e é este mapa que promete que o filtro com aquele id vai existir no documento.
- * Renomear um id aqui sem renomear lá apaga a canvas (referência de filtro inexistente não renderiza).
+ * Mode → the SVG `<filter>` id. The ids are this module's PUBLIC API: `VIZ_FILTER` (render/viz-modes) asks for the
+ * filter by `url(#…)`, and this map is what promises the filter with that id will exist in the document. Renaming an id
+ * here without renaming it there blanks the canvas (a reference to a missing filter does not render).
  */
 export const CVD_SVG_ID = {
     'sim-protan': 'cvd-protan', 'sim-deuter': 'cvd-deuter', 'sim-tritan': 'cvd-tritan',
     'fix-protan': 'cvd-fix-protan', 'fix-deuter': 'cvd-fix-deuter', 'fix-tritan': 'cvd-fix-tritan',
 };
-/** Atributo `values` de um `<feColorMatrix>`: as 4 linhas separadas por espaço duplo (legibilidade). PURA. */
+/** A `<feColorMatrix>`'s `values` attribute: the 4 rows separated by a double space (readability). PURE. */
 export function cvdMatrixValues(k) {
     const m = CVD_MATRIX[k];
     return [0, 5, 10, 15].map((i) => m.slice(i, i + 5).join(' ')).join('  ');
 }
 const SVG_NS = 'http://www.w3.org/2000/svg';
 /**
- * Gera os seis `<filter>` DENTRO do `<defs id="cvd-defs">` do index.html, a partir de `CVD_MATRIX`.
+ * Generates the six `<filter>`s INSIDE the given host (an SVG `<defs>`), from `CVD_MATRIX`.
  *
- * Por que no boot e não escrito à mão no HTML: era exatamente a segunda cópia dos números. Construído com
- * `createElementNS` (e não `innerHTML`) porque `<filter>`/`<feColorMatrix>` só funcionam no namespace SVG —
- * com innerHTML o resultado depende do algoritmo de fragmento do navegador.
+ * Why at boot and not written by hand in the HTML: that was exactly the second copy of the numbers. Built with
+ * `createElementNS` (and not `innerHTML`) because `<filter>`/`<feColorMatrix>` only work in the SVG namespace — with
+ * innerHTML the result depends on the browser's fragment algorithm.
  *
- * Idempotente: esvazia o host antes de preencher, então chamar duas vezes não duplica ids (id duplicado faria
- * o navegador escolher o primeiro — falha silenciosa outra vez).
+ * Idempotent: it empties the host before filling it, so calling twice does not duplicate ids (a duplicated id would make
+ * the browser pick the first — a silent failure again).
  *
- * @returns quantos filtros foram instalados (0 = host ausente; o chamador decide se isso é fatal).
+ * @returns how many filters were installed (0 = no host; the caller decides whether that is fatal).
  */
 export function installCvdFilters(host) {
     if (!host)
@@ -79,7 +78,7 @@ export function installCvdFilters(host) {
     for (const k of CVD_KEYS) {
         const f = doc.createElementNS(SVG_NS, 'filter');
         f.setAttribute('id', CVD_SVG_ID[k]);
-        f.setAttribute('color-interpolation-filters', 'sRGB'); // idem PIXI: os dois caminhos operam em sRGB
+        f.setAttribute('color-interpolation-filters', 'sRGB'); // as PIXI does: both paths work in sRGB
         const fe = doc.createElementNS(SVG_NS, 'feColorMatrix');
         fe.setAttribute('type', 'matrix');
         fe.setAttribute('values', cvdMatrixValues(k));

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

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Papéis que `roleOf(tile)` sabe devolver — os que o repinte do alto contraste aplica direto no tile. */
+/** The roles `roleOf(tile)` can return — those the high-contrast repaint applies straight to the tile. */
 export type PaintableRole = 'hazard' | 'climb' | 'water';
-/** Todos os papéis customizáveis. `gate` não vem de `roleOf()`: é usado à parte pelo desenho do portão
- *  trancado (game/level-geometry), mas o jogador escolhe a cor dele no mesmo painel. */
+/** All the customisable roles. `gate` does not come from `roleOf()`: a game's locked-gate drawing uses it apart, but
+ *  the player picks its colour in the same panel. */
 export type HcRoleKey = PaintableRole | 'gate';
-/** Ordem canônica dos papéis — a ordem em que o painel desenha os seletores de cor. */
+/** The roles' canonical order — the order in which the panel draws the colour pickers. */
 export declare const HC_ROLE_KEYS: readonly HcRoleKey[];
 /**
- * Cores padrão por papel (RGB 0-255). Color-blocking: perigo = laranja-quente, escalável/interativo
- * (escada/trampolim) = ciano, água = azul, portão = magenta. A estrutura (pedra/parede) fica no cinza-azulado
- * do nível e por isso não é um papel. Customizável e persistido — ver `HC_ROLE` em render/high-contrast.
+ * Default colours per role (RGB 0-255). Color-blocking: hazard = warm orange, climbable/interactive (ladder/trampoline)
+ * = cyan, water = blue, gate = magenta. Structure (stone/wall) stays in the level's blue-grey and so is not a role.
+ * Customisable and persisted — see the `role` palette of render/high-contrast's `createHighContrast`.
  */
 export declare const HC_ROLE_DEF: Record<HcRoleKey, [number, number, number]>;

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

@@ -1,23 +1,23 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// render/hc-role-data — os PAPÉIS SEMÂNTICOS do color-blocking, num só lugar.
+// render/hc-role-data — color-blocking's SEMANTIC ROLES, in one place.
 //
-// Existiam duas listas dos mesmos quatro papéis: `RoleKey`/`ROLE_KEYS` em ui/settings-visual (que desenha um
-// seletor de cor por papel) e `PaintableRole`/`HcRoleKey` em render/high-contrast (que repinta os tiles). Nada
-// ligava as duas, e a falha era silenciosa: um quinto papel adicionado ao render ganharia cor e não ganharia
-// seletor, sem erro de tipo em lugar nenhum — o painel simplesmente não ofereceria como customizar.
+// There were two lists of the same four roles: one in the visual settings panel (which draws a colour picker per role)
+// and one in render/high-contrast (which repaints the tiles). Nothing tied them, and the failure was silent: a fifth
+// role added to the renderer would get a colour and no picker, with no type error anywhere — the panel would simply not
+// offer a way to customise it.
 //
-// Este módulo é FOLHA de propósito: zero dependências. Ele é importado tanto pelo render quanto pela UI, e um
-// arquivo de dados sem dependência nenhuma pode ser importado dos dois lados sem arrastar o pipeline de
-// renderização para dentro de um painel de configuração (nem o contrário).
+// This module is a LEAF on purpose: zero dependencies. Both the renderer and the UI import it, and a data file with no
+// dependency at all can be imported from both sides without dragging the rendering pipeline into a settings panel (nor
+// the reverse).
 //
-// O que NÃO mora aqui: os rótulos em pt-BR dos papéis, que são apresentação e ficam em ui/settings-visual.
-// Eles são digitados por `HcRoleKey`, então continuam obrigados a cobrir exatamente estes quatro papéis.
-/** Ordem canônica dos papéis — a ordem em que o painel desenha os seletores de cor. */
+// What does NOT live here: the roles' labels, which are presentation and sit in ui/visual-choices (`ROLE_LABELS`). They
+// are typed by `HcRoleKey`, so they stay obliged to cover exactly these four roles.
+/** The roles' canonical order — the order in which the panel draws the colour pickers. */
 export const HC_ROLE_KEYS = ['hazard', 'climb', 'water', 'gate'];
 /**
- * Cores padrão por papel (RGB 0-255). Color-blocking: perigo = laranja-quente, escalável/interativo
- * (escada/trampolim) = ciano, água = azul, portão = magenta. A estrutura (pedra/parede) fica no cinza-azulado
- * do nível e por isso não é um papel. Customizável e persistido — ver `HC_ROLE` em render/high-contrast.
+ * Default colours per role (RGB 0-255). Color-blocking: hazard = warm orange, climbable/interactive (ladder/trampoline)
+ * = cyan, water = blue, gate = magenta. Structure (stone/wall) stays in the level's blue-grey and so is not a role.
+ * Customisable and persisted — see the `role` palette of render/high-contrast's `createHighContrast`.
  */
 export const HC_ROLE_DEF = {
     hazard: [255, 110, 45], climb: [55, 225, 205], water: [70, 140, 255], gate: [194, 58, 212],

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import { type CanvasDoc } from './canvas.js';
 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;
+import type { Store } from '../platform/storage.js';
+export { HC_ROLE_DEF } from './hc-role-data.js';
+/** A role palette: one RGB triple per role. */
+export type RolePalette = Record<HcRoleKey, [number, number, number]>;
 export interface DirectCfg {
     off: number;
     mul: number;
@@ -14,56 +14,67 @@ 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 {
+    /** The document the recoloured canvases are made in — passed, never the global one (ADR-0232). */
+    doc: CanvasDoc;
     W: number;
     H: number;
+    /**
+     * WHICH TILE IS AT (tx,ty) — a QUESTION and not an import. This module is the engine's (its subject is WCAG 1.4.6's
+     * high contrast), but to paint role by role it needs to know what is in each cell — and that is ONE game's grid.
+     * By asking, the engine does not import tile geometry: whoever has a grid answers, and whoever does not never mounts
+     * this module.
+     * ⚠️ REQUIRED, by ADR-0224's precedent: an optional door is one more field a game can forget, and forgetting this one
+     * would paint the whole world one colour.
+     */
+    tileAt: (tx: number, ty: number) => 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.
+     * THE SPRITES THE GAME WANTS RECOLOURED, BY ID. The engine caches per `(id, mode)` and never knows what the id means
+     * — it may be a coin, a syllable, a board piece.
      *
-     * 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.
+     * Not a fixed pair shaped like one game's coin: a second game wanting to recolour its piece would have no way in —
+     * it would have to call the piece a "coin", or reimplement the 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.
+     * A function and not a value because a sprite's canvas may be redrawn at boot (the same reason as
+     * `getWorldCanvasNormal`), and a value read once would freeze the first instant's.
      */
     sprites: () => Record<string, {
         canvas: HTMLCanvasElement | null;
         tex: unknown;
     }>;
     /**
-     * TILE → PAPEL SEMÂNTICO, e é o consumidor quem sabe. `null` = estrutura (sem repintura).
+     * TILE → SEMANTIC ROLE, and the consumer is who knows. `null` = structure (no repaint).
      *
-     * 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.
+     * Not a table fixed IN HERE (`9` hazard, `4|5|10` climbable, `3` water): ADR-0027 named that the base's no. 1
+     * coupling. "Hazard is tile 9" is true of ONE MAP, not of the engine; a second game with another numbering would
+     * paint the floor orange and the lava grey — no error, no red test, for whoever can least check it by looking.
      *
-     * A tabela do jogo de plataforma mora em `game/tile-roles`. Trocar de tabela é trocar de jogo, e é só isso.
+     * Swapping the table is swapping the game, and nothing more.
      */
     roleOf: (t: number) => PaintableRole | null;
+    /**
+     * Where the child's role colours are kept — the page's store, built by the root (ADR-0232, issue #207). Required: colours
+     * read from nowhere come back to the defaults at every visit, and a child who chose them because that is how they see
+     * would lose them in silence.
+     */
+    store: HighContrastStore;
 }
-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 {
+/** What the role palette is read and written through. */
+export type HighContrastStore = Pick<Store, 'getJSON' | 'setJSON'>;
+/** The minimal PIXI.Texture surface directBgTexture/directSpriteTexture touch (resource.source may be a canvas OR an
+ *  image — a parallax loaded from a PNG through PIXI.Texture.from(img)). Structural, so PIXI's Resource union types are
+ *  not dragged in here. */
+export 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.
+     * The frame's CLIP inside the base — a character packed in an atlas is a clip, not a canvas of its own. Optional
+     * because `directBgTexture` gets textures that really fill the whole base (parallax, tree) and does not need it.
      */
     frame?: {
         x: number;
@@ -79,31 +90,31 @@ interface DirectTexSource {
         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;
+/** One world's high contrast: its palette, its recolours and their caches. */
+export interface HighContrast {
+    /** The LIVE role palette: the defaults with the child's stored colours laid over them. Mutated in place by the panel. */
+    readonly role: RolePalette;
+    /** Keeps `role` in the store this instance was built with (called by whoever changes or resets a role colour). */
+    saveRole(): void;
+    /** The world in high contrast: a desaturated/lightened base + repaint by role + a background outline on the perimeter. */
+    worldToTextureDirect(srcCanvas: HTMLCanvasElement, mode: string): unknown;
+    /** Background/decoration in high contrast: only desaturation/darkening (it steps back). */
+    directBgTexture(srcTex: DirectTexSource, mode: string): unknown;
+    /** A foreground sprite in high contrast: the art's colour + a DARK outline (WCAG 2.4.7). */
+    directSpriteCanvas(srcCanvas: HTMLCanvasElement, mode: string): HTMLCanvasElement;
+    /** The PIXI.Texture variant of `directSpriteCanvas`. */
+    directSpriteTexture(srcTex: DirectTexSource, mode: string): unknown;
+    /** The WORLD texture for `mode` (normal → the live texture; hc-* → Direct Rendering, cached). */
+    worldTexFor(mode: string): unknown;
+    /** Sprite `id`'s texture for `mode`, cached by `id|mode`; `undefined` for an id the game did not declare. */
+    spriteTexFor(id: string, mode: string): unknown;
+    /** Invalidates the world cache (the theme/scenery changed → the normal world canvas is another canvas). */
+    clearWorldTexCache(): void;
+    /** Invalidates the sprite cache: everything, or only `id`'s entries. */
+    clearSpriteTexCache(id?: string): 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.
+ * 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 declare function clearSpriteTexCache(id?: string): void;
+export declare function createHighContrast(ctx: HighContrastCtx): HighContrast;