@the-inclusionist/engine 6.36.1

package/dist-pkg/render/weather.js

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/weather — visual CLIMA: rain intensity ramp, thunder cadence/flash, and the rain-drop layer drawn in
+// screen-space on top of everything. Extracted from game.js's updateWeather/drawWeather (behavior-preserving,
+// formulas verbatim). `weatherLayer` (the PIXI.Graphics) and `stage` are CREATED in game.js — the layer's z-order
+// is soldered into the render-graph assembly there, same precedent as render/scene-sky.ts — and are INJECTED via
+// initWeather(); only the logic moves. `_rainLevel` is the bridge to platform/audio-ambient.ts (thunder/rain
+// track follow the visual): exposed here ONLY via getRainLevel(), never the raw mutable value, exactly like the
+// game.js `get rainLevel(){return _rainLevel;}` it replaces. `cenario` is read as a live binding from
+// core/state.ts (shared state home); `rnd` from core/rng.ts's DECORATION stream — same pattern as render/fx.ts.
+// A corrente da DECORACAO, nao a do jogo: uma particula sorteada aqui nao pode mover o sorteio
+// das moedas. Ver o cabecalho de core/rng.ts (issue #107).
+import { rngDecoracao } from '../core/rng.js';
+const rnd = rngDecoracao.rnd;
+/**
+ * L5 (rotina do José): tempo bom nos primeiros 30s; depois LOOP de 60s = garoa 5s → chuva 5s → garoa 5s → bom 45s.
+ * Skipped when scene decor is reduced-motion.
+ *
+ * QUEM TEM CHUVA É DADO DO TEMA (`CENARIOS[...].chuva`), e não uma condição escrita aqui. Era
+ * `cenario === 'cidade'` — verdade enquanto a Cidade era o único tema com chuva, e mentira no dia em que o Dev
+ * pediu chuva na Floresta. O defeito de uma condição dessas não é estar errada, é ser INVISÍVEL de onde a
+ * pessoa procura: quem abre a tabela de cenários para dar chuva a um tema novo não encontra nada para mudar.
+ *
+ * @param sec elapsed weather-clock time, in seconds
+ * @param temChuva true when the active theme declares `chuva`
+ * @param reduceDecor true when reduced-motion scene decor (rm.decor) is on
+ * @returns target rain level: 0 (dry), 0.35 (garoa) or 1 (chuva)
+ */
+export function rainLevelTarget(sec, temChuva, reduceDecor) {
+    if (!(sec >= 30 && !reduceDecor && temChuva))
+        return 0;
+    const c = (sec - 30) % 60;
+    return c < 5 ? 0.35 : c < 10 ? 1 : c < 15 ? 0.35 : 0;
+}
+/** Onde estamos DENTRO do ciclo de 60s, em segundos. 0 = a primeira gota; 59 = um segundo antes dela. */
+export function faseDoClima(sec) { return (((sec - 30) % 60) + 60) % 60; }
+/**
+ * AGLOMERAÇÃO DAS NUVENS: 0 = espalhadas e altas, com o céu aparecendo entre elas; 1 = fechadas numa manta.
+ *
+ * O pedido do Dev foi de um MOVIMENTO, não de um estado: as nuvens se juntam, chove, elas se separam e o pôr
+ * do sol aparece nas frestas. Quem faz isso ler como causa e não como coincidência é a ANTECEDÊNCIA — a manta
+ * fecha OITO SEGUNDOS ANTES da primeira gota. Se fechasse junto, a chuva pareceria vir do nada e as nuvens
+ * pareceriam reagir a ela; fechando antes, é a nuvem que traz a chuva, que é o que uma criança já sabe.
+ *
+ * Anda no MESMO ciclo da chuva (`faseDoClima`), e não num relógio próprio, porque dois relógios independentes
+ * desandam um do outro — não de imediato, mas depois de alguns minutos, e aí ninguém liga o defeito à causa.
+ * Devolve uma rampa contínua: não precisa de suavização depois.
+ */
+export function aglomeracaoAlvo(sec, temChuva, reduceDecor) {
+    if (!(sec >= 22 && !reduceDecor && temChuva))
+        return 0; // 22s = exatamente a fase 52, onde a rampa começa
+    const f = faseDoClima(sec);
+    if (f >= 52)
+        return (f - 52) / 8; // 8s juntando, antes da primeira gota
+    if (f < 12)
+        return 1; // fechado durante a garoa e a chuva
+    if (f < 22)
+        return 1 - (f - 12) / 10; // 10s abrindo — é aqui que o pôr do sol reaparece
+    return 0;
+}
+/** Ramps `current` toward `target` by at most `step`, snapping to `target` once within 0.02 (no "quase seco" flicker). */
+export function rampRainLevel(current, target, step) {
+    let next = current + Math.max(-step, Math.min(step, target - current));
+    if (Math.abs(target - next) < 0.02)
+        next = target;
+    return next;
+}
+export function stepThunder(rainLevel, thunderCD, flash, rndFn, onThunder) {
+    if (rainLevel > 0.45) {
+        thunderCD--;
+        if (thunderCD <= 0) {
+            thunderCD = 200 + Math.floor(rndFn() * 420);
+            const inten = 0.35 + rndFn() * 0.65;
+            flash = Math.max(flash, inten);
+            onThunder(inten);
+        }
+    }
+    if (flash > 0)
+        flash = Math.max(0, flash - 0.05);
+    return { thunderCD, flash };
+}
+/** Seeds `n` rain drops at random positions across the WxH screen (lazy — built once on first rain). */
+export function makeRainDrops(n, W, H, rndFn) {
+    const drops = [];
+    for (let i = 0; i < n; i++)
+        drops.push({ x: rndFn() * W, y: rndFn() * H, len: 6 + rndFn() * 9, spd: 8 + rndFn() * 7 });
+    return drops;
+}
+/** Advances one drop by its own speed; wraps to the top (new random x) past H. GAG: drops freeze when `moving` is false (pause). */
+export function stepRainDrop(d, W, H, moving, rndFn) {
+    if (!moving)
+        return;
+    d.y += d.spd;
+    d.x -= d.spd * 0.35;
+    if (d.y > H) {
+        d.y = -d.len;
+        d.x = rndFn() * W;
+    }
+    if (d.x < 0)
+        d.x += W;
+}
+let _weatherLayer = null;
+let _stage = null;
+let _screen = null;
+let _getRm = null;
+let _thunder = null;
+let _temChuva = null;
+let _mundoRodando = () => true;
+let _rainLevel = 0, _weatherT = 0, _flash = 0, _thunderCD = 240, _aglomeracao = 0;
+let _rainDrops = null;
+export function initWeather(ctx) {
+    _weatherLayer = ctx.weatherLayer;
+    _stage = ctx.stage;
+    _screen = ctx.screen;
+    _getRm = ctx.getRm;
+    _thunder = ctx.thunder;
+    _temChuva = ctx.temChuva;
+    _mundoRodando = ctx.mundoRodando;
+}
+/** Per-frame clima update (game.js calls this only while `phase==='playing'`, same as before). */
+export function updateWeather() {
+    _weatherT++;
+    const sec = _weatherT / 60;
+    const rm = _getRm ? _getRm() : {};
+    const temChuva = _temChuva ? _temChuva() : false;
+    const target = rainLevelTarget(sec, temChuva, !!rm.decor);
+    _rainLevel = rampRainLevel(_rainLevel, target, 1 / 30); // rampa ~1s
+    _aglomeracao = aglomeracaoAlvo(sec, temChuva, !!rm.decor); // já é rampa: nada a suavizar aqui
+    const step = stepThunder(_rainLevel, _thunderCD, _flash, rnd, (inten) => { if (_thunder)
+        _thunder(inten); });
+    _thunderCD = step.thunderCD;
+    _flash = step.flash;
+}
+/** Redraws the rain/flash overlay (chuva/clarão em tela-espaço, sobre tudo). */
+export function drawWeather() {
+    if (!_weatherLayer)
+        return;
+    const g = _weatherLayer;
+    if (_stage && g.parent === _stage)
+        _stage.setChildIndex(g, _stage.children.length - 1); // mantido no topo em draw
+    g.clear();
+    const W = _screen ? _screen.width : 0, H = _screen ? _screen.height : 0;
+    if (_rainLevel <= 0 && _flash <= 0)
+        return;
+    if (_rainLevel > 0) {
+        g.beginFill(0x0a0e1a, _rainLevel * 0.34);
+        g.drawRect(0, 0, W, H);
+        g.endFill(); // céu mais escuro
+        if (!_rainDrops)
+            _rainDrops = makeRainDrops(110, W, H, rnd);
+        const mv = _mundoRodando(); // GAG: gotas congelam na pausa
+        g.lineStyle(1, 0xaebfe0, 0.5 * _rainLevel);
+        for (const d of _rainDrops) {
+            stepRainDrop(d, W, H, mv, rnd);
+            g.moveTo(d.x, d.y);
+            g.lineTo(d.x - 2, d.y + d.len);
+        }
+        g.lineStyle(0);
+    }
+    if (_flash > 0) {
+        g.beginFill(0xe4ecff, _flash * 0.55);
+        g.drawRect(0, 0, W, H);
+        g.endFill();
+    } // clarão do relâmpago
+}
+/** The clima→áudio bridge: platform/audio-ambient.ts reads this (never the raw value) so its rain track follows the visual. */
+export function getRainLevel() { return _rainLevel; }
+/** A ponte clima→céu: render/scene-sky lê isto para juntar e separar as nuvens no compasso da chuva. */
+export function getAglomeracao() { return _aglomeracao; }
+/** Weather-clock read/write — the game.js `window.__incl.weatherT` debug hook fast-forwards the cycle via this. */
+export function getWeatherT() { return _weatherT; }
+export function setWeatherT(v) { _weatherT = v; }

package/dist-pkg/render/wheelchair-sprites.d.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PlayerView } from '../core/entity.js';
+/** Minimal PIXI.Graphics surface these draws use (structural → module stays PIXI-free for node tests). */
+export interface DrawGraphics {
+    lineStyle(width: number, color?: number): unknown;
+    moveTo(x: number, y: number): unknown;
+    lineTo(x: number, y: number): unknown;
+    beginFill(color: number): unknown;
+    endFill(): unknown;
+    drawCircle(x: number, y: number, r: number): unknown;
+}
+/** Cadeira e bengala: onde o jogador está, para que lado olha, e em que modo de visão desenhar. */
+type DrawablePlayer = PlayerView<'facing' | 'x' | 'y' | 'viz'>;
+/** Cane color: green for low-vision, white otherwise (blind). */
+export declare function caneColor(pl: {
+    viz: string;
+}): number;
+/** Rigid half-block cane (~8px): front-hand extension, fixed to the body (does not swing on its own). */
+export declare function drawCane(g: DrawGraphics, pl: DrawablePlayer): void;
+/** Running cane (item): a wheel at the tip, constant ground contact (high performance). */
+export declare function drawRunCane(g: DrawGraphics, pl: DrawablePlayer): void;
+/** The wheelchair (big spoked wheel + backrest + footrest), drawn under the seated player. */
+export declare function drawChair(g: DrawGraphics, pl: DrawablePlayer): void;
+export {};

package/dist-pkg/render/wheelchair-sprites.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/wheelchair-sprites — the a11y mobility props (Estágio 4, Tier 2): the white/green cane (blind /
+// low-vision), the running cane (item), and the wheelchair. Stateless PIXI drawing (verbatim from game.js):
+// each takes a Graphics `g` + the player. The layers (caneLayer/chairLayer) stay in game.js and are passed in.
+// `caneColor` (pure) moves here too — it was only used by the cane draws. See docs/5-Refactoring/plano-modularizacao-mapa.md.
+import { VIZ_BY_KEY } from './viz-modes.js';
+/** Cane color: green for low-vision, white otherwise (blind). */
+export function caneColor(pl) {
+    const m = VIZ_BY_KEY[pl.viz];
+    return m && m.kind === 'lowvision' ? 0x35d06a : 0xf2f2f2;
+}
+/** Rigid half-block cane (~8px): front-hand extension, fixed to the body (does not swing on its own). */
+export function drawCane(g, pl) {
+    const dir = pl.facing < 0 ? -1 : 1, C = caneColor(pl);
+    const hx = pl.x + dir * 4, hy = pl.y - 9, tx = pl.x + dir * 8, ty = pl.y - 1; // punho na mão → ponteira no chão à frente
+    g.lineStyle(2, C);
+    g.moveTo(hx, hy);
+    g.lineTo(tx, ty); // haste curta (branca=cego / verde=baixa visão)
+    g.lineStyle(1, 0xd23b3b);
+    g.moveTo(tx - dir * 2, ty - 2);
+    g.lineTo(tx, ty); // faixa vermelha (ponta)
+    g.lineStyle(0);
+    g.beginFill(C);
+    g.drawCircle(tx, ty, 1.3);
+    g.endFill(); // ponteira
+}
+/** Running cane (item): a wheel at the tip, constant ground contact (high performance). */
+export function drawRunCane(g, pl) {
+    const dir = pl.facing < 0 ? -1 : 1, C = caneColor(pl);
+    const hx = pl.x + dir * 4, hy = pl.y - 9, wx = pl.x + dir * 10, wy = pl.y - 2; // haste até o eixo da roda, à frente
+    g.lineStyle(2, C);
+    g.moveTo(hx, hy);
+    g.lineTo(wx, wy - 1);
+    g.lineStyle(1.5, C);
+    g.drawCircle(wx, wy, 2.4); // RODA na ponta (contato constante)
+    g.lineStyle(1, 0xd23b3b);
+    g.moveTo(wx - 2.4, wy);
+    g.lineTo(wx + 2.4, wy);
+    g.lineStyle(0); // eixo/faixa
+}
+/** The wheelchair (big spoked wheel + backrest + footrest), drawn under the seated player. */
+export function drawChair(g, pl) {
+    const cx = pl.x, base = pl.y, f = pl.facing < 0 ? -1 : 1, MET = 0x4a586e, HUB = 0x1c2230;
+    g.lineStyle(2, MET);
+    g.drawCircle(cx, base - 6, 7); // roda grande
+    g.lineStyle(1, MET);
+    for (let a = 0; a < 6; a++) {
+        const an = a * Math.PI / 3;
+        g.moveTo(cx, base - 6);
+        g.lineTo(cx + Math.cos(an) * 6, base - 6 + Math.sin(an) * 6);
+    } // raios
+    g.lineStyle(0);
+    g.beginFill(HUB);
+    g.drawCircle(cx, base - 6, 2);
+    g.endFill(); // cubo
+    g.lineStyle(3, MET);
+    g.moveTo(cx - f * 5, base - 6);
+    g.lineTo(cx - f * 5, base - 22);
+    g.lineTo(cx - f * 2, base - 24); // encosto
+    g.moveTo(cx + f * 4, base - 4);
+    g.lineTo(cx + f * 9, base - 2); // apoio de pés
+    g.lineStyle(0);
+}

package/dist-pkg/render/world-tex.d.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Inject the loaded level grid + dimensions (from game.js, after the map fetch). */
+export declare function initWorldTex(ctx: {
+    world: number[][];
+    W: number;
+    H: number;
+}): void;
+/** Ground/platform tiles that receive the theme tileset. */
+export declare const isGroundType: (t: number) => boolean;
+/** Optional theme tileset: `fill` (interior) + `surface` (top). */
+export interface Tileset {
+    fill: CanvasImageSource;
+    surface: CanvasImageSource;
+}
+/** Build the NORMAL world canvas: theme tileset on ground (if given), else the v3 per-tile drawings. */
+export declare function worldCanvas(tiles?: Tileset | null): HTMLCanvasElement;
+/** The NORMAL world texture (PIXI) from the current level. */
+export declare function worldToTexture(tiles?: Tileset | null): unknown;

package/dist-pkg/render/world-tex.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// render/world-tex — the NORMAL world tile texture builder (Estágio 4, Tier 2). Draws the whole level to a
+// canvas (theme tileset on ground, else the v3 per-tile art). Verbatim from game.js. The loaded level grid is
+// runtime state (fetched at boot) → injected via initWorldTex, like core/coins. The high-contrast variant
+// (worldToTextureDirect) + the viz selector (worldTexFor) + animated water/lava (stepTileFx) stay in game.js.
+// See docs/5-Refactoring/plano-modularizacao-mapa.md.
+import { makeCanvas, tex } from './canvas.js';
+import { TILE, TILE_COLOR } from '../core/constants.js';
+import { isSolidType } from '../core/collision.js';
+let WORLD = [];
+let W = 0, H = 0, PXW = 0, PXH = 0;
+/** Inject the loaded level grid + dimensions (from game.js, after the map fetch). */
+export function initWorldTex(ctx) {
+    WORLD = ctx.world;
+    W = ctx.W;
+    H = ctx.H;
+    PXW = W * TILE;
+    PXH = H * TILE;
+}
+/** Ground/platform tiles that receive the theme tileset. */
+export const isGroundType = (t) => t === 2 || t === 6;
+/** Build the NORMAL world canvas: theme tileset on ground (if given), else the v3 per-tile drawings. */
+export function worldCanvas(tiles) {
+    const cv = makeCanvas(PXW, PXH), c = cv.getContext('2d');
+    const solidAt = (x, y) => y >= 0 && y < H && x >= 0 && x < W && isSolidType(WORLD[y][x]);
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++) {
+            const t = WORLD[y][x];
+            if (t === 0 || t === 1)
+                continue; // ar/interior: transparente → o parallax aparece pela área jogável
+            if (tiles && isGroundType(t)) { // tileset: superfície (topo claro) se há ar acima, senão preenchimento
+                c.drawImage(solidAt(x, y - 1) ? tiles.fill : tiles.surface, x * TILE, y * TILE);
+                continue;
+            }
+            // DESENHOS DA V3 (drawTile); água/lava animadas ficam no stepTileFx (game.js)
+            const X = x * TILE, Y = y * TILE;
+            if (t === 2) {
+                c.fillStyle = '#555';
+                c.fillRect(X, Y, TILE, TILE); // pedra + pontos escuros
+                c.fillStyle = '#3a3a3a';
+                c.fillRect(X + 2, Y + 3, 1, 1);
+                c.fillRect(X + 9, Y + 5, 1, 1);
+                c.fillRect(X + 5, Y + 11, 1, 1);
+                c.fillRect(X + 12, Y + 9, 1, 1);
+            }
+            else if (t === 6) {
+                c.fillStyle = '#666';
+                c.fillRect(X, Y, TILE, TILE); // parede dura + linhas
+                c.fillStyle = '#444';
+                c.fillRect(X, Y, TILE, 1);
+                c.fillRect(X, Y + TILE - 1, TILE, 1);
+            }
+            else if (t === 4) {
+                c.fillStyle = '#777'; // escada VAZADA: trilhos + degraus
+                c.fillRect(X + 3, Y, 2, TILE);
+                c.fillRect(X + 11, Y, 2, TILE);
+                c.fillRect(X + 3, Y + 2, 10, 2);
+                c.fillRect(X + 3, Y + 8, 10, 2);
+                c.fillRect(X + 3, Y + 14, 10, 2);
+            }
+            else if (t === 5) {
+                c.fillStyle = '#E373FA';
+                c.fillRect(X, Y, TILE, TILE); // trampolim SÓLIDO (bloco inteiro)
+                c.fillStyle = '#fff';
+                c.fillRect(X + 1, Y + 2, TILE - 2, 1);
+                c.fillStyle = '#9a3fb0';
+                c.fillRect(X, Y + TILE - 2, TILE, 2);
+            }
+            else if (t === 3) {
+                c.fillStyle = 'rgba(121,220,242,0.4)';
+                c.fillRect(X, Y, TILE, TILE);
+            } // água translúcida
+            else if (t === 9) {
+                c.fillStyle = '#C93232';
+                c.fillRect(X, Y, TILE, TILE);
+            } // lava (tracinhos no stepTileFx)
+            else {
+                c.fillStyle = TILE_COLOR[t] || '#202';
+                c.fillRect(X, Y, TILE, TILE);
+            }
+        }
+    return cv;
+}
+/** The NORMAL world texture (PIXI) from the current level. */
+export function worldToTexture(tiles) {
+    return tex(worldCanvas(tiles));
+}

package/dist-pkg/ui/activities-menu.d.ts

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type ActivityDef, type ActivityCat } from '../educational/activities-registry.js';
+import type { TitleMenuId } from './title.js';
+export type { ActivityCat, GameMode } from '../educational/activities-registry.js';
+export { activityCategory, modeForCategory } from '../educational/activities-registry.js';
+/** The five fraction notations the "Fração" submenu toggles. */
+export type FracNotKey = 'v' | 'd' | 'dec' | 'pct' | 'mix';
+/** On/off state per notation, stored as 0/1 (game.js persisted numbers, not booleans — kept verbatim). */
+export type FracNot = Record<FracNotKey, number>;
+/** The 6 directional/confirm flags the title menu reacts to. Single definition in input/edges. */
+import type { NavKeys } from '../input/edges.js';
+import type { DomQuery } from '../core/dom-query.js';
+export type { NavKeys } from '../input/edges.js';
+/** One scenario as the "Cenário" submenu needs it — id + display name only (CENARIOS' texture data stays put). */
+export interface CenarioOption {
+    readonly id: string;
+    readonly nome: string;
+}
+/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
+export type { DomQuery } from '../core/dom-query.js';
+export interface ActivitiesMenuCtx {
+    /**
+     * O ID DO JOGO, para escopar as duas chaves que pertencem a ESTA partida (`tabsel`, `fracnot`).
+     *
+     * ⚠️ Entra pelo ctx e não por constante porque a engine não pode tê-lo (ADR-0080): este menu serve
+     * qualquer jogo do catálogo, e duas partidas diferentes que escolhessem a mesma tabuada no mesmo perfil de
+     * navegador escreviam uma por cima da outra. Quem sabe o id é o jogo, e ele o passa aqui.
+     */
+    gameId: string;
+    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
+     *  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`). */
+    getNumPlayers: () => number;
+    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
+     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    getPlayers: () => readonly unknown[];
+    /** DOM selector (ui/dom.ts `$`) — injected so the node project can hand over fake elements. */
+    $: DomQuery;
+    /** `document.activeElement`, injected: navTitle needs the focused button and node has no document. */
+    getActiveElement: () => Element | null;
+    /** Polite screen-reader announcement (core/a11y-sr.ts `srSay`). Injected: it reaches `document` when called. */
+    srSay: (text: string) => void;
+    /** Assertive announcement (core/a11y-sr.ts `srAlert`) — the three refusals of this menu use it. */
+    srAlert: (text: string) => void;
+    /** ui/title.ts's `show()` — game.js already owns the initTitle({ $ }) instance; we reuse it, never rebuild it. */
+    titleShow: (which: TitleMenuId) => void;
+    /** The scenarios of the "Cenário" submenu, in menu order. Source is game.js's CENARIOS, whose other fields
+     *  (sky/cloud/hills/decor) are parallax TEXTURE data — that belongs to the render slice, not to a menu. */
+    cenarios: readonly CenarioOption[];
+    /** Applies the chosen scenario (game.js: validates, persists via core/state, rebuilds the parallax textures). */
+    setCenario: (theme: string) => void;
+    /** A ATIVIDADE ESCOLHIDA, por injeção. É estado do JOGO (`game/state`), e este módulo é engine — o gate
+     *  de fronteira proíbe a importação, então a raiz de composição entrega. */
+    getActivityId: () => string;
+    setActivityId: (id: string) => void;
+    /** game.js's setQuizLevel(n, announce): persists via core/state and refreshes the `.pm-nivel` pause labels.
+     *  Stays in game.js because the pause menu — not this menu — owns those labels. */
+    setQuizLevel: (n: number, announce: boolean) => void;
+    /** Coarse-pointer detection (game.js): on mobile the round is forced to a single screen + fullscreen. */
+    isMobile: () => boolean;
+    /** "Do N viewports still fit this window?" — game.js's fitsN, which mirrors layout()'s arithmetic. */
+    fitsN: (n: number) => boolean;
+    /** Rebuilds the player list + viewports for N screens (game.js). Also restarts the round internally. */
+    setNumPlayers: (n: number) => void;
+    /** Restarts the round in place (game.js) — the branch taken when the screen count did not change. */
+    restartGame: () => void;
+    /** Phase transition (game.js setPhase, which also shows/hides overlays and the HUD). */
+    setPhase: (p: 'title' | 'playing' | 'paused') => void;
+    /** Start-hints dismissal (game.js). Today a no-op stub kept for its call sites — see the extraction notes. */
+    hideTips: () => void;
+    /** Requests fullscreen on the document element (game.js keeps the vendor-prefix try/catch verbatim). */
+    enterFullscreen: () => void;
+}
+export interface ActivitiesMenuApi {
+    /** Category of the CURRENT activity ('ludico' when unknown) — read by the quiz/win flow in game.js. */
+    actCat: () => ActivityCat;
+    /** Validates + commits an activity id: state, quiz level (literacy) and MODE. */
+    setActivity: (id: string) => void;
+    /** Step 1 of starting: remembers the pick, computes the "Voltar" target, opens the scenario submenu. */
+    startActivity: (id: string) => void;
+    /** Step 2: commits the pending activity and actually starts the round. */
+    reallyStart: () => void;
+    /** (Re)writes the markup of the alf/mat/fr/tab/cen submenus. */
+    buildTitleMenus: () => void;
+    /** The buttons of the ONE visible title submenu, in DOM order. */
+    titleButtons: () => HTMLElement[];
+    /** Arrow/confirm/back traversal of the visible submenu (keyboard + gamepad). */
+    navTitle: (k: NavKeys) => void;
+    /** Tabuada numbers, LIVE array — mutated in place (splice/push), never reassigned, exactly as in game.js. */
+    readonly tabSel: number[];
+    /** Fraction notations, LIVE object — mutated in place, never reassigned (window.__incl reads it). */
+    readonly fracNot: FracNot;
+    /** Where "Voltar" on the scenario submenu goes right now (the `_cenBack` latch). */
+    getCenBack: () => TitleMenuId;
+    /** The player count staged on the splash (only reallyStart applies it). */
+    getPendingPlayers: () => number;
+}
+/** The five literacy levels of the Ferreiro psychogenesis, by number. Domain content (pt-BR) — read by educators. */
+export declare const QL_NAME: Readonly<Record<number, string>>;
+/** Which literacy activity trains which of the 5 levels — setActivity reuses the psychogenesis ladder. */
+export declare const ALF_LEVEL: Readonly<Record<string, number>>;
+/** One row of the per-screen pause menu. `letra` marks the label that ABC/abc rewrites live. */
+export interface PauseBtnDef {
+    readonly act: string;
+    /**
+     * Rótulo CRU, e ele só é usado quando o botão tem rótulo dinâmico (`letra`/`nivel`).
+     *
+     * Virou opcional, e o motivo é o gate de i18n: `pmBtnMarkup` resolve todo botão comum por `t('pause.' +
+     * act)`, então o texto aqui nunca ia para tela nenhuma — era português cru dentro de um módulo de ENGINE,
+     * parado, esperando alguém confiar nele. Nenhuma entrada de hoje marca `letra` ou `nivel`, então nenhuma
+     * precisa dele; a chave `pause.*` é a fonte, e ela existe nos três idiomas.
+     */
+    readonly lbl?: string;
+    readonly letra?: boolean;
+    readonly nivel?: boolean;
+}
+/** The pause menu's items — MENU DATA, so it lives with the other menu tables. The pause slice (ui/pause-icons)
+ *  receives it through its own ctx instead of re-declaring it; nobody owns two copies of a list of buttons. */
+export declare const PM_BTNS: readonly PauseBtnDef[];
+/**
+ * O SUBMENU DE OPÇÕES — os sete painéis que saíram da lista raiz, na ordem que o Dev ditou.
+ *
+ * A saída vem PRIMEIRO aqui também, pela mesma razão que `resume` vem primeiro lá: a regra do ADR-0044 é
+ * sobre menus, não sobre um menu. Um submenu de onde não se sai é a mesma armadilha, um nível abaixo.
+ *
+ * 'letra' virou 'caa' (ADR-0028): era um CICLO de duas posições cujo rótulo mudava junto (`letra: true`), e
+ * virou a porta de um menu. Sem ciclo não há rótulo dinâmico, então ele volta a ser traduzível como os
+ * irmãos — o `letra: true` existia só para o i18n não sobrescrever o ABC/abc que o ciclo escrevia.
+ */
+export declare const PM_OPTIONS_BTNS: readonly PauseBtnDef[];
+/** i18n KEY of the spoken/aria name of each fraction notation. Keys, not text: a module-level const is
+ *  evaluated once at import and would freeze the language at boot (see the note in input/devices). */
+export declare const FNOT_LBL: Readonly<Record<FracNotKey, string>>;
+/** Visible label = the notation ITSELF (x/y), so the five toggles fit side by side; aria-label keeps the word. */
+export declare const FNOT_SYM: Readonly<Record<FracNotKey, string>>;
+/** i18n KEY of the footer text (same style as the pause menu) shown on focus/hover of a notation toggle. */
+export declare const FNOT_DESC: Readonly<Record<FracNotKey, string>>;
+/** The notation keys in menu order — also the defaults' key order (`v` on, rest off). */
+export declare const FNOT_KEYS: readonly FracNotKey[];
+/** Ids of the literacy submenu, in menu order. */
+export declare const ALF_MENU_IDS: readonly string[];
+/** Ids of the math submenu (the "Fração" button is not an activity — it opens another submenu). */
+export declare const MAT_MENU_IDS: readonly string[];
+/** Ids of the fractions submenu, in menu order. */
+export declare const FR_MENU_IDS: readonly string[];
+/** The 6 title submenus, in the order game.js has always scanned them for the visible one. */
+export { TITLE_MENU_IDS_ORDERED as TITLE_MENU_ORDER } from './title.js';
+/** The two rows of the tabuada number picker (0–5 then 6–10). */
+export declare const TAB_ROWS: readonly (readonly number[])[];
+/** Default tabuada selection when storage is empty (or holds something unusable). */
+export declare const TAB_SEL_DEFAULT: readonly number[];
+/** Unknown/absent id → the default activity. game.js's `if(!hasActivity(id))id=DEFAULT_ACTIVITY_ID`. */
+export declare function normalizeActivityId(id: string): string;
+/**
+ * Where "Voltar" on the scenario submenu must return to — a pure mapping from the activity that opened it:
+ * number-picking activities (Tabuada/Divisão) came through `tm-tab`, fraction activities through `tm-fr`,
+ * and otherwise the category's own submenu; free play came straight off `tm-main`.
+ * VERBATIM caveat: game.js dereferences `getActivity(id)` without a guard, so an unknown id throws here too.
+ */
+export declare function cenBackMenuFor(id: string): TitleMenuId;
+/**
+ * Reads the persisted tabuada selection. VERBATIM port, quirks included: the filter is `n>=0 && n<=10`, which
+ * JavaScript evaluates after coercion — so `"3"`, `true` and `null` all survive it while `'x'` and `{}` do not.
+ * Anything that is not a non-empty array falls back to [2,3,4,5]; an array that filters down to EMPTY stays
+ * empty (the "Jogar" button then refuses with an srAlert, which is how game.js has always behaved).
+ */
+export declare function sanitizeTabSel(raw: unknown): number[];
+/**
+ * Reads the persisted fraction notations. Defaults `{v:1,d:0,dec:0,pct:0,mix:0}`; only the five known keys are
+ * copied over (any extra key in storage is ignored) and each is coerced to 0/1; if the result would leave every
+ * notation off, `v` is forced back on — the menu's invariant "at least one notation is always lit".
+ */
+export declare function sanitizeFracNot(raw: unknown): FracNot;
+/** How many notations are currently on — the guard behind "Deixe ao menos uma notação ligada." */
+export declare function fracNotOnCount(f: FracNot): number;
+/** True when turning `k` OFF is allowed (it is not the last one lit). */
+export declare function canToggleFracNot(f: FracNot, k: FracNotKey): boolean;
+/** Player count staged on the splash: 1..4, never outside. */
+export declare function clampPendingPlayers(n: number): number;
+/**
+ * Next focused index for arrow traversal. VERBATIM quirk: when nothing in the submenu has focus (`cur < 0`),
+ * BOTH directions land on index 0 — pressing "up" from nowhere does not wrap to the last button.
+ *
+ * A CONTA DO ANEL saiu daqui e passou a ser `passoNoAnel` (ui/menu-nav), que é a mesma do menu de pausa. Eram
+ * duas escritas da mesma volta — `(cur + d + len) % len` aqui, a de lá — e o ADR-0044 §5 pede UMA resposta
+ * para "o que acontece no fim da lista" no jogo inteiro. Duas cópias respondem igual até o dia em que uma
+ * delas é corrigida sozinha.
+ */
+export declare function nextTitleIndex(cur: number, len: number, k: NavKeys): number;
+/**
+ * O NOME de uma atividade, no idioma vigente.
+ *
+ * A chave, quando existe, vence o texto cru — e a ausência dela é significado, não esquecimento: as cinco
+ * atividades de alfabetização não declaram chave porque a palavra e a sílaba SÃO a matéria da atividade
+ * (pilar 3 do ADR-0010). Todo o resto declara, matemática inclusive: `2 + 3` independe de língua.
+ *
+ * Resolve AQUI, no ponto de exibição, e não no catálogo — `educational/activities-registry` é DADO e não
+ * importa nada; e uma `const` de módulo com `t()` já resolvido congelaria o idioma no boot.
+ */
+export declare function nomeDaAtividade(a: ActivityDef | null | undefined): string;
+/** A descrição de rodapé de uma atividade, pela mesma regra do nome. */
+export declare function descricaoDaAtividade(a: ActivityDef | null | undefined): string;
+/** Footer description for a focused/hovered title button: notation text wins, else the activity's `d`.
+ *  The notation half resolves its key here; the activity's `d` comes from educational/activities-registry
+ *  and is still pt-BR, for the same curriculum-boundary reason as the activity `nome` (ADR-0032). */
+export declare function titleDescFor(actId: string | undefined, fnotKey: string | undefined): string;
+/** One activity button, with the optional example sub-label (literacy). */
+export declare function activityBtnHtml(id: string): string;
+/** The "Voltar" ghost button of a submenu. */
+export declare function backBtnHtml(to: TitleMenuId): string;
+/** The live-region footer that shows the focused minigame's description. */
+export declare const TM_DESC_HTML = "<div class=\"tm-desc\" aria-live=\"polite\"></div>";
+/** A submenu heading. O parâmetro chamava-se `t` e sombreava a função de tradução — quarta colisão desse
+ *  nome no projeto; recebe o texto JÁ resolvido, e agora se chama `titulo` para dizê-lo. */
+export declare function tmTitleHtml(titulo: string): string;
+export declare function alfMenuHtml(): string;
+export declare function matMenuHtml(): string;
+/**
+ * AS CINCO NOTAÇÕES — ajustes, e não itens de menu (pedido do Dev).
+ *
+ * Elas eram `.title-btn`, a MESMA classe dos itens que ABREM uma atividade, empilhadas logo acima deles: para
+ * quem enxerga, cinco coisas com cara de "entrar" que na verdade LIGAM e DESLIGAM. Para quem navega por
+ * escuta é pior — o cursor atravessa dez itens em que os cinco primeiros respondem "ligado/desligado" e os
+ * cinco últimos começam uma partida, sem nada entre eles dizendo que a regra mudou. É a mesma doença que o
+ * item 5 do ADR-0044 curou no cartão de pausa: dois modelos de interação numa tela, sem fronteira.
+ *
+ * Três coisas mudam: MOLDURA com nome (`fieldset`/`legend`, a fronteira que o leitor anuncia ao entrar),
+ * MARCA visível na frente (`☑`/`☐`, para o estado não depender de cor — WCAG 1.4.1) e PAPEL de caixa de
+ * seleção (`role="checkbox"` + `aria-checked`), porque a pergunta aqui é "está marcada?" e não "confirmar?".
+ *
+ * ⚠️ CONTINUAM SENDO `<button>`, e é deliberado: `titleButtons()` varre `button` para montar o anel de
+ * navegação. Um `<input type="checkbox">` seria mais correto no papel e tiraria as cinco do alcance do
+ * direcional — quem mais precisa delas é justamente quem só tem ele.
+ */
+export declare function fracNotsHtml(f: FracNot): string;
+export declare function frMenuHtml(f: FracNot): string;
+export declare function tabRowHtml(row: readonly number[], sel: readonly number[]): string;
+export declare function tabMenuHtml(sel: readonly number[]): string;
+export declare function cenMenuHtml(cenarios: readonly CenarioOption[]): string;
+/** token found in a label → the letters it hides. */
+export declare const ABBR_MID: Readonly<Record<string, string>>;
+/** The three fixed pieces of an abbreviated label, or null when the label carries no known token. */
+export interface AbbrParts {
+    readonly pre: string;
+    readonly hid: string;
+    readonly suf: string;
+}
+/** Splits a label around its abbreviation token. `pre` keeps the first letter, `suf` starts at the last one. */
+export declare function abbrParts(txt: string): AbbrParts | null;
+/** Label with `k` of the hidden letters revealed; the remaining count stands in for the rest ("A12e" at k=0). */
+export declare function abbrText(p: AbbrParts, k: number): string;
+/**
+ * Wires one button's expand/collapse animation. Idempotent (`data-abbrDone`) and a no-op for labels without a
+ * token — which, today, is EVERY button in the app: no label in index.html or PM_BTNS contains "A12e"/"S11e"
+ * any more (they were spelled out). Ported verbatim rather than deleted; see the extraction report.
+ */
+export declare function attachAbbr(b: HTMLElement | null | undefined): void;
+export declare function initActivitiesMenu(ctx: ActivitiesMenuCtx): ActivitiesMenuApi;