@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/ui/latch-refusal.js

@@ -1,60 +1,60 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/latch-refusal.ts — QUANDO A ALTERNÂNCIA NÃO É UMA ESCOLHA, e o que se diz a quem carregou no botão.
+// ui/latch-refusal.ts — WHEN LATCHING IS NOT A CHOICE, and what to say to whoever pressed the button.
 //
-// ========================= A CLÁUSULA 3 DO ADR-0113 =========================
-// «É impossível desligá-la em modos que não tem como funcionar sem ela (voz e câmera)» — a frase do Dev. Em
-// olhos, rosto, gestos e fala a alternância é o que faz a entrada funcionar: sem ela, um comando de cada vez
-// significa que a criança não consegue andar e agir.
+// ========================= CLAUSE 3 OF ADR-0113 =========================
+// «É impossível desligá-la em modos que não tem como funcionar sem ela (voz e câmera)» — the Dev's sentence. With
+// eyes, face, gestures and speech, latching is what makes the input work: without it, one command at a time means
+// the child cannot move and act.
 //
-// ⚠️ E O CONTROLE NÃO SOME — FICA DESABILITADO, COM O MOTIVO DITO. Sumir ensina que a coisa não existe: um
-// adulto conclui que ela foi retirada, não que a webcam a exige. É a mesma metade «never silently removed»
-// que o ADR-0076 escreveu para a simulação, e este ficheiro é o irmão do `ui/simulation-refusal` de propósito
-// — mesma forma, mesmo lugar na camada, e portanto conferível no project `node`, sem documento.
+// ⚠️ AND THE CONTROL DOES NOT DISAPPEAR — IT IS DISABLED, WITH THE REASON SAID. Disappearing teaches that the thing
+// does not exist: an adult concludes it was removed, not that the webcam requires it. It is the same «never silently
+// removed» half that ADR-0076 wrote for the simulation, and this file is the sibling of `ui/simulation-refusal` on
+// purpose — same shape, same place in the layer, and so checkable in the `node` project, with no document.
 //
-// 🔴 E O MOTIVO É UM FACTO SOBRE O APARELHO, NUNCA UMA REPREENSÃO. «O controle por olhar precisa das teclas de
-// alternância para funcionar» diz por que o botão não responde; «não desligue isto» repreende uma criança por
-// mexer num ajuste de que ela depende. O ADR-0076 já pagou esta distinção uma vez, e a mutação que a apanhou
-// trocava a frase por uma mais curta, mais clara e mais útil — que reprovava na mesma.
+// 🔴 AND THE REASON IS A FACT ABOUT THE DEVICE, NEVER A REPRIMAND. "Gaze control needs tap-to-move to work." says why
+// the button does not respond; telling the child not to turn it off scolds them for touching a setting they depend
+// on. ADR-0076 already paid for this distinction once.
 //
-// Módulo-folha: importa só a regra pura da alternância.
-import { alternanciaEhEscolha, UM_COMANDO_DE_CADA_VEZ } from '../input/latch-scope.js';
+// Leaf module: it imports only the pure latching rule.
+import { latchIsOptional, ONE_COMMAND_AT_A_TIME } from '../input/latch-scope.js';
 /**
- * A chave i18n do motivo, POR TRANSPORTE.
+ * The i18n key of the reason, PER TRANSPORT.
  *
- * ⚠️ QUATRO CHAVES E NÃO UMA COM `{aparelho}`, e a razão é de tradução e não de estilo: «os gestos» é plural
- * e «o olhar» não, logo uma frase única obrigaria cada idioma a montar concordância a partir de um
- * substantivo solto. É exactamente o defeito que o `sr.nav.clockOne` registou para «às 1 horas», e que o
- * `ui/simulation-refusal` já recusou pela mesma razão com os três eixos dele.
+ * ⚠️ FOUR KEYS AND NOT ONE WITH `{aparelho}`, and the reason is translation, not style: «os gestos» is plural and
+ * «o olhar» is not, so a single sentence would force each language to build agreement from a loose noun. It is
+ * exactly the defect `sr.nav.clockOne` recorded for «às 1 horas», and that `ui/simulation-refusal` already refused
+ * for the same reason with its three axes.
  */
-export const CHAVE_DA_RECUSA = Object.freeze({
+export const REFUSAL_KEY = Object.freeze({
     olhos: 'alt.exigida.olhos',
     rosto: 'alt.exigida.rosto',
     gestos: 'alt.exigida.gestos',
     fala: 'alt.exigida.fala',
 });
 /**
- * A alternância pode ser desligada neste aparelho? E se não, o que dizer.
+ * Can latching be turned off on this device? And if not, what to say.
  *
- * `null` = pode; a interface não mostra nada, porque um aviso que aparece sempre deixa de ser lido.
+ * `null` = it can; the interface shows nothing, because a warning that always appears stops being read.
  */
-export function recusaDaAlternancia(transporte) {
-    if (alternanciaEhEscolha(transporte))
+export function latchRefusal(transportName) {
+    if (latchIsOptional(transportName))
         return null;
-    const chave = CHAVE_DA_RECUSA[transporte];
-    // 📌 Um transporte que exija alternância e não tenha frase seria um botão desabilitado SEM motivo — pior do
-    // que o defeito que isto conserta, porque a criança deixa de saber sequer que há uma razão. O gate afirma
-    // que os dois conjuntos coincidem; aqui a ausência degrada para «não recuso», que mantém o controle vivo.
-    return chave ? { chave, transporte } : null;
+    const refusalKey = REFUSAL_KEY[transportName];
+    // 📌 A transport that requires latching and has no sentence would be a button disabled WITHOUT a reason — worse
+    // than the defect this fixes, because the child would not even know there is a reason. The gate asserts that the
+    // two sets match; here the absence degrades to "do not refuse", which keeps the control alive.
+    return refusalKey ? { key: refusalKey, transport: transportName } : null;
 }
 /**
- * O controle continua NA TELA quando a alternância é exigida?
+ * Does the control stay ON SCREEN when latching is required?
  *
- * ⚠️ SEMPRE, e é a metade «não some» da cláusula 3. Existe como função com nome próprio, e não como um
- * `!recusa` no ponto de uso, porque responde a outra pergunta: `recusaDaAlternancia` diz *por que* não dá;
- * esta diz *que a linha continua na tela*. Juntá-las faria «não há motivo» parecer «não desenhe a linha».
+ * ⚠️ ALWAYS, and it is the "does not disappear" half of clause 3. It exists as a function with its own name, and
+ * not as a negated refusal at the point of use, because it answers another question: `latchRefusal` says *why* it
+ * cannot; this says *that the row stays on screen*. Merging them would make "no reason" look like "do not draw the
+ * row".
  */
-export function mostraMesmoExigida() {
+export function showsEvenWhenRequired() {
     return true;
 }
-/** Os transportes que exigem alternância, para quem precisa de os enumerar. Vem da REGRA, não de uma cópia. */
-export const EXIGEM_ALTERNANCIA = UM_COMANDO_DE_CADA_VEZ;
+/** The transports that require latching, for whoever needs to enumerate them. It comes from the RULE, not a copy. */
+export const NEED_LATCH = ONE_COMMAND_AT_A_TIME;

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

@@ -1,38 +1,113 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * A RÉGUA DO ALVO DE TOQUE, INDEXADA PELA ALTURA DO VIEWPORT (ADR-0095, decisão do Dev).
+ * THE TOUCH TARGET FLOOR, in CSS px, for a CSS scale factor `k` (ADR-0163).
  *
- * ⚠️ O ALVO DEIXOU DE SER UM NÚMERO E PASSOU A SER UMA FUNÇÃO DA TELA, e o motivo é um custo que o gate de
- * `pausa-44px` já tinha MEDIDO e deixado por resolver: a 640×360 o cartão de pausa não cabe e a lista ROLA.
- * Remedido em 06/09, porque o cartão mudou desde então: 391 px de conteúdo para 349 visíveis, ou seja 42 px
- * de excesso (o comentário antigo dizia 413/353). Um alvo de 44 px que exige rolagem para ser alcançado
- * pode custar mais dedo do que um de 24 px que está à vista.
+ * 🔴 IT WAS A RULER BY VIEWPORT HEIGHT (ADR-0095: 24 px under 540, 34 under 720, 44 above), because a 640×360 pause
+ * card with 44 px items scrolled. ADR-0163 made the resolution the engine's — never under 640×360 — and the Dev set the
+ * target — «44px é o correto, eu errei quando disse 42px» — so the floor is 44 px at the minimum (k = 2) and
+ * grows with the scale, like the text; there is no smaller screen left to shrink for.
+ */
+export declare function minimumTarget(k: number): number;
+/** One node inside the region, as measured by whoever calls: its computed font size if it holds text, its box if it is a target. */
+export interface NodeMeasure {
+    readonly name: string;
+    readonly daEngine: boolean;
+    readonly fontPx: number | null;
+    readonly target: {
+        readonly w: number;
+        readonly h: number;
+    } | null;
+}
+/**
+ * WHAT A CARTRIDGE DRAWS UNDER THE FLOOR (ADR-0163 rule 4): text under 8·k px (16 at 640×360) and targets whose SMALLER
+ * side is under 22·k px (44 at 640×360). The engine's own nodes are not the cartridge's to answer for, and a node with no
+ * area is not drawn. Half a pixel of slack absorbs subpixel layout.
+ */
+export declare function belowFloor(nodes: readonly NodeMeasure[], k: number): {
+    text: string[];
+    targets: string[];
+};
+/**
+ * THE GAME'S NODES THAT INVADE THE ACCESSIBILITY BAR'S RECTANGLE (ADR-0148 §3).
+ *
+ * 🔴 The bar is `position:absolute` INSIDE `#game-region`, so a game can draw right over it — a question title on top
+ * of the buttons, and the child looking for blind mode finds text over them.
+ *
+ * ⚠️ AND NOTHING FAILS. No error, no type, no console: just a row of covered buttons — and whoever depends on it most is
+ * precisely whoever cannot see it is covered.
  *
- * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ * 📌 PURE AND WITH THE BOXES INJECTED, so the gate can drive it with no browser. Whoever calls measures; what this
+ * function decides is what COUNTS as an invasion, which is the part people get wrong.
  *
- *     altura ≥ 720   44 px   WCAG 2.2 · 2.5.5 Target Size (Enhanced) — AAA
- *     altura ≥ 540   34 px   o degrau do meio
- *     altura <  540  24 px   WCAG 2.2 · 2.5.8 Target Size (Minimum)  — AA
+ * ⚠️ IT IGNORES THE BAR'S OWN DESCENDANTS: its buttons intersect it by definition, and counting them would make the gate
+ * accuse always — the defect ADR-0106 §2 calls drowning what can be fixed.
+ */
+export interface NamedBox {
+    readonly name: string;
+    readonly box: Box;
+    readonly isBar: boolean;
+}
+export interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export declare function barIntruders(barBox: Box | null, nodes: readonly NamedBox[]): string[];
+/** The document a layout measures — only the lookup it uses. */
+export type LayoutDoc = Pick<Document, 'querySelector'>;
+/**
+ * The scale ADR-0001 gives a stage: the factor in REAL pixels (whole, except at the floor — ADR-0179), the CSS factor, and
+ * the region's CSS size.
+ */
+export interface Scale {
+    readonly kDev: number;
+    readonly k: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * ADR-0001 AS A PURE FUNCTION — so the engine can apply it to every cartridge (ADR-0163) and a test can pin it.
  *
- * ⚠️ ISTO É «MARCAR HONESTAMENTE ONDE SÓ DÁ AA», que é regra escrita do projeto — e não uma renúncia
- * silenciosa. O que se perde em 360 está registrado com número no ADR-0095: a 96 px/pol, 24 CSS px são
- * 6,4 mm, abaixo do alvo de polegar de 9,6 mm que o painel de toque deste jogo cita. É por isso que o
- * ESPAÇAMENTO entre alvos passa a ser o que protege o dedo onde o tamanho não pode — a mesma saída que a
- * própria 2.5.8 dá na sua exceção de spacing.
+ * Integer multiple of 320×180 (per the screen grid) in REAL pixels; up to 5 logical px of crop per side when that buys one
+ * more step (the `−10`: `base·kDev − avail·dpr ≤ 10·kDev`). Never under 2 CSS px per logical pixel — 640×360 CSS, text 16 px,
+ * targets 44 px: where the whole multiple gives less (a fractional display scale on the minimum window) the scale is exactly
+ * 2 CSS px, whole in real pixels or not, because WCAG 2.2 AA decides (ADR-0179).
  */
-export declare const REGUA_DE_ALVO: readonly {
-    readonly altura: number;
-    readonly alvo: number;
-}[];
+export declare function stageScale(availW: number, availH: number, dpr: number, baseW: number, baseH: number): Scale;
 /**
- * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ * Writes a scale onto the game region: its size, and the UI variables that grow with it.
  *
- * ⚠️ NUNCA DEVOLVE MENOS DE 24: abaixo disso não é «AA num aparelho pequeno», é furar o piso da WCAG. Uma
- * tela mais baixa que 360 não compra o direito de encolher mais — compra o direito de mostrar menos itens.
+ * ⚠️ HOST-INJECTED (the region is passed in): `createGame` serves documents that
+ * are not the global one — the fault the root's finding 15 names about reaching `document` from under the injection.
+ */
+export declare function applyScale(region: HTMLElement, e: Scale): void;
+export interface LayoutCtx {
+    /** The document holding the stage shell and `#game-region` — passed, never the global one (ADR-0232). */
+    doc: LayoutDoc;
+    /** The window, for its pixel ratio only: the scale is locked to whole REAL pixels. */
+    win: Pick<Window, 'devicePixelRatio'>;
+    /**
+     * THE PLAYER COUNT, as the GETTER of the round the game owns (ADR-0038): the screen grid sets the base size. A number
+     * would freeze the count at the first layout.
+     */
+    numPlayers: () => number;
+    /**
+     * CALLED AFTER EVERY SCALE — the root's CRT re-anchoring its scanlines to real pixels (`engine.crt.scanVars`).
+     * REQUIRED: the layout used to call the page's one CRT by import, and a game that forgets this would get scanlines
+     * spaced for the previous scale, with no error. A game with no CRT passes `() => {}` and says so.
+     */
+    afterScale: () => void;
+    /** Logs the scale to the console (`?debug=true`). Optional: absent, nothing is logged. */
+    debug?: () => boolean;
+}
+/** A game's stage scaler. */
+export interface Layout {
+    /** Measures the shell, scales `#game-region` and calls `afterScale`. Call it at boot and on every `resize`. */
+    layout(): void;
+}
+/**
+ * Builds a stage scaler over the document and window it is handed. It keeps nothing between calls: every `layout()`
+ * measures again, reads the player count again, and writes onto the region.
  */
-export declare function alvoMinimoDeToque(alturaCss: number): number;
-/** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
-export declare function initLayout(deps: {
-    numJogadores: () => number;
-}): void;
-export declare function layout(): void;
+export declare function createLayout(ctx: LayoutCtx): Layout;

package/dist-pkg/ui/layout.js

@@ -1,117 +1,132 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/layout.ts — ESCALA do jogo (Estágio 4, Tier 1). Trava o #game-region num múltiplo inteiro de PIXELS REAIS
-// de 320×180 (por jogador) e reescala as vars de UI escopadas ao canvas. Deps: ui/dom ($), core/screens,
-// render/crt (crtScanVars). A contagem de jogadores entra por `initLayout`. fpsTick/configureRender seguem no main.js.
+// ui/layout.ts — the game's SCALE. Locks #game-region to a whole multiple of REAL PIXELS of 320×180 (per player) and
+// rescales the UI variables scoped to the canvas. Deps: core/screens. The pure arithmetic (`stageScale`, `applyScale`,
+// the target floor, the reporters' rules) is exported as functions; `createLayout` is the shell that measures a
+// document it is HANDED and calls `afterScale` (the root's CRT re-anchoring its scanlines) — ADR-0232 D4, issue #207.
 //
-// JÁ NÃO RESERVA ESPAÇO PARA O INTÉRPRETE. Reservava 380px à direita quando o painel do VLibras "abria", e o
-// jogo deslocava para a esquerda — decisão revista pelo Dev: o intérprete deve aparecer NA FRENTE da tela
-// enquanto um áudio toca, e sumir. E a reserva estava sendo aplicada O TEMPO TODO, porque o detector de
-// "aberto" lia um div vazio (ver o cabeçalho de ui/vlibras): o canvas vivia em `left: -136`, fora da tela,
-// com ou sem modo pessoa surda. O acoplamento vlibras↔layout desaparece junto.
-import { $ } from './dom.js';
+// IT RESERVES NO SPACE FOR THE INTERPRETER: the Dev decided the interpreter appears IN FRONT of the screen while audio
+// plays, and disappears (see ui/vlibras), so the layout does not shift the game for it.
 import { screenBaseSize } from '../core/screens.js';
-import { crtScanVars } from '../render/crt.js';
 /**
- * A RÉGUA DO ALVO DE TOQUE, INDEXADA PELA ALTURA DO VIEWPORT (ADR-0095, decisão do Dev).
+ * THE TOUCH TARGET FLOOR, in CSS px, for a CSS scale factor `k` (ADR-0163).
  *
- * ⚠️ O ALVO DEIXOU DE SER UM NÚMERO E PASSOU A SER UMA FUNÇÃO DA TELA, e o motivo é um custo que o gate de
- * `pausa-44px` já tinha MEDIDO e deixado por resolver: a 640×360 o cartão de pausa não cabe e a lista ROLA.
- * Remedido em 06/09, porque o cartão mudou desde então: 391 px de conteúdo para 349 visíveis, ou seja 42 px
- * de excesso (o comentário antigo dizia 413/353). Um alvo de 44 px que exige rolagem para ser alcançado
- * pode custar mais dedo do que um de 24 px que está à vista.
- *
- * Os três degraus são os do Dev, e os dois extremos são as duas normas — não números de gosto:
+ * 🔴 IT WAS A RULER BY VIEWPORT HEIGHT (ADR-0095: 24 px under 540, 34 under 720, 44 above), because a 640×360 pause
+ * card with 44 px items scrolled. ADR-0163 made the resolution the engine's — never under 640×360 — and the Dev set the
+ * target — «44px é o correto, eu errei quando disse 42px» — so the floor is 44 px at the minimum (k = 2) and
+ * grows with the scale, like the text; there is no smaller screen left to shrink for.
+ */
+export function minimumTarget(k) {
+    return 22 * (Number.isFinite(k) && k > 2 ? k : 2);
+}
+/**
+ * WHAT A CARTRIDGE DRAWS UNDER THE FLOOR (ADR-0163 rule 4): text under 8·k px (16 at 640×360) and targets whose SMALLER
+ * side is under 22·k px (44 at 640×360). The engine's own nodes are not the cartridge's to answer for, and a node with no
+ * area is not drawn. Half a pixel of slack absorbs subpixel layout.
+ */
+export function belowFloor(nodes, k) {
+    const ratio = minimumTarget(k) / 22;
+    const smallText = [];
+    const smallTargets = [];
+    for (const n of nodes) {
+        if (n.daEngine)
+            continue;
+        if (n.fontPx !== null && n.fontPx > 0 && n.fontPx < 8 * ratio - 0.5)
+            smallText.push(n.name);
+        if (n.target && n.target.w > 0 && n.target.h > 0 && Math.min(n.target.w, n.target.h) < minimumTarget(k) - 0.5)
+            smallTargets.push(n.name);
+    }
+    return { text: smallText, targets: smallTargets };
+}
+export function barIntruders(barBox, nodes) {
+    // A bar with no area reserves nothing — and accusing against a zero rectangle would accuse everyone.
+    if (!barBox || barBox.w <= 0 || barBox.h <= 0)
+        return [];
+    // ⚠️ THE ZERO-AREA GUARD DOES WORK: the strict inequalities exclude a node that is DEGENERATE AT THE BOUNDARY, not one
+    // in general — a zero-width stripe crossing the bar passes all four comparisons. 📌 Containers of zero height or width
+    // are common in generated markup, and accusing them would be pure noise — which is how a consumer learns to ignore
+    // the line.
+    return nodes
+        .filter((n) => !n.isBar && n.box.w > 0 && n.box.h > 0)
+        .filter((n) => n.box.x < barBox.x + barBox.w && barBox.x < n.box.x + n.box.w
+        && n.box.y < barBox.y + barBox.h && barBox.y < n.box.y + n.box.h)
+        .map((n) => n.name);
+}
+/**
+ * THE SHELL THAT GIVES THE AVAILABLE SPACE — by id OR by class, and both forms count the same.
  *
- *     altura ≥ 720   44 px   WCAG 2.2 · 2.5.5 Target Size (Enhanced) — AAA
- *     altura ≥ 540   34 px   o degrau do meio
- *     altura <  540  24 px   WCAG 2.2 · 2.5.8 Target Size (Minimum)  — AA
+ * ⚠️ BY ID ONLY, a host with `<div class="stage-wrap">` (the quiz) got no scale at all: `layout()` returned early and
+ * nothing reported anything — a silent `return` is indistinguishable from "there was nothing to do".
  *
- * ⚠️ ISTO É «MARCAR HONESTAMENTE ONDE SÓ DÁ AA», que é regra escrita do projeto — e não uma renúncia
- * silenciosa. O que se perde em 360 está registrado com número no ADR-0095: a 96 px/pol, 24 CSS px são
- * 6,4 mm, abaixo do alvo de polegar de 9,6 mm que o painel de toque deste jogo cita. É por isso que o
- * ESPAÇAMENTO entre alvos passa a ser o que protege o dedo onde o tamanho não pode — a mesma saída que a
- * própria 2.5.8 dá na sua exceção de spacing.
+ * The consumer is not wrong to use the class: a document can have several screens, and an id is unique. Accepting both
+ * is what makes the engine consumable by whoever did not copy its markup.
  */
-export const REGUA_DE_ALVO = Object.freeze([
-    { altura: 720, alvo: 44 },
-    { altura: 540, alvo: 34 },
-    { altura: 0, alvo: 24 },
-]);
+function findStageWrap(doc) {
+    return doc.querySelector('#stage-wrap') ?? doc.querySelector('.stage-wrap');
+}
 /**
- * O menor alvo de toque aceitável num viewport desta altura, em CSS px.
+ * ADR-0001 AS A PURE FUNCTION — so the engine can apply it to every cartridge (ADR-0163) and a test can pin it.
  *
- * ⚠️ NUNCA DEVOLVE MENOS DE 24: abaixo disso não é «AA num aparelho pequeno», é furar o piso da WCAG. Uma
- * tela mais baixa que 360 não compra o direito de encolher mais — compra o direito de mostrar menos itens.
+ * Integer multiple of 320×180 (per the screen grid) in REAL pixels; up to 5 logical px of crop per side when that buys one
+ * more step (the `−10`: `base·kDev − avail·dpr ≤ 10·kDev`). Never under 2 CSS px per logical pixel — 640×360 CSS, text 16 px,
+ * targets 44 px: where the whole multiple gives less (a fractional display scale on the minimum window) the scale is exactly
+ * 2 CSS px, whole in real pixels or not, because WCAG 2.2 AA decides (ADR-0179).
  */
-export function alvoMinimoDeToque(alturaCss) {
-    const h = Number.isFinite(alturaCss) ? alturaCss : 0;
-    for (const degrau of REGUA_DE_ALVO)
-        if (h >= degrau.altura)
-            return degrau.alvo;
-    return 24;
+export function stageScale(availW, availH, dpr, baseW, baseH) {
+    const MIN_K = 2;
+    const integerK = Math.floor(Math.min(availW * dpr / (baseW - 10), availH * dpr / (baseH - 10)));
+    const kDev = integerK / dpr >= MIN_K ? integerK : MIN_K * dpr;
+    const k = kDev / dpr;
+    return { kDev, k, width: baseW * k, height: baseH * k };
 }
-// A CONTAGEM DE JOGADORES entra por injeção desde 2026-08-26. Era `numPlayers`, um `let` de `core/state`
-// importado como binding vivo — e um `let` de módulo é compartilhado por qualquer segundo jogo que a
-// mesma página carregue (D13 do `demos`, ADR-0038). O que entra aqui é o GETTER da rodada que a raiz
-// possui; o `let` que sobra guarda a função, não o número.
-let _numJogadores = () => 1;
-/** Liga a contagem de jogadores. Chamado uma vez pela raiz, antes do primeiro `layout()`. */
-export function initLayout(deps) { _numJogadores = deps.numJogadores; }
 /**
- * A CASCA QUE DÁ O ESPAÇO DISPONÍVEL — por id OU por classe, e as duas formas valem o mesmo.
- *
- * ⚠️ ERA SÓ `#stage-wrap`, E ISSO DEIXOU A ENGINE SEM ESCALA NO PRÓPRIO HOST. O `app/index.html` do jogo
- * trazia `<div id="stage-wrap">`; quando o cartucho saiu (issue #111) sobrou o `app/quiz.html`, que tem
- * `<div class="stage-wrap">`. A procura por id falhava, `layout()` fazia early-return, e **nada reportava
- * nada**: um `return` silencioso é indistinguível de «não havia o que fazer». O comentário do próprio
- * `quiz.html` dizia «mesmo id que ui/layout escala» — quem o escreveu acreditava que corria.
+ * Writes a scale onto the game region: its size, and the UI variables that grow with it.
  *
- * O consumidor não erra ao usar a classe: um documento pode ter várias telas, e um id é único. Aceitar as
- * duas é o que torna a engine consumível por quem não copiou o markup dela.
+ * ⚠️ HOST-INJECTED (the region is passed in): `createGame` serves documents that
+ * are not the global one — the fault the root's finding 15 names about reaching `document` from under the injection.
  */
-function cascaDoPalco() {
-    return $('#stage-wrap') ?? $('.stage-wrap');
+export function applyScale(region, e) {
+    region.style.width = e.width + 'px';
+    region.style.height = e.height + 'px';
+    region.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * e.k * 0.052)) + 'px');
+    region.style.setProperty('--ui-fs', (8 * e.k) + 'px'); // LOGICAL base 8px × k (16px at k=2)
+    // One ruler (plan phase 5b): `--tap` is the name three sibling games read, `--alvo-min` the engine's (ADR-0163); both come
+    // from `minimumTarget`, so a display scale that gives k under 2 (Windows 110%) no longer drops `--tap` under 44 px.
+    region.style.setProperty('--tap', minimumTarget(e.k) + 'px');
+    region.style.setProperty('--alvo-min', minimumTarget(e.k) + 'px'); // 44 px at 640×360, growing with k (ADR-0163)
 }
-export function layout() {
-    const wrap = cascaDoPalco();
-    if (!wrap)
-        return;
-    wrap.style.paddingRight = '0px';
-    const availW = wrap.clientWidth || 320;
-    const availH = wrap.clientHeight || 180;
-    // E11: a grade de telas define a base (1=320×180, 2=640×180, 3-4=640×360)
-    const n = _numJogadores();
-    // (`screenGrid(n)` SAIU em 2026-08-26: `cols`/`rows` eram desestruturados e nunca lidos — a escala sai de
-    //  `screenBaseSize`, logo abaixo. Era uma chamada paga a cada `layout()` por nada. `noUnusedLocals` achou.)
-    const { w: baseW, h: baseH } = screenBaseSize(n);
-    // Piso k=2: CADA viewport tem no mínimo 640×360. Assim 2×2 = 1280×720 cabe num Chromebook do governo (1366×768).
-    const MIN_K = 2;
-    // ADR-001 (CORRIGIDO 2026-07-04): ESCALA travada em PIXELS REAIS INTEIROS. Cada pixel de arte = kDev pixels
-    // FÍSICOS (inteiro) → scanlines SEMPRE regulares e arte uniforme em QUALQUER dpr. Tolera ≤5px lógicos de corte
-    // por lado (o −10): base·kDev − avail·dpr ≤ 10·kDev ⇒ kDev ≤ avail·dpr/(base−10). (José escolheu inteiro-REAL.)
-    const dpr = window.devicePixelRatio || 1;
-    const kDev = Math.max(Math.round(MIN_K * dpr), Math.floor(Math.min(availW * dpr / (baseW - 10), availH * dpr / (baseH - 10))));
-    const k = kDev / dpr; // fator LÓGICO/CSS (kDev = fator em pixels REAIS, inteiro)
-    // ESCALA das vars de UI é ESCOPADA ao #game-region: só a UI DENTRO do canvas (menus/HUD/pausa/quiz) escala com o
-    // k. Fora do canvas (barra de topo, painel de debug) herda o :root → texto SEMPRE 16px, toque 44px (José).
-    const gr = $('#game-region');
-    if (gr) {
-        gr.style.width = (baseW * k) + 'px';
-        gr.style.height = (baseH * k) + 'px';
-        gr.style.setProperty('--hud-fs', Math.max(9, Math.round(180 * k * 0.052)) + 'px');
-        gr.style.setProperty('--ui-fs', (8 * k) + 'px'); // base LÓGICA 8px × k (16px em k=2)
-        gr.style.setProperty('--tap', (22 * k) + 'px'); // toque 22px × k (44px em k=2, piso WCAG)
-        // ⚠️ O PISO DA RÉGUA (ADR-0095), e ele é OUTRA COISA que o `--tap`. O `--tap` é o tamanho PREFERIDO e
-        // cresce com a escala do canvas; `--alvo-min` é o CHÃO por altura de tela — 24 px abaixo de 540, 34 a
-        // partir de 540, 44 a partir de 720. Um botão isolado usa o preferido; um item de LISTA, que tem de
-        // caber inteiro na tela, usa o chão.
-        //
-        // ⚠️ A ALTURA É A DO ESPAÇO DISPONÍVEL, e não a da sub-tela de um jogador: o dedo toca o aparelho, não
-        // o viewport lógico. Em quatro telas divididas cada uma tem 180 px de alto, e encolher o alvo por causa
-        // disso seria ler o número errado — o aparelho continua o mesmo.
-        gr.style.setProperty('--alvo-min', alvoMinimoDeToque(availH) + 'px');
+/**
+ * Builds a stage scaler over the document and window it is handed. It keeps nothing between calls: every `layout()`
+ * measures again, reads the player count again, and writes onto the region.
+ */
+export function createLayout(ctx) {
+    function layout() {
+        const wrap = findStageWrap(ctx.doc);
+        if (!wrap)
+            return;
+        wrap.style.paddingRight = '0px';
+        const availW = wrap.clientWidth || 320;
+        const availH = wrap.clientHeight || 180;
+        // The screen grid sets the base (1=320×180, 2=640×180, 3-4=640×360).
+        const n = ctx.numPlayers();
+        const { w: baseW, h: baseH } = screenBaseSize(n);
+        // Floor k=2: EACH viewport is at least 640×360, so 2×2 = 1280×720 fits a government Chromebook (1366×768).
+        // ADR-0001: SCALE locked to WHOLE REAL PIXELS. Each art pixel = kDev PHYSICAL pixels (whole) → scanlines ALWAYS regular
+        // and uniform art at ANY dpr. Tolerates ≤5 logical px of crop per side (the −10): base·kDev − avail·dpr ≤ 10·kDev ⇒
+        // kDev ≤ avail·dpr/(base−10). (The Dev chose whole REAL pixels.) The arithmetic lives in `stageScale` (ADR-0163), so the
+        // engine applies it to every cartridge.
+        const dpr = ctx.win.devicePixelRatio || 1;
+        const ratio = stageScale(availW, availH, dpr, baseW, baseH);
+        const { kDev, k } = ratio;
+        // The UI variables' SCALE is SCOPED to #game-region: only the UI INSIDE the canvas (menus/HUD/pause/quiz) scales with
+        // k. Outside the canvas (top bar, debug panel) it inherits :root → text ALWAYS 16px, touch 44px (the Dev).
+        const gr = ctx.doc.querySelector('#game-region');
+        if (gr) {
+            // `--tap` is the PREFERRED size (22·k) and `--alvo-min` the FLOOR (22·k, 44 px at 640×360 — ADR-0163), written in `applyScale`.
+            applyScale(gr, ratio);
+        }
+        ctx.afterScale(); // scanlines realign when the scale k changes
+        if (ctx.debug?.())
+            console.info(`[escala] kDev=${kDev}× px REAIS (canvas físico ${baseW * kDev}×${baseH * kDev} = múltiplo INTEIRO de ${baseW}×${baseH}); CSS ${Math.round(baseW * k)}×${Math.round(baseH * k)} (k=${k.toFixed(3)}, dpr=${dpr})`);
     }
-    crtScanVars(); // scanlines re-alinham quando a escala k muda
-    if (/[?&]debug=true/.test(location.search))
-        console.info(`[escala] kDev=${kDev}× px REAIS (canvas físico ${baseW * kDev}×${baseH * kDev} = múltiplo INTEIRO de ${baseW}×${baseH}); CSS ${Math.round(baseW * k)}×${Math.round(baseH * k)} (k=${k.toFixed(3)}, dpr=${dpr})`);
+    return { layout };
 }

package/dist-pkg/ui/locale-flags.d.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The locales the button cycles, in the Dev's order. */
+export declare const LOCALE_CYCLE: readonly ["pt", "en", "es"];
+export type CycleLocale = (typeof LOCALE_CYCLE)[number];
+/** The next locale of the cycle; a locale outside it starts the cycle again. */
+export declare const nextLocale: (current: string) => CycleLocale;
+/** Each language in its own words, with the place its flag stands for. */
+export declare const LANGUAGE_NAME: {
+    readonly [L in CycleLocale]: string;
+};
+/** Brazil, the United States and Mexico, simplified to icon size. */
+export declare const FLAG_SVG: {
+    readonly [L in CycleLocale]: string;
+};
+/** The flag of a locale, or Brazil's for one outside the cycle (the engine's base language). */
+export declare const flagOf: (locale: string) => string;

package/dist-pkg/ui/locale-flags.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/locale-flags — THE LANGUAGE BUTTON'S THREE FLAGS (the Dev, 2026-09-16: «três bandeiras que se intercalam cada vez que o botão é
+// apertado: Brasil, Estados Unidos e México. Cada bandeira indica a localização para qual o app está configurado»).
+//
+// The flags are DRAWN, not emoji: 📏 measured in Chromium on Windows, 🇧🇷 🇺🇸 🇲🇽 render as the letters BR, US and MX (zero coloured pixels,
+// against 716 for 🧑) — a school's Windows machine would show the child two letters where a flag was promised. Simplified to their shapes
+// and colours at icon size. Each language is named in itself, so a child who does not read the current language still finds their own.
+/** The locales the button cycles, in the Dev's order. */
+export const LOCALE_CYCLE = ['pt', 'en', 'es'];
+/** The next locale of the cycle; a locale outside it starts the cycle again. */
+export const nextLocale = (current) => {
+    const i = LOCALE_CYCLE.indexOf(current);
+    return LOCALE_CYCLE[(i + 1) % LOCALE_CYCLE.length];
+};
+/** Each language in its own words, with the place its flag stands for. */
+export const LANGUAGE_NAME = {
+    pt: 'Português (Brasil)', en: 'English (United States)', es: 'Español (México)',
+};
+const svg = (inner) => `<svg class="pi-flag" viewBox="0 0 30 20" width="1.4em" height="0.93em" aria-hidden="true" focusable="false">${inner}</svg>`;
+/** Brazil, the United States and Mexico, simplified to icon size. */
+export const FLAG_SVG = {
+    pt: svg('<rect width="30" height="20" fill="#009c3b"/><polygon points="15,2.2 27.4,10 15,17.8 2.6,10" fill="#ffdf00"/><circle cx="15" cy="10" r="4.4" fill="#002776"/>'),
+    en: svg('<rect width="30" height="20" fill="#b22234"/>'
+        + [1, 3, 5, 7, 9, 11].map((r) => `<rect y="${(r * 20) / 13}" width="30" height="${20 / 13}" fill="#fff"/>`).join('')
+        + '<rect width="12" height="10.77" fill="#3c3b6e"/>'
+        + [[2, 2], [6, 2], [10, 2], [4, 5.4], [8, 5.4], [2, 8.8], [6, 8.8], [10, 8.8]].map(([x, y]) => `<circle cx="${x}" cy="${y}" r=".7" fill="#fff"/>`).join('')),
+    es: svg('<rect width="10" height="20" fill="#006847"/><rect x="10" width="10" height="20" fill="#fff"/><rect x="20" width="10" height="20" fill="#ce1126"/><circle cx="15" cy="10" r="2.6" fill="#8b5a2b"/>'),
+};
+/** The flag of a locale, or Brazil's for one outside the cycle (the engine's base language). */
+export const flagOf = (locale) => FLAG_SVG[LOCALE_CYCLE.includes(locale) ? locale : 'pt'];