@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/ui/help-panel.js

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/help-panel — WHICH BUTTON DOES WHAT, in this game, on this child's keyboard: a slide show, one slide per button.
+//
+// ========================= WHY THIS MODULE EXISTS =========================
+// 🔴 MEASURED 2026-09-12: the pause card carries a `ajuda` item and NOTHING in the engine can action it, so
+// `itemsThatAct` hides it in every game. The help screen that used to fill it — `openHelp()` — did not
+// die: it LEFT WITH THE CARTRIDGE (#111) and now lives in `game-platformer/app/js/main.ts`. So each of the
+// three hundred games would have to write its own, which is the arrangement ADR-0139 measured failing in five
+// games of six.
+//
+// 🎯 AND THE ENGINE ALREADY HAS EVERY INGREDIENT, which is what makes this cheap rather than new:
+//   · WHICH positions this game uses, and the game's own WORD for each — `ActionPreset` (ADR-0085).
+//   · The sentence that explains one — the `hint` of that preset, a field declared, typed, documented and,
+//     until this module, never displayed anywhere.
+//   · WHICH KEY reaches it FOR THIS CHILD — `input/keyboard-runtime.kbFor(seat)`, i.e. her remap and not the
+//     factory default.
+//
+// ⚠️ THE ENGINE NEVER NAMES AN ACTION HERE, and that is the whole boundary (ADR-0074, ADR-0086). It knows a
+// POSITION exists; only the game knows the word. A row whose word is missing is therefore ABSENT — never a
+// row reading «action2», which is the defect `labellerFrom` returns `null` to prevent.
+//
+// 📌 AND THIS IS THE MIGRATION `ui/settings-controls.ACT_LABEL` HAS BEEN WAITING FOR. That table holds ONE
+// game's words — `act.run`, `act.jump` — inside the engine, and its own header says it can only leave once
+// the help screen asks the GAME instead. This module is a help screen that asks the game.
+import { ACTIONS } from '../core/actions.js';
+/**
+ * The help table for one seat.
+ *
+ * ⚠️ WALKS `ACTIONS` AND NOT THE PRESET'S OWN KEYS, for the reason `presetActions` already carries: the
+ * canonical order is the one the child meets everywhere else — the remap screen, the pad wizard, the
+ * on-screen legend. A help screen ordered by whatever order the game happened to write its object in would
+ * teach a different order from every other surface.
+ *
+ * @param preset  what this game declares — positions, words, hints.
+ * @param keysOf  the codes bound to a position FOR THIS SEAT. `kbFor(seat)[action]`, so a child who remapped
+ *                sees her own key. `null`/empty means the keyboard does not reach it.
+ * @param keyName code → readable label (`ui/settings-controls.keyName`), injected so this half stays pure.
+ */
+export function helpRows(preset, keysOf, keyName) {
+    if (!preset)
+        return [];
+    const rows = [];
+    for (const action of ACTIONS) {
+        const word = preset[action];
+        // ⚠️ A BLANK LABEL IS THE SAME AS NO LABEL, and it is the case `presetProblems` already names: a row
+        // whose word is whitespace reads, to a screen reader, as a button with no name.
+        if (!word || !word.label.trim())
+            continue;
+        // 📌 THE FIRST CODE, and the rest are not lost — they are the same position, and a help screen that listed
+        // every alias would spend the child's attention on the keyboard instead of on the game. The remap screen
+        // is where all of them are visible, because THERE they are the subject.
+        const codes = keysOf(action);
+        const key = codes && codes.length ? keyName(codes[0]) : null;
+        rows.push({ action, key, word: word.label, ...(word.hint ? { hint: word.hint } : {}) });
+    }
+    return rows;
+}
+/** What the slide says where the keyboard reaches nothing. A KEY, not a sentence — the caller translates it. */
+export const NO_KEY = 'help.noKey';
+/** Why a `howToPlay` declaration is malformed; empty when well formed. Absent is well formed: the help shows the buttons alone. */
+export function howToPlayProblems(slides) {
+    if (slides === undefined)
+        return [];
+    if (!Array.isArray(slides))
+        return ['howToPlay must be a list of slides'];
+    const out = [];
+    slides.forEach((s, i) => {
+        const at = `howToPlay[${i}]`;
+        if (!s || typeof s !== 'object') {
+            out.push(`${at} must be a slide`);
+            return;
+        }
+        if (typeof s.text !== 'function')
+            out.push(`${at}.text must be a function returning the slide's text, in the page's language`);
+        if (s.figure !== undefined && typeof s.figure !== 'function')
+            out.push(`${at}.figure must be a function drawing on the surface it is given`);
+    });
+    return out;
+}
+const isFromGame = (s) => typeof s.text === 'function';
+/**
+ * Draws the shown slide's figure, and keeps drawing it while the slide show is in the document and the same slide is shown.
+ * Returns a stop. A figure that throws is a cartridge defect: it stops drawing and the text stays.
+ */
+export function animateFigure(el, slide, clock) {
+    const screen = el.querySelector('.slide-figura');
+    const ctx = screen?.getContext('2d');
+    if (!screen || !ctx || !slide.figure)
+        return () => { };
+    const figureFn = slide.figure;
+    // the drawing surface is the size it is shown at, in CSS pixels, so a figure's coordinates are the ones the child sees
+    const screenBox = screen.getBoundingClientRect();
+    if (screenBox.width > 0 && screenBox.height > 0) {
+        screen.width = Math.round(screenBox.width);
+        screen.height = Math.round(screenBox.height);
+    }
+    let id = 0, still = false, start = -1;
+    const draw = (ms) => {
+        if (still || !el.isConnected)
+            return;
+        if (start < 0)
+            start = ms;
+        const time = clock.reduced ? 0 : (ms - start) / 1000;
+        ctx.clearRect(0, 0, screen.width, screen.height);
+        try {
+            figureFn({ ctx, width: screen.width, height: screen.height, time });
+        }
+        catch {
+            still = true;
+            return;
+        }
+        if (!clock.reduced)
+            id = clock.requestFrame(draw);
+    };
+    draw(0);
+    return () => { still = true; clock.cancelFrame(id); };
+}
+/** Builds the slide show's frame: the stop, its two arrows, the slide and the dots. `showSlide` fills it. */
+export function mountSlides(ctx) {
+    const el = ctx.create('div');
+    el.className = 'slides';
+    el.setAttribute('role', 'spinbutton');
+    el.setAttribute('tabindex', '0');
+    el.setAttribute('data-passos', '');
+    const arrow = (delta, glyph) => {
+        const s = ctx.create('span');
+        s.className = 'passo-seta';
+        s.setAttribute('data-passo', String(delta));
+        s.setAttribute('aria-hidden', 'true');
+        s.textContent = glyph;
+        s.addEventListener('click', () => el.dispatchEvent(new CustomEvent('passo', { detail: delta, bubbles: true })));
+        return s;
+    };
+    const slide = ctx.create('div');
+    slide.className = 'slide';
+    slide.setAttribute('aria-hidden', 'true'); // heard through the stop's value, once
+    const figureFn = ctx.create('canvas');
+    figureFn.className = 'slide-figura';
+    figureFn.hidden = true;
+    const keyGlyphOf = ctx.create('kbd');
+    keyGlyphOf.className = 'slide-tecla';
+    const word = ctx.create('p');
+    word.className = 'slide-palavra';
+    const text = ctx.create('p');
+    text.className = 'slide-texto';
+    const dots = ctx.create('div');
+    dots.className = 'slide-pontos';
+    for (const child of [figureFn, keyGlyphOf, word, text, dots])
+        slide.appendChild(child);
+    el.appendChild(arrow(-1, '◀'));
+    el.appendChild(slide);
+    el.appendChild(arrow(1, '▶'));
+    return el;
+}
+/**
+ * Shows slide `i` (held at the ends, like every steps control: the last slide is a wall, not a way back to the first) and returns
+ * the index shown, and what a screen reader hears of it. A slide is a button row (`helpRows`) or a cartridge's «how to play» slide
+ * (ADR-0195), which the help puts first.
+ */
+export function showSlide(el, rows, i, ctx) {
+    const last = Math.max(0, rows.length - 1);
+    const shown = Math.max(0, Math.min(last, i));
+    const r = rows[shown];
+    const parts = slidePartsOf(el);
+    if (!r || !parts)
+        return { index: shown, spoken: '' };
+    drawDots(parts.dots, rows.length, shown, ctx);
+    const spokenText = isFromGame(r) ? showPlaySlide(parts, r) : showButtonSlide(parts, r, ctx.t);
+    el.setAttribute('aria-label', ctx.title);
+    el.setAttribute('aria-valuemin', '0');
+    el.setAttribute('aria-valuemax', String(last));
+    el.setAttribute('aria-valuenow', String(shown));
+    el.setAttribute('aria-valuetext', spokenText);
+    el.querySelector('[data-passo="-1"]')?.classList.toggle('no-limite', shown === 0);
+    el.querySelector('[data-passo="1"]')?.classList.toggle('no-limite', shown === last);
+    return { index: shown, spoken: spokenText };
+}
+function slidePartsOf(el) {
+    const slide = el.querySelector('.slide');
+    const figure = el.querySelector('.slide-figura');
+    const keyCap = el.querySelector('.slide-tecla');
+    const word = el.querySelector('.slide-palavra');
+    const text = el.querySelector('.slide-texto');
+    const dots = el.querySelector('.slide-pontos');
+    if (!slide || !figure || !keyCap || !word || !text || !dots)
+        return null;
+    return { slide, figure, keyCap, word, text, dots };
+}
+/** One dot per slide, the current one filled — the place without a number (ADR-0167). */
+function drawDots(dots, count, current, ctx) {
+    while (dots.firstChild)
+        dots.removeChild(dots.firstChild);
+    Array.from({ length: count }, (_, n) => {
+        const dot = ctx.create('span');
+        dot.className = n === current ? 'slide-ponto is-on' : 'slide-ponto';
+        return dots.appendChild(dot);
+    });
+}
+/** What is heard, the parts joined — a sentence that already ends in a full stop is not given a second one. */
+const joinParts = (parts) => parts.filter(Boolean).map((part) => part.replace(/[.!?…]+\s*$/, '')).join('. ');
+/**
+ * A cartridge's «how to play» slide (ADR-0195): its text and, if it has one, its figure — no key cap, no word, and no action,
+ * whatever the slide before it was.
+ */
+function showPlaySlide(p, r) {
+    p.slide.setAttribute('data-kind', 'play');
+    p.slide.removeAttribute('data-act');
+    p.figure.hidden = !r.figure;
+    p.keyCap.hidden = true;
+    p.word.hidden = true;
+    const phrase = r.text();
+    p.text.textContent = phrase;
+    p.text.hidden = false;
+    return joinParts([phrase]);
+}
+/** A button's slide: the child's key (or that the keyboard does not reach it, marked), the game's word, and its sentence. */
+function showButtonSlide(p, r, t) {
+    p.slide.setAttribute('data-kind', 'button');
+    p.slide.setAttribute('data-act', r.action);
+    p.figure.hidden = true;
+    p.keyCap.hidden = false;
+    p.word.hidden = false;
+    p.keyCap.textContent = r.key ?? t(NO_KEY);
+    if (r.key)
+        p.keyCap.removeAttribute('data-sem-tecla');
+    else
+        p.keyCap.setAttribute('data-sem-tecla', '1');
+    p.word.textContent = r.word;
+    p.text.textContent = r.hint ?? '';
+    p.text.hidden = !r.hint;
+    return joinParts([r.word, r.hint, r.key ? t('help.slide.tecla', { k: r.key }) : t(NO_KEY)]);
+}

package/dist-pkg/ui/hud-bands.d.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Speakable } from '../core/contract.js';
+import type { Translate } from '../core/i18n.js';
+export type HudBand = 'identity' | 'mission' | 'power' | 'learning';
+/**
+ * A skill's bar, as `educational/segment-bar.barOf` returns it — the same field names and values, so its `Bar` passes
+ * straight in. Written again here because `ui` does not import `educational` (ADR-0173).
+ */
+export interface HudBar {
+    readonly segmentos: readonly ('azul' | 'verde' | 'vermelho')[];
+    readonly cor: 'nenhuma' | 'laranja' | 'roxa';
+}
+export type HudNumber = {
+    readonly band: 'identity' | 'mission' | 'power';
+    /** What is counted, in the interface language («points», «balls»). */
+    readonly name: Speakable;
+    /** A count, or how many of how many, for seat `seat`. Read on every animation frame while mounted: keep it cheap. */
+    readonly value: (seat: number) => number | {
+        readonly have: number;
+        readonly need: number;
+    };
+} | {
+    readonly band: 'learning';
+    /** The skill, in the interface language. */
+    readonly name: Speakable;
+    readonly value: (seat: number) => HudBar;
+};
+/** Why a `hud` declaration is malformed; empty when it is well formed. Absent is well formed: no HUD is mounted. */
+export declare function hudNumbersProblems(numbers: unknown): string[];
+export interface HudBandsMounted {
+    /** The top-left column: identity, then mission. */
+    readonly left: HTMLElement;
+    /** The top-right column: power (under the clock, when #94 builds it). */
+    readonly right: HTMLElement;
+    readonly learning: HTMLElement;
+    /** Rewrites what changed; `true` when a text at the top did, so the caller measures the room again. */
+    refresh(): boolean;
+    remove(): void;
+}
+/**
+ * Mounts the two top columns and the footer bars in the game region, one element per declared number, and fills them. A
+ * column with no number is hidden. The learning band goes in BEFORE the screen footer when one exists, so the explanation band, drawn later on the
+ * same layer, covers it.
+ */
+export declare function mountHudBands(t: Translate, doc: Document, region: HTMLElement, numbers: readonly HudNumber[], seat?: number): HudBandsMounted;

package/dist-pkg/ui/hud-bands.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+const HUD_BANDS = ['identity', 'mission', 'power', 'learning'];
+/** ADR-0049 §5: three ten-segment bars are thirty lit elements; a fourth stops being a reading. */
+const MAX_BARS = 3;
+const SEGMENTS = 10;
+/** Why a `hud` declaration is malformed; empty when it is well formed. Absent is well formed: no HUD is mounted. */
+export function hudNumbersProblems(numbers) {
+    if (numbers === undefined)
+        return [];
+    if (!Array.isArray(numbers))
+        return ['hud must be a list of numbers'];
+    const out = [];
+    numbers.forEach((n, i) => {
+        if (!n || !HUD_BANDS.includes(n.band))
+            out.push(`hud[${i}].band must be one of ${HUD_BANDS.join(', ')}`);
+        if (!n || typeof n.name?.text !== 'string' || !n.name.text.trim())
+            out.push(`hud[${i}].name.text must say what is counted`);
+        if (!n || typeof n.value !== 'function')
+            out.push(`hud[${i}].value must be a function of the seat`);
+    });
+    const bars = numbers.filter((n) => n?.band === 'learning').length;
+    if (bars > MAX_BARS)
+        out.push(`hud declares ${bars} learning bars: at most ${MAX_BARS}, one per skill the adult enabled (ADR-0049 §5)`);
+    return out;
+}
+/** What the child reads, or hears on the bar: the frame in the dictionary, the name through a parameter (pillar 3). */
+function numberText(t, n, seat) {
+    const v = n.value(seat);
+    return typeof v === 'number'
+        ? t('hud.numero', { nome: n.name.text, valor: String(v) })
+        : t('hud.contador', { have: String(v.have), need: String(v.need), nome: n.name.text });
+}
+function barLabel(t, name, bar) {
+    const count = (c) => String(bar.segmentos.filter((s) => s === c).length);
+    const base = t('hud.barra', { nome: name, azuis: count('azul'), verdes: count('verde'), vermelhos: count('vermelho') });
+    return bar.cor === 'roxa' ? `${base}. ${t('hud.barra.sobe')}` : bar.cor === 'laranja' ? `${base}. ${t('hud.barra.desce')}` : base;
+}
+/**
+ * Mounts the two top columns and the footer bars in the game region, one element per declared number, and fills them. A
+ * column with no number is hidden. The learning band goes in BEFORE the screen footer when one exists, so the explanation band, drawn later on the
+ * same layer, covers it.
+ */
+export function mountHudBands(t, doc, region, numbers, seat = 0) {
+    const band = (cls, count) => {
+        const el = doc.createElement('div');
+        el.className = `hud-faixa ${cls}`;
+        el.hidden = count === 0;
+        return el;
+    };
+    const texts = numbers.filter((n) => n.band !== 'learning');
+    const bars = numbers.filter((n) => n.band === 'learning');
+    // the identity lines first and the mission under them, whatever order the game declared them in
+    const leftTexts = [...texts.filter((n) => n.band === 'identity'), ...texts.filter((n) => n.band === 'mission')];
+    const rightTexts = texts.filter((n) => n.band === 'power');
+    const left = band('hud-esquerda', leftTexts.length);
+    const right = band('hud-direita', rightTexts.length);
+    const learning = band('hud-aprendizagem', bars.length);
+    const lines = [...leftTexts, ...rightTexts].map((n) => {
+        const p = doc.createElement('p');
+        p.className = 'hud-numero';
+        p.dataset.band = n.band;
+        (n.band === 'power' ? right : left).appendChild(p);
+        return [n, p];
+    });
+    const bardivs = bars.map((n) => {
+        const div = doc.createElement('div');
+        div.className = 'hud-barra';
+        div.setAttribute('role', 'img');
+        for (let i = 0; i < SEGMENTS; i++)
+            div.appendChild(doc.createElement('span')).className = 'hud-seg';
+        learning.appendChild(div);
+        return [n, div];
+    });
+    region.appendChild(left);
+    region.appendChild(right);
+    region.insertBefore(learning, [...region.children].find((c) => c.classList.contains('rodape-da-tela')) ?? null);
+    function refresh() {
+        let changed = false;
+        for (const [n, p] of lines) {
+            const text = numberText(t, n, seat);
+            if (p.textContent !== text) {
+                p.textContent = text;
+                changed = true;
+            }
+        }
+        for (const [n, div] of bardivs) {
+            const bar = n.value(seat);
+            const shown = bar.segmentos.slice(-SEGMENTS);
+            const label = barLabel(t, n.name.text, { segmentos: shown, cor: bar.cor }); // in the key: a language change rewrites it
+            const key = `${bar.cor}:${shown.join(',')}:${label}`;
+            if (div.dataset.estado === key)
+                continue;
+            div.dataset.estado = key;
+            div.dataset.cor = bar.cor;
+            [...div.children].forEach((cell, i) => { cell.dataset.seg = shown[i] ?? 'vazio'; });
+            div.setAttribute('aria-label', label);
+        }
+        return changed;
+    }
+    refresh();
+    return {
+        left,
+        right,
+        learning,
+        refresh,
+        remove: () => { left.remove(); right.remove(); learning.remove(); },
+    };
+}

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

@@ -1,17 +1,18 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { PlayerView } from '../core/entity.js';
 import type { Objective } from '../core/contract.js';
+import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
 /** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
 export type { DomQuery } from '../core/dom-query.js';
-/** Só os campos do jogador que o HUD lê. Estrutural de propósito: o `players[]` real é `unknown[]` no core/state. */
-/** O que o HUD lê do JOGADOR: o poder ativo e se ele desistiu. O progresso vem do `Objective`, não daqui —
- *  `collected` saiu da fatia, e com ele a última coisa que o HUD sabia sobre juntar objetos. */
+/** Only the player fields the HUD reads. Structural on purpose: the real `players[]` is `unknown[]` in core/state. */
+/** What the HUD reads from the PLAYER: the active power and whether they quit. Progress comes from the `Objective`,
+ *  not from here. */
 export type HudPlayer = PlayerView<'activePower' | 'quit'>;
-/** Grade de telas: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (a 3ª tela é centralizada na linha de baixo). */
+/** Screen grid: 1 → 1×1, 2 → 2×1, 3-4 → 2×2 (the 3rd screen is centred on the bottom row). */
 export { screenGrid } from '../core/screens.js';
 export type { ScreenGrid } from '../core/screens.js';
-/** Retângulo da tela `i` em porcentagens de CSS, já prontas para `style.left/top/width/height`. */
+/** Screen `i`'s rectangle in CSS percentages, ready for `style.left/top/width/height`. */
 export interface ScreenRect {
     L: string;
     T: string;
@@ -19,119 +20,121 @@ export interface ScreenRect {
     H: string;
 }
 /**
- * Posição/tamanho da tela `i` numa grade de `n` jogadores. Verbatim de screenRect(i) — que lia `numPlayers`
- * global; aqui `n` é parâmetro (mesma conta, testável sem estado). Caso especial preservado: com 3 telas, a
- * terceira é centralizada na linha de baixo, para casar com o posicionamento do render (configureRender).
+ * Position/size of screen `i` in a grid of `n` players; `n` is a parameter, so it is testable without state. Special
+ * case: with 3 screens, the third is centred on the bottom row, to match the renderer's positioning.
  */
 export declare function screenRect(i: number, n: number): ScreenRect;
-/** Quantas telas o HUD monta: ao menos uma, mesmo antes de `players[]` existir no boot. Verbatim (Math.max(1,…)). */
+/** How many screens the HUD mounts: at least one, even before `players[]` exists at boot. */
 export declare function screenCount(n: number): number;
-/** O texto que o leitor de tela ouve no contador. A MOLDURA é a chave; o NOME do objetivo atravessa por
- *  parâmetro — a regra do pilar 3 (ADR-0010), a mesma que o currículo segue. */
-export declare const contadorLabel: (o: Objective) => string;
+/** The text a screen reader hears on the counter. The FRAME is the key; the objective's NAME passes through as a
+ *  parameter — pillar 3's rule (ADR-0010), the same the curriculum follows. */
+export declare const counterLabel: (t: Translate, o: Objective) => string;
 /**
- * Markup do contador (objetivo na 1ª coluna, poder na 2ª).
+ * The counter's markup (objective in the 1st column, power in the 2nd).
  *
- * O objetivo entra INTEIRO — nome, quanto tem, quanto precisa — em vez de só o alvo numérico, e o ícone entra
- * por injeção. É o que tira o desenho da moeda de dentro da engine: o HUD mostra o que o jogo declarou
- * (campo 5 do contrato), sem saber se é moeda, palavra ou conta.
+ * The objective comes in WHOLE — name, how much you have, how much you need — and the icon by injection: the HUD shows
+ * what the game declared (field 5 of the contract), without knowing whether it is a coin, a word or a sum.
  *
- * O `aria-label` é a parte que não é renomeação: sem o nome do objetivo não havia o que dizer, e o contador
- * era mudo para quem não vê a tela.
+ * The accessible name is set separately (`applyCounterLabel`), because the objective's name is outside data.
  */
-export declare function vphudHtml(objetivo: Objective, icone: string): string;
+export declare function vphudHtml(objective: Objective, icon: string): string;
 /**
- * PÕE O NOME DECLARADO PELO JOGO NO RÓTULO DO LEITOR DE TELA — por atributo, nunca por markup (issue #106).
+ * PUTS THE NAME THE GAME DECLARED INTO THE SCREEN READER'S LABEL — by attribute, never by markup (issue #106).
  *
- * ⚠️ ESTE É UM VETOR QUE A AUDITORIA DE 2026-08-26 NÃO TINHA COMO CONHECER, e vale dizer por quê: ela varreu
- * por FONTE DE DADO e concluiu, com razão para a época, que nada de fora chegava a markup. Depois disso o
- * contrato passou a existir (ADR-0030) e os jogos passaram a viver em REPOSITÓRIOS SEPARADOS, consumindo a
- * engine como pacote (ADR-0083). O `name.text` do objetivo é texto de um jogo que esta árvore não revê.
+ * ⚠️ The games live in SEPARATE REPOSITORIES and consume the engine as a package (ADR-0083), so the objective's
+ * `name.text` is text from a game this tree does not review.
  *
- * ⚠️ E ELE ENTRAVA NUM ATRIBUTO, que é o pior contexto dos dois: dentro de um elemento uma aspa é inofensiva,
- * dentro de `aria-label="…"` ela FECHA o atributo e o que vem a seguir vira atributo — um `onmouseover` sem
- * precisar de uma única tag.
+ * ⚠️ AND IT GOES INTO AN ATTRIBUTE, the worse of the two contexts: inside an element a quote is harmless; inside
+ * `aria-label="…"` it CLOSES the attribute and what follows becomes an attribute — an `onmouseover` without a single
+ * tag.
  *
- * `setAttribute` escapa por construção, e é por isso que a resposta é «construir nós» e não «escapar à mão»:
- * um escape esquecido não deixa rasto; um `setAttribute` esquecido tira o rótulo, e há caso a prendê-lo.
+ * `setAttribute` escapes by construction, which is why the answer is building nodes and not escaping by hand: a
+ * forgotten escape leaves no trace; a forgotten `setAttribute` removes the label, and a case holds it.
  */
-export declare function aplicarRotuloDoContador(vphud: Element | null, objetivo: Objective): void;
-/** Markup do selo "aperte um botão para entrar" (tela criada em jogo, ainda sem dono). `i` é o índice 0-based. */
-export declare function waitBadgeHtml(i: number): string;
-/** Projeção do HUD de UMA tela: tudo que updateGameHud() escreve no DOM, sem tocar no DOM. */
+export declare function applyCounterLabel(t: Translate, vphud: Element | null, objective: Objective): void;
+/**
+ * The markup of the press-a-button-to-join badge (a screen created mid-game, still with no owner). `i` is 0-based.
+ *
+ * 🔴 FROM THE DICTIONARY, never raw text: it is the only sentence that tells the child who just got a screen HOW to join,
+ * and the badge is their whole screen at that instant, not a corner detail.
+ *
+ * 📌 ITS OWN KEY and not the existing `sr.player.pressToJoin`, although the two look alike: the screen reader's says to
+ * press a button, this one says WHICH — your own keyboard or a free controller —, because whoever reads it is looking
+ * at a screen with other people around and needs to know it is not just any keyboard. Merging them would erase that
+ * half of one of the two.
+ */
+export declare function waitBadgeHtml(t: Translate, i: number): string;
+/** The HUD projection of ONE screen: everything updateGameHud() writes to the DOM, without touching the DOM. */
 export interface HudRowView {
-    /** Texto do contador: quanto o jogador tem, verbatim (sem formatação nem clamp). */
+    /** The counter's text: how much the player has, as given (no formatting nor clamp). */
     have: string;
-    /** O que o leitor de tela ouve no contador — reescrito junto com o número, senão ele ficaria falando o
-     *  valor do primeiro quadro a partida inteira. É o defeito que um `aria-label` estático teria. */
+    /** What the screen reader hears on the counter — rewritten with the number, otherwise it would keep saying the first
+     *  frame's value the whole match. That is the defect a static `aria-label` would have. */
     label: string;
-    /** Rótulo curto do poder ativo, com o travessão como fallback de poder desconhecido/ausente. */
+    /** Short label of the active power, with the dash as the fallback for an unknown/absent power. */
     power: string;
-    /** `hidden` do selo "Jogo abandonado": escondido enquanto o jogador NÃO desistiu. */
+    /** `hidden` of the quit badge: hidden while the player has NOT quit. */
     quitHidden: boolean;
-    /** `style.visibility` do contador: quem desistiu vê tela preta com o selo, sem números. */
+    /** The counter's `style.visibility`: whoever quit sees a black screen with the badge, no numbers. */
     visibility: 'hidden' | 'visible';
 }
 /**
- * Estado do HUD de um jogador. Verbatim do corpo de updateGameHud(), só que como valor.
- * `powerShort` é o POWER_SHORT do game.js (injetado — a mesma FUNÇÃO que game/coin-spawning.ts já recebe).
- * Função e não tabela: o texto depende do idioma ATUAL, e uma tabela lida no boot ficaria congelada nele.
+ * One player's HUD state, as a value. `powerShort` is injected by the host (the same function other game modules
+ * receive). A function and not a table: the text depends on the CURRENT language, and a table read at boot would stay
+ * frozen in it.
  */
-export declare function hudRowView(p: HudPlayer, powerShort: (kind: string) => string, objetivo: Objective): HudRowView;
+export declare function hudRowView(t: Translate, p: HudPlayer, powerShort: (kind: string) => string, objective: Objective): HudRowView;
 export interface HudCtx {
-    /** 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`). */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** How many players/screens. ROUND state (ADR-0038): it comes from the instance the root owns — a module `let` would
+     *  be shared by any second game the same page loads. */
     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). */
+    /** The players. ROUND state, for the same reason. `readonly unknown[]` because each consumer narrows to ITS slice —
+     *  the real type is the game's, not the engine's (ADR-0033). */
     getPlayers: () => readonly unknown[];
-    /** Seletor DOM (forma do `$` de ui/dom.ts), injetado — o módulo nunca alcança `document` por global. */
+    /** DOM selector (ui/dom.ts's `$` shape), injected — the module never reaches `document` through a global. */
     $: DomQuery;
     /**
-     * POWER_SHORT: rótulos curtos de poder mostrados no HUD. Fica no game.js porque game/coin-spawning.ts
-     * (showPower) também o recebe — injetar evita a 2ª cópia da tabela.
+     * Short power labels shown on the HUD. Injected so the host keeps one table for every module that shows powers.
      */
     powerShort: (kind: string) => string;
     /**
-     * O OBJETIVO do jogador `i` — campo 5 do contrato (`core/contract.Objective`): o nome do que se junta,
-     * quanto tem e quanto precisa. FUNÇÃO e não valor, porque `have` muda a cada quadro.
-     *
-     * Era `hudTarget: number`, e antes disso `COIN_TARGET` por importação. Cada passo tirou uma coisa que o HUD
-     * sabia sobre o jogo: primeiro a dependência, agora o assunto.
+     * Player `i`'s OBJECTIVE — field 5 of the contract (`core/contract.Objective`): the name of what is collected, how
+     * much they have and how much they need. A FUNCTION and not a value, because `have` changes every frame.
      */
     hudObjective: (playerIndex: number) => Objective;
-    /** O ícone do contador. Era o desenho da moeda cravado no markup da engine; é do jogo, como o nome. */
+    /** The counter's icon. It is the game's, like the name. */
     hudIcon: string;
     /**
-     * Painel de pausa da tela `i`. NÃO é deste módulo (slice de pausa/ícones): entra por injeção e o HUD só
-     * anexa o retorno dentro da `.player-screen` correspondente.
+     * Screen `i`'s pause panel. NOT this module's: it comes in by injection and the HUD only attaches the result inside
+     * the matching `.player-screen`.
      */
     buildScreenPause: (i: number) => HTMLElement;
     /**
-     * A BARRA RÁPIDA de acessibilidade da tela `i` (ui/pause-icons `buildQuickBar`). Anexada como IRMÃ da
-     * `.screen-exp`, e não dentro dela: a barra é CONTROLE, e o modo empatia não a alcança (issue #82).
+     * Screen `i`'s accessibility QUICK BAR (ui/pause-icons `buildQuickBar`). Attached as a SIBLING of `.screen-exp`, not
+     * inside it: the bar is CONTROL, and empathy mode does not reach it (issue #82).
      */
     buildQuickBar: (i: number) => HTMLElement;
     /**
-     * Chamado no FIM de buildGameHud() com os painéis de pausa recém-criados, em ordem de tela. É o gancho onde o
-     * game.js reatribui `vpPause` (binding local dele) e roda o que o original rodava depois do laço
-     * (applyLetra/renderPauseLegend). Opcional: sem ele o HUD monta igual, só não avisa ninguém.
+     * Called at the END of buildGameHud() with the freshly created pause panels, in screen order — the hook where the
+     * host keeps its references and runs what depends on them. Optional: without it the HUD mounts the same, it just
+     * tells nobody.
      */
     onScreensBuilt?: (pausePanels: HTMLElement[]) => void;
-    /** As barras rápidas recém-montadas, na ordem das telas. A raiz guarda para o `getA11yBars`. */
+    /** The freshly mounted quick bars, in screen order. The root keeps them for `getA11yBars`. */
     onBarsBuilt?: (bars: HTMLElement[]) => void;
 }
 export interface HudApi {
-    /** (Re)monta `#game-hud`: uma `.player-screen` por jogador, com HUD, selo de abandono e painel de pausa. */
+    /** (Re)mounts `#game-hud`: one `.player-screen` per player, with HUD, quit badge and pause panel. */
     buildGameHud: () => void;
-    /** Reescreve moedas/poder e o selo de abandono de todas as telas montadas. Chamado a cada frame. */
+    /** Rewrites the objective/power and the quit badge on every mounted screen. Called every frame. */
     updateGameHud: () => void;
-    /** Contêiner `.player-screen` da tela `i` (o quiz de MP e outros overlays por jogador penduram aqui). */
+    /** Screen `i`'s `.player-screen` container (the multiplayer quiz and other per-player overlays hang here). */
     getScreen: (i: number) => HTMLElement | null;
-    /** Cria o selo `.vp-wait` na tela `i` (idempotente: não duplica se já existir). */
+    /** Creates the `.vp-wait` badge on screen `i` (idempotent: does not duplicate if it already exists). */
     showWaitingBadge: (i: number) => void;
-    /** Remove o selo `.vp-wait` da tela `i` (o jogador entrou). No-op se a tela ou o selo não existirem. */
+    /** Removes the `.vp-wait` badge from screen `i` (the player joined). No-op if the screen or the badge does not exist. */
     clearWaitingBadge: (i: number) => void;
 }
 export declare function initHud(ctx: HudCtx): HudApi;