@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/render/viz-modes.d.ts

@@ -1,29 +1,29 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * `sim` — este modo SIMULA uma deficiência em quem não a tem, em vez de CORRIGIR a tela para quem a tem.
+ * `sim` — this mode SIMULATES a disability in someone who does not have it, instead of CORRECTING the screen for someone
+ * who does.
  *
- * O `kind` não responde a isso e nunca respondeu: `sim-deuter` (simular daltonismo) e `fix-deuter` (corrigir
- * daltonismo) compartilham `kind:'filter'`, ainda que sirvam a duas pessoas opostas. Enquanto ninguém
- * precisava distinguir, a lacuna era inofensiva. Passou a não ser quando o menu de empatia ganhou um
- * "restaurar padrões" (ADR-0028): desligar as simulações é o objetivo do botão, e desligar as correções junto
- * seria tirar de uma criança daltônica a única correção que ela tem — a partir do menu que existe para quem
- * NÃO tem a deficiência. Um reset que faz isso é pior que a armadilha que ele deveria desfazer.
+ * `kind` does not answer that: `sim-deuter` (simulating colour blindness) and `fix-deuter` (correcting it) share
+ * `kind:'filter'`, though they serve two opposite people. It matters because the empathy menu's "restore defaults"
+ * (ADR-0028) turns the simulations off, and turning the corrections off with them would take from a colour-blind child
+ * the only correction they have — from the menu that exists for whoever does NOT have the disability. A reset that does
+ * that is worse than the trap it should undo.
  *
- * Só os 9 modos marcados simulam. Os 3 `fix-*` corrigem, os 3 `hc-direto*` corrigem, e `normal` não faz nada.
+ * Only the 9 marked modes simulate. The 3 `fix-*` correct, the 3 `hc-direto*` correct, and `normal` does nothing.
  */
 /**
- * Um modo de visão. `nome` e `desc` guardam CHAVE i18n, não texto — mesma decisão de `CenarioTema.nome` e
- * `RM_LABEL`, e pelo mesmo motivo: uma tabela de `const` com texto resolve UMA vez, no import, e fica
- * congelada no idioma do boot. Este menu é o que uma criança de baixa visão ou daltônica lê para configurar o
- * PRÓPRIO jogo; deixá-lo em português numa build em inglês tira dela a única página que ela precisava ler.
+ * A vision mode. `name` and `desc` keep an i18n KEY, not text — the same decision as `SceneryTheme.name` and
+ * `RM_LABEL`, for the same reason: a `const` table with text resolves ONCE, on import, and stays frozen in the boot's
+ * language. This menu is what a low-vision or colour-blind child reads to configure their OWN game; leaving it in
+ * Portuguese in an English build takes from them the one page they needed to read.
  *
- * Quem EXIBE resolve (`render/viz-setters`, `consumer-quiz`), e por isso este módulo continua FOLHA: dado
- * puro, sem dependência nenhuma, importável dos dois lados da fronteira.
+ * Whoever SHOWS it resolves it (`render/viz-setters`, `consumer-quiz`), and that is why this module stays a LEAF: pure
+ * data, no dependency, importable from both sides of the boundary.
  */
 export type VizMode = {
     key: string;
     kind: string;
-    nome: string;
+    name: string;
     desc: string;
     lv?: string;
     sim?: true;
@@ -33,29 +33,28 @@ export declare const VIZ_BY_KEY: Record<string, VizMode>;
 export declare const VIZ_FILTER: Record<string, string>;
 export declare const VIZ_CYCLE: string[];
 /**
- * Este modo simula uma deficiência? Chave desconhecida (ou vazia) → false, porque a pergunta que o chamador
- * está fazendo é "posso desligar isto sem tirar nada de ninguém?", e a resposta honesta diante do
- * desconhecido é não.
+ * Does this mode simulate a disability? An unknown (or empty) key → false, because the question the caller is asking is
+ * "can I turn this off without taking anything from anyone?", and the honest answer in front of the unknown is no.
  */
 export declare function simulatesDisability(key: string): boolean;
 /**
- * As CORREÇÕES de daltonismo: daltonizam a tela para quem TEM a condição. Derivadas do catálogo, nunca
- * listadas à mão — são exatamente os filtros que não simulam.
+ * The colour-blindness CORRECTIONS: they daltonise the screen for whoever HAS the condition. Derived from the catalogue,
+ * never listed by hand — they are exactly the filters that do not simulate.
  *
- * Existem como lista própria porque moram no menu de ACESSIBILIDADE VISUAL, e não no de empatia (decisão do
- * Dev, issue #60). Ficaram anos no menu errado por um motivo que este arquivo agora conserta: `kind` não
- * distinguia simular de corrigir, então o painel de empatia, que se recorta por `kind:'filter'`, arrastava as
- * três junto. Dois públicos opostos na mesma lista — quem quer sentir como é ser daltônico e quem é.
+ * They exist as a list of their own because they live in the VISUAL ACCESSIBILITY menu, and not in the empathy one (the
+ * Dev's decision, issue #60). With `kind` not telling simulating from correcting, the empathy panel, which cuts itself
+ * by `kind:'filter'`, dragged the three along: two opposite audiences in one list — whoever wants to feel what being
+ * colour-blind is like, and whoever is.
  */
 export declare const VIZ_CORRECTIONS: readonly VizMode[];
-/** Este modo precisa de um CANVAS de mundo para existir? Só os `hcnew` precisam: eles repintam texturas. */
+/** Does this mode need a world CANVAS to exist? Only the `hcnew` ones do: they repaint textures. */
 export declare function needsCanvas(key: string): boolean;
 /**
- * Os modos que funcionam em QUALQUER jogo — os que se aplicam como filtro de CSS sobre um elemento.
+ * The modes that work in ANY game — the ones applied as a CSS filter over an element.
  *
- * Derivada, nunca listada à mão: um modo novo entra na pilha certa por causa do `kind` que ele declara, e não
- * porque alguém lembrou de acrescentá-lo aqui. É a mesma regra de `VIZ_CORRECTIONS`.
+ * Derived, never listed by hand: a new mode enters the right stack because of the `kind` it declares, not because
+ * someone remembered to add it here. The same rule as `VIZ_CORRECTIONS`.
  */
 export declare const VIZ_DOM_ONLY: readonly VizMode[];
-/** Os modos que EXIGEM mundo. Complemento exato de `VIZ_DOM_ONLY` — juntos, os 16, sem sobra nem repetição. */
+/** The modes that REQUIRE a world. The exact complement of `VIZ_DOM_ONLY` — together, the 16, no leftover and no repeat. */
 export declare const VIZ_CANVAS_ONLY: readonly VizMode[];

package/dist-pkg/render/viz-modes.js

@@ -1,21 +1,21 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 export const VIZ_MODES = [
-    { key: 'normal', kind: 'normal', nome: 'viz.normal', desc: 'viz.desc.normal' },
-    { key: 'hc-direto', kind: 'hcnew', nome: 'viz.hc-direto', desc: 'viz.desc.hc-direto' },
-    { key: 'hc-direto-45', kind: 'hcnew', nome: 'viz.hc-direto-45', desc: 'viz.desc.hc-direto-45' },
-    { key: 'hc-direto-7', kind: 'hcnew', nome: 'viz.hc-direto-7', desc: 'viz.desc.hc-direto-7' },
-    { key: 'sim-deuter', sim: true, kind: 'filter', nome: 'viz.sim-deuter', desc: 'viz.desc.sim-deuter' },
-    { key: 'sim-protan', sim: true, kind: 'filter', nome: 'viz.sim-protan', desc: 'viz.desc.sim-protan' },
-    { key: 'sim-tritan', sim: true, kind: 'filter', nome: 'viz.sim-tritan', desc: 'viz.desc.sim-tritan' },
-    { key: 'fix-protan', kind: 'filter', nome: 'viz.fix-protan', desc: 'viz.desc.fix-protan' },
-    { key: 'fix-deuter', kind: 'filter', nome: 'viz.fix-deuter', desc: 'viz.desc.fix-deuter' },
-    { key: 'fix-tritan', kind: 'filter', nome: 'viz.fix-tritan', desc: 'viz.desc.fix-tritan' },
-    { key: 'lv-blur', sim: true, kind: 'lowvision', lv: 'blur', nome: 'viz.lv-blur', desc: 'viz.desc.lv-blur' },
-    { key: 'lv-haze', sim: true, kind: 'lowvision', lv: 'haze', nome: 'viz.lv-haze', desc: 'viz.desc.lv-haze' },
-    { key: 'lv-tunnel', sim: true, kind: 'lowvision', lv: 'tunnel', nome: 'viz.lv-tunnel', desc: 'viz.desc.lv-tunnel' },
-    { key: 'lv-macular', sim: true, kind: 'lowvision', lv: 'macular', nome: 'viz.lv-macular', desc: 'viz.desc.lv-macular' },
-    { key: 'lv-diabetic', sim: true, kind: 'lowvision', lv: 'diabetic', nome: 'viz.lv-diabetic', desc: 'viz.desc.lv-diabetic' },
-    { key: 'blind', sim: true, kind: 'blind', nome: 'viz.blind', desc: 'viz.desc.blind' },
+    { key: 'normal', kind: 'normal', name: 'viz.normal', desc: 'viz.desc.normal' },
+    { key: 'hc-direto', kind: 'hcnew', name: 'viz.hc-direto', desc: 'viz.desc.hc-direto' },
+    { key: 'hc-direto-45', kind: 'hcnew', name: 'viz.hc-direto-45', desc: 'viz.desc.hc-direto-45' },
+    { key: 'hc-direto-7', kind: 'hcnew', name: 'viz.hc-direto-7', desc: 'viz.desc.hc-direto-7' },
+    { key: 'sim-deuter', sim: true, kind: 'filter', name: 'viz.sim-deuter', desc: 'viz.desc.sim-deuter' },
+    { key: 'sim-protan', sim: true, kind: 'filter', name: 'viz.sim-protan', desc: 'viz.desc.sim-protan' },
+    { key: 'sim-tritan', sim: true, kind: 'filter', name: 'viz.sim-tritan', desc: 'viz.desc.sim-tritan' },
+    { key: 'fix-protan', kind: 'filter', name: 'viz.fix-protan', desc: 'viz.desc.fix-protan' },
+    { key: 'fix-deuter', kind: 'filter', name: 'viz.fix-deuter', desc: 'viz.desc.fix-deuter' },
+    { key: 'fix-tritan', kind: 'filter', name: 'viz.fix-tritan', desc: 'viz.desc.fix-tritan' },
+    { key: 'lv-blur', sim: true, kind: 'lowvision', lv: 'blur', name: 'viz.lv-blur', desc: 'viz.desc.lv-blur' },
+    { key: 'lv-haze', sim: true, kind: 'lowvision', lv: 'haze', name: 'viz.lv-haze', desc: 'viz.desc.lv-haze' },
+    { key: 'lv-tunnel', sim: true, kind: 'lowvision', lv: 'tunnel', name: 'viz.lv-tunnel', desc: 'viz.desc.lv-tunnel' },
+    { key: 'lv-macular', sim: true, kind: 'lowvision', lv: 'macular', name: 'viz.lv-macular', desc: 'viz.desc.lv-macular' },
+    { key: 'lv-diabetic', sim: true, kind: 'lowvision', lv: 'diabetic', name: 'viz.lv-diabetic', desc: 'viz.desc.lv-diabetic' },
+    { key: 'blind', sim: true, kind: 'blind', name: 'viz.blind', desc: 'viz.desc.blind' },
 ];
 export const VIZ_BY_KEY = Object.fromEntries(VIZ_MODES.map((m) => [m.key, m]));
 export const VIZ_FILTER = { 'sim-deuter': 'url(#cvd-deuter)', 'sim-protan': 'url(#cvd-protan)', 'sim-tritan': 'url(#cvd-tritan)',
@@ -23,52 +23,47 @@ export const VIZ_FILTER = { 'sim-deuter': 'url(#cvd-deuter)', 'sim-protan': 'url
     'lv-blur': 'blur(2.4px)', 'lv-haze': 'contrast(.58) brightness(1.14) blur(.6px)', 'lv-tunnel': 'blur(.5px)', 'lv-macular': '', 'lv-diabetic': 'blur(.8px)', 'blind': 'brightness(0)' };
 export const VIZ_CYCLE = VIZ_MODES.map((m) => m.key);
 /**
- * Este modo simula uma deficiência? Chave desconhecida (ou vazia) → false, porque a pergunta que o chamador
- * está fazendo é "posso desligar isto sem tirar nada de ninguém?", e a resposta honesta diante do
- * desconhecido é não.
+ * Does this mode simulate a disability? An unknown (or empty) key → false, because the question the caller is asking is
+ * "can I turn this off without taking anything from anyone?", and the honest answer in front of the unknown is no.
  */
 export function simulatesDisability(key) {
     return VIZ_BY_KEY[key]?.sim === true;
 }
 /**
- * As CORREÇÕES de daltonismo: daltonizam a tela para quem TEM a condição. Derivadas do catálogo, nunca
- * listadas à mão — são exatamente os filtros que não simulam.
+ * The colour-blindness CORRECTIONS: they daltonise the screen for whoever HAS the condition. Derived from the catalogue,
+ * never listed by hand — they are exactly the filters that do not simulate.
  *
- * Existem como lista própria porque moram no menu de ACESSIBILIDADE VISUAL, e não no de empatia (decisão do
- * Dev, issue #60). Ficaram anos no menu errado por um motivo que este arquivo agora conserta: `kind` não
- * distinguia simular de corrigir, então o painel de empatia, que se recorta por `kind:'filter'`, arrastava as
- * três junto. Dois públicos opostos na mesma lista — quem quer sentir como é ser daltônico e quem é.
+ * They exist as a list of their own because they live in the VISUAL ACCESSIBILITY menu, and not in the empathy one (the
+ * Dev's decision, issue #60). With `kind` not telling simulating from correcting, the empathy panel, which cuts itself
+ * by `kind:'filter'`, dragged the three along: two opposite audiences in one list — whoever wants to feel what being
+ * colour-blind is like, and whoever is.
  */
 export const VIZ_CORRECTIONS = VIZ_MODES.filter((m) => m.kind === 'filter' && !m.sim);
-/* ===================== AS DUAS PILHAS COM UM NOME SÓ (achado 8, item 19) ===================== */
+/* ===================== TWO STACKS UNDER ONE NAME ===================== */
 //
-// O segundo consumidor mediu, e a medição é o motivo desta seção existir:
+// What the menu calls "visual accessibility" is TWO stacks under one name — the engine's second consumer measured it:
+// the `hcnew` modes REPAINT tile TEXTURES in PIXI, and a quiz has no tiles to repaint. One stack is DOM/CSS
+// (colour-blindness filters, typography, letter case) and serves any game; the other is CANVAS (direct rendering,
+// outlines, role colours) and only exists where there is a world.
 //
-//     "O ALTO CONTRASTE NÃO VIAJA, e a razão é estrutural, não um defeito. Os modos `hcnew` REPINTAM
-//      TEXTURAS de tile na PIXI; um quiz não tem tiles, e não há o que repintar. Ou seja: o que o menu chama
-//      de 'acessibilidade visual' são DUAS pilhas com um nome só — uma de DOM/CSS (filtros de daltonismo,
-//      tipografia, caixa alta) que serve a qualquer jogo; uma de CANVAS (renderização direta, contornos,
-//      cores de papel) que só existe onde há mundo. O painel as apresenta numa lista única de 7 modos… A
-//      divisão do passo 5 precisa cortar AQUI."
+// This is the cut, and it is one of DATA, not of files — the files were already apart (`render/cvd-matrices` is pure
+// DOM; `render/high-contrast` repaints a world whose tiles it is handed). What was missing was the table SAYING which
+// stack each mode belongs to, so nobody rebuilds the answer in their head.
 //
-// Este é o corte, e ele é de DADO e não de arquivo — os arquivos já estavam separados (`render/cvd-matrices`
-// é DOM puro; `render/high-contrast` importa `core/collision.tileAt`). O que faltava era a tabela DIZER a
-// qual pilha cada modo pertence, para que ninguém mais reconstruísse a resposta de cabeça.
-//
-// E era reconstruída: o segundo consumidor escrevia
+// And it was being rebuilt: the second consumer wrote
 //     `VIZ_MODES.filter((m) => m.kind === 'normal' || (m.kind === 'filter' && !simulatesDisability(m.key)))`
-// — uma expressão que mistura DUAS perguntas diferentes ("precisa de canvas?" e "isto simula deficiência?")
-// e que todo consumidor futuro teria de reinventar, com a chance de acertar uma e errar a outra.
-/** Este modo precisa de um CANVAS de mundo para existir? Só os `hcnew` precisam: eles repintam texturas. */
+// — an expression mixing TWO different questions ("does it need a canvas?" and "does it simulate a disability?") that
+// every future consumer would have to reinvent, with the chance of getting one right and the other wrong.
+/** Does this mode need a world CANVAS to exist? Only the `hcnew` ones do: they repaint textures. */
 export function needsCanvas(key) {
     return VIZ_BY_KEY[key]?.kind === 'hcnew';
 }
 /**
- * Os modos que funcionam em QUALQUER jogo — os que se aplicam como filtro de CSS sobre um elemento.
+ * The modes that work in ANY game — the ones applied as a CSS filter over an element.
  *
- * Derivada, nunca listada à mão: um modo novo entra na pilha certa por causa do `kind` que ele declara, e não
- * porque alguém lembrou de acrescentá-lo aqui. É a mesma regra de `VIZ_CORRECTIONS`.
+ * Derived, never listed by hand: a new mode enters the right stack because of the `kind` it declares, not because
+ * someone remembered to add it here. The same rule as `VIZ_CORRECTIONS`.
  */
 export const VIZ_DOM_ONLY = VIZ_MODES.filter((m) => !needsCanvas(m.key));
-/** Os modos que EXIGEM mundo. Complemento exato de `VIZ_DOM_ONLY` — juntos, os 16, sem sobra nem repetição. */
+/** The modes that REQUIRE a world. The exact complement of `VIZ_DOM_ONLY` — together, the 16, no leftover and no repeat. */
 export const VIZ_CANVAS_ONLY = VIZ_MODES.filter((m) => needsCanvas(m.key));

package/dist-pkg/render/viz-refusal.d.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type UnavailableReason, type VisualState } from './viz-axes.js';
+/** A line ready to translate: the key and what it needs. `null` = nothing to say. */
+export interface Refusal {
+    readonly key: string;
+    /** What the child has to undo for the demonstration to be honest. */
+    readonly axis: UnavailableReason;
+}
+/**
+ * The reason's i18n key, per axis off its default.
+ *
+ * ⚠️ THREE KEYS AND NOT ONE WITH A PARAMETER, and the difference is one of translation, not style: in Portuguese
+ * «o tema» and «a correção de cor» take different articles, and «os dois» is the plural of neither. A sentence with an
+ * axis parameter would force each language to build agreement from a loose noun — exactly the defect `sr.nav.clockOne`
+ * already recorded for «às 1 horas».
+ */
+export declare const REASON_KEY: Readonly<Record<UnavailableReason, string>>;
+/**
+ * Can this simulation be offered? And if not, what to say.
+ *
+ * `null` = it can; the interface shows nothing, because a notice that always appears stops being read.
+ */
+export declare function simulationRefusal(v: VisualState): Refusal | null;
+/**
+ * Should the simulation appear DISABLED instead of vanishing?
+ *
+ * ⚠️ ALWAYS, AND IT IS ADR-0076's «never silently removed» HALF. It exists as a function with a name of its own, and not
+ * as a `!refusal` at the call site, because it answers a different question: `simulationRefusal` says *why* it cannot;
+ * this one says *that the line stays on screen*. Whoever draws needs both, and merging them would make the answer
+ * "there is no reason" look like "do not draw the line".
+ */
+export declare function showsEvenWhenUnavailable(): boolean;

package/dist-pkg/render/viz-refusal.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/viz-refusal — WHY THE SIMULATION IS NOT AVAILABLE, told to the child (ADR-0076, issue #104).
+//
+// ========================= WHAT THE REFUSAL HAS TO DO, AND WHAT IT MUST NOT DO =========================
+// ADR-0076 requires an unavailable simulation to appear **VISIBLE and explained** — «never silently removed, never
+// accepted then ignored». The two halves of that sentence describe two different defects:
+//
+//   · REMOVING SILENTLY teaches that the thing does not exist. An adult who showed the simulation to a class yesterday
+//     and cannot find it today concludes it was taken away, not that they themselves turned high contrast on.
+//   · ACCEPTING AND IGNORING is worse: the demonstration SEEMS to be running. Over an already corrected screen it shows
+//     neither the disability nor the correction; over a high-contrast theme it shows what the THEME does and not what
+//     deuteranopia does. ⚠️ It is not a weaker demonstration — **it teaches something false**.
+//
+// ⚠️ AND THE REASON IS A FACT ABOUT THE DEMONSTRATION, NEVER A REPROACH TO WHOEVER CHOSE. Whoever turned high contrast
+// on did so because they need it; whoever turned colour correction on sees better with it. The sentence says what the
+// demonstration needs to be honest, and how to go back — never "turn that off".
+//
+// ========================= WHY THIS IS A PURE MODULE =========================
+// The same shape as `ui/reach-notice`: it returns DATA (an i18n key + parameters), not ready text. The sentence belongs
+// to the interface and has to go through `t()`; returning prose from here would put a language in a module that has
+// none. And, being pure, the refusal's design can be checked in the `node` project, with no document.
+//
+// A leaf module: it imports only the types and the predicate of the two-axis model.
+import { simulationUnavailable } from './viz-axes.js';
+/**
+ * The reason's i18n key, per axis off its default.
+ *
+ * ⚠️ THREE KEYS AND NOT ONE WITH A PARAMETER, and the difference is one of translation, not style: in Portuguese
+ * «o tema» and «a correção de cor» take different articles, and «os dois» is the plural of neither. A sentence with an
+ * axis parameter would force each language to build agreement from a loose noun — exactly the defect `sr.nav.clockOne`
+ * already recorded for «às 1 horas».
+ */
+export const REASON_KEY = Object.freeze({
+    tema: 'sim.indisponivel.tema',
+    correcao: 'sim.indisponivel.correcao',
+    ambos: 'sim.indisponivel.ambos',
+});
+/**
+ * Can this simulation be offered? And if not, what to say.
+ *
+ * `null` = it can; the interface shows nothing, because a notice that always appears stops being read.
+ */
+export function simulationRefusal(v) {
+    const reason = simulationUnavailable(v);
+    return reason === null ? null : { key: REASON_KEY[reason], axis: reason };
+}
+/**
+ * Should the simulation appear DISABLED instead of vanishing?
+ *
+ * ⚠️ ALWAYS, AND IT IS ADR-0076's «never silently removed» HALF. It exists as a function with a name of its own, and not
+ * as a `!refusal` at the call site, because it answers a different question: `simulationRefusal` says *why* it cannot;
+ * this one says *that the line stays on screen*. Whoever draws needs both, and merging them would make the answer
+ * "there is no reason" look like "do not draw the line".
+ */
+export function showsEvenWhenUnavailable() {
+    return true;
+}

package/dist-pkg/render/viz-setters.d.ts

@@ -1,60 +1,67 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { type VizMode } from './viz-modes.js';
-import { type Tema, type Correcao, type VisualState } from './viz-axes.js';
+import { type Theme, type Correction, type VisualState } from './viz-axes.js';
+import type { Translate } from '../core/i18n.js';
+import { type HighContrast } from './high-contrast.js';
+import type { Store } from '../platform/storage.js';
+/** What each player's visual state is read and written through. */
+export type VisualStore = Pick<Store, 'get' | 'getJSON' | 'set' | 'setJSON'>;
 import type { DomQuery } from '../core/dom-query.js';
-import type { ComFiltro, ComTextura, Visivel, DesenhoComCirculo, AplicarFiltroCss, AlcanceDoFiltro, AplicarAltoContrasteNoDom } from './port.js';
+import type { WithFilter, WithTexture, Visible, DrawingWithCircle, ApplyCssFilter, FilterReach, ApplyHighContrastToDom } from './port.js';
 /**
- * Até onde o filtro deste modo vai. MELHORIA alcança os menus; EMPATIA fica no mundo (ver `AlcanceDoFiltro`).
- * Derivado de `sim`, do catálogo — a mesma flag que já distingue os dois, e não uma segunda lista para
- * alguém esquecer de atualizar.
+ * How far this mode's filter reaches. ENHANCEMENT reaches the menus; EMPATHY stays in the world (see `FilterReach`).
+ * Derived from the catalogue's `sim` — the same flag that already tells the two apart, not a second list for someone
+ * to forget to update.
  */
-export declare function alcanceDoModo(mode: string): AlcanceDoFiltro;
-/** Modo por chave, com o fallback do original: chave desconhecida (ou nula) CAI em `normal`. */
+export declare function reachOfMode(mode: string): FilterReach;
+/** The mode by key, with a fallback: an unknown (or null) key FALLS to `normal`. */
 export declare function resolveViz(key: string | null | undefined): VizMode;
 /**
- * O ESTADO VISUAL GUARDADO deste jogador, de qualquer das duas formas (issue #104).
+ * This player's STORED VISUAL STATE, in either of its two shapes (issue #104).
  *
- * ⚠️ ESTA FUNÇÃO É A CAIXA «um ajuste salvo antes da divisão restaura o mesmo estado visível» da definition
- * of done, e a ordem das duas leituras é a decisão inteira:
+ * ⚠️ THIS FUNCTION IS THE definition of done's box that says a setting saved before the split restores the same visible
+ * state, and the order of the two reads is the whole decision:
  *
- *   1. a chave NOVA (`visualP`), que é a única que sabe dizer dois eixos;
- *   2. na falta dela, a chave VELHA (`vizP`), que guarda a string única — e é aqui que mora o ajuste de toda
- *      criança que já jogou este jogo antes de hoje;
- *   3. na falta das duas, o padrão.
+ *   1. the NEW key (`visualP`), the only one that can express two axes;
+ *   2. without it, the OLD key (`vizP`), which keeps the single string — and where the setting of every child who
+ *      played this game before the split lives;
+ *   3. without either, the default.
  *
- * ⚠️ O RECUO NÃO É ZELO: sem ele, a primeira sessão depois da actualização apagaria o modo visual que ela
- * escolheu — e quem escolheu `fix-deuter` ou `hc-direto-7` escolheu-o porque enxerga assim. É a diferença
- * entre migrar e recomeçar.
+ * ⚠️ THE FALLBACK IS NOT ZEAL: without it, the first session after the update would erase the visual mode the child
+ * chose — and whoever chose `fix-deuter` or `hc-direto-7` chose it because that is how they see. It is the difference
+ * between migrating and starting over.
  *
- * `migrarVisual` aceita as duas formas e é idempotente, então isto pode correr quantas vezes for preciso.
+ * `migrateVisual` accepts both shapes and is idempotent, so this can run as many times as needed.
+ *
+ * 📌 THE STORE IS A PARAMETER (ADR-0232, issue #207): the page's store, built by whoever composes the page.
  */
-export declare function lerVisualGuardado(i: number): VisualState;
-/** É um dos três níveis de Renderização Direta (alto contraste)? Mesmo teste do original: `!!DIRECT_CFG[mode]`. */
+export declare function readStoredVisual(store: VisualStore, i: number): VisualState;
+/** Is it one of the three Direct Rendering (high contrast) levels? The test is `!!DIRECT_CFG[mode]`. */
 export declare function isDirectMode(mode: string): boolean;
-/** Filtro CSS da canvas no SOLO: simulação/correção de visão + realce L→Q, compostos e sem vazios. */
+/** The canvas's CSS filter in SOLO: vision simulation/correction + the L→Q enhancement, composed and with no gaps. */
 export declare function cssFilterFor(mode: string, lq: string): string;
-/** Bolinha indicadora de um viewport: só cegueira (branca) e baixa visão (verde) acendem. */
+/** A viewport's indicator dot: only blindness (white) and low vision (green) light it. */
 export declare function vizDotFor(m: VizMode | undefined): {
     visible: boolean;
     fill: number | null;
 };
-/** Bolinha GLOBAL (#viz-indicator) para um `kind`: visível, classes e rótulo de leitor de tela. */
+/** The GLOBAL dot (#viz-indicator) for a `kind`: visible, classes and screen-reader label. */
 export declare function vizIndicatorFor(kind: string): {
     on: boolean;
     blind: boolean;
     low: boolean;
     label: string;
 };
-/** Classe do overlay DOM de baixa visão (`lv-haze`/`lv-tunnel`/…); '' para qualquer outro kind. */
+/** The low-vision DOM overlay's class (`lv-haze`/`lv-tunnel`/…); '' for any other kind. */
 export declare function lvOverlayClassFor(m: VizMode): string;
-/** HTML do grupo de rádios de modos visuais (uma linha por modo; o atual marcado). Verbatim do game.js. */
-export declare function vizGroupHtml(modes: readonly VizMode[], cur: string): string;
-/** Fala do leitor de tela ao escolher um modo: prefixa "Jogador N:" só em multi-tela. */
-export declare function vizGroupSay(numPlayers: number, sel: number, nome: string): string;
-type Filtered = ComFiltro;
-type Textured = ComTextura;
-/** PIXI.Graphics da bolinha por viewport — só o que updateVpDots realmente usa. */
-type DotGfx = Visivel & DesenhoComCirculo;
+/** The HTML of the vision modes' radio group (one row per mode; the current one marked). */
+export declare function vizGroupHtml(t: Translate, modes: readonly VizMode[], cur: string): string;
+/** The screen reader's line when a mode is chosen: prefixed with the player only on several screens. */
+export declare function vizGroupSay(numPlayers: number, sel: number, name: string): string;
+type Filtered = WithFilter;
+type Textured = WithTexture;
+/** The per-viewport dot's PIXI.Graphics — only what updateVpDots really uses. */
+type DotGfx = Visible & DrawingWithCircle;
 interface ClassListHost {
     classList: {
         toggle(token: string, force?: boolean): unknown;
@@ -72,16 +79,21 @@ interface Pu {
     sprite?: Textured | null;
 }
 export interface VizSettersCtx {
-    /** O seletor do jogo (#viz-overlay, #viz-indicator, listas do painel). `DomQuery` de `core/dom-query`
-     *  desde 2026-08-26: a versão local era NÃO-GENÉRICA, e uma função genérica atribuída a uma
-     *  assinatura não-genérica é instanciada pela RESTRIÇÃO. O `El` estrutural continua abaixo — ele é a
-     *  fatia que este módulo LÊ, e `HTMLElement` a satisfaz. */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /**
+     * Where each player's visual state is kept — the page's store, built by the root (ADR-0232, issue #207). Required: a
+     * correction written nowhere is gone at the next visit, for the child who chose it because that is how they see.
+     */
+    store: VisualStore;
+    /** The game's selector (#viz-overlay, #viz-indicator, the panel's lists). `DomQuery` from `core/dom-query`: a local
+     *  NON-GENERIC version would instantiate a generic function by its CONSTRAINT when assigned to it. */
     $: DomQuery;
     body: ClassListHost;
     srSay: (s: string) => void;
-    aplicarFiltroCss: AplicarFiltroCss;
-    /** Alto contraste no DOM — o filtro não o alcança porque ele não É filtro. Issue #83. */
-    aplicarAltoContrasteNoDom: AplicarAltoContrasteNoDom;
+    applyCssFilter: ApplyCssFilter;
+    /** High contrast in the DOM — the filter does not reach it because it IS not a filter. Issue #83. */
+    applyHighContrastToDom: ApplyHighContrastToDom;
     camera: Filtered;
     worldSprite: Textured;
     parallaxLayers: Textured[];
@@ -89,19 +101,17 @@ export interface VizSettersCtx {
     getVpSpr: () => Filtered[];
     getVpDots: () => DotGfx[];
     /**
-     * Os sprites dos ITENS declarados (o array vive no jogo e pode ser recriado — por isso getter).
+     * The declared ITEMS' sprites (the array lives in the game and may be recreated — hence a getter).
      *
-     * Era `getCoinSprites`, e o nome dizia o que eles são. Mesma fatia que `render/draw` recebe desde o corte
-     * das entidades declaradas: uma lista de sprites, sem o desenho saber o que cada um representa.
+     * A list of sprites, with the drawing not knowing what each one represents — not a coin-shaped getter.
      */
     getItemSprites: () => (Textured | null | undefined)[];
     /**
-     * Como o JOGO chama os itens dele no cache de recoloração de `render/high-contrast`.
+     * What the GAME calls its items in `render/high-contrast`'s recolour cache.
      *
-     * Era `spriteTexFor('coin', mode)` — a string cravada aqui dentro. O cache já não tinha forma de moeda
-     * (ele chaveia por `(id, modo)`); quem ainda nomeava uma era este módulo. Repare no vizinho de baixo: os
-     * power-ups sempre carregaram o próprio `kind`, e a engine só o repassa. Os itens não carregavam nada, e
-     * por isso o nome tinha de estar em algum lugar — agora está do lado de quem o escolheu.
+     * The cache keys by `(id, mode)`; a `'coin'` string fixed in here would be this module naming one game's item. Note
+     * the neighbour below: power-ups always carried their own `kind`, and the engine only passes it on. The items carried
+     * nothing, so the name had to live somewhere — it lives on the side of whoever chose it.
      */
     itemTexId: string;
     getPowerups: () => readonly Pu[];
@@ -117,46 +127,74 @@ export interface VizSettersCtx {
     playerVizTex: (base: unknown, mode: string) => unknown;
     pixiFilterFor: (mode: string) => unknown;
     clearPlayerDirectCache: () => void;
+    /**
+     * A POWER-UP'S TEXTURE IN THIS VISUAL MODE, and forgetting it — through a DOOR (ADR-0228).
+     *
+     * 🔴 A power-up is a game's furniture, and so is its texture cache. What is the ENGINE's is the rule — switching visual
+     * mode repaints what is on screen —, and that rule does not need to know what a power-up is.
+     */
+    pupTexFor: (kind: string, mode: string) => unknown;
+    resetPupTexCache: () => void;
+    /**
+     * THE WORLD'S HIGH CONTRAST (`render/high-contrast`'s `createHighContrast`), built by whoever has the world — the root
+     * has none (ADR-0232 D4, issue #207). REQUIRED: the recoloured world and sprites, and their caches, are that instance's.
+     */
+    hc: Pick<HighContrast, 'worldTexFor' | 'spriteTexFor' | 'clearWorldTexCache' | 'clearSpriteTexCache'>;
+    /**
+     * The L→Q contrast enhancement's CSS fragment (`render/lq-filter`'s `createLqFilter().filter`), '' when off. REQUIRED:
+     * the enhancement is a low-vision child's, and a filter recomposed without it would drop it in silence.
+     */
+    lqFilter: () => string;
     setFrontDim: (on: boolean) => void;
     rebuildExtras: () => void;
     rebuildCoins: () => void;
-    setModoCego?: (on: boolean) => void;
+    /**
+     * The blindness empathy mode turns on the cane + audio cues: the settings store's blind-mode writer (write, persist,
+     * notify). REQUIRED (ADR-0232 D2c): the store is built by the root and passed in; a game that is its own root passes
+     * `setBlindModeValue` from `core/state`.
+     */
+    setBlindMode: (on: boolean) => void;
+    /**
+     * Writes the single LEGACY visual-mode mirror (`incl_viz`) — the settings store's `setVizModeValue`. REQUIRED for the
+     * same reason: the old readers of the global key would lose the child's mode without it.
+     */
+    setVizMode: (mode: string) => void;
     hideTouchControls: (reason?: string) => void;
     reflectVizButtons: () => void;
     renderVisualPanel: () => void;
     renderEmpathyPanel: () => void;
 }
 export interface VizSettersApi {
-    /** Multi-tela: aplica as texturas ESTÁTICAS do modo (memoizado) + a do quadro atual de cada jogador. */
+    /** Several screens: applies the mode's STATIC textures (memoised) + each player's current frame. */
     applySharedTextures(mode: string): void;
-    /** Bolinhas indicadoras por viewport (fora do filtro do viewport — visíveis mesmo em cegueira). */
+    /** Per-viewport indicator dots (outside the viewport's filter — visible even in blindness). */
     updateVpDots(): void;
-    /** Filtro PIXI de cada viewport = modo do jogador daquela tela. */
+    /** Each viewport's PIXI filter = the mode of that screen's player. */
     applyVpFilters(): void;
-    /** Troca o modo de UM jogador: persiste, invalida o render estático e reaplica pelo caminho certo. */
+    /** Changes ONE player's mode: persists, invalidates the static render and reapplies by the right path. */
     setPlayerViz(i: number, mode: string): void;
     /**
-     * O ESTADO INTEIRO de um jogador, e os DOIS escritores por eixo (#104).
+     * A player's WHOLE state, and the TWO per-axis writers (#104).
      *
-     * ⚠️ Os dois de eixo existem separados porque é isso que um painel de dois controles precisa: mexer no
-     * TEMA sem tocar na correção, e vice-versa. Enquanto havia um campo só, «mexer num» significava
-     * inevitavelmente «apagar o outro» — e era o defeito, não a API.
+     * ⚠️ The per-axis writers are separate because that is what a two-control panel needs: changing the THEME without
+     * touching the correction, and vice versa. With a single field, changing one inevitably meant erasing the other — and
+     * that was the defect, not the API.
      */
-    setVisualDoJogador(i: number, v: VisualState): void;
-    setTemaDoJogador(i: number, tema: Tema): void;
-    setCorrecaoDoJogador(i: number, correcao: Correcao): void;
-    /** Caminho SOLO: filtro CSS na canvas + texturas globais + overlay DOM + bolinha. */
+    setPlayerVisual(i: number, v: VisualState): void;
+    setPlayerTheme(i: number, theme: Theme): void;
+    setPlayerCorrection(i: number, correction: Correction): void;
+    /** The SOLO path: CSS filter on the canvas + global textures + DOM overlay + dot. */
     applyVizGlobal(v: VisualState): void;
-    /** Reaplica tudo depois de uma mudança estrutural (cenário, nº de telas). */
+    /** Reapplies everything after a structural change (scenery, number of screens). */
     reapplyVizAll(): void;
-    /** Bolinha global (#viz-indicator) para um `kind`. */
+    /** The global dot (#viz-indicator) for a `kind`. */
     updateVizIndicator(kind: string): void;
-    /** Invalida os caches de textura direta (mundo/moeda/power-up/jogador) e re-renderiza. */
+    /** Invalidates the direct texture caches (world/sprites/power-ups/player) and re-renders. */
     rebakeDirect(): void;
-    /** Grupo de rádios de modos visuais nos painéis (visual/empatia). */
+    /** The vision modes' radio group in the panels (visual/empathy). */
     renderVizGroup(listSel: string, tabsSel: string, modes: readonly VizMode[]): void;
-    /** Os DOIS eixos do painel visual (#104). Irmão do de cima — ver a nota na implementação. */
-    renderEixosVisuais(listSel: string, tabsSel: string): void;
+    /** The visual panel's TWO axes (#104). The sibling of the one above — see the note in the implementation. */
+    renderVisualAxes(listSel: string, tabsSel: string): void;
 }
 export declare function initVizSetters(ctx: VizSettersCtx): VizSettersApi;
 export {};