@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type FontItem } from './fonts.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
+import type { Translate } from '../core/i18n.js';
 /** Minimal platform/storage.ts shape this module needs (get/set only — no direct localStorage access). */
 export interface TypoStore {
     get(key: string, fallback?: string | null): string | null;
     set(key: string, value: string | number | boolean): boolean;
 }
 export interface SettingsTypoCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
     /** DOM selector (querySelector), injected — never reaches `document` globally. */
     $: DomQuery;
     /** Screen-reader announcement (core/a11y-sr's srSay), injected. */
@@ -17,32 +17,29 @@ export interface SettingsTypoCtx {
     /** Element the chosen font is applied to (dataset.fonte + --font-custom): document.documentElement in prod. */
     root: HTMLElement;
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA `render()`, e
-     * não só ao abrir — que é o defeito que este parâmetro existe para fechar.
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY `render()`, not only on
+     * open.
      *
-     * `fillExplain` roda uma vez quando o overlay é frontalizado e reescreve cada `<span>` para conter só o
-     * rótulo curto. Mas `render()` reconstrói o `#typo-list` inteiro a cada clique numa fonte, e as linhas novas
-     * voltam com o `.opt-hint` dentro. Sem esta chamada a descrição aparece DUAS vezes — no rodapé, vinda da
-     * primeira passada, e sob o nome da fonte, vinda do redesenho. O CLAUDE.md §4 avisa exatamente isso.
+     * Relabelling a row puts its `.opt-hint` back inside it. Without this call the description appears TWICE — in the
+     * footer, from the first pass, and under the font's name, from the redraw. CLAUDE.md §4 warns about exactly that.
      *
-     * OPCIONAL de propósito: um consumidor que monte este painel sem a casca (o segundo consumidor, um teste)
-     * continua desenhando. O que ele não pode é desenhar prosa duplicada, e sem casca não há rodapé para duplicar.
+     * OPTIONAL on purpose: a consumer that mounts this panel without the shell (a test) keeps drawing. What it cannot do
+     * is draw duplicated prose, and without the shell there is no footer to duplicate.
      */
     fillExplain?: (card: HTMLElement | null) => void;
     /**
-     * ESTA FAMÍLIA ESTÁ INSTALADA NO APARELHO? — em produção, `(f) => doc.fonts.check(\`16px "${f}"\`)`.
+     * IS THIS FAMILY INSTALLED ON THE DEVICE? — in production, `(f) => doc.fonts.check(\`16px "${f}"\`)`.
      *
-     * É o que transforma o «enquanto» do ADR-0012 em código: a opção da Ronde fica desabilitada ENQUANTO
-     * nenhuma das três faces estiver presente, e volta a ficar disponível quando o adulto instalar uma.
+     * It turns ADR-0012's «enquanto» into code: an `off` face stays disabled WHILE none of its families is present, and
+     * becomes available again when the adult installs one. (The ronde no longer depends on it: its stack ends in the
+     * packaged Cookie, ADR-0154.)
      *
-     * ⚠️ INJECTADO E NUNCA `document.fonts` LIDO AQUI, pela regra que este ficheiro já segue para o `$`: um
-     * global do navegador num módulo que corre em node é o ACHADO 15, e este projecto já pagou por ele com um
-     * boot rebentado.
-     * 📌 OPCIONAL, e aqui o padrão é mesmo seguro — ao contrário do `seguraTeclas` do `PauseIconsCtx`, onde os
-     * dois lados erravam. Sem detector a linha fica desabilitada COM a mensagem, e a mensagem diz ao adulto as
-     * três fontes que resolvem. O estado por omissão é o de hoje, e é accionável.
+     * ⚠️ INJECTED, and `document.fonts` is NEVER read here, by the rule this file already follows for `$`: a browser
+     * global in a module that runs in node is a boot waiting to crash.
+     * 📌 OPTIONAL, and here the default really is safe: with no detector an `off` row stays disabled WITH its message, and
+     * the message says what to install. The default state is actionable.
      */
-    fonteInstalada?: (familia: string) => boolean;
+    fontInstalled?: (family: string) => boolean;
 }
 export interface SettingsTypoApi {
     /** Re-renders #typo-list from current selection and (re)wires its buttons. Idempotent. */
@@ -52,67 +49,21 @@ export interface SettingsTypoApi {
     /** Currently selected font key. */
     getFontKey: () => string;
 }
-/**
- * A key is selectable when it exists in the catalog, is not marked `.off` (licence pending, etc.) — and is
- * `geral`.
- *
- * ⚠️ O TERCEIRO TERMO ENTROU EM 2026-09-07 (issue #87), e sem ele o resto da mudança seria decoração: o menu
- * deixaria de OFERECER as caligráficas e elas continuariam SELECIONÁVEIS por qualquer outro caminho — o
- * `resolveFontKey` de uma chave guardada, um `data-font` num markup de consumidor. «Não está na lista» e «não
- * pode ser escolhida» têm de ser a mesma afirmação, ou a lista é só uma sugestão.
- */
-export declare function isSelectableFont(k: string, instalada?: (familia: string) => boolean): boolean;
 export { resolveFontKey, persistFontKey } from './fonts.js';
 import type { DomQuery } from '../core/dom-query.js';
-export interface FontCssTarget {
-    /** Value written to root.dataset.fonte. */
-    fonte: 'padrao' | 'alfabetizacao' | 'dislexia' | 'custom';
-    /** Value for the --font-custom CSS property, or null to remove the property. */
-    customFamily: string | null;
-}
-/**
- * Maps a selectable font key to the CSS it drives. The three canonical EdSP 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).
- * Verbatim port of the branching inside the old setGameFont().
- */
-export declare function fontCssTarget(k: string, it: FontItem): FontCssTarget;
-export interface TypoRow {
-    key: string;
-    fam: string;
-    selected: boolean;
-    disabled: boolean;
-    /** Description (+ "— <off reason>" when disabled), or '' when there is none. */
-    note: string;
-}
-export interface TypoGroupView {
-    g: string;
-    rows: TypoRow[];
-}
-/**
- * UMA linha da lista, a partir de uma face do catálogo. Extraída em 2026-09-07 (issue #87) porque o gate do
- * mecanismo `.off` precisava de a exercitar com uma face de MENTIRA: as duas únicas entradas desligadas
- * saíram do roster, e um caso que dependa da composição do catálogo reprova sempre que o roster muda.
- *
- * O mecanismo fica, e é preciso: o item 4 da #87 usa-o para a **Ronde**, que só pode ser oferecida se uma de
- * três faces estiver instalada, porque duas delas são gratuitas apenas para uso pessoal e não podem ser
- * empacotadas.
- */
-export declare function linhaDaFonte(it: FontItem, fontKey: string, instalada?: (familia: 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(fontKey: string, instalada?: (familia: string) => boolean): TypoGroupView[];
+import type { PanelShellCtx } from './panel-shell.js';
 /**
- * Full innerHTML for #typo-list, given the currently selected key. Pure string building — no DOM.
+ * Mounts the list ONCE, inside a single radio group. Called again, it RELABELS instead of rebuilding.
  *
- * ⚠️ É UM GRUPO DE RÁDIO SÓ, ATRAVESSANDO AS TRÊS SECÇÕES, e isso é a decisão e não um detalhe de
- * marcação: a exclusividade é do MENU inteiro — uma fonte activa no total —, não de cada família. Três
- * grupos diriam a quem escuta que dá para ter uma sans E uma serif ao mesmo tempo.
+ * ⚠️ ONE RADIO GROUP ACROSS ALL SECTIONS, and that is the decision and not a markup detail: exclusivity belongs to the
+ * WHOLE menu — one active font in total —, not to each family. Separate groups would tell a listener they can have a
+ * sans AND a serif at once. That is why the `radiogroup` belongs to the PANEL and not the kit: only the panel knows
+ * where exclusivity ends.
  *
- * ⚠️ E ISTO DEIXOU DE SER UM INTERRUPTOR EM 2026-09-07. Era `class="mode-btn switch"` + `aria-pressed` +
- * `toggleLabel()`, ou seja dezassete interruptores independentes anunciando «Ligado»/«Desligado» para
- * escolher UMA fonte. A emenda do ADR-0012 diz o contrário em tantas palavras: «THE MENU IS A CHOICE, NOT
- * A TOGGLE […] One font is active; the others are alternatives, not switches.» O `switch` do
- * `style.css:427` desenha uma chave de 52×28 px com bolinha — era o desenho de um estado que não existe.
+ * 🔴 AND EACH ROW'S LABEL IS DRAWN IN ITS OWN FACE, which is this menu's central behaviour: a list of NAMES lets no one
+ * choose a typeface, and whoever most needs to choose is whoever reads the face they are looking at poorly. The note
+ * beside it stays in the READING face on purpose — it explains the choice, it is not the choice. (With `fillExplain`,
+ * it does not even stay on the row: it goes to the footer.)
  */
-export declare function typoListHTML(fontKey: string, instalada?: (familia: string) => boolean): string;
+export declare function mountTypoInside(t: Translate, ctx: PanelShellCtx, list: HTMLElement, fontKey: string, isInstalled?: (family: string) => boolean): void;
 export declare function initSettingsTypo(ctx: SettingsTypoCtx): SettingsTypoApi;

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

@@ -1,194 +1,216 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/settings-typo — Typography panel (Estágio 4): extracted from game.js's renderTypo()/setGameFont(). Pure
-// logic (catalog view-model, key→CSS-target mapping, persisted-value validation) is separated from the thin
-// DOM-touching render()/setFont(). DI via initSettingsTypo(ctx): `$` (DOM selector), `srSay`, `store`
-// (platform/storage shape) and `root` (the element the chosen font is applied to — document.documentElement in
-// production). Overlay open/close plumbing (frontOverlay, focus management, the #typo hidden toggle, Escape
-// handling) is the SHARED helper used by every settings panel and stays in game.js. The font catalog itself
-// (FONT_GROUPS/FONT_BY_KEY) stays in ./fonts.js (Phase 2 extraction) — imported here, never duplicated.
-// (`toggleLabel` saiu daqui em 2026-09-07: ele devolve «Ligado»/«Desligado», e este menu é uma ESCOLHA.)
-import { t } from '../core/i18n.js';
-import { FONT_GROUPS, FONT_BY_KEY, DEFAULT_FONT_KEY, papelDaFonte, faceDisponivel } from './fonts.js';
+// ui/settings-typo — Typography panel. The thin DOM-touching render()/setFont(); what a choice IS lives in
+// ./typo-choices.js. DI via initSettingsTypo(ctx): `$` (DOM selector), `srSay`, `store` (platform/storage shape) and
+// `root` (the element the chosen font is applied to — document.documentElement in production). Overlay open/close
+// plumbing (frontOverlay, focus management, Escape handling) is the SHARED helper every settings panel uses. The font
+// catalog itself (FONT_GROUPS/FONT_BY_KEY) lives in ./fonts.js — imported here, never duplicated.
+import { FONT_BY_KEY, DEFAULT_FONT_KEY, faceAvailable, faceScale, familyStack } from './fonts.js';
 import { markChanged, markMenuChanged, CHANGED_CLASS } from './changed-mark.js';
 // ---------------------------------------------------------------------------------------------
 // Pure logic (no `document`, testable in node)
 // ---------------------------------------------------------------------------------------------
-/**
- * A key is selectable when it exists in the catalog, is not marked `.off` (licence pending, etc.) — and is
- * `geral`.
- *
- * ⚠️ O TERCEIRO TERMO ENTROU EM 2026-09-07 (issue #87), e sem ele o resto da mudança seria decoração: o menu
- * deixaria de OFERECER as caligráficas e elas continuariam SELECIONÁVEIS por qualquer outro caminho — o
- * `resolveFontKey` de uma chave guardada, um `data-font` num markup de consumidor. «Não está na lista» e «não
- * pode ser escolhida» têm de ser a mesma afirmação, ou a lista é só uma sugestão.
- */
-export function isSelectableFont(k, instalada) {
-    const it = FONT_BY_KEY[k];
-    return !!it && faceDisponivel(it, instalada) && papelDaFonte(it) === 'geral';
-}
-// A semantica da chave (validacao + migracao da chave antiga) mora em ui/fonts.ts, que e o dono do
-// catalogo; re-exportada aqui para quem ja consome este modulo. Uma implementacao, nao duas.
+// The key's semantics (validation + migration of the old key) live in ui/fonts.ts, which owns the catalogue;
+// re-exported here for whoever already consumes this module. One implementation, not two.
 export { resolveFontKey, persistFontKey } from './fonts.js';
 import { resolveFontKey, persistFontKey } from './fonts.js';
-/**
- * Maps a selectable font key to the CSS it drives. The three canonical EdSP 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).
- * Verbatim port of the branching inside the old setGameFont().
+import { controlRow, labelRow, sectionHeader } from './panel-widgets.js';
+/*
+ * 🎯 WHAT A TYPOGRAPHY CHOICE IS lives in `./typo-choices.js`, and this file keeps the work its name always described:
+ * finding the nodes it reaches and never created, wiring them, and reflecting the choice. No alias left behind — a
+ * re-export would keep alive a published path nothing here uses, surface with no consumer (#204).
  */
-export function fontCssTarget(k, it) {
-    if (k === 'atkinson')
-        return { fonte: 'padrao', customFamily: null };
-    if (k === 'andika')
-        return { fonte: 'alfabetizacao', customFamily: null };
-    if (k === 'lexend')
-        return { fonte: 'dislexia', customFamily: null };
-    const suffix = it.fb === 'serif' ? ',Georgia,serif' : it.fb === 'cursive' ? ',cursive' : '';
-    return { fonte: 'custom', customFamily: `'${it.fam}'${suffix}` };
-}
+import { typoGroups, typoRowSpec, fontCssTarget } from './typo-choices.js';
 /**
- * UMA linha da lista, a partir de uma face do catálogo. Extraída em 2026-09-07 (issue #87) porque o gate do
- * mecanismo `.off` precisava de a exercitar com uma face de MENTIRA: as duas únicas entradas desligadas
- * saíram do roster, e um caso que dependa da composição do catálogo reprova sempre que o roster muda.
+ * ⚠️ THE SELECTION MARK, and it exists because COLOUR IS NOT STATE.
  *
- * O mecanismo fica, e é preciso: o item 4 da #87 usa-o para a **Ronde**, que só pode ser oferecida se uma de
- * três faces estiver instalada, porque duas delas são gratuitas apenas para uso pessoal e não podem ser
- * empacotadas.
+ * `.mode-btn.is-on` paints the button with `var(--accent)` — the yellow background the ADR-0012 amendment asks for in
+ * so many words. But whoever does not tell the colour apart sees no state at all: the state has to come in TWO forms,
+ * and neither of them a colour.
  */
-export function linhaDaFonte(it, fontKey, instalada) {
-    // ⚠️ A MESMA pergunta que o `isSelectableFont` faz, pela MESMA função. Duas respostas dariam uma linha
-    // clicável que o clique recusa — ou, pior, uma linha cinzenta que o `resolveFontKey` aceita por outro
-    // caminho. «Não está disponível» e «não pode ser escolhida» têm de ser a mesma afirmação.
-    const disabled = !faceDisponivel(it, instalada);
-    // `d` e `off` também guardam CHAVE. O travessão que junta os dois é pontuação, não frase — as duas
-    // metades são independentes e cada uma traduz por si.
-    const desc = it.d ? t(it.d) : '', motivo = it.off ? t(it.off) : '';
-    const note = desc ? desc + (disabled ? ' — ' + motivo : '') : disabled ? motivo : '';
-    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(fontKey, instalada) {
-    // ⚠️ SÓ AS GERAIS ENTRAM NA LISTA (emenda do ADR-0012, issue #87). As caligráficas existem para a criança
-    // APRENDER a ler letra cursiva — isso é matéria, e vive DENTRO das atividades, em botões próprios. Oferecê-
-    // las aqui é dar-lhe a matéria como obstáculo em todo lugar onde ela só quer navegar o menu.
-    //
-    // Um grupo que fique sem nenhuma face geral desaparece da lista, em vez de aparecer como título vazio.
-    return FONT_GROUPS.map((g) => ({
-        g: t(g.g), // `g` guarda CHAVE i18n desde o item 14 (ver ui/fonts)
-        rows: g.items.filter((it) => papelDaFonte(it) === 'geral').map((it) => linhaDaFonte(it, fontKey, instalada)),
-    })).filter((grupo) => grupo.rows.length > 0);
-}
+const CHOSEN_MARK = '●';
+const OFFERED_MARK = '○';
 /**
- * ⚠️ A MARCA DE SELEÇÃO, e ela existe porque COR NÃO É ESTADO.
+ * Mounts the list ONCE, inside a single radio group. Called again, it RELABELS instead of rebuilding.
+ *
+ * ⚠️ ONE RADIO GROUP ACROSS ALL SECTIONS, and that is the decision and not a markup detail: exclusivity belongs to the
+ * WHOLE menu — one active font in total —, not to each family. Separate groups would tell a listener they can have a
+ * sans AND a serif at once. That is why the `radiogroup` belongs to the PANEL and not the kit: only the panel knows
+ * where exclusivity ends.
  *
- * O `.mode-btn.is-on` pinta o botão com `var(--accent)` — o fundo amarelo que a emenda do ADR-0012 pede
- * por extenso. Mas quem não distingue a cor não vê estado nenhum, e é a mesma razão pela qual
- * `ui/activities-menu.ts:656` já emite ☑/☐ ao lado do `aria-checked`: «o estado em DUAS formas, e nenhuma
- * delas é cor».
+ * 🔴 AND EACH ROW'S LABEL IS DRAWN IN ITS OWN FACE, which is this menu's central behaviour: a list of NAMES lets no one
+ * choose a typeface, and whoever most needs to choose is whoever reads the face they are looking at poorly. The note
+ * beside it stays in the READING face on purpose — it explains the choice, it is not the choice. (With `fillExplain`,
+ * it does not even stay on the row: it goes to the footer.)
  */
-const MARCA_ESCOLHIDA = '●';
-const MARCA_ALTERNATIVA = '○';
-function rowHTML(row) {
-    const noteHTML = row.note
-        ? `<br><span class="opt-hint" style="margin:0;font-family:var(--font)">${row.note}</span>`
-        : '';
-    const ariaLabel = row.fam + (row.note ? ' — ' + row.note : '');
-    return (`<div class="ctrl-row"><span style="font-family:'${row.fam}'"><strong>${row.fam}</strong>${noteHTML}</span>` +
-        `<button class="mode-btn${row.selected ? ' is-on' : ''}" data-font="${row.key}" type="button" role="radio"` +
-        `${row.disabled ? ' disabled' : ''} aria-checked="${row.selected}" aria-label="${ariaLabel}">` +
-        `${row.selected ? MARCA_ESCOLHIDA : MARCA_ALTERNATIVA}</button></div>`);
+export function mountTypoInside(t, ctx, list, fontKey, isInstalled) {
+    let radios = list.querySelector('[role="radiogroup"]');
+    if (!radios) {
+        radios = ctx.create('div');
+        radios.setAttribute('role', 'radiogroup');
+        list.appendChild(radios);
+    }
+    radios.setAttribute('aria-label', t('font.grupo.rotulo'));
+    for (const group of typoGroups(t, fontKey, isInstalled)) {
+        const head = radios.querySelector(`[data-typo-group="${group.g}"]`)
+            ? null
+            : sectionHeader(ctx, group.g, '', group.rows.length);
+        if (head) {
+            head.setAttribute('data-typo-group', group.g);
+            radios.appendChild(head);
+        }
+        for (const row of group.rows) {
+            const spec = typoRowSpec(row);
+            const old = ctx.find('#' + spec.id)?.closest('.ctrl-row');
+            if (old) {
+                labelRow(old, spec);
+                dressRow(old, row);
+                continue;
+            }
+            const { row: rowNode, control: faceButton } = controlRow(ctx, spec);
+            faceButton.dataset.font = row.key;
+            dressRow(rowNode, row);
+            radios.appendChild(rowNode);
+        }
+    }
+}
+/** What the kit does not know about a face: the face itself on the label, and the note in the reading face. */
+function dressRow(where, row) {
+    const label = where.querySelector(':scope > span');
+    // the whole stack, each family quoted: the ronde's label must draw in Cookie on a device without the three (ADR-0154)
+    if (label)
+        label.style.fontFamily = familyStack(row.fam);
+    const note = where.querySelector('.opt-hint');
+    if (note) {
+        note.style.fontFamily = 'var(--font)';
+        note.style.margin = '0';
+    }
 }
 /**
- * Full innerHTML for #typo-list, given the currently selected key. Pure string building — no DOM.
+ * Reflects the choice onto the rows that already exist: the mark, the spoken state and the lock.
  *
- * ⚠️ É UM GRUPO DE RÁDIO SÓ, ATRAVESSANDO AS TRÊS SECÇÕES, e isso é a decisão e não um detalhe de
- * marcação: a exclusividade é do MENU inteiro — uma fonte activa no total —, não de cada família. Três
- * grupos diriam a quem escuta que dá para ter uma sans E uma serif ao mesmo tempo.
+ * 🔴 THE ● / ○ MARK EXISTS BECAUSE COLOUR IS NOT STATE (see `CHOSEN_MARK`).
  *
- * ⚠️ E ISTO DEIXOU DE SER UM INTERRUPTOR EM 2026-09-07. Era `class="mode-btn switch"` + `aria-pressed` +
- * `toggleLabel()`, ou seja dezassete interruptores independentes anunciando «Ligado»/«Desligado» para
- * escolher UMA fonte. A emenda do ADR-0012 diz o contrário em tantas palavras: «THE MENU IS A CHOICE, NOT
- * A TOGGLE […] One font is active; the others are alternatives, not switches.» O `switch` do
- * `style.css:427` desenha uma chave de 52×28 px com bolinha — era o desenho de um estado que não existe.
+ * 📌 THE LOCK is reflected and not built, because it can CHANGE: an `off` face becomes available the instant the adult
+ * installs one of the faces its message names (ADR-0012, the word «enquanto»).
  */
-export function typoListHTML(fontKey, instalada) {
-    const grupos = typoGroups(fontKey, instalada)
-        .map((group) => `<h3 class="panel-sub">${group.g}</h3>` + group.rows.map(rowHTML).join(''))
-        .join('');
-    return `<div role="radiogroup" aria-label="${t('font.grupo.rotulo')}">${grupos}</div>`;
+function reflectTypo(list, fontKey, isInstalled) {
+    // Walks what EXISTS in the list, not the catalogue: reflecting is about the nodes already there, and asking the
+    // catalogue again would build the list a second time just to read it.
+    for (const b of list.querySelectorAll('button[data-font]')) {
+        const it = FONT_BY_KEY[b.dataset.font ?? ''];
+        const isChosen = b.dataset.font === fontKey;
+        b.classList.toggle('is-on', isChosen);
+        b.setAttribute('aria-checked', String(isChosen));
+        b.textContent = isChosen ? CHOSEN_MARK : OFFERED_MARK;
+        b.disabled = !it || !faceAvailable(it, isInstalled);
+    }
 }
 // ---------------------------------------------------------------------------------------------
 // DOM-facing (thin) — requires `document`/injected ctx
 // ---------------------------------------------------------------------------------------------
 export function initSettingsTypo(ctx) {
+    const { t } = ctx;
     let fontKey = resolveFontKey(ctx.store);
-    function setFont(k, announce = false) {
+    /*
+     * 📌 THE KIT'S CTX COMES FROM THE LIST NODE ITSELF: `ownerDocument` is the document it LIVES in, which is where the
+     * rows must be born. So this module's global reach stays zero (ADR-0221) and `SettingsTypoCtx`, which is published
+     * surface, gains no required member (ADR-0172).
+     */
+    const panelCtx = (list) => ({
+        find: (sel) => ctx.$(sel),
+        create: (tag) => list.ownerDocument.createElement(tag),
+    });
+    function setFont(k, announce = false) { choose(k, announce, true); }
+    function choose(k, announce, persist) {
         const it = FONT_BY_KEY[k];
-        // A MESMA função das outras duas leituras: uma face que a lista mostra clicável tem de ser aceite aqui,
-        // e uma que ela mostra cinzenta tem de ser recusada. Três respostas à mesma pergunta divergem.
-        if (!it || !faceDisponivel(it, ctx.fonteInstalada))
+        // The SAME function as the other two readings: a face the list shows clickable has to be accepted here, and one it
+        // shows grey has to be refused. Three answers to the same question drift.
+        if (!it || !faceAvailable(it, ctx.fontInstalled))
             return;
         fontKey = k;
-        persistFontKey(ctx.store, k);
+        if (persist)
+            persistFontKey(ctx.store, k);
         const target = fontCssTarget(k, it);
-        ctx.root.dataset.fonte = target.fonte;
+        ctx.root.dataset.fonte = target.font;
+        /*
+         * 🔴 THE JOINED-FACE MARK (ADR-0149 §3), which removes the BDA spacing. `:root[data-cursiva]` returns
+         * `letter-spacing`/`word-spacing` to `normal`, because spacing a cursive face breaks it at the joins that make it
+         * cursive — «para manter os conectores».
+         *
+         * ⚠️ IT ERASES WHEN IT IS NOT, not only writes when it is: without the `delete`, a child who chose a cursive face
+         * and went back to Atkinson would have the reading face WITHOUT the spacing — the defect in the costliest
+         * direction, because whoever goes back to the reading face is whoever needs it.
+         */
+        if (target.cursive)
+            ctx.root.dataset.cursiva = '1';
+        else
+            delete ctx.root.dataset.cursiva;
         if (target.customFamily)
             ctx.root.style.setProperty('--font-custom', target.customFamily);
         else
             ctx.root.style.removeProperty('--font-custom');
+        // drawn at its floor, never under it (ADR-0176 §4): a face asking 20 px makes the text 25% larger; the others give it back
+        ctx.root.style.setProperty('--fonte-escala', String(faceScale(it)));
         const pv = ctx.$('#typo-preview');
         if (pv)
-            pv.style.fontFamily = `'${it.fam}'`;
+            pv.style.fontFamily = familyStack(it.fam);
         if (announce)
             ctx.srSay(t('sr.typo.font', { fam: it.fam }));
     }
+    /*
+     * The listeners are wired ONCE, on the list, by delegation — which mounting once allows. ⚠️ A `disabled` button emits
+     * no click, so the lock is still what protects the face the device does not have — not a guard here, which would be
+     * a second answer to the same question.
+     */
+    let listening = false;
     function render() {
         const el = ctx.$('#typo-list');
         if (!el)
             return;
-        el.innerHTML = typoListHTML(fontKey, ctx.fonteInstalada);
-        el.querySelectorAll('button[data-font]').forEach((b) => {
-            b.addEventListener('click', () => {
-                const k = b.dataset.font;
+        mountTypoInside(t, panelCtx(el), el, fontKey, ctx.fontInstalled);
+        reflectTypo(el, fontKey, ctx.fontInstalled);
+        if (!listening) {
+            listening = true;
+            el.addEventListener('click', (ev) => {
+                const b = ev.target?.closest('button[data-font]');
+                const k = b?.dataset.font;
                 if (!k)
                     return;
                 setFont(k, true);
                 render();
             });
-        });
+        }
         const cur = FONT_BY_KEY[fontKey];
         const pv = ctx.$('#typo-preview');
         if (pv && cur)
-            pv.style.fontFamily = `'${cur.fam}'`;
+            pv.style.fontFamily = familyStack(cur.fam);
         refreshMarks();
-        // A ÚLTIMA COISA DO RENDER, e tem de ser: as linhas acabaram de ser recriadas com a prosa dentro delas.
+        // THE LAST THING IN RENDER, and it has to be: the rows were just relabelled with the prose inside them.
         ctx.fillExplain?.(ctx.$('#typo .overlay__card'));
     }
     /**
-     * A marca de "saiu do padrão" (ADR-0029). Mora DENTRO do render porque é derivada, nunca guardada: ela é
-     * recalculada de valor-atual-contra-padrão a cada desenho, então não tem como envelhecer no armazenamento.
-     * Envelhecer na TELA ela tem — se algum dia alguém mudar a fonte sem redesenhar —, e é por isso que a
-     * atualização anda junto com quem já redesenha, e não numa função própria que se possa esquecer de chamar.
+     * The left-the-default mark (ADR-0029). It lives INSIDE render because it is derived, never stored: it is recomputed
+     * from current-value-against-default on every draw, so it cannot go stale in storage. It could go stale on SCREEN —
+     * if someone changed the font without redrawing —, which is why the update travels with what already redraws.
      *
-     * Aqui a linha marcada é a da fonte ESCOLHIDA, e só quando ela não é a padrão: as outras quinze não saíram
-     * do padrão, foram apenas oferecidas.
+     * Here the marked row is the CHOSEN font's, and only when it is not the default: the others did not leave the default,
+     * they were only offered.
      */
     function refreshMarks() {
         const changed = fontKey !== DEFAULT_FONT_KEY;
         const list = ctx.$('#typo-list');
-        list?.querySelectorAll('.' + CHANGED_CLASS).forEach((el) => markChanged(el, false));
+        list?.querySelectorAll('.' + CHANGED_CLASS).forEach((el) => markChanged(t, el, false));
         const sel = list?.querySelector(`button[data-font="${fontKey}"]`);
-        markChanged(sel?.closest('.ctrl-row') ?? null, changed);
-        markMenuChanged(ctx.$('[data-act="tipo"]'), [changed]);
+        markChanged(t, sel?.closest('.ctrl-row') ?? null, changed);
+        markMenuChanged(t, ctx.$('[data-act="tipo"]'), [changed]);
     }
-    // ---- restaurar os padrões DESTE menu (ADR-0028) ----
+    // ---- reset THIS menu's defaults (ADR-0028) ----
     //
-    // O menu mais simples dos oito: a tipografia guarda uma escolha só, então o reset é uma linha. Ainda assim
-    // vale dizer para onde ele volta — a Atkinson Hyperlegible não é o padrão por ser bonita, é o padrão por ter
-    // sido desenhada para quem tem baixa visão. Uma criança que experimentou seis fontes e não consegue mais ler
-    // a tela precisa de um caminho de volta que termine na MAIS legível, não numa qualquer.
+    // Typography stores a single choice, so the reset is one line. Still, where it returns to is worth saying — Atkinson
+    // Hyperlegible is not the default for being pretty, it is the default for having been designed for low vision. A
+    // child who tried six fonts and can no longer read the screen needs a way back that ends at the MOST legible one.
     //
-    // O anúncio nomeia a fonte porque a mudança é visível para quem enxerga e invisível para quem não enxerga.
+    // The announcement names the font because the change is visible to whoever sees and invisible to whoever does not.
     const resetBtn = ctx.$('#typo-reset');
     if (resetBtn)
         resetBtn.addEventListener('click', () => {
@@ -196,6 +218,13 @@ export function initSettingsTypo(ctx) {
             render();
             ctx.srSay(t('sr.typo.reset', { fam: FONT_BY_KEY[DEFAULT_FONT_KEY].fam }));
         });
-    setFont(fontKey, false); // aplica a fonte persistida ao boot (== antigo `setGameFont(fontKey,false)`)
+    /*
+     * Applies the persisted font at boot. 📌 A stored face THIS page does not have — a library family its game did not declare
+     * (ADR-0255) — is drawn as the default and NOT written over: the choice stays stored for a game that declares the family, and
+     * `getFontKey` answers the face really drawn instead of one the page cannot draw.
+     */
+    const stored = FONT_BY_KEY[fontKey];
+    const drawable = !!stored && faceAvailable(stored, ctx.fontInstalled);
+    choose(drawable ? fontKey : DEFAULT_FONT_KEY, false, drawable);
     return { render, setFont, getFontKey: () => fontKey };
 }