@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/pause-markup.d.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate, Translator } from '../core/i18n.js';
+import { type PauseIcon } from '../core/pause-icon-catalogue.js';
+/**
+ * What the bar's markup reads of the root's translator (ADR-0232 D3 erratum): its `t`, and the page's language, which the
+ * 🌐 button shows as a flag. A Pick and not a bare `t`, because the flag reads the language.
+ */
+export type BarTranslator = Pick<Translator, 't' | 'locale'>;
+/** One `.pm-btn` descriptor — the shape of an entry of `PM_BTNS` (owned by ui/pause-buttons). */
+export interface PauseMenuButton {
+    act: string;
+    /** Read ONLY when the button has a dynamic label; see the note on `PauseBtnDef` (ui/pause-buttons). */
+    lbl?: string;
+    /** Dynamic label (the ABC cycle) — rendered from `lbl`, not from i18n, and NOT given `data-i18n`. */
+    dynamicLabel?: boolean;
+    /** Dynamic label (the literacy level) — rendered from quizLevel + qlName. Currently dormant: no PM_BTNS
+     *  entry sets it, but the branch is live code and is ported verbatim. */
+    level?: boolean;
+}
+/** One `.pi-btn`. The label is the RESTING one: reflectIconBtn overwrites it with the stateful label as soon as the bar is
+ *  reflected. `ic.n` is an i18n key, so it must be resolved here too — the markup is rendered once at build
+ *  time and would otherwise ship the raw key to a screen reader. */
+export declare function iconBtnMarkup(tr: BarTranslator, ic: PauseIcon): string;
+/** The whole icon bar. Used by the pause screen AND by the splash `#title-icons` — one builder, so the two bars
+ *  cannot drift apart.
+ *  The parameter is ADDITIVE and the default is the whole list: whoever already called it with no arguments gets the same
+ *  string back. */
+export declare function iconsMarkup(tr: BarTranslator, icons?: readonly PauseIcon[]): string;
+/**
+ * One `.pm-btn`. Dynamic labels (`letra`/`nivel`) are rendered eagerly and carry NO `data-i18n`, so `i18n.applyDom()` cannot
+ * overwrite them.
+ *
+ * ⚠️ THE DYNAMIC LABEL ARRIVES READY-MADE, and that change fixed TWO things at once.
+ *
+ * The line used to be `'📚 Nível ' + level + ' · ' + qlName[level]`, and it had two defects that only show together:
+ *
+ *   1. BOUNDARY. `level` came from `core/state.quizLevel` and `qlName` from a table owned by the game. An ENGINE pause menu
+ *      was assembling the label of a literacy activity — pedagogical content, not mechanics.
+ *   2. LANGUAGE. «Nível» is raw pt-BR inside an engine module. The gate of that time did not reach `ui/`, so this line
+ *      crossed the whole i18n pass unseen. In an English build, a child's pause menu said «📚 Nível 2 · …».
+ *
+ * Now the game hands over the finished phrase (`dynLabel`) and the engine only puts it on the button. The game is the one who
+ * knows what a level is, what it is called, and in which language to say it.
+ */
+export declare function pmBtnMarkup(b: PauseMenuButton, dynLabel: (b: PauseMenuButton) => string | null, tr: (key: string) => string): string;
+/**
+ * WHICH of the lists the pause card is showing.
+ *
+ * THREE lists in the markup, ONE visible — and the hidden ones carry `hidden`, which takes them out of the accessibility
+ * tree entirely. That is what makes «one menu per screen» (ADR-0044 §5) true for whoever listens and not only for whoever
+ * sees, and it is what lets the ring wrap around INSIDE the visible list without ever crossing into another.
+ *
+ * ⚠️ THREE since 2026-09-12 (ADR-0146): `jogo` is the list of what belongs to THIS game, beside the list of what the child
+ * carries between games. The rule above does not change for being three.
+ */
+export type PauseSub = 'raiz' | 'opcoes' | 'jogo';
+/**
+ * THE ACCESSIBILITY QUICK BAR — the toggles and the caption that explains them (ADR-0044, item 7).
+ *
+ * It left the pause card and went to live in the HUD. The reason is about use, not tidiness: it is DURING the game that a
+ * child needs to change a setting that is getting in her way, not after pausing. The secondary reason is structural — without
+ * it, the card stops having two zones and becomes a LIST, which is what finally authorises the ring (XAG 106 allows wrapping
+ * for a linear menu and forbids it for a grid).
+ *
+ * THE CAPTION TRAVELS WITH IT. It is the hint that replaces, for whoever does not see, the `title` only a mouse reveals;
+ * leaving it behind in the card would have made the HUD bar mute.
+ */
+export declare function quickBarMarkup(tr: BarTranslator, icons?: readonly PauseIcon[]): string;
+export interface ScreenPauseMarkupOpts {
+    /** Screen/player index (0-based); the dialog label and the seat suffix are 1-based. */
+    player: number;
+    /** Live player count — the suffix only appears in multiplayer. */
+    numPlayers: number;
+    /** The ROOT list: the items of ADR-0044, `resume` first and `quit` last. */
+    pmButtons: readonly PauseMenuButton[];
+    /** The settings submenu: the adjustment panels, with «back» in front. */
+    optionsButtons: readonly PauseMenuButton[];
+    /** The GAME's submenu (ADR-0146). Absent = only «back», which is the case of a game that declares nothing of its own. */
+    gameButtons?: readonly PauseMenuButton[];
+    /** The finished label of a DYNAMIC button, or `null` if that button has none. The game is who builds the phrase. */
+    dynLabel: (b: PauseMenuButton) => string | null;
+    /** Translates in the page's language — the root's translator (ADR-0232 D3), with the {param}s the seat needs. */
+    t: Translate;
+}
+/** The full innerHTML of a `.screen-pause`. Pure — every input is a parameter. */
+export declare function screenPauseMarkup(o: ScreenPauseMarkupOpts): string;

package/dist-pkg/ui/pause-markup.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/pause-markup — THE HTML OF THE PAUSE CARD AND OF THE ACCESSIBILITY BAR, as pure strings (ADR-0221; issue #203).
+//
+// Every function here takes what it needs and returns a string: no `document`, no injected ctx, no state. That is what lets a
+// node test read the card's markup without mounting a browser, and it is the half of `ui/pause-icons` that never had to know
+// anything about the DOM.
+//
+// 🔴 WHY IT LEFT: `ui/pause-icons` was 645 lines and 122 decision nodes after the catalogue left, and it held two jobs that do
+// not need each other — BUILDING the strings, and then wiring, reflecting and navigating the elements the browser made from
+// them. 📌 And the DATA had to leave FIRST: the markup needs the icon catalogue, so with all three in one file the markup
+// could not be extracted without the two modules importing each other — the cycle ADR-0173 forbids. Catalogue in `core`,
+// markup here, DOM next door.
+//
+// ⚠️ THE i18n KEY IS RESOLVED HERE, and that is not a matter of style: this markup is rendered ONCE and assigned to
+// `innerHTML`, so a key left unresolved would ship the literal `icon.blind` to a screen reader. Where a label is rewritten
+// later (state, seat, dynamic rows) the element that carries it is rendered with its own `<span>` or `data-i18n`, which is the
+// seam `ui/pause-icons` writes through.
+import { PAUSE_ICONS } from '../core/pause-icon-catalogue.js';
+import { flagOf } from './locale-flags.js';
+import { PM_GAME_BTNS } from './pause-buttons.js';
+/** One `.pi-btn`. The label is the RESTING one: reflectIconBtn overwrites it with the stateful label as soon as the bar is
+ *  reflected. `ic.n` is an i18n key, so it must be resolved here too — the markup is rendered once at build
+ *  time and would otherwise ship the raw key to a screen reader. */
+export function iconBtnMarkup(tr, ic) {
+    return '<button class="pi-btn" type="button" data-pi="' + ic.k +
+        '" aria-label="' + tr.t(ic.n) + '">' + (ic.k === 'idioma' ? flagOf(tr.locale()) : ic.e) + '</button>';
+}
+/** The whole icon bar. Used by the pause screen AND by the splash `#title-icons` — one builder, so the two bars
+ *  cannot drift apart.
+ *  The parameter is ADDITIVE and the default is the whole list: whoever already called it with no arguments gets the same
+ *  string back. */
+export function iconsMarkup(tr, icons = PAUSE_ICONS) {
+    return icons.map((ic) => iconBtnMarkup(tr, ic)).join('');
+}
+/**
+ * One `.pm-btn`. Dynamic labels (`letra`/`nivel`) are rendered eagerly and carry NO `data-i18n`, so `i18n.applyDom()` cannot
+ * overwrite them.
+ *
+ * ⚠️ THE DYNAMIC LABEL ARRIVES READY-MADE, and that change fixed TWO things at once.
+ *
+ * The line used to be `'📚 Nível ' + level + ' · ' + qlName[level]`, and it had two defects that only show together:
+ *
+ *   1. BOUNDARY. `level` came from `core/state.quizLevel` and `qlName` from a table owned by the game. An ENGINE pause menu
+ *      was assembling the label of a literacy activity — pedagogical content, not mechanics.
+ *   2. LANGUAGE. «Nível» is raw pt-BR inside an engine module. The gate of that time did not reach `ui/`, so this line
+ *      crossed the whole i18n pass unseen. In an English build, a child's pause menu said «📚 Nível 2 · …».
+ *
+ * Now the game hands over the finished phrase (`dynLabel`) and the engine only puts it on the button. The game is the one who
+ * knows what a level is, what it is called, and in which language to say it.
+ */
+export function pmBtnMarkup(b, dynLabel, tr) {
+    const dyn = b.dynamicLabel || b.level;
+    const lbl = dynLabel(b) ?? (dyn ? (b.lbl ?? '') : tr('pause.' + b.act));
+    const glyph = ITEM_GLYPH[b.act];
+    return '<button class="pm-btn' + (b.dynamicLabel ? ' pm-letra' : '') + (b.level ? ' pm-nivel' : '') +
+        '" role="menuitem" type="button" data-act="' + b.act + '"' +
+        (glyph ? ' data-glifo="' + glyph + '"' : '') +
+        (dyn ? '' : (' data-i18n="pause.' + b.act + '"')) + '>' + lbl + '</button>';
+}
+/**
+ * THE GLYPH OF EACH PAUSE ITEM, drawn by the stylesheet and never part of the name (ADR-0159 rule 12: «An emoji or
+ * symbol in a menu is decorative and hidden from narration»). It lived at the start of each dictionary value, so the
+ * engine's narration and a screen reader both said «⚙ Inclusion settings». The glyph is the same in every language;
+ * the words stay in the dictionary.
+ *
+ * 📌 NOT exported any more, and the `exports-without-consumer` gate is what said so: it sat in the declared debt of
+ * `ui/pause-icons` — published with nobody importing it — and moving house was the moment to stop publishing it. Its only
+ * reader is `pmBtnMarkup`, one screen above.
+ */
+const ITEM_GLYPH = {
+    // 🔴 `resume` HAS THE BACK GLYPH, not a «tocar» arrow: the Dev asked «não seria melhor usar "↩ Voltar" para o primeiro
+    // item do menu pausado também?». ADR-0158 had already made «Voltar» item 1 of every panel; the card was the only
+    // exception, with no reason of its own. From the child's point of view it is one word — leave here and go back to what
+    // I was doing —, and the destination is always the previous level: from the panel, the card; from the submenu, the
+    // root; from the root, the game. «Voltar ao jogo» named the DESTINATION instead of the action, and it was the only one.
+    resume: '↩', acessibilidade: '♿', options: '⚙', opcoesdojogo: '🎮', pmback: '↩', tipo: '🔤', addplayer: '👥',
+    audio: '🦻', som: '🔊', motora: '♿', anim: '🎞', visual: '🎨', empatia: '🫂', ajuda: '❓', print: '📷', quit: '🚪',
+    caa: '🔠',
+};
+/** The innerHTML of ONE `.pause-menu`: the list, and nothing else.
+ *  📌 Also no longer exported, by the same measurement as `ITEM_GLYPH`: it was in the declared debt, and what calls it is
+ *  `screenPauseMarkup`, three times, right below. */
+function pauseMenuHtml(bs, sub, dynLabel, tr) {
+    return '<div class="pause-menu" role="menu" data-sub="' + sub + '"' + (sub === 'raiz' ? '' : ' hidden') + '>' +
+        bs.map((b) => pmBtnMarkup(b, dynLabel, tr)).join('') + '</div>';
+}
+/**
+ * THE ACCESSIBILITY QUICK BAR — the toggles and the caption that explains them (ADR-0044, item 7).
+ *
+ * It left the pause card and went to live in the HUD. The reason is about use, not tidiness: it is DURING the game that a
+ * child needs to change a setting that is getting in her way, not after pausing. The secondary reason is structural — without
+ * it, the card stops having two zones and becomes a LIST, which is what finally authorises the ring (XAG 106 allows wrapping
+ * for a linear menu and forbids it for a grid).
+ *
+ * THE CAPTION TRAVELS WITH IT. It is the hint that replaces, for whoever does not see, the `title` only a mouse reveals;
+ * leaving it behind in the card would have made the HUD bar mute.
+ */
+export function quickBarMarkup(tr, icons = PAUSE_ICONS) {
+    return '<div class="pause-icons" role="group" aria-label="' + tr.t('pause.iconBarAria') + '">' + iconsMarkup(tr, icons) +
+        '</div><p class="pause-icons-cap" aria-live="polite"></p>';
+}
+/** The full innerHTML of a `.screen-pause`. Pure — every input is a parameter. */
+export function screenPauseMarkup(o) {
+    // THE DIALOG'S ACCESSIBLE NAME goes through the dictionary. It was raw text, and MEASURED in an English game the effect was
+    // this: the visible title said «Paused» and the dialog's name «Menu de pausa do jogador 1». Whoever saw read English;
+    // whoever listened got the menu announced in Portuguese — the same asymmetry as item 4 of ADR-0044, one level up. And
+    // `aria-label`, not `aria-labelledby`: the `<h2>` is a VISUAL label, which is why hiding it in a tight frame does not take
+    // the dialog's name away from whoever listens.
+    return '<div class="pause-card" role="dialog" aria-modal="true" aria-label="' + o.t('pause.cardAria', { n: o.player + 1 }) + '">' +
+        '<h2><span data-i18n="pause.title">' + o.t('pause.title') + '</span>'
+        // ⚠️ THE SEAT SUFFIX USED TO BE `' · Jogador ' + (o.player + 1)` — raw Portuguese inside an engine module, and an English
+        // game read «Paused · Jogador 2». It is a key now, and it lives in a `<span>` of its own because the item refresh needs
+        // somewhere to REPAINT it: since `pause.cardSeat` takes a parameter, the `data-i18n` path of `applyDom` — which calls
+        // `t(k)` with no parameters — does not serve here.
+        // 📌 `o.t` is the root's `Translate` (ADR-0232 D3), which carries the seat's `{n}` across.
+        + '<span class="pause-seat">' + (o.numPlayers > 1 ? o.t('pause.cardSeat', { n: o.player + 1 }) : '') + '</span></h2>' +
+        pauseMenuHtml(o.pmButtons, 'raiz', o.dynLabel, o.t) +
+        pauseMenuHtml(o.optionsButtons, 'opcoes', o.dynLabel, o.t) +
+        // ⚠️ THE THIRD LIST IS ALWAYS IN THE MARKUP, even for a game that declares nothing — and it is not waste: it is the same
+        // reason the other two are built whole and hidden afterwards (see the note on `buildScreenPause`). The game's table
+        // arrives LATE, and a list filtered at mount time would erase for ever what only came to exist after boot. What decides
+        // what is SEEN is the item refresh.
+        pauseMenuHtml(o.gameButtons ?? PM_GAME_BTNS, 'jogo', o.dynLabel, o.t) +
+        '<p class="pause-legend"></p></div>';
+}

package/dist-pkg/ui/reach-notice.d.ts

@@ -1,34 +1,33 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { Alcance } from '../input/transports.js';
-/** `core/i18n.t` — injetado para o núcleo continuar puro e para o teste poder ver as chaves cruas. */
-export type Tradutor = (chave: string, params?: Record<string, string | number>) => string;
+import type { Reach } from '../input/transports.js';
+/** `core/i18n.t` — injected so the core stays pure and the test can see the raw keys. */
+export type Translator = (key: string, params?: Record<string, string | number>) => string;
 /**
- * AS FRASES DO AVISO, na ordem em que são lidas. Vazio = não há nada a dizer, e é o caso comum.
+ * THE NOTICE'S SENTENCES, in reading order. Empty = there is nothing to say, which is the common case.
  *
- * ⚠️ A ÚLTIMA LINHA TEM DUAS FORMAS, e a diferença entre elas é a diferença entre ajudar e mentir:
+ * ⚠️ THE LAST LINE HAS TWO FORMS, and the difference between them is the difference between helping and lying:
  *
- *   · há transporte que serviria se ligado → «ligue um controle», que é acionável.
- *   · não há nenhum → dizer «ligue um controle» seria mandar a criança procurar uma coisa que não resolve.
- *     Nesse caso o problema é do JOGO, que pede mais posições do que qualquer transporte deste aparelho
- *     oferece, e a frase honesta é outra.
+ *   · some transport would serve if switched on → tell the child to switch it on, which is actionable.
+ *   · there is none → telling them to plug in a controller would send the child looking for something that does not
+ *     solve it. Then the problem is the GAME's, which asks for more positions than any transport on this device
+ *     offers, and the honest sentence is a different one.
  */
-export declare function linhasDoAviso(a: Alcance, t: Tradutor): string[];
+export declare function noticeRows(a: Reach, t: Translator): string[];
 export interface ReachNoticeCtx {
-    /** `querySelector` do documento deste jogo. */
-    procurar: (sel: string) => HTMLElement | null;
-    /** `document.createElement`. Injetado como tudo o mais que toca o documento. */
-    criar: (tag: string) => HTMLElement;
-    t: Tradutor;
-    /** Anúncio assertivo. Uma criança cega tem de OUVIR isto — ela não vai ver o cartão. */
-    srAlert: (texto: string) => void;
+    /** `querySelector` of this game's document. */
+    find: (sel: string) => HTMLElement | null;
+    /** `document.createElement`. Injected like everything else that touches the document. */
+    create: (tag: string) => HTMLElement;
+    t: Translator;
+    /** Assertive announcement. A blind child has to HEAR this — they will not see the card. */
+    srAlert: (text: string) => void;
 }
-/** O id do cartão. Estável porque o teste e a folha de estilo o procuram. */
+/** The card's id. Stable because the test and the stylesheet look for it. */
 export declare const REACH_NOTICE_ID = "reach-notice";
 /**
- * Mostra o aviso, se houver o que dizer. Devolve `true` quando mostrou.
+ * Shows the notice, if there is something to say. Returns `true` when it showed.
  *
- * ⚠️ MONTA POR NÓS E NÃO POR `innerHTML`. As frases passam por `t()` e um dicionário é conteúdo que muda sem
- * passar por revisão de código — é exatamente a fronteira que a issue #106 mapeia. `textContent` fecha a
- * questão sem precisar de escapar nada.
+ * ⚠️ BUILT FROM NODES AND NOT `innerHTML`. The sentences go through `t()`, and a dictionary is content that changes
+ * without code review — exactly the boundary issue #106 maps. `textContent` settles it with nothing to escape.
  */
-export declare function mostrarAvisoDeAlcance(ctx: ReachNoticeCtx, a: Alcance): boolean;
+export declare function showReachNotice(ctx: ReachNoticeCtx, a: Reach): boolean;

package/dist-pkg/ui/reach-notice.js

@@ -1,79 +1,76 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * AS FRASES DO AVISO, na ordem em que são lidas. Vazio = não há nada a dizer, e é o caso comum.
+ * THE NOTICE'S SENTENCES, in reading order. Empty = there is nothing to say, which is the common case.
  *
- * ⚠️ A ÚLTIMA LINHA TEM DUAS FORMAS, e a diferença entre elas é a diferença entre ajudar e mentir:
+ * ⚠️ THE LAST LINE HAS TWO FORMS, and the difference between them is the difference between helping and lying:
  *
- *   · há transporte que serviria se ligado → «ligue um controle», que é acionável.
- *   · não há nenhum → dizer «ligue um controle» seria mandar a criança procurar uma coisa que não resolve.
- *     Nesse caso o problema é do JOGO, que pede mais posições do que qualquer transporte deste aparelho
- *     oferece, e a frase honesta é outra.
+ *   · some transport would serve if switched on → tell the child to switch it on, which is actionable.
+ *   · there is none → telling them to plug in a controller would send the child looking for something that does not
+ *     solve it. Then the problem is the GAME's, which asks for more positions than any transport on this device
+ *     offers, and the honest sentence is a different one.
  */
-export function linhasDoAviso(a, t) {
+export function noticeRows(a, t) {
     if (a.ok)
         return [];
-    const nome = (id) => t('reach.nome.' + id);
-    const linhas = [t('reach.titulo', { pedidas: a.pedidas })];
-    for (const c of a.curtos) {
-        linhas.push(t('reach.curto', { transporte: nome(c.id), lugares: c.slots }));
+    const name = (id) => t('reach.nome.' + id);
+    const rows = [t('reach.titulo', { pedidas: a.asked })];
+    for (const c of a.short) {
+        rows.push(t('reach.curto', { transporte: name(c.id), lugares: c.slots }));
     }
-    // ⚠️ A TERCEIRA FRASE, e ela existe porque um transporte pode CHEGAR a todas as ações e ainda assim não
-    // deixar a criança jogar (ADR-0104). Medido: a plataforma pede nove ações, o controle de tela tem nove
-    // lugares, e o cartão nunca aparecia — mas correr, andar e pular ao mesmo tempo são três dedos, e um
-    // telemóvel que reconhece dois não os dá. A criança tentava, não acontecia nada, e concluía que o jogo
-    // estava partido. Uma frase antes de começar é a resposta honesta; meia tela jogável não é.
-    for (const s of a.naoSeguram) {
-        linhas.push(t('reach.naoSegura', { transporte: nome(s.id), segura: s.holds, pedidas: a.seguraPedidas }));
+    // ⚠️ THE THIRD SENTENCE exists because a transport can REACH every action and still not let the child play
+    // (ADR-0104): holding three actions at once takes three fingers, and a phone that recognises two does not give
+    // them. The child would try, nothing would happen, and they would conclude the game was broken.
+    for (const s of a.cannotHold) {
+        rows.push(t('reach.naoSegura', { transporte: name(s.id), segura: s.holds, pedidas: a.holdsAsked }));
     }
-    linhas.push(a.serviriamSeLigados.length
-        ? t('reach.ligue', { saida: a.serviriamSeLigados.map(nome).join(t('reach.ou')) })
+    rows.push(a.wouldServeIfOn.length
+        ? t('reach.ligue', { saida: a.wouldServeIfOn.map(name).join(t('reach.ou')) })
         : t('reach.semSaida'));
-    return linhas;
+    return rows;
 }
-/** O id do cartão. Estável porque o teste e a folha de estilo o procuram. */
+/** The card's id. Stable because the test and the stylesheet look for it. */
 export const REACH_NOTICE_ID = 'reach-notice';
 /**
- * Mostra o aviso, se houver o que dizer. Devolve `true` quando mostrou.
+ * Shows the notice, if there is something to say. Returns `true` when it showed.
  *
- * ⚠️ MONTA POR NÓS E NÃO POR `innerHTML`. As frases passam por `t()` e um dicionário é conteúdo que muda sem
- * passar por revisão de código — é exatamente a fronteira que a issue #106 mapeia. `textContent` fecha a
- * questão sem precisar de escapar nada.
+ * ⚠️ BUILT FROM NODES AND NOT `innerHTML`. The sentences go through `t()`, and a dictionary is content that changes
+ * without code review — exactly the boundary issue #106 maps. `textContent` settles it with nothing to escape.
  */
-export function mostrarAvisoDeAlcance(ctx, a) {
-    const linhas = linhasDoAviso(a, ctx.t);
-    if (linhas.length === 0)
+export function showReachNotice(ctx, a) {
+    const rows = noticeRows(a, ctx.t);
+    if (rows.length === 0)
         return false;
-    const dentro = ctx.procurar('#game-region');
-    if (!dentro)
-        return false; // sem a marcação do hospedeiro não há onde mostrar; o `problems` já o denuncia
-    const fora = ctx.criar('div');
-    fora.id = REACH_NOTICE_ID;
-    fora.className = 'overlay';
-    const cartao = ctx.criar('div');
-    cartao.className = 'overlay__card';
-    cartao.setAttribute('role', 'dialog');
-    cartao.setAttribute('aria-modal', 'true');
-    cartao.setAttribute('tabindex', '-1');
-    for (const [i, texto] of linhas.entries()) {
-        const p = ctx.criar('p');
-        p.textContent = texto;
+    const isInside = ctx.find('#game-region');
+    if (!isInside)
+        return false; // without the host's markup there is nowhere to show it; `problems` already reports that
+    const overlay = ctx.create('div');
+    overlay.id = REACH_NOTICE_ID;
+    overlay.className = 'overlay';
+    const card = ctx.create('div');
+    card.className = 'overlay__card';
+    card.setAttribute('role', 'dialog');
+    card.setAttribute('aria-modal', 'true');
+    card.setAttribute('tabindex', '-1');
+    for (const [i, text] of rows.entries()) {
+        const p = ctx.create('p');
+        p.textContent = text;
         if (i === 0)
             p.className = 'reach-notice__titulo';
-        cartao.appendChild(p);
+        card.appendChild(p);
     }
-    // ⚠️ O BOTÃO É O QUE FAZ DISTO UM AVISO E NÃO UMA PORTA FECHADA. Ver o cabeçalho: a detecção de teclado
-    // erra, e o erro só é aceitável enquanto a criança puder seguir em frente.
-    const seguir = ctx.criar('button');
-    seguir.setAttribute('type', 'button');
-    seguir.className = 'mode-btn';
-    seguir.textContent = ctx.t('reach.continuar');
-    seguir.addEventListener('click', () => fora.remove());
-    cartao.appendChild(seguir);
-    fora.appendChild(cartao);
-    dentro.appendChild(fora);
-    // O foco vai para o cartão, não para o botão: a criança tem de OUVIR o motivo antes de encontrar a saída.
-    // (Se fosse para o botão, o leitor de tela leria «Jogar assim mesmo» e o resto ficaria para quem procurasse.)
-    cartao.focus();
-    ctx.srAlert(linhas.join(' '));
+    // ⚠️ THE BUTTON IS WHAT MAKES THIS A NOTICE AND NOT A CLOSED DOOR. See the header: keyboard detection errs, and the
+    // error is only acceptable while the child can carry on.
+    const continueButton = ctx.create('button');
+    continueButton.setAttribute('type', 'button');
+    continueButton.className = 'mode-btn';
+    continueButton.textContent = ctx.t('reach.continuar');
+    continueButton.addEventListener('click', () => overlay.remove());
+    card.appendChild(continueButton);
+    overlay.appendChild(card);
+    isInside.appendChild(overlay);
+    // Focus goes to the card, not the button: the child has to HEAR the reason before finding the way out.
+    // (On the button, a screen reader would read "Play anyway" and the rest would be left for whoever looked.)
+    card.focus();
+    ctx.srAlert(rows.join(' '));
     return true;
 }

package/dist-pkg/ui/scan-overlay.d.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import type { Translate } from '../core/i18n.js';
+/** What the chip reads for one item. Pure: the engine's word where the item is the engine's, else the game's own word. */
+export declare function scanItemText(item: string, label: (a: Action) => string | null, t: Translate): string;
+export interface ScanOverlay {
+    /**
+     * Puts the item on screen, and answers whether the words CHANGED. The same item twice does not rewrite the node — a live
+     * region that repeats itself says it twice — and the answer is what lets the caller re-measure the room only when a word of
+     * a different length arrives, instead of every frame.
+     */
+    showing(text: string): boolean;
+    /** Takes the chip off screen; the scan is off. */
+    hide(): void;
+    remove(): void;
+}
+/**
+ * Mounts the chip inside the game's region, under the quick bar's band.
+ *
+ * ⚠️ `role="status"`, not `alert`: a child who plays by ear hears each item as it comes, and an alert would interrupt whatever
+ * the game is saying at every step of a scan that never stops.
+ */
+export declare function mountScanOverlay(doc: Document, host: HTMLElement): ScanOverlay;

package/dist-pkg/ui/scan-overlay.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/scan-overlay — WHAT «ONE BUTTON ONLY» IS OFFERING RIGHT NOW (ADR-0218, issue #201).
+//
+// A scan is the machine offering and the child taking, and she cannot take what she cannot see: the whole accommodation is the
+// list going by, so the list going by has to be ON SCREEN, in the game's own words, and it has to reach a child who plays by
+// ear as well — which is why the chip is a live region and not a picture.
+//
+// 📌 THE WORDS ARE THE GAME'S. What is offered is a position the cartridge declared and NAMED (`preset`), so the chip says
+// «Confirmar» or «Dizer a resposta», never `action2` (ADR-0074). A position the game did not name is not offered at all — the
+// list is built from the named ones — because a scan that stopped on a word nobody wrote would cost the child a full pass.
+import { SCAN_CANCEL } from '../input/switch-scan.js';
+/** The ENGINE's words, by dictionary key — the wording is an interface choice (interface log 2026-09-26). */
+const ENGINE_WORDS = new Map([
+    [SCAN_CANCEL, 'scan.nothing'],
+    ['select', 'scan.door.menus'], ['start', 'scan.door.pause'],
+    ['next', 'scan.menu.next'], ['confirm', 'scan.menu.confirm'], ['back', 'scan.menu.back'], ['previous', 'scan.menu.previous'],
+    ['increase', 'scan.menu.increase'], ['decrease', 'scan.menu.decrease'],
+]);
+/** What the chip reads for one item. Pure: the engine's word where the item is the engine's, else the game's own word. */
+export function scanItemText(item, label, t) {
+    const key = ENGINE_WORDS.get(item);
+    return key ? t(key) : (label(item) ?? '');
+}
+/**
+ * Mounts the chip inside the game's region, under the quick bar's band.
+ *
+ * ⚠️ `role="status"`, not `alert`: a child who plays by ear hears each item as it comes, and an alert would interrupt whatever
+ * the game is saying at every step of a scan that never stops.
+ */
+export function mountScanOverlay(doc, host) {
+    const el = doc.createElement('div');
+    el.className = 'scan-now';
+    el.setAttribute('role', 'status');
+    el.hidden = true;
+    host.appendChild(el);
+    let last = null;
+    return {
+        showing(text) {
+            const appeared = el.hidden;
+            el.hidden = false;
+            if (text === last)
+                return appeared;
+            last = text;
+            el.textContent = text;
+            return true;
+        },
+        hide() { el.hidden = true; last = null; el.textContent = ''; },
+        remove() { el.remove(); },
+    };
+}

package/dist-pkg/ui/screen-text.d.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import type { WorldScope } from '../core/contract.js';
+/** What the reader is built over. Both are read at every call: a `mount()` swaps the cartridge, a panel opens. */
+export interface ScreenTextCtx {
+    /** The root's document. */
+    readonly doc: Document;
+    /** The world the mounted game declares (`GameDeclaration.world`). */
+    readonly world: () => WorldScope;
+}
+/**
+ * WHAT IS ON THE SCREEN NOW, as the sonar reads it — `''` when there is nothing the engine can read: no world, an empty one,
+ * or a world drawn on a canvas.
+ */
+export declare function screenText(ctx: ScreenTextCtx): string;
+/**
+ * The `problems` line for a world the sonar cannot read — none, or one (ADR-0169: the subject, the child's cost, the fix).
+ * Measured at every read of `problems`: a canvas is often drawn after the boot.
+ */
+export declare function unreadableWorldProblems(ctx: ScreenTextCtx): string[];
+/**
+ * A press made WITH A MENU OPEN: the menu sonar's position reads what is in front (`read`) and takes the press. Any other
+ * position is left to the menus — answers whether this one was taken.
+ */
+export declare function menuSonarPress(action: Action, ctx: ScreenTextCtx, read: (text: string) => void): boolean;