@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/typo-choices.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { FONT_GROUPS, FONT_BY_KEY, fontRole, faceAvailable } from './fonts.js';
+/**
+ * A key is selectable when it exists in the catalog, is not marked `.off` (licence pending, etc.) — and is
+ * `geral`.
+ *
+ * ⚠️ WITHOUT THE THIRD TERM (issue #87) the menu would stop OFFERING the handwriting faces and they would stay
+ * SELECTABLE by any other path — `resolveFontKey` of a stored key, a `data-font` in a consumer's markup. "Not in the
+ * list" and "cannot be chosen" have to be the same statement, or the list is only a suggestion.
+ */
+export function isSelectableFont(k, installed) {
+    const it = FONT_BY_KEY[k];
+    return !!it && faceAvailable(it, installed) && fontRole(it) === 'geral';
+}
+/**
+ * Maps a selectable font key to the CSS it drives. The three canonical fonts (atkinson/andika/lexend) use
+ * dedicated data-fonte values (Lexend's keeps the BDA letter/word spacing tied to data-fonte="dislexia"); every
+ * other catalog font goes through --font-custom with a generic fallback by family (serif/cursive/none).
+ */
+export function fontCssTarget(k, it) {
+    // ⚠️ THE THREE CANONICAL FACES ARE NOT CURSIVE, and answering `false` for them is a statement, not an oversight:
+    // Atkinson, Andika and Lexend are reading faces, and it is exactly on them that the BDA spacing must hold.
+    if (k === 'atkinson')
+        return { font: 'padrao', customFamily: null, cursive: false };
+    if (k === 'andika')
+        return { font: 'alfabetizacao', customFamily: null, cursive: false };
+    if (k === 'lexend')
+        return { font: 'dislexia', customFamily: null, cursive: false };
+    // `joined` is the word the field's own documentation uses — "is this a JOINED face?".
+    const joined = it.fb === 'cursive';
+    const suffix = it.fb === 'serif' ? ',Georgia,serif' : joined ? ',cursive' : '';
+    return { font: 'custom', customFamily: `'${it.fam}'${suffix}`, cursive: joined };
+}
+/**
+ * ONE row of the list, from a catalogue face. A function of its own so the gate of the `.off` mechanism can exercise it
+ * with a FAKE face: a case that depends on the catalogue's composition fails every time the roster changes.
+ *
+ * The mechanism is needed (issue #87, item 4): the **Ronde** can only be offered if one of three faces is installed,
+ * because two of them are free for personal use only and cannot be bundled.
+ */
+export function fontRow(t, it, fontKey, installed) {
+    // ⚠️ THE SAME question `isSelectableFont` asks, through the SAME function. Two answers would give a clickable row the
+    // click refuses — or, worse, a grey row that `resolveFontKey` accepts by another path. "Not available" and "cannot be
+    // chosen" have to be the same statement.
+    const disabled = !faceAvailable(it, installed);
+    // `d` and `off` hold KEYS too. The dash joining them is punctuation, not a sentence — the two halves are independent
+    // and each translates on its own.
+    const desc = it.d ? t(it.d) : '', reason = it.off ? t(it.off) : '';
+    const note = desc ? desc + (disabled ? ' — ' + reason : '') : disabled ? reason : '';
+    return { key: it.k, fam: it.fam, selected: fontKey === it.k, disabled, note };
+}
+/** Pure view-model for the typography list: which row is selected/disabled and its note, per catalog group. */
+export function typoGroups(t, fontKey, installed) {
+    // ⚠️ ONLY THE GENERAL FACES ENTER THE LIST (ADR-0012 amendment, issue #87). The handwriting faces exist for the child
+    // to LEARN to read cursive — that is subject matter, and it lives INSIDE the activities, on buttons of their own.
+    // Offering them here would hand the child the subject as an obstacle everywhere they only want to navigate the menu.
+    //
+    // A group left with no general face disappears from the list, instead of appearing as an empty heading.
+    return FONT_GROUPS.map((g) => ({
+        g: t(g.g), // `g` holds an i18n KEY (see ui/fonts)
+        rows: g.items.filter((it) => fontRole(it) === 'geral').map((it) => fontRow(t, it, fontKey, installed)),
+    })).filter((group) => group.rows.length > 0);
+}
+/** The id of a face's button. It comes from the catalogue KEY, which is unique by construction (`FONT_BY_KEY`). */
+export const typoControlId = (key) => `typo-font-${key}`;
+/**
+ * What a font row SAYS, before any node exists — the shape the kit consumes.
+ *
+ * ⚠️ `shape: 'radio'` and not a switch: independent switches announcing on/off to choose ONE font say the opposite of
+ * the ADR-0012 amendment, «THE MENU IS A CHOICE, NOT A TOGGLE […] One font is active; the others are alternatives, not
+ * switches.»
+ *
+ * 📌 The note goes into the HINT — which `fillExplain` takes to the footer — and ALSO into the accessible name, because
+ * whoever does not see the row needs to hear who that face is for without hunting for the footer.
+ */
+export function typoRowSpec(row) {
+    return {
+        id: typoControlId(row.key),
+        label: row.fam,
+        ...(row.note ? { hint: row.note } : {}),
+        shape: 'radio',
+        ariaLabel: row.fam + (row.note ? ' — ' + row.note : ''),
+    };
+}

package/dist-pkg/ui/visual-axes-panel.d.ts

@@ -1,48 +1,12 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type Tema, type Correcao, type VisualState } from '../render/viz-axes.js';
-/** O rótulo de cada tema. Chave i18n — quem exibe resolve, como todo o resto do menu. */
-export declare const ROTULO_DO_TEMA: Readonly<Record<Tema, string>>;
-/** O rótulo de cada correção de cor. */
-export declare const ROTULO_DA_CORRECAO: Readonly<Record<Correcao, string>>;
-/**
- * Os rótulos CURTOS, para os ícones da barra rápida — «7:1», «deuteranopia».
- *
- * ⚠️ SÃO AS CHAVES QUE JÁ EXISTIAM (`contrast.*`, `cvd.*`), re-chaveadas por eixo. A barra rápida sempre
- * falou curto porque anuncia UM ícone de cada vez, e o painel sempre falou por extenso porque a criança está
- * a ler uma lista — a diferença é de contexto e sobrevive à divisão. Reaproveitar em vez de traduzir de novo
- * é o que mantém a mesma palavra nos dois sítios.
- */
-export declare const CURTO_DO_TEMA: Readonly<Record<Tema, string>>;
-export declare const CURTO_DA_CORRECAO: Readonly<Record<Correcao, string>>;
-/** Os dois eixos, como o painel os identifica no DOM. */
-export type EixoVisual = 'tema' | 'correcao';
-/** Um tradutor, igual ao que o resto da interface recebe. */
-export type Tradutor = (chave: string, params?: Record<string, string | number>) => string;
-/**
- * As linhas de UM eixo, no formato de rádio que o painel já usa.
- *
- * ⚠️ RÁDIO E NÃO SETE BOTÕES, e o motivo sobrevive à divisão: DENTRO de um eixo os valores continuam
- * exclusivos — um tema de cada vez, uma correção de cada vez. O que deixou de ser exclusivo é a relação
- * ENTRE os eixos, e é por isso que eles viram dois rádios em vez de um.
- *
- * ⚠️ E MANTÉM-SE A FORMA DE LINHA VISÍVEL, não um `<select>`. O `settings-visual` regista o erro que o Dev
- * apanhou na primeira tentativa: dentro de uma caixa fechada, um controle cuja razão de existir é ser ACHADO
- * por quem enxerga mal fica «quase o mesmo que não ter movido».
- */
-export declare function linhasDoEixo(eixo: EixoVisual, valores: readonly string[], rotulos: Readonly<Record<string, string>>, atual: string, t: Tradutor): string;
-/**
- * Os DOIS eixos, um a seguir ao outro, com um título cada.
- *
- * O título existe porque dois rádios seguidos sem nome são um rádio de oito para quem lê depressa — e essa
- * leitura é exactamente o mal-entendido que a divisão existe para desfazer.
- */
-export declare function eixosHtml(v: VisualState, t: Tradutor): string;
-/** O que um clique num botão do painel quer dizer. `null` quando o botão não é de eixo nenhum. */
-export interface EscolhaDeEixo {
-    readonly eixo: EixoVisual;
-    readonly valor: string;
-}
-export declare function escolhaDoBotao(dataset: {
-    eixo?: string;
-    valor?: string;
-}): EscolhaDeEixo | null;
+import { axisRows as linhasDoEixoDeRender, axesHtml as eixosHtmlDeRender, buttonChoice as escolhaDoBotaoDeRender, type VisualAxis as EixoVisualDeRender, type Translator as TradutorDeRender, type AxisChoice as EscolhaDeEixoDeRender } from '../render/viz-axes-labels.js';
+export declare const THEME_LABEL: Readonly<Record<import("../core/visual-state.js").Theme, string>>;
+export declare const CORRECTION_LABEL: Readonly<Record<import("../core/visual-state.js").Correction, string>>;
+export declare const SHORT_THEME: Readonly<Record<import("../core/visual-state.js").Theme, string>>;
+export declare const SHORT_CORRECTION: Readonly<Record<import("../core/visual-state.js").Correction, string>>;
+export declare const axisRows: typeof linhasDoEixoDeRender;
+export declare const axesHtml: typeof eixosHtmlDeRender;
+export declare const buttonChoice: typeof escolhaDoBotaoDeRender;
+export type VisualAxis = EixoVisualDeRender;
+export type Translator = TradutorDeRender;
+export type AxisChoice = EscolhaDeEixoDeRender;

package/dist-pkg/ui/visual-axes-panel.js

@@ -1,95 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/visual-axes-panel — O MENU VISUAL COM DOIS CONTROLES (ADR-0076, issue #104), na metade pura.
-//
-// ========================= O COMENTÁRIO QUE AUTORIZA ESTA MUDANÇA =========================
-// O `ui/settings-visual` justifica o controle ÚNICO com estas palavras, e elas continuam lá, verdadeiras
-// sobre o dia em que foram escritas:
-//
-//     «Os sete vivem num CONTROLE SÓ, e isso não é economia de espaço: `p.viz` guarda UM valor. Dois
-//      controles separados se sobrescreveriam em silêncio — a criança escolheria a correção, depois o
-//      contraste, e perderia a correção sem nada dizer que perdeu.»
-//
-// ⚠️ A RAZÃO QUE ELE DÁ DEIXOU DE EXISTIR. `p.viz` já não guarda um valor: guarda dois eixos mais a
-// simulação, e os escritores por eixo (`setTemaDoJogador`/`setCorrecaoDoJogador`) mexem num sem tocar no
-// outro. O controle único era a forma honesta de contar uma exclusividade REAL; mantê-lo agora seria contar
-// uma exclusividade que já não existe — e continuar a negar os dois a quem precisa dos dois.
-//
-// ========================= OS NOMES DOS PADRÕES SÃO DECISÃO, NÃO ROTINA =========================
-// ⚠️ «Tema padrão» e «Visão tricromática», e o ADR-0076 fecha a *definition of done* com a regra que os
-// escolheu: **nenhum rótulo de padrão diagnostica quem lê**. `modo sem deficiência visual` foi oferecido e
-// recusado — ele diz à criança o que ela NÃO é, no menu que ela abriu para conseguir jogar. Um padrão
-// chama-se pelo que ele É.
-//
-// E `Modo padrão` (o `viz.normal` de hoje) deixa de servir aqui: era o neutro PARTILHADO, de quando os dois
-// eixos eram um só. Com dois controles, um «padrão» sem dizer padrão de QUÊ é ambíguo em ambos.
-//
-// Módulo puro: devolve HTML e chaves i18n, não toca documento nenhum. Quem monta é o `render/viz-setters`.
-import { TEMAS, CORRECOES } from '../render/viz-axes.js';
-/** O rótulo de cada tema. Chave i18n — quem exibe resolve, como todo o resto do menu. */
-export const ROTULO_DO_TEMA = Object.freeze({
-    padrao: 'eixo.tema.padrao',
-    hc3: 'viz.hc-direto',
-    hc45: 'viz.hc-direto-45',
-    hc7: 'viz.hc-direto-7',
-});
-/** O rótulo de cada correção de cor. */
-export const ROTULO_DA_CORRECAO = Object.freeze({
-    tricro: 'eixo.correcao.tricro',
-    protan: 'viz.fix-protan',
-    deuter: 'viz.fix-deuter',
-    tritan: 'viz.fix-tritan',
-});
-/**
- * Os rótulos CURTOS, para os ícones da barra rápida — «7:1», «deuteranopia».
- *
- * ⚠️ SÃO AS CHAVES QUE JÁ EXISTIAM (`contrast.*`, `cvd.*`), re-chaveadas por eixo. A barra rápida sempre
- * falou curto porque anuncia UM ícone de cada vez, e o painel sempre falou por extenso porque a criança está
- * a ler uma lista — a diferença é de contexto e sobrevive à divisão. Reaproveitar em vez de traduzir de novo
- * é o que mantém a mesma palavra nos dois sítios.
- */
-export const CURTO_DO_TEMA = Object.freeze({
-    padrao: 'contrast.off', hc3: 'contrast.3', hc45: 'contrast.45', hc7: 'contrast.7',
-});
-export const CURTO_DA_CORRECAO = Object.freeze({
-    tricro: 'cvd.off', protan: 'cvd.protan', deuter: 'cvd.deuter', tritan: 'cvd.tritan',
-});
-/**
- * As linhas de UM eixo, no formato de rádio que o painel já usa.
- *
- * ⚠️ RÁDIO E NÃO SETE BOTÕES, e o motivo sobrevive à divisão: DENTRO de um eixo os valores continuam
- * exclusivos — um tema de cada vez, uma correção de cada vez. O que deixou de ser exclusivo é a relação
- * ENTRE os eixos, e é por isso que eles viram dois rádios em vez de um.
- *
- * ⚠️ E MANTÉM-SE A FORMA DE LINHA VISÍVEL, não um `<select>`. O `settings-visual` regista o erro que o Dev
- * apanhou na primeira tentativa: dentro de uma caixa fechada, um controle cuja razão de existir é ser ACHADO
- * por quem enxerga mal fica «quase o mesmo que não ter movido».
- */
-export function linhasDoEixo(eixo, valores, rotulos, atual, t) {
-    return valores.map((valor) => {
-        const sel = valor === atual;
-        return `<div class="ctrl-row"><span><strong>${t(rotulos[valor])}</strong></span>`
-            + `<button class="mode-btn${sel ? ' is-on' : ''}" role="radio" aria-checked="${sel}"`
-            + ` data-eixo="${eixo}" data-valor="${valor}" type="button">${sel ? t('viz.escolhido') : t('viz.escolher')}</button></div>`;
-    }).join('');
-}
-/**
- * Os DOIS eixos, um a seguir ao outro, com um título cada.
- *
- * O título existe porque dois rádios seguidos sem nome são um rádio de oito para quem lê depressa — e essa
- * leitura é exactamente o mal-entendido que a divisão existe para desfazer.
- */
-export function eixosHtml(v, t) {
-    return `<h3 class="opt-sub">${t('eixo.tema.titulo')}</h3>`
-        + linhasDoEixo('tema', TEMAS, ROTULO_DO_TEMA, v.tema, t)
-        + `<h3 class="opt-sub">${t('eixo.correcao.titulo')}</h3>`
-        + linhasDoEixo('correcao', CORRECOES, ROTULO_DA_CORRECAO, v.correcao, t);
-}
-export function escolhaDoBotao(dataset) {
-    const { eixo, valor } = dataset;
-    if (eixo !== 'tema' && eixo !== 'correcao')
-        return null;
-    if (!valor)
-        return null;
-    const validos = eixo === 'tema' ? TEMAS : CORRECOES;
-    return validos.includes(valor) ? { eixo, valor } : null;
-}
+// ui/visual-axes-panel — the two visual axes' labels, rows and click reading (ADR-0076): the names cartridges import from ui.
+//
+// The module lives in `render/viz-axes-labels` since issue #167: `render/viz-setters` uses it, and render may not import ui
+// (ADR-0173). These names stay, bound to the same values and types.
+import { THEME_LABEL as ROTULO_DO_TEMADeRender, CORRECTION_LABEL as ROTULO_DA_CORRECAODeRender, SHORT_THEME as CURTO_DO_TEMADeRender, SHORT_CORRECTION as CURTO_DA_CORRECAODeRender, axisRows as linhasDoEixoDeRender, axesHtml as eixosHtmlDeRender, buttonChoice as escolhaDoBotaoDeRender, } from '../render/viz-axes-labels.js';
+export const THEME_LABEL = ROTULO_DO_TEMADeRender;
+export const CORRECTION_LABEL = ROTULO_DA_CORRECAODeRender;
+export const SHORT_THEME = CURTO_DO_TEMADeRender;
+export const SHORT_CORRECTION = CURTO_DA_CORRECAODeRender;
+export const axisRows = linhasDoEixoDeRender;
+export const axesHtml = eixosHtmlDeRender;
+export const buttonChoice = escolhaDoBotaoDeRender;

package/dist-pkg/ui/visual-choices.d.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { HcRoleKey } from '../render/hc-role-data.js';
+import { type VizMode } from '../render/viz-modes.js';
+export type { HcRoleKey as RoleKey } from '../render/hc-role-data.js';
+type RoleKey = HcRoleKey;
+export type RGB = readonly [number, number, number];
+/**
+ * EVERYTHING this menu writes into `p.viz`: the 4 contrast levels PLUS the 3 colour-blindness corrections, which live
+ * here by the Dev's decision (#60) — in the empathy panel a colour-blind child would have had to enter the menu for
+ * "feeling what a disability is like" to find the correction for the one they have.
+ *
+ * The seven live in ONE control, and that is not about saving space: `p.viz` holds ONE value. Two separate controls
+ * would overwrite each other silently — the child would pick the correction, then the contrast, and lose the
+ * correction with nothing saying so. One list tells the truth about the exclusivity.
+ */
+export declare const VISUAL_MODES: readonly string[];
+/** Short announcement labels. */
+export declare const CONTRAST_LABELS: Readonly<Record<string, string>>;
+export declare const ROLE_KEYS: readonly RoleKey[];
+/** Readable labels for the color-blocking roles. */
+export declare const ROLE_LABELS: Readonly<Record<RoleKey, string>>;
+/**
+ * The 7 modes as the panel OFFERS them: a radio list, with a name and a description on each row.
+ *
+ * Not a `<select>`, and the Dev caught that immediately: inside a `<select>` the corrections become one closed line in
+ * a closed box. For a control whose reason to exist is to be FOUND by someone who sees poorly, hiding it behind a
+ * click is almost the same as not offering it.
+ *
+ * Radio, and not seven buttons: `p.viz` holds ONE value, and the exclusivity is said by the shape of the control
+ * instead of being discovered by losing the correction just chosen.
+ */
+export declare const VISUAL_MODE_LIST: readonly VizMode[];
+/**
+ * `viz` when it is a mode of THIS menu (contrast or correction), otherwise 'normal'.
+ *
+ * Named for what it returns: a name that said "contrast" would lie when it returns `fix-deuter`, and a name that lies
+ * about what it returns is worse than a long one.
+ */
+export declare function resolveVisualMode(viz: string): string;
+/** i18n KEY of a contrast level's label; unknown modes fall back to the 'off' key. Resolve with `t()`. */
+export declare function contrastLabel(mode: string): string;
+export declare function clamp01(t: number): number;
+/**
+ * i18n KEY of the L->Q slider label ('lq.off'/'lq.linear'/'lq.mixed'/'lq.quadratic'). The label belongs to the L->Q
+ * feature, so it lives with the filter that owns it (render/lq-filter) and is re-exported here under the name this
+ * overlay has always used. Two copies of one rule is one copy too many: only the owner may change what the levels
+ * mean. Callers resolve with `t()` — see the note on lqName about the `t` shadowing.
+ */
+export { lqName as lqLabel } from '../render/lq-filter.js';
+/**
+ * THE FOUR POSITIONS OF THE CONTRAST BOOST, chosen with left and right (ADR-0151): off, linear, mixed and quadratic —
+ * «da mesma forma que se troca o número de jogadores, e não através de uma barra».
+ *
+ * ⚠️ THE "LINEAR" VALUE CANNOT BE ZERO: `setLq(0)` turns the filter off, and any value above turns the curve on. 0.05
+ * is the most linear value that still turns the filter on. Mixed is the middle, and quadratic is the whole S-curve.
+ * Each position falls within the range `lqName` already gives its name.
+ */
+export declare const LQ_STEPS: readonly number[];
+/**
+ * Which position a continuous value is in — including one STORED by the old slider (0.35, 0.7…). By `lqName`'s range,
+ * not by the nearest value: the NAME the child heard has to stay the name now.
+ */
+export declare function lqPosition(amount: number): number;
+/** t (0..1) -> slider percent (0..100, rounded) — mirrors `Math.round(lqT*100)`.
+ *  @deprecated Since ADR-0151 the boost is chosen by STEPS (`LQ_STEPS`/`lqPosition`); kept for consumers.
+ *  ⚠️ It has no reader inside the engine: that debt is said here so that it stays in view. */
+export declare function lqPercent(t: number): number;
+/** slider percent (any number) -> clamped t (0..1) — mirrors `+lq.value/100` fed into setLq's clamp.
+ *  @deprecated Since ADR-0151 the boost is chosen by STEPS; kept for consumers. */
+export declare function lqFromPercent(pct: number): number;
+/** Defensive clamp when the player count shrank — mirrors `if(selVizPlayer>=numPlayers)selVizPlayer=0`. */
+export declare function clampSelectedPlayer(selected: number, playerCount: number): number;
+/** [r,g,b] (0..255) -> '#rrggbb'. */
+export declare function rgbToHex(rgb: RGB): string;
+/** Shared on/off button label used by this panel's toggle buttons. */
+export declare function onOffLabel(t: Translate, on: boolean): string;

package/dist-pkg/ui/visual-choices.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/visual-choices — WHAT A VISUAL CHOICE IS, with no document anywhere near it.
+//
+// 📌 THE SUITE HAD ALREADY DRAWN THIS SEAM, which is what makes the cut a reading and not an opinion:
+// `tests/settings-visual.node.test.js` imports exactly these names and nothing else, and the node project mounts no
+// document — so whoever wrote those cases had to know where the panel stopped being a panel. It is the fourth module to
+// come out this way, after `ui/audio-choices`, `ui/typo-choices` and `ui/control-choices`.
+//
+// What lives here answers «what are the positions, what is each one called, and what does a value mean»; what stayed in
+// `ui/settings-visual` is the work its name never mentioned — finding the controls, wiring them, and reflecting the
+// choice on three surfaces.
+import { toggleLabel } from './dom.js';
+import { CONTRAST_LEVELS } from '../core/visual-cycles.js';
+import { HC_ROLE_KEYS } from '../render/hc-role-data.js';
+import { VIZ_CORRECTIONS, VIZ_MODES } from '../render/viz-modes.js';
+/**
+ * EVERYTHING this menu writes into `p.viz`: the 4 contrast levels PLUS the 3 colour-blindness corrections, which live
+ * here by the Dev's decision (#60) — in the empathy panel a colour-blind child would have had to enter the menu for
+ * "feeling what a disability is like" to find the correction for the one they have.
+ *
+ * The seven live in ONE control, and that is not about saving space: `p.viz` holds ONE value. Two separate controls
+ * would overwrite each other silently — the child would pick the correction, then the contrast, and lose the
+ * correction with nothing saying so. One list tells the truth about the exclusivity.
+ */
+export const VISUAL_MODES = [...CONTRAST_LEVELS, ...VIZ_CORRECTIONS.map((m) => m.key)];
+const VISUAL_MODE_SET = new Set(VISUAL_MODES);
+/** Short announcement labels. */
+// i18n keys, not text. The ratios look like universal numbers, but '4,5:1' uses the pt-BR decimal comma and becomes
+// '4.5:1' in English — and 'off' is a word in each language.
+export const CONTRAST_LABELS = { normal: 'contrast.off', 'hc-direto': 'contrast.3', 'hc-direto-45': 'contrast.45', 'hc-direto-7': 'contrast.7' };
+export const ROLE_KEYS = HC_ROLE_KEYS;
+/** Readable labels for the color-blocking roles. */
+export const ROLE_LABELS = { hazard: 'perigo (lava)', climb: 'escalável (escada/trampolim)', water: 'água', gate: 'portão' };
+/**
+ * The 7 modes as the panel OFFERS them: a radio list, with a name and a description on each row.
+ *
+ * Not a `<select>`, and the Dev caught that immediately: inside a `<select>` the corrections become one closed line in
+ * a closed box. For a control whose reason to exist is to be FOUND by someone who sees poorly, hiding it behind a
+ * click is almost the same as not offering it.
+ *
+ * Radio, and not seven buttons: `p.viz` holds ONE value, and the exclusivity is said by the shape of the control
+ * instead of being discovered by losing the correction just chosen.
+ */
+export const VISUAL_MODE_LIST = VIZ_MODES.filter((m) => m.kind === 'normal' || m.kind === 'hcnew').concat(VIZ_CORRECTIONS);
+/**
+ * `viz` when it is a mode of THIS menu (contrast or correction), otherwise 'normal'.
+ *
+ * Named for what it returns: a name that said "contrast" would lie when it returns `fix-deuter`, and a name that lies
+ * about what it returns is worse than a long one.
+ */
+export function resolveVisualMode(viz) {
+    return VISUAL_MODE_SET.has(viz) ? viz : 'normal';
+}
+/** i18n KEY of a contrast level's label; unknown modes fall back to the 'off' key. Resolve with `t()`. */
+export function contrastLabel(mode) {
+    return CONTRAST_LABELS[mode] ?? CONTRAST_LABELS.normal;
+}
+export function clamp01(t) {
+    return Math.max(0, Math.min(1, t));
+}
+/**
+ * i18n KEY of the L->Q slider label ('lq.off'/'lq.linear'/'lq.mixed'/'lq.quadratic'). The label belongs to the L->Q
+ * feature, so it lives with the filter that owns it (render/lq-filter) and is re-exported here under the name this
+ * overlay has always used. Two copies of one rule is one copy too many: only the owner may change what the levels
+ * mean. Callers resolve with `t()` — see the note on lqName about the `t` shadowing.
+ */
+export { lqName as lqLabel } from '../render/lq-filter.js';
+import { lqName } from '../render/lq-filter.js';
+/**
+ * THE FOUR POSITIONS OF THE CONTRAST BOOST, chosen with left and right (ADR-0151): off, linear, mixed and quadratic —
+ * «da mesma forma que se troca o número de jogadores, e não através de uma barra».
+ *
+ * ⚠️ THE "LINEAR" VALUE CANNOT BE ZERO: `setLq(0)` turns the filter off, and any value above turns the curve on. 0.05
+ * is the most linear value that still turns the filter on. Mixed is the middle, and quadratic is the whole S-curve.
+ * Each position falls within the range `lqName` already gives its name.
+ */
+export const LQ_STEPS = [0, 0.05, 0.5, 1];
+/**
+ * Which position a continuous value is in — including one STORED by the old slider (0.35, 0.7…). By `lqName`'s range,
+ * not by the nearest value: the NAME the child heard has to stay the name now.
+ */
+export function lqPosition(amount) {
+    return Math.max(0, ['lq.off', 'lq.linear', 'lq.mixed', 'lq.quadratic'].indexOf(lqName(amount)));
+}
+/** t (0..1) -> slider percent (0..100, rounded) — mirrors `Math.round(lqT*100)`.
+ *  @deprecated Since ADR-0151 the boost is chosen by STEPS (`LQ_STEPS`/`lqPosition`); kept for consumers.
+ *  ⚠️ It has no reader inside the engine: that debt is said here so that it stays in view. */
+export function lqPercent(t) {
+    return Math.round(clamp01(t) * 100);
+}
+/** slider percent (any number) -> clamped t (0..1) — mirrors `+lq.value/100` fed into setLq's clamp.
+ *  @deprecated Since ADR-0151 the boost is chosen by STEPS; kept for consumers. */
+export function lqFromPercent(pct) {
+    return clamp01(pct / 100);
+}
+/** Defensive clamp when the player count shrank — mirrors `if(selVizPlayer>=numPlayers)selVizPlayer=0`. */
+export function clampSelectedPlayer(selected, playerCount) {
+    return selected >= playerCount ? 0 : selected;
+}
+/** [r,g,b] (0..255) -> '#rrggbb'. */
+export function rgbToHex(rgb) {
+    return '#' + rgb.map((n) => n.toString(16).padStart(2, '0')).join('');
+}
+/** Shared on/off button label used by this panel's toggle buttons. */
+export function onOffLabel(t, on) {
+    return toggleLabel(t, on);
+}

package/dist-pkg/ui/vlibras.d.ts

@@ -1,11 +1,34 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-/** Estado do modo pessoa surda. Escolha da PESSOA, persistida — não inferência sobre um widget de terceiro. */
-export declare let librasOpen: boolean;
-export declare function setOnLibrasChange(fn: () => void): void;
-export declare function vlibrasSay(text: string): void;
-/** O modo pessoa surda está ligado? Lê o NOSSO estado — nunca mais a geometria do widget. */
-export declare function vlibrasOpen(): boolean;
-/** Liga/desliga o modo pessoa surda. Um toggle de verdade: o estado é nosso, então ele sempre alterna. */
-export declare function toggleLibras(): void;
-/** Mantido para o laço do jogo, que o chama a cada quadro. Já não decide nada — o estado é nosso. */
-export declare function vlTick(): void;
+import type { Translate } from '../core/i18n.js';
+import type { Store } from '../platform/storage.js';
+/** What deaf mode is read and written through: the page's store, built by the root (ADR-0232, issue #207). */
+export type LibrasStore = Pick<Store, 'getBool' | 'setBool'>;
+/** What a deaf mode is built over. */
+export interface LibrasPorts {
+    /** Where the hidden node the interpreter clicks lives (its `body`), and where the widget's access button is looked for. */
+    readonly doc: Document;
+    /** Where the widget's close event is dispatched, and whose timer drains the one-utterance queue. */
+    readonly win: Pick<Window, 'dispatchEvent' | 'setTimeout'>;
+    /** The page's store: the person's choice is read once, at build, and written at each toggle. */
+    readonly store: LibrasStore;
+    /** Milliseconds now — the queue's clock (`Date.now`). */
+    readonly now: () => number;
+}
+/** One root's deaf mode. */
+export interface Libras {
+    /** Is deaf mode on? Reads OUR state — never the widget's geometry. */
+    readonly isOpen: () => boolean;
+    /** Turns deaf mode on/off. A real toggle: the state is ours, so it always flips; the confirmation is signed in `t`'s language. */
+    readonly toggle: (t: Translate) => void;
+    /** Signs in Libras: sends the text to the interpreter (only while it is open). A queue of 1 — a new utterance replaces the pending one. */
+    readonly say: (text: string) => void;
+    /** Kept for a game loop that calls it every frame: it opens the interpreter for a choice restored from storage. It decides nothing. */
+    readonly tick: () => void;
+    /** Runs `fn` when the mode opens or closes (a host's reflow); returns its release. */
+    readonly onChange: (fn: () => void) => () => void;
+}
+/**
+ * Builds a deaf mode. The PERSON's choice, persisted — not an inference about a third-party widget — read from the store
+ * here, at build, never at import (ADR-0232).
+ */
+export declare function createLibras({ doc, win, store, now }: LibrasPorts): Libras;

package/dist-pkg/ui/vlibras.js

@@ -1,87 +1,64 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/vlibras.ts — MODO PESSOA SURDA (intérprete de Libras) — Estágio 4, Tier 1.
-//
-// DOIS DEFEITOS CONSERTADOS AQUI, e eles têm a mesma raiz.
-//
-// `librasOpen` era deduzido da GEOMETRIA do botão de acesso do VLibras: altura zero ou sem `offsetParent`
-// significava "o painel está aberto". Isso funcionava enquanto o widget renderizava dentro do nosso
-// `<div vw>`. Ele parou — hoje ele anexa `#vlibras-access-wrapper` direto no `<body>` —, e o que sobrou no
-// nosso markup é um div VAZIO, de 747×0. Altura zero. Então o detector respondia "aberto" para sempre:
-//
-//   1. o layout reservava 380px à direita para um intérprete inexistente e empurrava o jogo para fora da
-//      tela (medido: canvas em `left: -136`);
-//   2. o toggle não desligava, porque mandava um evento de fechar a um widget que não estava ali.
-//
-// (É a mesma raiz da falha do gate axe-core, consertada em 0657578: o VLibras mudou de lugar e três coisas
-// que o localizavam pelo nosso markup pararam juntas, em silêncio.)
-//
-// O ESTADO AGORA É NOSSO. `librasOpen` é uma escolha da pessoa, persistida, e não a leitura de um retângulo
-// de terceiro. Um modo de acessibilidade cujo estado é inferido da geometria de outra biblioteca é um modo
-// que desliga sozinho quando essa biblioteca muda — e quem paga é quem depende dele.
-//
-// O QUE AINDA NÃO É: o Dev decidiu que o intérprete deve aparecer NA FRENTE da tela quando um áudio toca e
-// sumir depois, sem clicar em nada e sem depender de clicar em textos. O widget do VLibras não faz isso (é um
-// painel encaixado, que traduz o texto do elemento clicado), então essa é a razão de o pilar 2 do ADR-0010
-// prever um motor próprio em zdog. Este arquivo para de empurrar a tela e passa a ter um toggle honesto; o
-// intérprete sob demanda é trabalho à parte.
-import { t } from '../core/i18n.js';
-import * as store from '../platform/storage.js';
-/** Estado do modo pessoa surda. Escolha da PESSOA, persistida — não inferência sobre um widget de terceiro. */
-export let librasOpen = store.getBool('incl_libras', false);
-let _vlOpen = false, _vlNode = null, _vlBusyUntil = 0, _vlNext = null;
-let _onLibrasChange = () => { };
-// Registra o reflow (layout) a rodar quando o painel abre/fecha. Chamado no boot do game.js.
-export function setOnLibrasChange(fn) { _onLibrasChange = fn; }
-// Fala em Libras: manda o texto ao intérprete (só quando o painel está aberto). Fila de 1 — fala nova substitui a pendente.
-export function vlibrasSay(text) {
-    if (!_vlOpen || !text)
-        return;
-    const now = Date.now();
-    if (now < _vlBusyUntil) {
-        _vlNext = text;
-        return;
-    }
-    _vlBusyUntil = now + 4000;
-    if (!_vlNode) {
-        _vlNode = document.createElement('span');
-        _vlNode.setAttribute('aria-hidden', 'true');
-        _vlNode.style.cssText = 'position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;opacity:.01;z-index:1;pointer-events:auto';
-        document.body.appendChild(_vlNode);
-    }
-    _vlNode.textContent = text;
-    try {
-        _vlNode.click();
-    }
-    catch (e) { /* noop */ }
-    setTimeout(() => { const nx = _vlNext; _vlNext = null; _vlBusyUntil = 0; if (nx)
-        vlibrasSay(nx); }, 4100);
-}
-const vwBtn = () => document.querySelector('[vw-access-button]');
-/** O modo pessoa surda está ligado? Lê o NOSSO estado — nunca mais a geometria do widget. */
-export function vlibrasOpen() { return librasOpen; }
-/** Liga/desliga o modo pessoa surda. Um toggle de verdade: o estado é nosso, então ele sempre alterna. */
-export function toggleLibras() {
-    librasOpen = !librasOpen;
-    _vlOpen = librasOpen;
-    store.setBool('incl_libras', librasOpen);
-    // Tentativa BEST-EFFORT de acordar o widget do VLibras, se ele estiver carregado. Falhar aqui não pode
-    // impedir o modo de ligar: o estado é a escolha da pessoa, o widget é só um tradutor possível para ela.
-    const b = vwBtn();
-    if (librasOpen && b) {
-        try {
-            b.click();
+/**
+ * Builds a deaf mode. The PERSON's choice, persisted — not an inference about a third-party widget — read from the store
+ * here, at build, never at import (ADR-0232).
+ */
+export function createLibras({ doc, win, store, now }) {
+    let open = store.getBool('incl_libras', false);
+    let vlOpen = false, node = null, busyUntil = 0, next = null;
+    const changeListeners = new Set();
+    const say = (text) => {
+        if (!vlOpen || !text)
+            return;
+        const at = now();
+        if (at < busyUntil) {
+            next = text;
+            return;
         }
-        catch (e) { /* noop */ }
-    }
-    else if (!librasOpen) {
+        busyUntil = at + 4000;
+        if (!node) {
+            node = doc.createElement('span');
+            node.setAttribute('aria-hidden', 'true');
+            node.style.cssText = 'position:fixed;left:0;top:0;width:1px;height:1px;overflow:hidden;opacity:.01;z-index:1;pointer-events:auto';
+            doc.body.appendChild(node);
+        }
+        node.textContent = text;
         try {
-            window.dispatchEvent(new CustomEvent('vp-widget-close'));
+            node.click();
         }
         catch (e) { /* noop */ }
-    }
-    _onLibrasChange();
-    if (librasOpen)
-        vlibrasSay(t('sr.libras.on'));
+        win.setTimeout(() => { const nx = next; next = null; busyUntil = 0; if (nx)
+            say(nx); }, 4100);
+    };
+    const toggle = (t) => {
+        open = !open;
+        vlOpen = open;
+        store.setBool('incl_libras', open);
+        // A BEST-EFFORT attempt to wake the VLibras widget, if it is loaded. Failing here must not stop the mode from
+        // turning on: the state is the person's choice, and the widget is only one possible translator for them.
+        const b = doc.querySelector('[vw-access-button]');
+        if (open && b) {
+            try {
+                b.click();
+            }
+            catch (e) { /* noop */ }
+        }
+        else if (!open) {
+            try {
+                win.dispatchEvent(new CustomEvent('vp-widget-close'));
+            }
+            catch (e) { /* noop */ }
+        }
+        for (const fn of [...changeListeners])
+            fn();
+        if (open)
+            say(t('sr.libras.on'));
+    };
+    return {
+        isOpen: () => open,
+        toggle,
+        say,
+        tick: () => { vlOpen = open; },
+        onChange: (fn) => { changeListeners.add(fn); return () => { changeListeners.delete(fn); }; },
+    };
 }
-/** Mantido para o laço do jogo, que o chama a cada quadro. Já não decide nada — o estado é nosso. */
-export function vlTick() { _vlOpen = librasOpen; }