@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/fonts.js

@@ -1,153 +1,308 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/fonts.ts — catálogo de fontes (dados) + índice por chave + carga/persistência da escolha. Módulo-folha
-// (só depende de storage). A instância `fontKey` e o setGameFont (aplica família/espaçamento) ficam no game.js.
-import * as store from '../platform/storage.js';
+// ui/fonts.ts — the font catalogue (data) + index by key + loading/persisting the choice. A leaf module WITH NO IMPORTS:
+// whoever stores comes in as a parameter (`FontStore`), in `resolveFontKey` and `persistFontKey` — so the decision of
+// WHERE it is stored belongs entirely to the caller.
+/**
+ * THIS CHILD'S COUNTRY HAND, and the COLONISER's fallback when the country has none of its own (ADR-0150 §1).
+ *
+ * 🎯 The rule is the Dev's and is truer than the one it replaced: ADR-0012 says the hand one learns to write is NATIONAL,
+ * not linguistic, and never said what to do with nations without a face of their own. Falling back to what the United
+ * States teaches was a default dressed as a country; the coloniser's hand is a true statement about how that child's
+ * school taught them to write.
+ *
+ * 📌 AND THREE FACES CLOSE THE WHOLE GAP, because the repertoire is already limited to English, Portuguese and Spanish
+ * (ADR-0012). That is what makes the truer rule also the cheapest to bundle.
+ *
+ * ⚠️ WHERE THE COUNTRY TEACHES TWO HANDS, IT RETURNS BOTH, in the Dev's order — the traditional first. That gives the
+ * eleventh button's cycle SIX positions in those countries instead of five.
+ */
+const HAND_BY_COUNTRY = Object.freeze({
+    BR: ['pwbr'],
+    US: ['pwustrad', 'pwusmod'], // the US teaches two, and choosing one would be choosing for the child
+    GB: ['pwgbj', 'pwgbs'], // joined and semi-joined
+    ES: ['pwes', 'pwesdeco'],
+    PT: ['pwpt'],
+    CA: ['pwca'], MX: ['pwmx'], AR: ['pwar'], CL: ['pwcl'], CO: ['pwco'], CU: ['pwcu'], PE: ['pwpe'],
+});
+/** The fallback by LANGUAGE: the coloniser's hand. Three entries cover every country the repertoire admits. */
+const HAND_BY_LANGUAGE = Object.freeze({
+    es: ['pwes', 'pwesdeco'],
+    pt: ['pwpt'],
+    en: ['pwgbj', 'pwgbs'],
+});
+/** The country hand's increase. Named so the gate can assert it against `minPx` instead of repeating it. */
+export 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 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 function typographyCycle(tag) {
+    const hands = handsForTag(tag);
+    return Object.freeze([
+        { letterCase: 'upper', font: 'andika', scale: 1 }, // (a) the literacy pair
+        { letterCase: 'mixed', font: 'andika', scale: 1 }, // (b)
+        { letterCase: 'mixed', font: 'atkinson', scale: 1 }, // (c) the default — the cycle starts here
+        { letterCase: 'mixed', font: 'lexend', scale: 1 }, // (d)
+        // (e), and (f) where the country teaches two. ⚠️ 25% LARGER, and the number is not taste: the document's base is
+        // 16 px, the Playwrite faces declare `minPx: 20`, and 16 × 1.25 is exactly 20. The scale IS the floor.
+        ...hands.map((face) => ({ letterCase: 'mixed', font: face, scale: HANDWRITING_SCALE })),
+    ]);
+}
+/** The index where the cycle STARTS — position (c). Named so the gate can assert it without recounting. */
+export const CYCLE_START = 2;
+/**
+ * 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 function handsForTag(tag) {
+    if (!tag)
+        return [];
+    const parts = String(tag).split('-');
+    const language = (parts[0] ?? '').toLowerCase();
+    const region = parts.slice(1).find((p) => /^[A-Za-z]{2}$/.test(p))?.toUpperCase();
+    if (region && HAND_BY_COUNTRY[region])
+        return HAND_BY_COUNTRY[region];
+    return HAND_BY_LANGUAGE[language] ?? [];
+}
 export const FONT_GROUPS = [
     { g: 'font.group.sans', items: [
-            { k: 'atkinson', fam: 'Atkinson Hyperlegible', fb: 'sans', d: 'font.desc.atkinson' },
-            { k: 'lexend', fam: 'Lexend', fb: 'sans', d: 'font.desc.lexend' },
-            { k: 'quattro', fam: 'iA Writer Quattro', fb: 'sans', d: 'font.desc.quattro' },
-            { k: 'andika', fam: 'Andika', fb: 'sans', d: 'font.desc.andika' },
-            // ⚠️ A OPENDYSLEXIC ENTRA SEM NENHUMA ALEGAÇÃO DE EFICÁCIA, e a restrição é da issue #87 item 3 e do
-            // `docs/game-design/typography.md`, que diz por extenso: «Ofereça a Dyslexie e a OpenDyslexic apenas como
-            // escolha do usuário. A pesquisa não mostra ganho de leitura com elas.» A descrição dela fala do DESENHO
-            // (hastes pesadas em baixo), nunca do efeito — prometer leitura melhor seria vender a uma criança
-            // disléxica uma coisa que a evidência não sustenta, e ela é quem menos pode pagar por isso.
-            { k: 'opendyslexic', fam: 'OpenDyslexic', fb: 'sans', d: 'font.desc.opendyslexic' },
-            { k: 'sourcesans', fam: 'Source Sans 3', fb: 'sans' },
-            { k: 'inter', fam: 'Inter', fb: 'sans' },
-            { k: 'opensans', fam: 'Open Sans', fb: 'sans' },
-            { k: 'lato', fam: 'Lato', fb: 'sans' }
+            { k: 'atkinson', id: 'atkinson_hyperlegible', fam: 'Atkinson Hyperlegible', fb: 'sans', d: 'font.desc.atkinson' },
+            { k: 'lexend', id: 'lexend', fam: 'Lexend', fb: 'sans', d: 'font.desc.lexend' },
+            { k: 'quattro', id: 'ia_writer_quattro', fam: 'iA Writer Quattro', fb: 'sans', d: 'font.desc.quattro' },
+            { k: 'andika', id: 'andika', fam: 'Andika', fb: 'sans', d: 'font.desc.andika' },
+            // ⚠️ OPENDYSLEXIC IS OFFERED WITH NO CLAIM OF EFFICACY — issue #87 item 3 and `docs/game-design/typography.md`: offer
+            // Dyslexie and OpenDyslexic only as a user's choice, because research shows no reading gain from them. Its description
+            // speaks of the DESIGN (heavy stems at the bottom), never of the effect — promising better reading would sell a
+            // dyslexic child something the evidence does not support, and they are who can least afford it.
+            { k: 'opendyslexic', id: 'opendyslexic', fam: 'OpenDyslexic', fb: 'sans', d: 'font.desc.opendyslexic' },
+            { k: 'sourcesans', id: 'source_sans_3', fam: 'Source Sans 3', fb: 'sans' },
+            { k: 'inter', id: 'inter', fam: 'Inter', fb: 'sans' },
+            { k: 'opensans', id: 'open_sans', fam: 'Open Sans', fb: 'sans' },
+            { k: 'lato', id: 'lato', fam: 'Lato', fb: 'sans' },
+            // ⚠️ THE FOUR ROUNDED FACES are here at the Dev's request, WITHOUT a description on purpose: a `d` exists when there
+            // is something to say the name does not — Atkinson has one because the Braille Institute designed it for this,
+            // OpenDyslexic because its description has to speak of the DESIGN and never the effect. Rounded is not a claim, it is
+            // what you see.
+            //
+            // 📌 `geral` (implicit role): interface faces, neither handwriting nor game — so they follow the BDA spacing ADR-0149
+            // §2 generalises, and appear in the typography menu like the others.
+            //
+            // ⚠️ `Fredoka` AND NOT "Fredoka One": that is the legacy name. Google publishes the variable family as `Fredoka`; the
+            // old static one was its 600 weight. See the matching block in `fonts.css`.
+            { k: 'fredoka', id: 'fredoka', fam: 'Fredoka', fb: 'sans' },
+            { k: 'quicksand', id: 'quicksand', fam: 'Quicksand', fb: 'sans' },
+            { k: 'nunito', id: 'nunito', fam: 'Nunito', fb: 'sans' },
+            { k: 'teachers', id: 'teachers', fam: 'Teachers', fb: 'sans' },
+            /*
+             * SEVEN MORE SANS FACES (ADR-0150, the Dev's request).
+             *
+             * 🔴 CLASH DISPLAY IS NOT HERE, and the absence is read, not forgotten: it is **not on Google Fonts** — it comes from
+             * Fontshare (Indian Type Foundry), and `LICENSES.md` §3 requires the licence checked BEFORE bundling. Read, it FAILS:
+             * it is «Closed Source» under the ITF Free Font License, whose §02 forbids distributing the file through a repository,
+             * an application or a public server and serving it as a selectable font to third parties. The gate is in
+             * `tests/what-fonts-the-package-carries.node.test.js`.
+             */
+            { k: 'robotoflex', id: 'roboto_flex', fam: 'Roboto Flex', fb: 'sans' },
+            { k: 'ubuntu', id: 'ubuntu', fam: 'Ubuntu', fb: 'sans' },
+            { k: 'notosans', id: 'noto_sans', fam: 'Noto Sans', fb: 'sans' },
+            { k: 'spacegrotesk', id: 'space_grotesk', fam: 'Space Grotesk', fb: 'sans', minPx: 20 },
+            { k: 'sora', id: 'sora', fam: 'Sora', fb: 'sans', minPx: 20 },
+            { k: 'jakarta', id: 'plus_jakarta_sans', fam: 'Plus Jakarta Sans', fb: 'sans', minPx: 20 }
         ] },
+    // ⚠️ NO COMFORTAA, by the Dev's decision: «ruim para dislexia». The reason is in the face — its near-geometric shapes
+    // reduce the differentiation between letters, the very axis that makes Atkinson Hyperlegible this project's default.
+    // Written down because a face that leaves no trace gets proposed again by the next person who thinks a rounded one is
+    // missing.
     { g: 'font.group.serif', items: [
-            { k: 'literata', fam: 'Literata', fb: 'serif' },
-            { k: 'sourceserif', fam: 'Source Serif 4', fb: 'serif' },
-            { k: 'newsreader', fam: 'Newsreader', fb: 'serif' }
+            { k: 'literata', id: 'literata', fam: 'Literata', fb: 'serif' },
+            { k: 'sourceserif', id: 'source_serif_4', fam: 'Source Serif 4', fb: 'serif' },
+            { k: 'newsreader', id: 'newsreader', fam: 'Newsreader', fb: 'serif' },
+            // Five READING faces: serifs for running text, like the three above.
+            { k: 'merriweather', id: 'merriweather', fam: 'Merriweather', fb: 'serif' },
+            { k: 'lora', id: 'lora', fam: 'Lora', fb: 'serif' },
+            { k: 'spectral', id: 'spectral', fam: 'Spectral', fb: 'serif' },
+            { k: 'domine', id: 'domine', fam: 'Domine', fb: 'serif' },
+            { k: 'bitter', id: 'bitter', fam: 'Bitter', fb: 'serif' },
+            /*
+             * ⚠️ THE FOUR DISPLAY FACES ARE SOMETHING ELSE, and come with the warning written instead of mixed with the reading
+             * ones. Playfair Display, DM Serif Display, Fraunces and Bodoni Moda have HIGH CONTRAST — thick stems beside very thin
+             * ones — and Bodoni is the extreme of the axis. It is exactly what Atkinson Hyperlegible was designed NOT to be, and at
+             * small sizes the thin stems disappear first for whoever sees least.
+             *
+             * 📌 They stay, because OFFERING is not applying: the default is still Atkinson, and whoever picks one of these is
+             * choosing. The defect would be the engine ADOPTING one by itself.
+             * 🔴 And they are not for activity body text; a game using them for a long prompt is using a title face as a reading
+             * face.
+             */
+            { k: 'playfair', id: 'playfair_display', fam: 'Playfair Display', fb: 'serif', minPx: 20 },
+            { k: 'dmserifdisplay', id: 'dm_serif_display', fam: 'DM Serif Display', fb: 'serif', minPx: 20 },
+            { k: 'fraunces', id: 'fraunces', fam: 'Fraunces', fb: 'serif', minPx: 20 },
+            { k: 'bodonimoda', id: 'bodoni_moda', fam: 'Bodoni Moda', fb: 'serif', minPx: 20 }
         ] },
-    // ⚠️ QUATRO FACES SAÍRAM DAQUI EM 2026-09-07 (issue #87, item 3, decisão do Dev):
-    //   · `greatvibes` (44 KB) e `ufcook` (20 KB) — peso que o roster não paga;
-    //   · `learningcurve` e `kindergarten` — eram entradas `.off` SEM FICHEIRO, isto é, o menu oferecia-as
-    //     desabilitadas e nada existia por trás. Uma linha que só serve para dizer «ainda não» é uma linha que
-    //     a criança lê e não pode usar.
+    // ⚠️ NO `.off` ENTRY WITHOUT A FILE (issue #87 item 3): a row that only exists to say "not yet" is a row the child
+    // reads and cannot use.
     { g: 'font.group.hand', items: [
-            { k: 'pinyon', fam: 'Pinyon Script', fb: 'cursive', d: 'font.desc.pinyon', papel: 'caligrafica', minPx: 24 },
-            { k: 'ufmag', fam: 'UnifrakturMaguntia', fb: 'cursive', d: 'font.desc.ufmag', papel: 'caligrafica', minPx: 20 },
-            // Fondamento entra pela emenda do ADR-0012 (#87 item 3) com o mínimo que o Dev fixou. Caligráfica, logo
-            // fora do menu — ela é para os botões DENTRO das atividades escolares, não para a interface.
-            { k: 'fondamento', fam: 'Fondamento', fb: 'cursive', d: 'font.desc.fondamento', papel: 'caligrafica', minPx: 20 },
-            // ⚠️ `comicneue` NÃO é caligráfica, e está neste grupo só por aparência: é uma face de propósito geral,
-            // frequentemente recomendada para dislexia. Marcá-la como caligráfica tirá-la-ia do menu — removendo uma
-            // opção legitimamente acessível pelo formato do grupo em vez de pelo papel.
-            { k: 'comicneue', fam: 'Comic Neue', fb: 'cursive', d: 'font.desc.comicneue' },
+            { k: 'pinyon', id: 'pinyon_script', fam: 'Pinyon Script', fb: 'cursive', d: 'font.desc.pinyon', role: 'caligrafica', minPx: 24 },
+            { k: 'ufmag', id: 'unifrakturmaguntia', fam: 'UnifrakturMaguntia', fb: 'cursive', d: 'font.desc.ufmag', role: 'caligrafica', minPx: 20 },
+            // Fondamento comes through the ADR-0012 amendment (#87 item 3) with the minimum the Dev set. Handwriting, so out of
+            // the menu — it is for the buttons INSIDE school activities, not for the interface.
+            { k: 'fondamento', id: 'fondamento', fam: 'Fondamento', fb: 'cursive', d: 'font.desc.fondamento', role: 'caligrafica', minPx: 20 },
+            /*
+             * THE FRENCH RONDE — #87 item 4, decided in ADR-0108 §4. It is NEVER bundled: the three faces are free for PERSONAL
+             * use only (ADR-0012), and distributing them would distribute what was not licensed for distribution. What the entry
+             * does is SPEAK.
+             *
+             * ⚠️ AND IT IS NOT A "NOT YET" ROW. The difference is ACTIONABILITY, the reason ADR-0108 gives in full: a "not yet"
+             * nobody can resolve; this names WHICH THREE FONTS TO INSTALL, which an adult resolves in an afternoon. 📌 "Install a
+             * ronde font" would be the defect back — an adult does not act on a category —, which is why the message names all
+             * three.
+             *
+             * ⚠️ `role` ABSENT, so `geral`, deliberately, although the ronde is handwriting by nature: handwriting faces are
+             * filtered out of the menu (`fontRole === 'geral'`), and a filtered row can say nothing to anyone. Marking the
+             * "right" role here would erase the one thing this entry exists to do.
+             */
             /*
-             * A RONDE FRANCESA — o item 4 da #87, decidido no ADR-0108 §4. Ela NUNCA é empacotada: as três faces são
-             * livres só para uso PESSOAL (ADR-0012), e distribuí-las seria distribuir o que não foi licenciado para
-             * distribuição. O que muda é que a opção passa a FALAR.
+             * THE PLAYWRITE FACES — #87 item 3, decided in ADR-0108 §2.
              *
-             * ⚠️ E ISTO NÃO É A ENTRADA `.off` QUE ESTE CATÁLOGO JÁ REMOVEU. O cabeçalho acima tirou a `learningcurve`
-             * e a `kindergarten` com a razão certa — «uma linha que só serve para dizer "ainda não" é uma linha que a
-             * criança lê e não pode usar». A diferença é ACCIONABILIDADE, e é a razão que o ADR-0108 dá por extenso:
-             * aquelas diziam «ainda não», que ninguém pode resolver; esta diz QUAIS TRÊS FONTES INSTALAR, que um
-             * adulto resolve numa tarde. 📌 «Instale uma fonte ronde» seria o defeito de volta — um adulto não age
-             * sobre uma categoria —, e é por isso que a mensagem nomeia as três.
+             * ⚠️ `role: caligrafica`, so OUT OF THE MENU: they are the hand one learns to write, for the buttons INSIDE school
+             * activities, not an interface option.
              *
-             * ⚠️ `papel` AUSENTE, logo `geral`, e é deliberado apesar de a ronde ser caligráfica por natureza: as
-             * caligráficas são filtradas do menu (`papelDaFonte === 'geral'`), e uma linha filtrada não pode dizer
-             * nada a ninguém. Marcar o papel «certo» aqui apagaria a única coisa que este item existe para fazer.
+             * 📌 `minPx: 20` is the same floor the other cursive faces carry. #87's list of minimums does not name the
+             * Playwrite — the number is its siblings', not a measurement of its own; correctable in one line.
              */
+            // THE HANDWRITING GROUP'S GENERAL FACE (ADR-0176 §6, the Dev): in the menu, drawn at `minPx` by the face's scale.
+            { k: 'pwbr', id: 'playwrite_br', fam: 'Playwrite BR', fb: 'cursive', d: 'font.desc.pw.br', minPx: 20 },
+            { k: 'pwustrad', id: 'playwrite_us_trad', fam: 'Playwrite US Trad', fb: 'cursive', d: 'font.desc.pw.ustrad', role: 'caligrafica', minPx: 20 },
+            { k: 'pwusmod', id: 'playwrite_us_modern', fam: 'Playwrite US Modern', fb: 'cursive', d: 'font.desc.pw.usmod', role: 'caligrafica', minPx: 20 },
+            { k: 'pwca', id: 'playwrite_ca', fam: 'Playwrite CA', fb: 'cursive', d: 'font.desc.pw.ca', role: 'caligrafica', minPx: 20 },
+            { k: 'pwmx', id: 'playwrite_mx', fam: 'Playwrite MX', fb: 'cursive', d: 'font.desc.pw.mx', role: 'caligrafica', minPx: 20 },
+            { k: 'pwar', id: 'playwrite_ar', fam: 'Playwrite AR', fb: 'cursive', d: 'font.desc.pw.ar', role: 'caligrafica', minPx: 20 },
+            { k: 'pwcl', id: 'playwrite_cl', fam: 'Playwrite CL', fb: 'cursive', d: 'font.desc.pw.cl', role: 'caligrafica', minPx: 20 },
+            { k: 'pwco', id: 'playwrite_co', fam: 'Playwrite CO', fb: 'cursive', d: 'font.desc.pw.co', role: 'caligrafica', minPx: 20 },
             /*
-             * AS OITO PLAYWRITE — o item 3 da #87, decidido no ADR-0108 §2 e entregue em 2026-09-09.
+             * SEVEN MORE, and they exist by a RULE and not by taste (ADR-0150, the Dev's decision).
+             *
+             * 🎯 `pwes`, `pwpt` and `pwgbj` are the FALLBACK BY LANGUAGE: a country without its own Playwrite gets the
+             * COLONISER's — Spanish → Spain, Portuguese → Portugal, English → England.
+             * 📌 `pwcu` and `pwpe` were asked for by name; `pwesdeco` and `pwgbs` come through the other half of the rule: where
+             * the country has more than one STROKE, both appear — like US Trad and US Modern.
              *
-             * ⚠️ `papel: caligrafica`, logo FORA DO MENU: elas são a mão que se aprende a escrever, para os botões
-             * DENTRO das atividades escolares, e não uma opção de interface. É a divisão do item 1 desta issue.
+             * ⚠️ NO "GUIDES" FACES, by the Dev's decision: a `Playwrite XX Guides` is not a second stroke, it is the SAME stroke
+             * with handwriting ruling on top. The engine does not use them; a game that needs them brings its own font.
              *
-             * 📌 `minPx: 20` é o mesmo piso que as outras três cursivas carregam. A lista de mínimos da #87 não
-             * nomeia a Playwrite — o número é o das irmãs, e não uma medição própria; corrigir-se com uma linha.
+             * 🔴 AND THEY ARE BUNDLED, which REVOKES ADR-0108's P3. The newer decision is the Dev's, literally: «estas fontes
+             * devem ser baixadas no primeiro dia para fazer parte do PWA». Written down because the old record still says the
+             * opposite.
              */
-            { k: 'pwbr', fam: 'Playwrite BR', fb: 'cursive', d: 'font.desc.pw.br', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwustrad', fam: 'Playwrite US Trad', fb: 'cursive', d: 'font.desc.pw.ustrad', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwusmod', fam: 'Playwrite US Modern', fb: 'cursive', d: 'font.desc.pw.usmod', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwca', fam: 'Playwrite CA', fb: 'cursive', d: 'font.desc.pw.ca', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwmx', fam: 'Playwrite MX', fb: 'cursive', d: 'font.desc.pw.mx', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwar', fam: 'Playwrite AR', fb: 'cursive', d: 'font.desc.pw.ar', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwcl', fam: 'Playwrite CL', fb: 'cursive', d: 'font.desc.pw.cl', papel: 'caligrafica', minPx: 20 },
-            { k: 'pwco', fam: 'Playwrite CO', fb: 'cursive', d: 'font.desc.pw.co', papel: 'caligrafica', minPx: 20 },
-            { k: 'ronde', fam: 'Ronde Script, OPTIFrench-Script, Merveille', fb: 'cursive',
-                d: 'font.desc.ronde', off: 'font.off.ronde' }
+            { k: 'pwes', id: 'playwrite_es', fam: 'Playwrite ES', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwesdeco', id: 'playwrite_es_deco', fam: 'Playwrite ES Deco', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwpt', id: 'playwrite_pt', fam: 'Playwrite PT', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwgbj', id: 'playwrite_gb_j', fam: 'Playwrite GB J', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwgbs', id: 'playwrite_gb_s', fam: 'Playwrite GB S', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwcu', id: 'playwrite_cu', fam: 'Playwrite CU', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'pwpe', id: 'playwrite_pe', fam: 'Playwrite PE', fb: 'cursive', role: 'caligrafica', minPx: 20 },
+            { k: 'ronde', id: 'ronde_script', fam: 'Ronde Script, OPTIFrench-Script, Merveille', fb: 'cursive',
+                d: 'font.desc.ronde', off: 'font.off.ronde', minPx: 18 }
         ] },
-    // ⚠️ A FACE DO JOGO, e ela tem grupo próprio porque não é nem sans, nem serifada, nem manuscrita — é uma
-    // face de PIXEL, e pô-la em qualquer um dos três diria a coisa errada sobre ela na lista.
+    // ⚠️ THE GAME'S FACE has its own group because it is neither sans, nor serif, nor handwriting — it is a PIXEL face,
+    // and putting it in any of the three would say the wrong thing about it in the list.
     //
-    // Ela NÃO aparece no menu (`papel:'jogo'`), e o ficheiro veio do `SP-the-inclusionist-whackwhack`, onde já
-    // estava verificado. Ver a nota do `@font-face` em `vendor/fonts.css`: o subconjunto errado desta família
-    // carrega, declara-se e reporta-se como certo, e não desenha uma única letra latina.
+    // It does NOT appear in the menu (`role:'jogo'`). See the `@font-face` note in `vendor/fonts.css`: the wrong subset of
+    // this family loads, declares itself and reports as correct, and draws not a single Latin letter.
     { g: 'font.group.arcade', items: [
-            { k: 'pressstart', fam: 'Press Start 2P', fb: 'monospace', d: 'font.desc.pressstart', papel: 'jogo' }
+            { k: 'pressstart', id: 'press_start_2p', fam: 'Press Start 2P', fb: 'monospace', d: 'font.desc.pressstart', role: 'jogo' }
         ] },
 ];
-/** O papel de uma face; ausente no catálogo quer dizer `geral`. */
-export function papelDaFonte(it) { return it.papel ?? 'geral'; }
 /**
- * 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 function faceScale(it) { return Math.max(1, (it.minPx ?? BASE_EM_PX) / BASE_EM_PX); }
+/** A face's role; absent in the catalogue means `geral`. */
+export function fontRole(it) { return it.role ?? 'geral'; }
+/**
+ * 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 three (`'Ronde Script, OPTIFrench-Script, Merveille'`) because any of them will do — three
+ * drawings of the same hand, and an adult installs whichever they find. The other faces declare one, and for them this
+ * returns a list of one.
  */
-export function familiasDaFace(it) {
+export function faceFamilies(it) {
     return it.fam.split(',').map((f) => f.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
 }
 /**
- * ESTA FACE PODE SER USADA AGORA? — o `off` deixa de ser uma sentença e passa a ser uma CONDIÇÃO.
+ * CAN THIS FACE BE USED NOW? — `off` stops being a sentence and becomes a CONDITION.
  *
- * 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.
+ * ADR-0012 decided the ronde option stays DISABLED WHILE no font is present, and ADR-0108 §4 added what it says. The word
+ * "while" is what this function builds: an `off` face becomes available again the instant the adult installs one of the
+ * ones the message names.
  *
- * ⚠️ 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.
+ * ⚠️ 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 installed, which is safe for a reason that does not hold for every default in this repository:
+ * with no detector the option stays disabled WITH the message, and the message tells the adult exactly what to do. The
+ * silence decides nothing against the child — it keeps a state that already existed and is actionable.
  */
-export function faceDisponivel(it, instalada) {
+export function faceAvailable(it, installed) {
     if (!it.off)
         return true;
-    return !!instalada && familiasDaFace(it).some((f) => instalada(f));
+    return !!installed && faceFamilies(it).some((f) => installed(f));
 }
-/** As faces que o MENU pode oferecer: só as gerais (emenda do ADR-0012). */
-export const OFERECIVEIS = FONT_GROUPS.flatMap((g) => g.items).filter((it) => papelDaFonte(it) === 'geral');
-export const FONT_BY_KEY = {};
-FONT_GROUPS.forEach((g) => g.items.forEach((it) => { FONT_BY_KEY[it.k] = it; }));
-export const FONT_KEY = 'incl_font_k';
-export const FONT_KEY_LEGACY = 'incl_fonte'; // pre-Fase-2: 'alfabetizacao' | 'dislexia'
+/** The faces the MENU may offer: only the general ones (ADR-0012 amendment). */
+export const OFERECIVEIS = FONT_GROUPS.flatMap((g) => g.items).filter((it) => fontRole(it) === 'geral');
+/**
+ * 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 const FONT_BY_KEY = Object.fromEntries(FONT_GROUPS.flatMap((g) => g.items.map((it) => [it.k, it])));
+const FONT_KEY = 'incl_font_k';
+const FONT_KEY_LEGACY = 'incl_fonte'; // pre-Fase-2: 'alfabetizacao' | 'dislexia'
 /**
- * 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 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 function resolveFontKey(s) {
     const k = s.get(FONT_KEY, null);
-    if (k && FONT_BY_KEY[k] && !FONT_BY_KEY[k].off && papelDaFonte(FONT_BY_KEY[k]) === 'geral')
+    if (k && FONT_BY_KEY[k] && !FONT_BY_KEY[k].off && fontRole(FONT_BY_KEY[k]) === 'geral')
         return k;
     const leg = s.get(FONT_KEY_LEGACY, null);
     if (leg === 'alfabetizacao')
@@ -157,6 +312,7 @@ export function resolveFontKey(s) {
     return DEFAULT_FONT_KEY;
 }
 export function persistFontKey(s, k) { s.set(FONT_KEY, k); }
-// Conveniencia sobre o storage real — mesma logica, sem duplicá-la.
-export function loadFontKey() { return resolveFontKey(store); }
-export function saveFontKey(k) { persistFontKey(store, k); }
+// ⚠️ `loadFontKey` AND `saveFontKey` ARE GONE (R3 of the plan, 2026-09-23): they were conveniences over
+// `resolveFontKey` and `persistFontKey` — the same two lines with `store` already filled in — and NOBODY took
+// them, not even a test. A shortcut nobody takes is not a convenience: it is published surface that asks whoever
+// reads it to migrate.

package/dist-pkg/ui/game-options.d.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { PanelShellCtx } from './panel-shell.js';
+/** One position of a steps or list row: the value the cartridge reads and writes, and its label in the interface language. */
+export interface GameOptionValue {
+    readonly value: string;
+    readonly label: string;
+}
+interface GameOptionBase {
+    /** Stable and unique among the game's rows; the control is `#game-option-<id>`. */
+    readonly id: string;
+    /** The row's short name, in the interface language. */
+    readonly label: string;
+    /** The explanation, shown in the footer (CLAUDE.md §4). */
+    readonly hint?: string;
+}
+export type GameOption = (GameOptionBase & {
+    /** Steps «◀ Label: value ▶», up to five positions; a list, any number (ADR-0130 erratum). */
+    readonly kind: 'steps' | 'list';
+    readonly values: readonly GameOptionValue[];
+    /** The value in use. Read at every opening and after every write: what shows is what the cartridge keeps. */
+    readonly read: () => string;
+    readonly write: (value: string) => void;
+}) | (GameOptionBase & {
+    readonly kind: 'switch';
+    readonly read: () => boolean;
+    readonly write: (on: boolean) => void;
+});
+/** Why a `gameOptions` declaration is malformed; empty when it is well formed. Absent is well formed: no options of its own. */
+export declare function gameOptionsProblems(options: unknown): string[];
+export interface GameOptionsDrawCtx extends PanelShellCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** Where a change is said (the polite live region). */
+    readonly say: (text: string) => void;
+}
+/**
+ * Draws the rows into `list`, replacing what was there — the rows are the CURRENT cartridge's, and `mount()` may have
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, at drawing and after each write.
+ */
+export declare function drawGameOptions(ctx: GameOptionsDrawCtx, list: HTMLElement, options: readonly GameOption[]): void;
+export {};