@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translator } 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';
+    /** The key of what is counted («points», «balls») in the game's dictionary. */
+    readonly nameKey: string;
+    /** 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 key of the skill's name in the game's dictionary. */
+    readonly nameKey: string;
+    readonly value: (seat: number) => HudBar;
+};
+/** What the HUD asks of the root's translator: the engine's frames, and the game's declared words. */
+type HudTranslator = Pick<Translator, 't' | 'word'>;
+/** 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[];
+/** The HUD row's cells the bands go into (`ui/hud-row`, ADR-0239). */
+export interface HudRowSlots {
+    readonly learning: HTMLElement;
+    readonly score: HTMLElement;
+}
+export interface HudBandsMounted {
+    /** The mission, at the top centre under the quick bar (the name is from when it sat top left). */
+    readonly left: HTMLElement;
+    /** The power in use, above the score. */
+    readonly right: HTMLElement;
+    /** The identity numbers — the score — in five digits (ADR-0238). */
+    readonly points: 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;
+}
+/**
+ * A count as FIVE DIGITS WITH LEADING ZEROS, clamped to 0…99999 (ADR-0238): 12 is «00012». `shown` is the number those digits
+ * say, which is what a listener hears — the same number a sighted child sees, never the zeros.
+ */
+export declare function fiveDigits(count: number): {
+    readonly digits: string;
+    readonly shown: number;
+};
+/**
+ * Mounts the bands, one element per declared number, and fills them: the mission in the game region, the rest in the HUD
+ * row's cells (`row`). A place with no number is hidden. Without a row every band goes in the region itself — the learning
+ * band BEFORE the screen footer when one exists, so the explanation band, drawn later on the same layer, covers it.
+ */
+export declare function mountHudBands(tr: HudTranslator, doc: Document, region: HTMLElement, numbers: readonly HudNumber[], seat?: number, row?: HudRowSlots): HudBandsMounted;
+export {};

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

@@ -0,0 +1,146 @@
+// 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.nameKey !== 'string' || !n.nameKey.trim())
+            out.push(`hud[${i}].nameKey must name what is counted by a key of the game's dictionary`);
+        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;
+}
+/** The highest count five digits hold; a larger score is shown as this (ADR-0238). */
+const MAX_POINTS = 99_999;
+/**
+ * A count as FIVE DIGITS WITH LEADING ZEROS, clamped to 0…99999 (ADR-0238): 12 is «00012». `shown` is the number those digits
+ * say, which is what a listener hears — the same number a sighted child sees, never the zeros.
+ */
+export function fiveDigits(count) {
+    const shown = Math.min(MAX_POINTS, Math.max(0, Math.floor(count) || 0));
+    return { digits: String(shown).padStart(5, '0'), shown };
+}
+/**
+ * What the child reads, and — for the points — what a listener hears instead (`label`): the frame in the dictionary, the name
+ * — resolved from the game's key at this refresh (ADR-0232 D3) — through a parameter (pillar 3). A count of objectives keeps
+ * its «3 of 10» wherever it is declared.
+ */
+function lineFace(t, name, n, seat) {
+    const v = n.value(seat);
+    if (typeof v !== 'number')
+        return { text: t('hud.contador', { have: String(v.have), need: String(v.need), nome: name }), label: null };
+    if (n.band !== 'identity')
+        return { text: t('hud.numero', { nome: name, valor: String(v) }), label: null };
+    const { digits, shown } = fiveDigits(v);
+    return { text: digits, label: t('hud.points', { count: String(shown), name }) };
+}
+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 bands, one element per declared number, and fills them: the mission in the game region, the rest in the HUD
+ * row's cells (`row`). A place with no number is hidden. Without a row every band goes in the region itself — the learning
+ * band BEFORE the screen footer when one exists, so the explanation band, drawn later on the same layer, covers it.
+ */
+export function mountHudBands(tr, doc, region, numbers, seat = 0, row) {
+    const { t } = tr;
+    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');
+    const ofBand = (b) => texts.filter((n) => n.band === b);
+    const left = band('hud-esquerda', ofBand('mission').length);
+    const right = band('hud-direita', ofBand('power').length);
+    const points = band('hud-points', ofBand('identity').length);
+    const learning = band('hud-aprendizagem', bars.length);
+    const place = { identity: points, mission: left, power: right };
+    const lines = texts.map((n) => {
+        const p = doc.createElement('p');
+        p.className = 'hud-numero';
+        p.dataset.band = n.band;
+        place[n.band].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);
+    // the power ABOVE the score (ADR-0239 point 3): the order of the two in their cell is the order on screen
+    (row?.score ?? region).append(right, points);
+    if (row)
+        row.learning.appendChild(learning);
+    else
+        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) {
+            // a name the game's dictionaries lack hides its line — never its key on screen (`problems` names it)
+            const name = tr.word(n.nameKey);
+            if (p.hidden !== !name) {
+                p.hidden = !name;
+                changed = true;
+            }
+            const face = name ? lineFace(t, name, n, seat) : { text: '', label: null };
+            if (p.textContent !== face.text) {
+                p.textContent = face.text;
+                changed = true;
+            }
+            // the points are an image of a number for a listener: the name says «12 points», never «zero zero zero one two»
+            if (face.label !== null && p.getAttribute('aria-label') !== face.label) {
+                p.setAttribute('role', 'img');
+                p.setAttribute('aria-label', face.label);
+            }
+        }
+        for (const [n, div] of bardivs) {
+            const name = tr.word(n.nameKey);
+            div.hidden = !name;
+            if (!name)
+                continue;
+            const bar = n.value(seat);
+            const shown = bar.segmentos.slice(-SEGMENTS);
+            const label = barLabel(t, name, { 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,
+        points,
+        learning,
+        refresh,
+        remove: () => { left.remove(); points.remove(); right.remove(); learning.remove(); },
+    };
+}

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The row's cells, each a place something else fills: the bands (`ui/hud-bands`), the clock (`ui/session-clock`), the map. */
+export interface HudRow {
+    readonly row: HTMLElement;
+    /** Bottom left: the learning bars. */
+    readonly learning: HTMLElement;
+    /** Bottom centre: the session clock. */
+    readonly clock: HTMLElement;
+    /** Between the centre and the right: the power above the score. */
+    readonly score: HTMLElement;
+    /** Bottom right: where a game mounts its own map. Empty, it is not drawn (ADR-0239 point 4). */
+    readonly map: HTMLElement;
+}
+/**
+ * Builds the row in `region`, BEFORE the screen footer when one exists, so the explanation band — drawn later on the same
+ * layer — covers it. `null` where the region takes no children.
+ */
+export declare function mountHudRow(doc: Document, region: HTMLElement | null): HudRow | null;
+/** What `reserveBottomBand` measures. The pad is the on-screen controller (`#touch-controls`), when the page has one. */
+export interface BottomBandCtx {
+    readonly region: HTMLElement | null;
+    readonly row: HTMLElement | null;
+    readonly pad: HTMLElement | null;
+}
+/**
+ * THE ROW FOLLOWS THE PAD AT ONCE (ADR-0239 §6): `measure` runs again whenever the on-screen pad under `host` shows, hides or is
+ * rebuilt, by whichever door — a touch, a key, a menu opening or closing (ADR-0166), a new cartridge. A resize and the session
+ * clock's tick are not enough: between them the row stood behind the pad for up to a second, and the explanation band that
+ * stands where the row stands lay over the pad's START pill. A mutation observer answers before the next frame is drawn.
+ * Returns what stops it; nothing is watched where the host has no observer.
+ */
+export declare function followThePad(host: Node | null, Observer: typeof MutationObserver | undefined, measure: () => void): () => void;
+/** Measures the bottom and writes `--hud-row-bottom` and `--hud-row-h` on the region (see the header). */
+export declare function reserveBottomBand(ctx: BottomBandCtx): void;

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

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/hud-row — THE HUD IS ONE ROW AT THE BOTTOM of the game region (ADR-0239; issue #94), and this module builds the row's
+// cells and measures the room it takes.
+//
+// Left to right: the learning bars · the session clock, in the centre · the score, with the power above it · the game's map.
+// The mission is not here: it sits at the top centre, just under the quick bar (ADR-0239 erratum; `ui/top-band`).
+//
+// WHO SITS OVER WHOM at the bottom (ADR-0239 point 6), written as two variables on the region that the stylesheet reads:
+//   · `--hud-row-bottom` — how far above the region's lower edge the row stands: 0, or the height of the on-screen pad's
+//     lower parts while the pad shows, so the row sits ABOVE the pad;
+//   · `--hud-row-h` — the row's own height, so the sound caption and the button legend sit above it, and a game's workspace
+//     ends above it: `--rodape-h` is these two and nothing else, because the caption and the legend are momentary and
+//     overlay the workspace while they show (ADR-0239 erratum).
+// The explanation band covers the row while a menu is open: that is the stylesheet's alone.
+//
+// ⚠️ IT RECEIVES THE NODES and reaches no global (ADR-0232), like `ui/top-band`.
+/**
+ * Builds the row in `region`, BEFORE the screen footer when one exists, so the explanation band — drawn later on the same
+ * layer — covers it. `null` where the region takes no children.
+ */
+export function mountHudRow(doc, region) {
+    if (!region || typeof region.insertBefore !== 'function')
+        return null;
+    const cell = (cls) => { const el = doc.createElement('div'); el.className = cls; return el; };
+    const row = cell('hud-row');
+    const learning = cell('hud-row-cell hud-row-learning');
+    const clock = cell('hud-row-cell hud-row-clock');
+    const end = cell('hud-row-cell hud-row-end');
+    const score = cell('hud-score');
+    const map = cell('hud-map');
+    end.appendChild(score);
+    end.appendChild(map);
+    for (const c of [learning, clock, end])
+        row.appendChild(c);
+    // `children` may be missing in a host double; then there is no footer to go before
+    region.insertBefore(row, Array.from(region.children ?? []).find((c) => c.classList.contains('rodape-da-tela')) ?? null);
+    return { row, learning, clock, score, map };
+}
+/** A pad part counts when it stands on the region's lower edge — within this many pixels of it. */
+const ON_THE_EDGE_PX = 24;
+/** How high the pad's lower parts reach above the region's lower edge while the pad shows; 0 when it is hidden or absent. */
+function padReach(pad, regionBottom) {
+    if (!pad || pad.hidden)
+        return 0;
+    let reach = 0;
+    for (const part of [...pad.children]) {
+        const b = part.getBoundingClientRect();
+        if (b.height > 0 && regionBottom - b.bottom <= ON_THE_EDGE_PX)
+            reach = Math.max(reach, regionBottom - b.top);
+    }
+    return reach;
+}
+/** The pad, or a part of it, in a mutation: its `hidden` changed, its parts were rebuilt, or it came or went. */
+function aboutThePad(r) {
+    return [r.target, ...Array.from(r.addedNodes), ...Array.from(r.removedNodes)].some((n) => !!n.closest?.('#touch-controls'));
+}
+/**
+ * THE ROW FOLLOWS THE PAD AT ONCE (ADR-0239 §6): `measure` runs again whenever the on-screen pad under `host` shows, hides or is
+ * rebuilt, by whichever door — a touch, a key, a menu opening or closing (ADR-0166), a new cartridge. A resize and the session
+ * clock's tick are not enough: between them the row stood behind the pad for up to a second, and the explanation band that
+ * stands where the row stands lay over the pad's START pill. A mutation observer answers before the next frame is drawn.
+ * Returns what stops it; nothing is watched where the host has no observer.
+ */
+export function followThePad(host, Observer, measure) {
+    if (!host || typeof Observer !== 'function')
+        return () => { };
+    const observer = new Observer((records) => { if (records.some(aboutThePad))
+        measure(); });
+    observer.observe(host, { attributes: true, attributeFilter: ['hidden'], childList: true, subtree: true });
+    return () => observer.disconnect();
+}
+/** Measures the bottom and writes `--hud-row-bottom` and `--hud-row-h` on the region (see the header). */
+export function reserveBottomBand(ctx) {
+    const { region, row } = ctx;
+    if (!region || !row || typeof region.getBoundingClientRect !== 'function')
+        return;
+    const lift = Math.ceil(padReach(ctx.pad, region.getBoundingClientRect().bottom));
+    region.style.setProperty('--hud-row-bottom', `${lift}px`);
+    region.style.setProperty('--hud-row-h', `${Math.ceil(row.getBoundingClientRect().height)}px`);
+}

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

@@ -1,17 +1,15 @@
 // 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 +17,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;