@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/focus-trap.d.ts

@@ -1,71 +1,61 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * O que conta como focável. Deliberadamente SEM `[contenteditable]` e sem `tabindex` positivo: os dois
- * existem, mas não aparecem em nenhum diálogo desta engine (conferido), e um seletor que promete mais do que
- * foi verificado é um seletor que mente na próxima revisão.
+ * What counts as focusable. Deliberately WITHOUT `[contenteditable]` and without positive `tabindex`: both exist, but
+ * appear in no dialog of this engine, and a selector that promises more than was verified is a selector that lies at
+ * the next review.
  */
-export declare const SELETOR_FOCAVEL: string;
+export declare const FOCUSABLE_SELECTOR: string;
 /**
- * Para onde o foco tem de ir quando o Tab está prestes a sair do diálogo — ou `null` quando não há nada a
- * fazer e o navegador deve seguir sozinho.
+ * Where focus has to go when Tab is about to leave the dialog — or `null` when there is nothing to do and the browser
+ * should carry on by itself.
  *
- * Os quatro casos, e o terceiro é a razão de isto existir:
+ * The four cases, and the third is why this exists:
  *
- *   1. lista VAZIA → `null`. Um diálogo sem nada focável é um defeito do diálogo, e prender o foco nele
- *      deixaria a criança sem saída nenhuma. Melhor deixar sair do que trancar num lugar mudo.
- *   2. o foco está no ÚLTIMO e vai para a frente → volta ao primeiro; no PRIMEIRO e vai para trás → vai ao
- *      último. É o ciclo, que é o que «armadilha» quer dizer.
- *   3. ⚠️ o foco está FORA da lista → traz de volta. É o caso que os outros três não cobrem: o foco pode já
- *      ter escapado antes de esta armadilha existir, ou por um clique no tabuleiro, ou porque o diálogo
- *      abriu sem focar nada. Sem ele a armadilha só funciona para quem já estava dentro.
- *   4. o foco está no MEIO → `null`, e o navegador caminha. Ver o comentário do cabeçalho.
+ *   1. EMPTY list → `null`. A dialog with nothing focusable is the dialog's defect, and trapping focus in it would
+ *      leave the child with no way out at all. Better to let it leave than to lock it in a mute place.
+ *   2. focus on the LAST going forward → back to the first; on the FIRST going backwards → to the last. That is the
+ *      cycle, which is what "trap" means.
+ *   3. ⚠️ focus OUTSIDE the list → bring it back. The case the other three do not cover: focus may have escaped by a
+ *      click on the board, or because the dialog opened without focusing anything. Without it the trap only works for
+ *      whoever was already inside.
+ *   4. focus in the MIDDLE → `null`, and the browser walks. See the header.
  */
-export declare function proximoNaArmadilha<T>(focaveis: readonly T[], atual: T | null, paraTras: boolean): T | null;
-interface AlvoDeEvento {
-    addEventListener: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
-    removeEventListener?: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
+export declare function nextInTrap<T>(focusables: readonly T[], current: T | null, backwards: boolean): T | null;
+interface KeydownTarget {
+    addEventListener: (kind: 'keydown', fn: (e: KeyboardEvent) => void, capture?: boolean) => void;
+    removeEventListener?: (kind: 'keydown', fn: (e: KeyboardEvent) => void, capture?: boolean) => void;
 }
 export interface FocusTrapCtx {
-    /** O diálogo VISÍVEL mais alto da pilha, ou `null`. É o `topVisibleOverlay` de `ui/settings-panel`. */
-    overlayDeCima: () => HTMLElement | null;
-    /** Quem tem o foco agora — `() => document.activeElement`. Injetado: o project node não tem documento. */
-    focoAtual: () => Element | null;
-    /** Os focáveis DENTRO do diálogo, na ordem do documento e já filtrados por visibilidade. */
-    focaveisDe: (dentro: HTMLElement) => HTMLElement[];
-    win: AlvoDeEvento;
+    /** The highest VISIBLE dialog in the stack, or `null`. It is `ui/settings-panel`'s `topVisibleOverlay`. */
+    topOverlay: () => HTMLElement | null;
+    /** Who has focus now — `() => document.activeElement`. Injected: the node project has no document. */
+    currentFocus: () => Element | null;
+    /** The focusables INSIDE the dialog, in document order and already filtered by visibility. */
+    focusablesIn: (isInside: HTMLElement) => HTMLElement[];
+    win: KeydownTarget;
 }
 export interface FocusTrapApi {
-    /** O manipulador, exposto para o teste o chamar sem instalar nada. */
-    aoTeclar: (e: KeyboardEvent) => void;
-    /** Instala na fase de CAPTURA, pelo mesmo motivo do `menu-nav`: ver a tecla antes de quem está por baixo. */
+    /** The handler, exposed so the test can call it without installing anything. */
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Installs in the CAPTURE phase, for the same reason as `menu-nav`: see the key before whoever is underneath. */
     attach: () => void;
     /**
-     * Desinstala.
+     * Uninstalls.
      *
-     * ⚠️ ELE NASCEU DE UM TESTE QUE REPROVOU, e não de simetria: dois casos no mesmo ficheiro instalaram duas
-     * armadilhas na mesma janela, e a primeira continuou a prender o foco durante o segundo — o caso «sem
-     * diálogo aberto o Tab é do jogo» ficou vermelho por causa de uma armadilha que já devia ter saído.
-     *
-     * O que isso mostra vale fora do teste: uma armadilha que não se desinstala é um vazamento para qualquer
-     * página que monte a engine duas vezes — o `demos`, que troca de jogo sem recarregar, é exatamente isso.
+     * ⚠️ A trap that does not uninstall is a leak for any page that mounts the engine twice — one that switches games
+     * without reloading is exactly that: the first trap keeps holding focus during the second.
      */
     detach: () => void;
 }
 export declare function initFocusTrap(ctx: FocusTrapCtx): FocusTrapApi;
 /**
- * Os focáveis de um contêiner, no navegador. Vive aqui e não na raiz para as duas raízes não escreverem duas
- * versões que divergiriam em silêncio — uma prenderia o foco e a outra deixaria escapar, no mesmo produto.
- *
- * ⚠️ A VISIBILIDADE É POR `getClientRects()`, e não por `offsetParent`.
- *
- * ⚠️ E A PRIMEIRA VERSÃO DESTE COMENTÁRIO ESTAVA ERRADA, o que vale mais registrar do que apagar: ele dizia
- * que `offsetParent` é `null` para «qualquer elemento em `position: fixed`». Não é — é `null` para o elemento
- * FIXO EM SI, e os descendentes dele devolvem o próprio contêiner. O teste de navegador reprovou a afirmação,
- * que é exatamente o que um teste tem de fazer com uma justificativa inventada.
+ * The focusables of a container, in the browser. It lives here and not in a root so that two roots do not write two
+ * versions that would drift silently — one trapping focus and the other letting it escape, in the same product.
  *
- * A razão verdadeira é mais simples e mais forte: `getClientRects()` responde *«isto desenha alguma caixa?»*,
- * o que cobre `display:none` em QUALQUER ancestral, elementos de tamanho zero e o caso do contêiner fixo —
- * sem que quem lê precise de saber em que casos `offsetParent` tem buracos.
+ * ⚠️ VISIBILITY IS BY `getClientRects()`, not by `offsetParent`: `getClientRects()` answers "does this draw any box?",
+ * which covers `display:none` on ANY ancestor, zero-size elements and the fixed-container case — without the reader
+ * needing to know where `offsetParent` has holes (it is `null` for a FIXED element itself, while its descendants return
+ * the container).
  */
-export declare function focaveisNoDom(dentro: HTMLElement): HTMLElement[];
+export declare function focusablesInDom(isInside: HTMLElement): HTMLElement[];
 export {};

package/dist-pkg/ui/focus-trap.js

@@ -1,28 +1,25 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/focus-trap.ts — A ARMADILHA DE FOCO. O segundo fio da issue #109, e o único dos três que não existia
-// EM LADO NENHUM da engine: os outros dois eram construídos e deixados desligados, este nunca foi escrito.
-// `ui/settings-panel.ts:17-19` diz isso por escrito — *"não instala armadilha de foco (o original também não
-// tem)"*.
+// ui/focus-trap.ts — THE FOCUS TRAP (issue #109).
 //
-// ⚠️ E O DOCUMENTO JÁ PROMETE O CONTRÁRIO. Todo `.overlay__card` do `index.html` tem `aria-modal="true"`, o
-// que diz à tecnologia assistiva que o resto da página está inerte. O Tab não concorda: ele sai do diálogo e
-// entra no tabuleiro por baixo. É a pior forma de defeito de acessibilidade — não a ausência de uma promessa,
-// mas uma promessa que o teclado desmente. Quem usa leitor de tela sai para um jogo cujo estado não consegue
-// perceber, e não tem caminho de volta que perceba.
+// ⚠️ THE DOCUMENT ALREADY PROMISES IT. Every `.overlay__card` carries `aria-modal="true"`, which tells assistive
+// technology the rest of the page is inert. Without a trap, Tab disagrees: it leaves the dialog and enters the board
+// underneath. That is the worst shape of accessibility defect — not the absence of a promise, but a promise the keyboard
+// contradicts. A screen-reader user steps out into a game whose state they cannot perceive, with no way back they can
+// perceive.
 //
-// ⚠️ SÓ INTERVÉM NAS BORDAS, e isso é decisão e não economia. Reimplementar a ordem de tabulação inteira
-// significaria reproduzir regras que o navegador já acerta — `tabindex` positivo, ordem do DOM em `shadow
-// root`, elementos que ficam focáveis por `contenteditable`. Uma armadilha que se mete no meio erra ao
-// caminhar; uma que só fecha o ciclo nas pontas não tem como errar o meio, porque não o toca.
+// ⚠️ IT ONLY INTERVENES AT THE EDGES, and that is a decision, not thrift. Reimplementing the whole tab order would mean
+// reproducing rules the browser already gets right — positive `tabindex`, DOM order in a shadow root, elements made
+// focusable by `contenteditable`. A trap that steps into the middle errs while walking; one that only closes the cycle
+// at the ends cannot err in the middle, because it does not touch it.
 //
-// A regra fica em UMA função pura (`proximoNaArmadilha`), testável no project node sem DOM nenhum. O que
-// precisa de navegador é só ler quem está focado e chamar `.focus()`.
+// The rule lives in ONE pure function (`nextInTrap`), testable in the node project with no DOM. What needs a browser is
+// only reading who is focused and calling `.focus()`.
 /**
- * O que conta como focável. Deliberadamente SEM `[contenteditable]` e sem `tabindex` positivo: os dois
- * existem, mas não aparecem em nenhum diálogo desta engine (conferido), e um seletor que promete mais do que
- * foi verificado é um seletor que mente na próxima revisão.
+ * What counts as focusable. Deliberately WITHOUT `[contenteditable]` and without positive `tabindex`: both exist, but
+ * appear in no dialog of this engine, and a selector that promises more than was verified is a selector that lies at
+ * the next review.
  */
-export const SELETOR_FOCAVEL = [
+export const FOCUSABLE_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
     'input:not([disabled])',
@@ -31,69 +28,63 @@ export const SELETOR_FOCAVEL = [
     '[tabindex]:not([tabindex="-1"])',
 ].join(',');
 /**
- * Para onde o foco tem de ir quando o Tab está prestes a sair do diálogo — ou `null` quando não há nada a
- * fazer e o navegador deve seguir sozinho.
+ * Where focus has to go when Tab is about to leave the dialog — or `null` when there is nothing to do and the browser
+ * should carry on by itself.
  *
- * Os quatro casos, e o terceiro é a razão de isto existir:
+ * The four cases, and the third is why this exists:
  *
- *   1. lista VAZIA → `null`. Um diálogo sem nada focável é um defeito do diálogo, e prender o foco nele
- *      deixaria a criança sem saída nenhuma. Melhor deixar sair do que trancar num lugar mudo.
- *   2. o foco está no ÚLTIMO e vai para a frente → volta ao primeiro; no PRIMEIRO e vai para trás → vai ao
- *      último. É o ciclo, que é o que «armadilha» quer dizer.
- *   3. ⚠️ o foco está FORA da lista → traz de volta. É o caso que os outros três não cobrem: o foco pode já
- *      ter escapado antes de esta armadilha existir, ou por um clique no tabuleiro, ou porque o diálogo
- *      abriu sem focar nada. Sem ele a armadilha só funciona para quem já estava dentro.
- *   4. o foco está no MEIO → `null`, e o navegador caminha. Ver o comentário do cabeçalho.
+ *   1. EMPTY list → `null`. A dialog with nothing focusable is the dialog's defect, and trapping focus in it would
+ *      leave the child with no way out at all. Better to let it leave than to lock it in a mute place.
+ *   2. focus on the LAST going forward → back to the first; on the FIRST going backwards → to the last. That is the
+ *      cycle, which is what "trap" means.
+ *   3. ⚠️ focus OUTSIDE the list → bring it back. The case the other three do not cover: focus may have escaped by a
+ *      click on the board, or because the dialog opened without focusing anything. Without it the trap only works for
+ *      whoever was already inside.
+ *   4. focus in the MIDDLE → `null`, and the browser walks. See the header.
  */
-export function proximoNaArmadilha(focaveis, atual, paraTras) {
-    if (focaveis.length === 0)
+export function nextInTrap(focusables, current, backwards) {
+    if (focusables.length === 0)
         return null;
-    const primeiro = focaveis[0];
-    const ultimo = focaveis[focaveis.length - 1];
-    const i = atual === null ? -1 : focaveis.indexOf(atual);
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const i = current === null ? -1 : focusables.indexOf(current);
     if (i < 0)
-        return paraTras ? ultimo : primeiro; // caso 3: o foco estava fora
-    if (!paraTras && i === focaveis.length - 1)
-        return primeiro;
-    if (paraTras && i === 0)
-        return ultimo;
-    return null; // caso 4: o meio é do navegador
+        return backwards ? last : first; // case 3: focus was outside
+    if (!backwards && i === focusables.length - 1)
+        return first;
+    if (backwards && i === 0)
+        return last;
+    return null; // case 4: the middle belongs to the browser
 }
 export function initFocusTrap(ctx) {
-    function aoTeclar(e) {
+    function trapKey(e) {
         if (e.key !== 'Tab')
             return;
-        const dialogo = ctx.overlayDeCima();
+        const dialogo = ctx.topOverlay();
         if (!dialogo)
-            return; // sem diálogo aberto o Tab é do jogo, e tem de continuar a ser
-        const alvo = proximoNaArmadilha(ctx.focaveisDe(dialogo), ctx.focoAtual(), e.shiftKey);
-        if (!alvo)
+            return; // with no dialog open, Tab belongs to the game, and has to stay that way
+        const target = nextInTrap(ctx.focusablesIn(dialogo), ctx.currentFocus(), e.shiftKey);
+        if (!target)
             return;
         e.preventDefault();
-        alvo.focus();
+        target.focus();
     }
     return {
-        aoTeclar,
-        attach: () => ctx.win.addEventListener('keydown', aoTeclar, true),
-        detach: () => ctx.win.removeEventListener?.('keydown', aoTeclar, true),
+        onKeydown: trapKey,
+        attach: () => ctx.win.addEventListener('keydown', trapKey, true),
+        detach: () => ctx.win.removeEventListener?.('keydown', trapKey, true),
     };
 }
 /**
- * Os focáveis de um contêiner, no navegador. Vive aqui e não na raiz para as duas raízes não escreverem duas
- * versões que divergiriam em silêncio — uma prenderia o foco e a outra deixaria escapar, no mesmo produto.
+ * The focusables of a container, in the browser. It lives here and not in a root so that two roots do not write two
+ * versions that would drift silently — one trapping focus and the other letting it escape, in the same product.
  *
- * ⚠️ A VISIBILIDADE É POR `getClientRects()`, e não por `offsetParent`.
- *
- * ⚠️ E A PRIMEIRA VERSÃO DESTE COMENTÁRIO ESTAVA ERRADA, o que vale mais registrar do que apagar: ele dizia
- * que `offsetParent` é `null` para «qualquer elemento em `position: fixed`». Não é — é `null` para o elemento
- * FIXO EM SI, e os descendentes dele devolvem o próprio contêiner. O teste de navegador reprovou a afirmação,
- * que é exatamente o que um teste tem de fazer com uma justificativa inventada.
- *
- * A razão verdadeira é mais simples e mais forte: `getClientRects()` responde *«isto desenha alguma caixa?»*,
- * o que cobre `display:none` em QUALQUER ancestral, elementos de tamanho zero e o caso do contêiner fixo —
- * sem que quem lê precise de saber em que casos `offsetParent` tem buracos.
+ * ⚠️ VISIBILITY IS BY `getClientRects()`, not by `offsetParent`: `getClientRects()` answers "does this draw any box?",
+ * which covers `display:none` on ANY ancestor, zero-size elements and the fixed-container case — without the reader
+ * needing to know where `offsetParent` has holes (it is `null` for a FIXED element itself, while its descendants return
+ * the container).
  */
-export function focaveisNoDom(dentro) {
-    const todos = [...dentro.querySelectorAll(SELETOR_FOCAVEL)];
-    return todos.filter((el) => !el.hidden && el.getClientRects().length > 0);
+export function focusablesInDom(isInside) {
+    const candidates = [...isInside.querySelectorAll(FOCUSABLE_SELECTOR)];
+    return candidates.filter((el) => !el.hidden && el.getClientRects().length > 0);
 }

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

@@ -1,111 +1,200 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * Uma fonte do catálogo. `fam` é o NOME DA FONTE — nome próprio, nunca traduzido. `d` guarda CHAVE i18n da
- * descrição, não o texto: mesma decisão de `VIZ_MODES` e `RM_LABEL`, e pelo mesmo motivo — uma tabela de
- * `const` com texto resolve uma vez, no import, e fica congelada no idioma do boot.
+ * A face's ROLE — the ADR-0012 amendment turned into data (issue #87).
+ *
+ * ⚠️ IT IS NOT THE SAME AS THE GROUP. The group (`sans`/`serif`/`hand`) is APPEARANCE and serves to read the list; the
+ * role is WHERE THE FACE MAY BE USED, and it is a rule:
+ *
+ *   · `geral` — anywhere. The only ones the typography menu offers.
+ *   · `caligrafica` — **only INSIDE school activities**, never in the HUD or menus, and so **not in the font menu**. They
+ *     exist for the child to LEARN to read cursive, which is subject matter; using them as interface would hand the
+ *     child the subject as an obstacle everywhere they only want to navigate.
+ *   · `jogo` — the face the GAME uses in the HUD, the title and short arcade labels. Not in the menu either, for the same
+ *     kind of reason: an 8-bit pixel face is drawn to say FEW words at a large size. As an interface face it contradicts
+ *     the argument that makes Atkinson Hyperlegible the default — little differentiation between letters, a wide
+ *     advance, no height variation. Right in a pixel-art game's HUD, wrong in a menu the child has to READ.
+ *
+ * ⚠️ AND THE CUT IS NOT THE `hand` GROUP. `pwbr` is there by appearance — it is the group's GENERAL face (ADR-0176) and
+ * often recommended for dyslexia. Removing it from the menu would remove a legitimately accessible option. The good
+ * definition is the list in #87 item 2, which names the handwriting faces by giving them a minimum size.
+ */
+export type FontRole = 'geral' | 'caligrafica' | 'jogo';
+/** One position of the eleventh button's typography cycle: the CASE and the FACE, together (ADR-0149 §1). */
+export interface TypographyStep {
+    /** `upper` = UPPER CASE; `mixed` = upper and lower case. The values of `core/state.letterCase`. */
+    readonly letterCase: 'upper' | 'mixed';
+    /** The face's key in the catalogue. */
+    readonly font: string;
+    /**
+     * This position's size multiplier — 1 on the reading faces, **1.25 on the country hand** (ADR-0149 §1).
+     *
+     * 🔴 NOT A PREFERENCE, IT IS THE LEGIBILITY FLOOR ALREADY MEASURED. The Playwrite faces declare `minPx: 20` (ADR-0012
+     * amendment): below it the face stops being DIFFICULT and becomes ILLEGIBLE — difficulty is the exercise, illegibility
+     * is the child giving up. The document's base is 16 px, and 16 × 1.25 = 20 — the multiplier IS the floor, written as a
+     * ratio instead of a loose number.
+     */
+    readonly scale: number;
+}
+/** The country hand's increase. Named so the gate can assert it against `minPx` instead of repeating it. */
+export declare const HANDWRITING_SCALE = 1.25;
+/** The document's base, in px — the `font-size` of `html,body`. The floor comes from multiplying it by the scale. */
+export declare const BASE_EM_PX = 16;
+/**
+ * THE ELEVENTH BUTTON'S CYCLE — five positions, or six where the country teaches two hands (ADR-0149 §1, ADR-0150 §2).
+ *
+ * 🎯 EACH STEP CHANGES THE CASE **AND** THE FACE, and that is the whole decision: `letterCase` (`core/state`, ADR-0028)
+ * and the face are two settings, but Andika in upper case is ONE pedagogical choice of whoever teaches literacy, not
+ * two. A child should not have to know the model to make it.
+ *
+ * 📌 IT STARTS AT ATKINSON, which is position (c) and the project's default. The cycle is a ring: from it, one press goes
+ * to Lexend and the last goes back to the start.
+ *
+ * ⚠️ THE COUNTRY HAND MAY NOT EXIST — a tag with no region and a language outside the repertoire returns nothing. Then the
+ * cycle has FOUR positions, which is the right answer: one position fewer is better than one showing the hand of a
+ * country that is not that child's.
+ *
+ * 🔴 ARASAAC AND PCS ARE NOT POSITIONS, a decision and not an oversight: ADR-0155 §3 says to skip them — while the licence
+ * does not allow, the cycle neither stops on them nor announces them. A position existing only to be skipped would be
+ * data with no reader; they enter the day they work.
  */
+export declare function typographyCycle(tag: string | null | undefined): readonly TypographyStep[];
+/** The index where the cycle STARTS — position (c). Named so the gate can assert it without recounting. */
+export declare const CYCLE_START = 2;
 /**
- * O PAPEL de uma face, e é a emenda do ADR-0012 (27/08) posta em dado (issue #87).
- *
- * ⚠️ NÃO É O MESMO QUE O GRUPO. O grupo (`sans`/`serif`/`hand`) é APARÊNCIA e serve para ler a lista; o papel
- * é ONDE A FACE PODE SER USADA, e é regra:
- *
- *   · `geral` — em qualquer lugar. São as únicas que o menu de tipografia oferece.
- *   · `caligrafica` — **só DENTRO das atividades escolares**, nunca no HUD nem nos menus, e por isso **não
- *     aparecem no menu de fonte**. Elas existem para a criança APRENDER a ler letra cursiva, o que é matéria;
- *     usá-las como interface é dar-lhe a matéria como obstáculo em todos os lugares onde ela só quer navegar.
- *   · `jogo` — a face que o JOGO usa no HUD, no título e em rótulos curtos de arcade. Também não aparece no
- *     menu, e pelo mesmo tipo de razão que as caligráficas: uma face de pixel de 8 bits é desenhada para
- *     dizer POUCAS palavras em tamanho grande. Como face de interface ela contradiz o argumento que faz a
- *     Atkinson Hyperlegible ser o padrão — pouca diferenciação entre letras, avanço largo, nenhuma variação
- *     de altura. É certa no HUD de um jogo de pixel-art e errada num menu que a criança precisa de LER.
- *
- * ⚠️ E O CORTE NÃO É O GRUPO `hand`. O `comicneue` está lá por aparência — a face é de propósito geral e é
- * frequentemente recomendada para dislexia. Tirá-la do menu removeria uma opção legitimamente acessível. A
- * definição boa é a lista do item 2 da #87, que nomeia as caligráficas dando-lhes tamanho mínimo.
+ * The handwriting font keys for a BCP-47 tag — `pt-BR` → `['pwbr']`, `es-MX` → `['pwmx']`.
+ *
+ * ⚠️ IT READS THE REGION AND THEN THE LANGUAGE, in that order, and the forgotten case is the tag WITHOUT a region: `en`
+ * alone names no country, and falling back is the right answer — not an error, a child whose browser did not say where
+ * they are.
+ *
+ * 📌 It returns a LIST and not one face: where the country teaches two hands, both enter the cycle.
+ * 📌 It returns NOTHING for a language outside the repertoire, and nothing is sayable: the caller drops the position
+ * from the cycle instead of showing a hand that is nobody's.
+ */
+export declare function handsForTag(tag: string | null | undefined): readonly string[];
+/**
+ * A catalogue font. `fam` is the FONT'S NAME — a proper noun, never translated. `d` holds the i18n KEY of the description,
+ * not the text: the same decision as `VIZ_MODES` and `RM_LABEL`, for the same reason — a `const` table of text resolves
+ * once, on import, and stays frozen in the boot language.
  */
-export type FontRole = 'geral' | 'caligrafica' | 'jogo';
 export type FontItem = {
+    /** The face's `id` in `catalogo_tipografico.json` (ADR-0176): the key that holds it to the catalogue's status, layer, floor and coverage. */
+    id: string;
     k: string;
     fam: string;
     fb: string;
     d?: string;
     off?: string;
-    /** Ausente = `geral`. Só as caligráficas se declaram, porque são a excepção. */
-    papel?: FontRole;
     /**
-     * O menor tamanho, em px, em que esta face ainda é legível (item 2 da #87, números do Dev).
+     * The i18n KEY of a sentence ALWAYS shown after the description — unlike `off`, which only speaks while the face is
+     * disabled. It is for a stack whose preferred faces the device may lack: the ronde's names the three to install, because
+     * without them the child sees Cookie, a related hand that is not the one taught at school (ADR-0154).
+     */
+    notice?: string;
+    /** Absent = `geral`. Only the handwriting faces declare it, because they are the exception. */
+    role?: FontRole;
+    /**
+     * The smallest size, in px, at which this face is still legible (#87 item 2, the Dev's numbers).
      *
-     * ⚠️ Abaixo disto a face deixa de ser DIFÍCIL e passa a ser ILEGÍVEL, que são coisas diferentes: a
-     * dificuldade é o exercício, a ilegibilidade é a criança a desistir. Por isso é gate e não recomendação.
+     * ⚠️ Below it the face stops being DIFFICULT and becomes ILLEGIBLE, which are different things: difficulty is the
+     * exercise, illegibility is the child giving up. That is why it is a gate and not a recommendation.
      */
     minPx?: number;
 };
-/** Um grupo do catálogo. `g` também guarda CHAVE ('font.group.sans'), pelo mesmo motivo. */
+/** A catalogue group. `g` holds a KEY too ('font.group.sans'), for the same reason. */
 export type FontGroup = {
     g: string;
     items: FontItem[];
 };
+/**
+ * THE TYPOGRAPHY PANEL'S KIT — every face a panel may list, grouped. The engine mounts no panel since ADR-0151 («quem escolhe a
+ * tipografia é o jogo»), and the kit stays for whoever mounts one (`ui/settings-typo`), because the eleventh button's cycle and
+ * the boot's stored choice go through its writer.
+ *
+ * 📌 MOST OF THESE FACES ARE THE FONT LIBRARY'S, not the engine's (ADR-0255): only the cycle's faces are packaged. A library face
+ * reaches a page when its cartridge declares the family in `uses.fonts` and the delivery carries it, so `faceAvailable` answers
+ * for it through the host's detector — a row whose family nobody declared is shown disabled, never offered and then drawn in the
+ * system font. Keeping the rows is what lets a game that declares its families offer them with no list of its own.
+ */
 export declare const FONT_GROUPS: FontGroup[];
-/** O papel de uma face; ausente no catálogo quer dizer `geral`. */
-export declare function papelDaFonte(it: FontItem): FontRole;
 /**
- * AS FAMÍLIAS QUE UMA FACE ACEITA, do `fam` que pode ser uma PILHA.
+ * How much larger the text is drawn with this face: enough to reach its `minPx` from the document's base, never smaller.
+ * A face whose catalogue floor is above the base (a display sans, the handwriting) is offered at that size, not under it
+ * (ADR-0176 §4, the catalogue's rule R2). The cycle's hand of the country is the same rule (`HANDWRITING_SCALE`).
+ */
+export declare function faceScale(it: FontItem): number;
+/** A face's role; absent in the catalogue means `geral`. */
+export declare function fontRole(it: FontItem): FontRole;
+/**
+ * THE FAMILIES A FACE ACCEPTS, from a `fam` that may be a STACK.
  *
- * 📌 A Ronde declara três (`'Ronde Script, OPTIFrench-Script, Merveille'`) porque qualquer uma delas serve —
- * são três desenhos da mesma letra de mão, e um adulto instala a que encontrar. As outras faces declaram uma
- * só, e para elas isto devolve uma lista de um.
+ * 📌 The ronde declares four (`'Ronde Script, OPTIFrench-Script, Merveille, Cookie'`): the three drawings of the same
+ * hand an adult may install, then the packaged fallback (ADR-0154). The other faces declare one, and for them this
+ * returns a list of one.
  */
-export declare function familiasDaFace(it: FontItem): string[];
+export declare function faceFamilies(it: FontItem): string[];
 /**
- * ESTA FACE PODE SER USADA AGORA? — o `off` deixa de ser uma sentença e passa a ser uma CONDIÇÃO.
- *
- * O ADR-0012 decidiu que a opção da ronde «fica DESABILITADA enquanto nenhuma fonte estiver presente», e o
- * ADR-0108 §4 acrescentou o que ela diz. A palavra «enquanto» é o que esta função constrói: uma face `off`
- * volta a ficar disponível no instante em que o adulto instala uma das que a mensagem nomeia.
- *
- * ⚠️ O DETECTOR É INJECTADO, e nunca `document.fonts` lido daqui: este módulo é o catálogo, corre em node nos
- * gates, e ler um global do navegador aqui é o ACHADO 15 outra vez — o `srAlert` que rebentou o boot contra um
- * documento injectado.
- * 📌 E o PADRÃO É «não instalada», que é seguro por uma razão que não vale para todos os padrões deste
- * repositório: sem detector a opção fica desabilitada COM a mensagem, e a mensagem diz ao adulto exactamente
- * o que fazer. O silêncio não decide nada contra a criança — ele mantém o estado que já existia e que é
- * accionável. É o oposto do `seguraTeclas`, onde os dois lados do padrão erravam.
+ * A `fam` as a CSS `font-family` value — each family quoted on its own: `'Ronde Script','OPTIFrench-Script',…,'Cookie'`.
+ *
+ * 🔴 QUOTING THE WHOLE STRING ONCE NAMES ONE FAMILY THAT DOES NOT EXIST. `'Ronde Script, …, Cookie'` is a single name with
+ * commas in it, so the browser skips it and draws the generic fallback — the stack would never reach Cookie, and the
+ * fallback ADR-0154 decided would exist only in the catalogue. For a one-family `fam` the result is the same `'Inter'`.
  */
-export declare function faceDisponivel(it: FontItem, instalada?: (familia: string) => boolean): boolean;
-/** As faces que o MENU pode oferecer: só as gerais (emenda do ADR-0012). */
+export declare function familyStack(fam: string): string;
+/**
+ * THE FACES THE ENGINE DRAWS WITH ITSELF, by key — the eleventh button's cycle over EVERY hand a tag can pick (ADR-0149,
+ * ADR-0150). With the mathematics face (`MATHEMATICS_FAMILY`) they are the only faces packaged and precached (ADR-0255 §1); every
+ * other face of the kit is the font library's. `tests/what-fonts-the-package-carries.node.test.js` holds `fonts.css` to this list.
+ */
+export declare const ENGINE_FACE_KEYS: readonly string[];
+/** The face the engine draws mathematics in (`--font-math` in `style.css`): packaged, never a typography choice (ADR-0012). */
+export declare const MATHEMATICS_FAMILY = "Atkinson Hyperlegible Mono";
+/**
+ * CAN THIS FACE BE USED NOW? — `off` stops being a sentence and becomes a CONDITION.
+ *
+ * An engine face is always there: it is packaged and precached (ADR-0255 §1). Any other face is used WHILE one of its families
+ * is present — a library family its cartridge declared in `uses.fonts` (the root's detector answers for those), or, for an `off`
+ * face, one the adult installed from the ones its message names (ADR-0012's «enquanto»). The ronde's stack ends in Cookie, a
+ * library family, so it is available where the game declares Cookie (ADR-0154, ADR-0255).
+ *
+ * ⚠️ THE DETECTOR IS INJECTED, and `document.fonts` is never read here: this module is the catalogue, it runs in node in
+ * the gates, and reading a browser global here would be a boot waiting to crash against an injected document.
+ * 📌 And the DEFAULT is not present, which is safe: with no detector a library row stays disabled, never offered and then drawn
+ * in the system font, and an `off` row keeps the message that tells the adult exactly what to do.
+ */
+export declare function faceAvailable(it: FontItem, installed?: (family: string) => boolean): boolean;
+/** The faces the MENU may offer: only the general ones (ADR-0012 amendment). */
 export declare const OFERECIVEIS: FontItem[];
+/**
+ * The catalogue by key. BUILT IN ONE EXPRESSION and never filled after it (ADR-0232 D4): the table was an empty object the
+ * module wrote into at import, which the code-health measure reads as module state. The last item with a key wins, as it did.
+ */
 export declare const FONT_BY_KEY: Record<string, FontItem>;
+/** The families `vendor/fonts.css` declares — the engine's faces and the mathematics face. A cartridge never declares these. */
+export declare const ENGINE_FAMILIES: ReadonlySet<string>;
 /** Narrow store shape these need — lets a caller inject a fake without touching real storage. */
 export interface FontStore {
     get(key: string, fallback: string | null): string | null;
     set(key: string, v: string): void;
 }
-export declare const FONT_KEY = "incl_font_k";
-export declare const FONT_KEY_LEGACY = "incl_fonte";
 /**
- * A fonte de fábrica, com nome. Atkinson Hyperlegible foi desenhada pelo Braille Institute justamente para
- * quem tem baixa visão — distingue as formas que mais se confundem (I/l/1, O/0). É por isso que ela é o padrão
- * e não uma preferência estética, e é por isso que o "restaurar padrões" da tipografia (ADR-0028) volta para
- * cá: o caminho de volta de um menu de acessibilidade tem que terminar na escolha mais legível, não numa
- * qualquer. Usada em DOIS lugares — o fim da cadeia de boot logo abaixo e o reset do painel —, e uma constante
- * porque duas cópias de um padrão são duas chances de o reset devolver algo que o jogo nunca usou.
+ * The factory font, named. Atkinson Hyperlegible was designed by the Braille Institute precisely for low vision — it
+ * tells apart the shapes most often confused (I/l/1, O/0). That is why it is the default and not an aesthetic preference,
+ * and why typography's reset (ADR-0028) returns here: the way back from an accessibility menu has to end at the most
+ * legible choice, not at any one. Used in TWO places — the end of the boot chain just below and the panel's reset —, and
+ * a constant because two copies of a default are two chances for the reset to return something the game never used.
  */
 export declare const DEFAULT_FONT_KEY = "atkinson";
 /**
  * Boot choice: validated persisted key (ignores .off fonts) -> legacy-key migration -> DEFAULT_FONT_KEY.
  *
- * ⚠️ E UMA CALIGRÁFICA GUARDADA VOLTA AO PADRÃO (issue #87, 2026-09-07). Antes da emenda do ADR-0012 o menu
- * oferecia as sete caligráficas, então há crianças com `pinyon` ou `ufmag` guardados — e o valor salvo
- * continua a ser escolha delas, que não é nossa para desfazer sem motivo. O motivo existe: a emenda diz que
- * uma caligráfica **não pode ser a face da interface**, e o menu deixou de a oferecer. Deixá-la valer daria
- * uma interface inteira em letra cursiva a quem já não tem como sair dela pelo menu — uma armadilha, e das
- * silenciosas.
+ * ⚠️ AND A STORED HANDWRITING FACE GOES BACK TO THE DEFAULT (issue #87). A child may have one stored from when the menu
+ * offered them, and a stored value is their choice, not ours to undo without a reason. The reason exists: the ADR-0012
+ * amendment says a handwriting face **cannot be the interface face**, and the menu no longer offers it. Letting it stand
+ * would give a whole interface in cursive to someone with no way out of it through the menu — a trap, and a silent one.
  *
- * ⚠️ E UMA CHAVE APAGADA TAMBÉM VOLTA, pelo mesmo caminho: as quatro faces que saíram do roster já não estão
- * no `FONT_BY_KEY`, então quem tinha `greatvibes` guardado cai no padrão em vez de ficar sem face nenhuma.
+ * ⚠️ AND A DELETED KEY GOES BACK TOO, by the same path: a face no longer in `FONT_BY_KEY` falls back to the default
+ * instead of leaving the child with no face at all.
  */
 export declare function resolveFontKey(s: FontStore): string;
 export declare function persistFontKey(s: FontStore, k: string): void;
-export declare function loadFontKey(): string;
-export declare function saveFontKey(k: string): void;