@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/top-band.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/top-band.ts — HOW MUCH SPACE THE ENGINE KEEPS FOR ITSELF AT THE TOP OF THE SCREEN (ADR-0148 §3; issue #160).
+//
+// The engine draws things over the game — the accessibility bar, the name of the pointed icon, the HUD's mission line
+// under the bar (the rest of the HUD is a row at the bottom, `ui/hud-row`) and the scan chip — and the game has to know how much of the top is not its own. This module measures what is there and
+// writes three variables on the region: `--barra-a11y-h`, the whole band, `--scan-top`, where the chip sits, and
+// `--hud-mission-top`, where the mission stands under the bar (0 with no bar) — which the stylesheet reads for the bands a
+// caller mounts on the region with no HUD row, since those never pass through here.
+//
+// 📌 It is a calculation, not wiring, which is exactly what a composition root should not hold (Seemann; Fowler): a root
+// is large because it connects many things, not because it decides (ADR-0221).
+//
+// ⚠️ IT RECEIVES THE NODES AND THE MEASURER, and never reaches a global: this module's global reach is ZERO, which is
+// what lets it be measured in a document that is not the browser's.
+//
+// 🔴 THE ORDER OF THE TWO WRITES IS THE DECISION: the chip is placed by `--scan-top`, which does NOT depend on it; only the
+// band does. Placing it by the band it makes grow creates a loop — the chip pushes the band, the band pushes the chip,
+// and it walks down the screen on every measurement. A loop is invisible to a single measurement, so the case that
+// holds it measures the chip, lets the scan advance three steps — which is what re-measures the band in real use — and
+// demands the same place.
+/** A quarter of the scale's base, resolved BY THE STYLESHEET through a probe, so the rule has one home. */
+function breathingRoom(region, fallback) {
+    const probe = region.ownerDocument.createElement('div');
+    // A quarter of the scale's base size, not of the name's: a face with a higher floor grows its TEXT, not this gap
+    // (#172). `--espaco-fixo` is what shrinks with Ctrl −.
+    probe.style.cssText = 'position:absolute;visibility:hidden;height:calc(var(--ui-fs,16px) / 4 * var(--espaco-fixo,1))';
+    region.appendChild(probe);
+    const h = probe.getBoundingClientRect().height || fallback;
+    probe.remove();
+    return h;
+}
+/**
+ * The room the bar asks for: its bottom, or the bottom of the pointed icon's NAME line, plus breathing room.
+ *
+ * 📌 The name line counts whether or not it is showing a name — reserving only while pointing would move the game under
+ * the child's finger, and leaving it out lets the name cover the top of the game.
+ */
+function barRoom(ctx, top) {
+    const { region, bar, computedStyle } = ctx;
+    if (!region || !bar || typeof bar.getBoundingClientRect !== 'function')
+        return { room: 0, breath: 4 };
+    let bottom = bar.getBoundingClientRect().bottom;
+    let breath = 0;
+    const name = bar.querySelector('.pause-icons-cap');
+    if (name && computedStyle) {
+        const cs = computedStyle(name);
+        const fs = parseFloat(cs.fontSize) || 16;
+        const line = (parseFloat(cs.lineHeight) || fs * 1.2) + (parseFloat(cs.paddingTop) || 0) + (parseFloat(cs.paddingBottom) || 0);
+        bottom = name.getBoundingClientRect().top + line;
+        breath = breathingRoom(region, fs / 4);
+    }
+    return { room: bottom - top + breath, breath };
+}
+/**
+ * Where the mission sits, and the room it asks for: TOP CENTRE, just under the quick bar (ADR-0239 erratum), a light gap
+ * below the bar's own box. 📌 The bar's momentary name line may cover it while a name shows — the Dev's call: «a legenda é
+ * momentânea, a escrita da missão aparece o tempo todo» — so the mission is placed by the BAR and not by the name line, and
+ * the room below the top counts whichever of the two reaches lower.
+ */
+function hudRoom(ctx, top, breath, room, under) {
+    const { region, hud } = ctx;
+    if (!region || !hud || hud.left.hidden)
+        return room;
+    hud.left.style.top = under;
+    return Math.max(room, hud.left.getBoundingClientRect().bottom - top + Math.max(breath, 4));
+}
+/**
+ * Measures the top and writes `--hud-mission-top`, `--scan-top` and `--barra-a11y-h` on the region.
+ *
+ * 🔴 THE SCAN CHIP TAKES ROOM FOR THE SAME REASON AS THE NAME LINE (ADR-0218): it is HUD, and HUD that does not reserve its
+ * space is the engine writing over the game. But it is PLACED by `--scan-top`, written BEFORE it widens the room; see
+ * the loop in the header.
+ */
+export function reserveTopBand(ctx) {
+    const { region } = ctx;
+    if (!region || typeof region.style?.setProperty !== 'function')
+        return;
+    const measures = typeof region.getBoundingClientRect === 'function';
+    if (!measures) {
+        region.style.setProperty('--barra-a11y-h', '0px');
+        return;
+    }
+    const top = region.getBoundingClientRect().top;
+    const { room: barPart, breath } = barRoom(ctx, top);
+    // the mission's place: just under the bar's own box, by the light gap — also for bands a caller mounts on the region with no
+    // row, which the stylesheet places by `--hud-mission-top`; with no bar there is nothing to stand under, and '' removes it
+    const barBox = ctx.bar && typeof ctx.bar.getBoundingClientRect === 'function' ? ctx.bar.getBoundingClientRect() : null;
+    const under = barBox ? `${Math.ceil(barBox.bottom - top + Math.max(breath, 4))}px` : '';
+    region.style.setProperty('--hud-mission-top', under);
+    let room = hudRoom(ctx, top, breath, barPart, under);
+    region.style.setProperty('--scan-top', `${Math.ceil(Math.max(0, room - breath))}px`);
+    const chip = region.querySelector('.scan-now');
+    if (chip && !chip.hidden)
+        room = Math.max(0, room - breath) + chip.getBoundingClientRect().height + breath;
+    region.style.setProperty('--barra-a11y-h', `${Math.ceil(room)}px`);
+}

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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import { type FontItem } from './fonts.js';
+import type { ControlRowSpec } from './panel-widgets.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 declare function isSelectableFont(k: string, installed?: (family: string) => boolean): boolean;
+export interface FontCssTarget {
+    /** Value written to root.dataset.fonte. */
+    font: 'padrao' | 'alfabetizacao' | 'dislexia' | 'custom';
+    /** Value for the --font-custom CSS property, or null to remove the property. */
+    customFamily: string | null;
+    /**
+     * Is this a JOINED face? (ADR-0149 §3.)
+     *
+     * 🔴 It drives `data-cursiva` on the root, which is what removes the BDA letter/word spacing. Letter
+     * spacing on a joined face pulls the letters apart at exactly the joins that make it cursive — the spacing
+     * meant to help reading would destroy the thing being read. The Dev's words: «para manter os conectores».
+     *
+     * 📌 Read off `FontItem.fb` rather than a new field: the catalogue already tells cursive faces apart, and a
+     * second source for the same fact is a second place for it to drift.
+     */
+    cursive: boolean;
+}
+/**
+ * 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 declare function fontCssTarget(k: string, it: FontItem): FontCssTarget;
+export interface TypoRow {
+    key: string;
+    fam: string;
+    selected: boolean;
+    disabled: boolean;
+    /** Description (+ "— <notice>") (+ "— <off reason>" when disabled), or '' when there is none. */
+    note: string;
+}
+export interface TypoGroupView {
+    g: string;
+    rows: TypoRow[];
+}
+/**
+ * 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 note is up to three halves: the description, the `notice` that always speaks (the ronde's three faces to install,
+ * ADR-0154), and the `off` reason while the face is disabled.
+ */
+export declare function fontRow(t: Translate, it: FontItem, fontKey: string, installed?: (family: string) => boolean): TypoRow;
+/** Pure view-model for the typography list: which row is selected/disabled and its note, per catalog group. */
+export declare function typoGroups(t: Translate, fontKey: string, installed?: (family: string) => boolean): TypoGroupView[];
+/** The id of a face's button. It comes from the catalogue KEY, which is unique by construction (`FONT_BY_KEY`). */
+export declare const typoControlId: (key: string) => string;
+/**
+ * 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 declare function typoRowSpec(row: TypoRow): ControlRowSpec;

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

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { FONT_GROUPS, FONT_BY_KEY, fontRole, faceAvailable, familyStack } 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' : '';
+    // Each family quoted on its own (`familyStack`): the ronde's stack must reach Cookie, its packaged fallback (ADR-0154).
+    return { font: 'custom', customFamily: `${familyStack(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 note is up to three halves: the description, the `notice` that always speaks (the ronde's three faces to install,
+ * ADR-0154), and the `off` reason while the face is disabled.
+ */
+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`, `notice` and `off` hold KEYS too. The dash joining them is punctuation, not a sentence — the halves are
+    // independent and each translates on its own.
+    const note = [it.d, it.notice, disabled ? it.off : undefined]
+        .filter((k) => !!k).map((k) => t(k)).join(' — ');
+    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);
+}