@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -1,103 +1,129 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/panel-shell — A CASCA DE UM PAINEL DE AJUSTES, construída em vez de exigida.
+// ui/panel-shell — THE SHELL OF A SETTINGS PANEL, built instead of required.
 //
-// ========================= O ACHADO QUE ISTO CONSERTA =========================
-// O segundo consumidor (a etapa C da issue #63) mediu-o e escreveu-o no achado 6:
+// ========================= WHAT THIS FIXES =========================
+// A second consumer (issue #63) measured it: a panel's ctx asks for `$` and `store`, but what it REALLY requires is
+// that the consumer's document contain five ids (`#typo`, `#typo-list`, `#typo-close`, …). Nothing in the type says so;
+// it is found by trial, and the failure mode is the worst possible one — the panel opens EMPTY, with no error.
 //
-//     «O CONTRATO DE MARKUP É INVISÍVEL. O ctx do painel pede `$` e `store`; o que ele REALMENTE exige é que
-//      o documento do consumidor contenha `#typo`, `#typo-list`, `#typo-preview`, `#typo-close` e
-//      `#typo-reset`. Nada no tipo diz isso — descobre-se por tentativa, e o modo de falhar é o pior
-//      possível: o painel abre VAZIO, sem erro.»
+// Each `ui/settings-*.ts` fills the INSIDE of its panel; this module builds the OUTSIDE — the veil, the card, the title,
+// the actions row and the reset button — and returns the ids it created, so the contract is stated instead of
+// discovered.
 //
-// Cada `ui/settings-*.ts` preenche o INTERIOR do seu painel; o EXTERIOR — o véu, o cartão, o título, o
-// rodapé de ações e o botão de restaurar — vinha do `app/index.html`, que saiu com o cartucho (#111). Desde
-// então a engine EXIGE cinco ids por painel e não os declara em lado nenhum.
+// ⚠️ AND THE MENU RULE OF `CLAUDE.md` §4 IS BUILT IN, not remembered. A panel's introduction goes in the card's
+// `data-explain-idle` — never in a `<p>` of prose at the top —, because a menu that explains item by item makes the
+// child READ EVERYTHING to find what they want (issue #62). The shell has no way to receive a `<p>` at the top.
 //
-// ⚠️ E A REGRA DE MENU DO `CLAUDE.md` §4 DEPENDIA DE ALGUÉM SE LEMBRAR DELA. A introdução de um painel vai no
-// `data-explain-idle` do cartão — nunca num `<p>` de prosa no topo —, porque um menu que explica item a item
-// obriga a criança a LER TUDO para achar o que procura. A issue #62 mandava editar seis blocos de markup para
-// isso; o markup saiu, e a regra ficou sem alvo. Aqui ela deixa de ser lembrete e passa a ser construção: a
-// casca não tem por onde receber um `<p>` no topo.
-//
-// ========================= A FORMA, QUE FOI MEDIDA E NÃO INVENTADA =========================
-// É a do painel de tipografia do `app/quiz.html`, que é o único que sobrou e o que o segundo consumidor
-// exercitou de facto:
+// ========================= THE SHAPE =========================
 //
 //     <div id="X" class="overlay" hidden>
 //       <div class="overlay__card" role="dialog" aria-modal="true" aria-labelledby="X-title" [data-explain-idle]>
 //         <h2 id="X-title">…</h2>
-//         <div id="X-list" class="ctrl-list" role="group" aria-label="…"></div>   ← o interior, do settings-*
+//         <button id="X-close">…</button>                                           ← item 1 (ADR-0158)
+//         <div id="X-list" class="ctrl-list" role="group" aria-label="…"></div>   ← the inside, from settings-*
 //         <div class="overlay__actions">
-//           <button id="X-reset">…</button>  <button id="X-close">…</button>
+//           <button id="X-reset">…</button>
 //         </div>
 //       </div>
 //     </div>
 //
-// ⚠️ O RODAPÉ `.opt-explain` NÃO É CRIADO AQUI, e isso é deliberado: `ui/settings-panel.fillExplain` cria-o
-// quando move a primeira dica para lá. Criá-lo vazio aqui daria uma região `aria-live` que anuncia nada, e
-// duas mãos a criar o mesmo nó é como ele acabaria duplicado.
+// ⚠️ THE `.opt-explain` FOOTER IS NOT CREATED HERE, on purpose: `ui/settings-panel.fillExplain` creates it when it moves
+// the first hint there. Creating it empty here would give an `aria-live` region that announces nothing, and two hands
+// creating the same node is how it would end up duplicated.
 //
-// Sem `innerHTML`: tudo por `criar` + `textContent`, no molde de `ui/loop-crash` e `ui/focus-trap`. O título
-// e o rótulo da lista vêm do CHAMADOR já resolvidos — este módulo não traduz, para poder ser exercitado sem
-// dicionário.
+// No `innerHTML`: everything through `create` + `textContent`, like `ui/loop-crash` and `ui/focus-trap`. The title and
+// the list label come from the CALLER already resolved — this module does not translate, so it can be exercised with no
+// dictionary.
 //
-// ⚠️ E NÃO IMPORTA NADA. Uma casca que não usa `innerHTML` também não precisa de escapar texto: `textContent`
-// escapa por construção. Chegou a haver aqui um `escaparHtml` importado «por conveniência» — que é como um
-// módulo-folha deixa de o ser, e como um leitor futuro passa a procurar a interpolação que não existe.
-/** Os ids que um painel de `id` ocupa. Exportado porque um gate e um consumidor precisam de os nomear. */
-export function idsDaCasca(id) {
-    return { overlay: id, title: `${id}-title`, lista: `${id}-list`, reset: `${id}-reset`, fechar: `${id}-close` };
+// ⚠️ AND IT IMPORTS NOTHING. A shell that does not use `innerHTML` does not need to escape text either: `textContent`
+// escapes by construction. An import "for convenience" is how a leaf module stops being one, and how a future reader
+// starts looking for an interpolation that does not exist.
+/** The ids a panel of `id` occupies. Exported because a gate and a consumer need to name them. */
+export function shellIds(id, customListId) {
+    return {
+        overlay: id,
+        title: `${id}-title`,
+        list: customListId ?? `${id}-list`,
+        reset: `${id}-reset`,
+        close: `${id}-close`,
+    };
 }
 /**
- * Monta (ou reaproveita) a casca do painel `spec.id` e devolve as suas partes.
+ * Mounts (or reuses) the shell of panel `spec.id` and returns its parts.
  *
- * IDEMPOTENTE: se já existir um `#id`, ele é reutilizado e o conteúdo do cartão é reconstruído. Um painel que
- * a raiz monte duas vezes não pode acabar com dois véus — e a raiz monta mais do que uma vez, porque a
- * contagem de jogadores muda a grade de telas.
+ * IDEMPOTENT: if a `#id` already exists, it is reused and the card's content is rebuilt. A panel mounted twice cannot
+ * end up with two veils — and it can be mounted more than once (two cartridges on one page, ADR-0139).
  */
-export function montarCasca(ctx, spec) {
-    const ids = idsDaCasca(spec.id);
-    const overlay = ctx.procurar('#' + ids.overlay) ?? ctx.criar('div');
+export function mountShell(ctx, spec) {
+    const ids = shellIds(spec.id, spec.listId);
+    const overlay = ctx.find('#' + ids.overlay) ?? ctx.create('div');
     overlay.id = ids.overlay;
     overlay.className = 'overlay';
     overlay.hidden = true;
     while (overlay.firstChild)
         overlay.removeChild(overlay.firstChild);
-    const card = ctx.criar('div');
+    const card = ctx.create('div');
     card.className = 'overlay__card';
     card.setAttribute('role', 'dialog');
     card.setAttribute('aria-modal', 'true');
     card.setAttribute('aria-labelledby', ids.title);
-    // A introdução do painel é o texto de REPOUSO do rodapé (CLAUDE.md §4), nunca um `<p>` no topo.
-    if (spec.introducao)
-        card.setAttribute('data-explain-idle', spec.introducao);
-    const h2 = ctx.criar('h2');
+    const h2 = ctx.create('h2');
     h2.id = ids.title;
-    h2.textContent = spec.titulo;
     card.appendChild(h2);
-    const lista = ctx.criar('div');
-    lista.id = ids.lista;
-    lista.className = 'ctrl-list';
-    lista.setAttribute('role', 'group');
-    lista.setAttribute('aria-label', spec.rotuloDaLista);
-    card.appendChild(lista);
-    const acoes = ctx.criar('div');
-    acoes.className = 'overlay__actions';
-    const reset = botao(ctx, ids.reset, spec.rotuloReset, 'mode-btn');
-    const fechar = botao(ctx, ids.fechar, spec.rotuloFechar, 'mode-btn is-on');
-    acoes.appendChild(reset);
-    acoes.appendChild(fechar);
-    card.appendChild(acoes);
+    // ADR-0158: «Voltar» is item 1 and nothing closes the panel after its rows. The way out is where the cursor lands
+    // when the panel opens — a close button at the bottom made the child walk every row to leave. The id stays
+    // `#X-close`, which is contract; only its place and its word changed.
+    const backButton = button(ctx, ids.close, 'mode-btn overlay__back');
+    card.appendChild(backButton);
+    const listNode = ctx.create('div');
+    listNode.id = ids.list;
+    listNode.className = 'ctrl-list';
+    listNode.setAttribute('role', 'group');
+    card.appendChild(listNode);
+    const actionsRow = ctx.create('div');
+    actionsRow.className = 'overlay__actions';
+    const reset = button(ctx, ids.reset, 'mode-btn');
+    actionsRow.appendChild(reset);
+    card.appendChild(actionsRow);
     overlay.appendChild(card);
-    return { overlay, card, lista, reset, fechar, ids };
+    const shell = { overlay, card, title: h2, list: listNode, reset, close: backButton, ids };
+    applyLabels(shell, spec);
+    return shell;
+}
+/**
+ * WRITES THE SHELL'S WORDS — separate from construction because they change AFTER it exists.
+ *
+ * 🔴 `initI18n` applies the fallback language synchronously — so the page is never blank — and, if the preferred
+ * language is another, REQUESTS the switch, which is asynchronous. Anything JavaScript builds in that gap captures the
+ * fallback text and nothing rebuilds it; and the language can also change mid-game.
+ *
+ * ⚠️ AND REBUILDING THE SHELL TO FIX THE TITLE DOES NOT WORK. `mountShell` empties the card, and each `ui/settings-*`
+ * wires its `#X-reset` ONCE, at `init` — remounting leaves the reset button in the document with no listener, a dead
+ * button that looks alive (ADR-0106 §5). Writing only the words touches no listener.
+ *
+ * IDEMPOTENT: writing the same labels twice is writing the same labels.
+ */
+export function applyLabels(shell, r) {
+    shell.title.textContent = r.title;
+    shell.list.setAttribute('aria-label', r.listLabel);
+    shell.reset.textContent = r.resetLabel;
+    shell.close.textContent = r.closeLabel;
+    // the arrow is drawn by the stylesheet, out of the name (ADR-0159 rule 12)
+    shell.close.setAttribute('data-glifo', '↩');
+    // The panel's introduction is the footer's RESTING text (CLAUDE.md §4), never a `<p>` at the top.
+    // ⚠️ ABSENCE HAS TO ERASE, not just stop writing: on a retranslation into a dictionary without the key, the old
+    // attribute would survive and the footer would rest in the previous language.
+    if (r.intro)
+        shell.card.setAttribute('data-explain-idle', r.intro);
+    else
+        shell.card.removeAttribute('data-explain-idle');
 }
-function botao(ctx, id, rotulo, classe) {
-    const b = ctx.criar('button');
+function button(ctx, id, cssClass) {
+    const b = ctx.create('button');
     b.id = id;
-    b.className = classe;
+    b.className = cssClass;
     b.setAttribute('type', 'button');
-    // `textContent` e não `innerHTML`: um rótulo traduzido é dado de fora como qualquer outro, e um dicionário
-    // de consumidor pode trazer o que quiser dentro dele.
-    b.textContent = rotulo;
+    // The label comes in through `applyLabels`, by `textContent` and not `innerHTML`: a translated label is outside data
+    // like any other, and a consumer's dictionary can bring anything inside it.
     return b;
 }

package/dist-pkg/ui/panel-widgets.d.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PanelShellCtx } from './panel-shell.js';
+/**
+ * The control's SHAPE, not its tag — because the question a panel asks is "does this turn on and off?", not "is this a
+ * `<button>`?".
+ *
+ * 📏 The first three came from measuring the panels: `interruptor` (a switch) covers most of the controls they reach,
+ * `escolha` (a select) and `cursor` (a slider) the rest. A new shape enters when a panel demands it, not before.
+ */
+export type ControlShape = 'interruptor' | 'escolha' | 'cursor' | 'radio' | 'button';
+export interface ControlRowSpec {
+    /** The CONTROL's id — `opt-facil`, `cane-div`. It is how the `settings-*` finds it. */
+    readonly id: string;
+    /** The SHORT label, already translated. It goes in the `<strong>`, and it is the only thing in view on the row. */
+    readonly label: string;
+    /**
+     * The explanation, already translated. It goes into a SINGLE `.opt-hint`, which `fillExplain` moves to the footer.
+     *
+     * 📌 Absent = this row has no explanation, which is a legitimate answer. The footer then rests on the panel's text
+     * (`data-explain-idle`) while the cursor is on it.
+     */
+    readonly hint?: string;
+    /** The control's shape. Absent: `interruptor`, the most common case. */
+    readonly shape?: ControlShape;
+    /**
+     * The name a screen reader announces, when it is not the label.
+     *
+     * ⚠️ IT EXISTS BECAUSE A SWITCH'S TEXT IS ITS STATE, not its name: a `<button>` whose `textContent` says "Off"
+     * announces "Off, button" and the person does not know off WHAT. The `<strong>` beside it solves that for whoever SEES
+     * the whole row; for whoever navigates control by control, this attribute solves it. Absent, it falls back to
+     * `label` — which is the right answer, not a fallback.
+     */
+    readonly ariaLabel?: string;
+}
+export interface ControlRow {
+    /** The whole `.ctrl-row`. It is where ADR-0029's `markChanged` puts the left-the-default mark. */
+    readonly row: HTMLElement;
+    /** The control itself, with the requested id. */
+    readonly control: HTMLElement;
+}
+/**
+ * Builds a menu row: a short label, a hint that goes to the footer, and a control.
+ *
+ * The row is NOT inserted anywhere — whoever mounts it decides the order, which in this project's menus is part of the
+ * decision (ADR-0044 §2).
+ */
+export declare function controlRow(ctx: PanelShellCtx, spec: ControlRowSpec): ControlRow;
+/**
+ * REWRITES THE WORDS OF A ROW THAT ALREADY EXISTS — the counterpart of `ui/panel-shell.applyLabels`, one level down.
+ *
+ * 🔴 The inside of a panel is mounted once, and anything mounted at boot captures the fallback language's text:
+ * `initI18n` applies the fallback synchronously and REQUESTS the preferred one, which arrives later — a panel would serve
+ * its TITLE in one language and its ROWS in another, on the same screen.
+ *
+ * ⚠️ AND NO UNIT TEST CATCHES IT, because they all run in a single language.
+ *
+ * ⚠️ REWRITE AND NOT REBUILD, for the reason `applyLabels` already states: each `ui/settings-*` wires its controls'
+ * clicks ONCE, at boot. Remaking the row would leave a control in the document with no listener — a dead button that
+ * looks alive (ADR-0106 §5).
+ */
+export declare function labelRow(rowNode: HTMLElement, spec: ControlRowSpec): void;
+/**
+ * The header of a panel section: a title and a tag that qualifies it.
+ *
+ * 📏 It is in the kit because several panels wrote it by hand, with the `.panel-sub__tag` markup copied into each — the
+ * same reason as `controlRow`: a rule repeated across files is a rule that drifts.
+ *
+ * ⚠️ AND IT REFUSES TO EXIST OVER NOTHING, which is the behaviour that makes it worth a function. An "awaiting
+ * negotiation" heading with no row under it tells the reader something is there when nothing is, and the person looks
+ * for what the title promises. `rows` is the NUMBER of rows the section will have — passing it is what makes this rule
+ * exercisable by a case, instead of an `if` no fixed tree reaches.
+ *
+ * 📌 The title and tag arrive ALREADY TRANSLATED, as in `controlRow`: the kit does not decide language, it builds shape.
+ */
+export declare function sectionHeader(ctx: PanelShellCtx, title: string, tag: string, rows: number): HTMLElement | null;
+/**
+ * What a steps control needs: a name, the positions (already translated) and the current one.
+ *
+ * 🎯 THE DEV ASKED FOR IT, with an exact shape: the contrast boost «deve funcionar trocando entre desligado, linear,
+ * misto e quadrático da mesma forma que se troca o número de jogadores, isto é, apertando botões direita e esquerda, e
+ * não através de uma barra», and the rounded corners «também». A slider hides how many positions there are; a dropdown
+ * hides them all until it opens. Steps always say where you are.
+ *
+ * 🔴 AND THE SHAPE IS A SINGLE LINE: «◀ Rótulo: valor ▶» (ADR-0130 errata, rule 3) — the Dev: «Não faça essa coisa
+ * estranha. Escreva "< Rounded corner: off >"». It is the way to cycle between FEW positions — up to five; above that,
+ * a dropdown.
+ */
+export interface StepsSpec {
+    /** The control's spoken name — it goes to `aria-label`. */
+    readonly label: string;
+    /** The positions, in order, already translated. */
+    readonly values: readonly string[];
+    /** The index of the current position. */
+    readonly current: number;
+}
+/**
+ * The next step, CLAMPED at the ends — not a ring, and the difference is the decision.
+ *
+ * ⚠️ In a ring, right from the largest position would return to off: whoever adjusts looking for the maximum would pass
+ * it without warning and switch off what they wanted to raise. Clamped, the end is a wall you feel — the number of
+ * players, the model the Dev gave, does not wrap either.
+ */
+export declare function nextStep(from: number, total: number, delta: number): number;
+/**
+ * Builds the control: ONE focusable element (`role="spinbutton"`) with the two arrows inside.
+ *
+ * ⚠️ THE ARROWS ARE NOT BUTTONS, on purpose: menu navigation treats every `button` as an item, and three items for one
+ * adjustment would make the cursor stop twice on nameless arrows. Focus belongs to the control; the arrows are FINGER
+ * targets (`data-passo`), outside the accessibility tree — whoever listens gets the `aria-valuetext`.
+ *
+ * The control emits `passo` (`CustomEvent<number>`, -1 or +1): a tapped arrow emits it from here, and the keyboard's and
+ * controller's left and right emit it through `ui/menu-nav`. The user listens to a single event.
+ */
+export declare function mountSteps(ctx: PanelShellCtx, spec: StepsSpec): HTMLElement;
+/** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
+export declare function updateSteps(el: HTMLElement, spec: StepsSpec): void;

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

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Builds a menu row: a short label, a hint that goes to the footer, and a control.
+ *
+ * The row is NOT inserted anywhere — whoever mounts it decides the order, which in this project's menus is part of the
+ * decision (ADR-0044 §2).
+ */
+export function controlRow(ctx, spec) {
+    const rowNode = ctx.create('div');
+    rowNode.className = 'ctrl-row';
+    const text = ctx.create('span');
+    const shortLabel = ctx.create('strong');
+    shortLabel.textContent = spec.label;
+    text.appendChild(shortLabel);
+    if (spec.hint) {
+        // ⚠️ ONLY ONE, and it is what `fillExplain` looks for. Two `.opt-hint`s on one row would give the control two
+        // descriptions, and the footer would show the first — the other would stay on the row, exactly the defect rule §4
+        // exists to prevent.
+        const explanation = ctx.create('span');
+        explanation.className = 'opt-hint';
+        explanation.textContent = spec.hint;
+        text.appendChild(explanation);
+    }
+    rowNode.appendChild(text);
+    const control = buildControl(ctx, spec);
+    control.id = spec.id;
+    control.setAttribute('aria-label', spec.ariaLabel ?? spec.label);
+    rowNode.appendChild(control);
+    return { row: rowNode, control: control };
+}
+/**
+ * REWRITES THE WORDS OF A ROW THAT ALREADY EXISTS — the counterpart of `ui/panel-shell.applyLabels`, one level down.
+ *
+ * 🔴 The inside of a panel is mounted once, and anything mounted at boot captures the fallback language's text:
+ * `initI18n` applies the fallback synchronously and REQUESTS the preferred one, which arrives later — a panel would serve
+ * its TITLE in one language and its ROWS in another, on the same screen.
+ *
+ * ⚠️ AND NO UNIT TEST CATCHES IT, because they all run in a single language.
+ *
+ * ⚠️ REWRITE AND NOT REBUILD, for the reason `applyLabels` already states: each `ui/settings-*` wires its controls'
+ * clicks ONCE, at boot. Remaking the row would leave a control in the document with no listener — a dead button that
+ * looks alive (ADR-0106 §5).
+ */
+export function labelRow(rowNode, spec) {
+    const shortLabel = rowNode.querySelector('strong');
+    if (shortLabel)
+        shortLabel.textContent = spec.label;
+    const explanation = rowNode.querySelector('.opt-hint');
+    // ⚠️ A hint that DISAPPEARS has to be erased, not just left unwritten: on a retranslation into a dictionary without
+    // the key, the old text would survive and the footer would rest in the previous language.
+    if (explanation)
+        explanation.textContent = spec.hint ?? '';
+    // The control is found by COMPARING its id, not by building a selector from it: a selector needs the id escaped, escaping
+    // needs `CSS.escape`, and `CSS` is a browser global that THROWS where it does not exist — it took down a boot in a case's fake
+    // document once (2026-09-21). No selector, nothing to escape, no global (ADR-0221 step 7d).
+    const control = [...rowNode.querySelectorAll('[id]')].find((el) => el.id === spec.id);
+    if (control)
+        control.setAttribute('aria-label', spec.ariaLabel ?? spec.label);
+}
+function buildControl(ctx, spec) {
+    const controlShape = spec.shape ?? 'interruptor';
+    if (controlShape === 'escolha') {
+        const s = ctx.create('select');
+        s.className = 'vol';
+        return s;
+    }
+    if (controlShape === 'cursor') {
+        const i = ctx.create('input');
+        i.className = 'vol';
+        i.setAttribute('type', 'range');
+        // The volume slider's bounds, the same the audio panel reads: 0..100 in steps of 1, converted to the project's
+        // 0..1 volume by the panel.
+        i.setAttribute('min', '0');
+        i.setAttribute('max', '100');
+        i.setAttribute('step', '1');
+        return i;
+    }
+    if (controlShape === 'button') {
+        /*
+         * 🎯 THE ONE SHAPE THAT HOLDS NO VALUE: the others answer "which position am I in", this one DOES something.
+         * `ui/settings-controls` demands it — its button opens the capture of a key.
+         *
+         * 📌 No `aria-pressed` and no `role`: a button that acts already IS a button to whoever listens, and an announced
+         * state that does not exist is worse than no state. The panel puts the FACE on it — for remapping, the current
+         * keys —, because only the panel knows what the button shows.
+         */
+        const a = ctx.create('button');
+        a.className = 'mode-btn';
+        a.setAttribute('type', 'button');
+        return a;
+    }
+    if (controlShape === 'radio') {
+        /*
+         * 🔴 A CHOICE IS NOT A SWITCH, and the difference is what the ADR-0012 amendment says in so many words: «THE MENU IS
+         * A CHOICE, NOT A TOGGLE […] One font is active; the others are alternatives, not switches.» Hence three
+         * differences: no `switch` class (which draws a 52×28 px knob, the drawing of a state that does not exist),
+         * `role="radio"`, and `aria-checked` instead of `aria-pressed` — independent switches would announce on/off to
+         * choose ONE thing.
+         *
+         * 📌 `ui/settings-typo` demands it. The panel, not the kit, groups the `role="radio"`s in a `role="radiogroup"`,
+         * because the panel knows whether exclusivity covers a section or the whole menu.
+         */
+        const r = ctx.create('button');
+        r.className = 'mode-btn';
+        r.setAttribute('type', 'button');
+        r.setAttribute('role', 'radio');
+        r.setAttribute('aria-checked', 'false');
+        return r;
+    }
+    const b = ctx.create('button');
+    // `switch` is the class this project's CSS gives switches, and `aria-pressed` is what tells the state to whoever
+    // listens. The panel reflects the value; what is born here is the HONEST state of something that has read nothing
+    // yet: off.
+    b.className = 'mode-btn switch';
+    b.setAttribute('type', 'button');
+    b.setAttribute('aria-pressed', 'false');
+    return b;
+}
+/* ===================== THE SECTION HEADER — whose turn it is to act ===================== */
+/**
+ * The header of a panel section: a title and a tag that qualifies it.
+ *
+ * 📏 It is in the kit because several panels wrote it by hand, with the `.panel-sub__tag` markup copied into each — the
+ * same reason as `controlRow`: a rule repeated across files is a rule that drifts.
+ *
+ * ⚠️ AND IT REFUSES TO EXIST OVER NOTHING, which is the behaviour that makes it worth a function. An "awaiting
+ * negotiation" heading with no row under it tells the reader something is there when nothing is, and the person looks
+ * for what the title promises. `rows` is the NUMBER of rows the section will have — passing it is what makes this rule
+ * exercisable by a case, instead of an `if` no fixed tree reaches.
+ *
+ * 📌 The title and tag arrive ALREADY TRANSLATED, as in `controlRow`: the kit does not decide language, it builds shape.
+ */
+export function sectionHeader(ctx, title, tag, rows) {
+    if (rows === 0)
+        return null;
+    const h = ctx.create('h3');
+    h.className = 'panel-sub';
+    h.textContent = title + ' ';
+    const mark = ctx.create('span');
+    mark.className = 'panel-sub__tag';
+    mark.textContent = tag;
+    h.appendChild(mark);
+    return h;
+}
+/**
+ * The next step, CLAMPED at the ends — not a ring, and the difference is the decision.
+ *
+ * ⚠️ In a ring, right from the largest position would return to off: whoever adjusts looking for the maximum would pass
+ * it without warning and switch off what they wanted to raise. Clamped, the end is a wall you feel — the number of
+ * players, the model the Dev gave, does not wrap either.
+ */
+export function nextStep(from, total, delta) {
+    if (total <= 0)
+        return 0;
+    return Math.max(0, Math.min(total - 1, from + Math.sign(delta)));
+}
+/**
+ * Builds the control: ONE focusable element (`role="spinbutton"`) with the two arrows inside.
+ *
+ * ⚠️ THE ARROWS ARE NOT BUTTONS, on purpose: menu navigation treats every `button` as an item, and three items for one
+ * adjustment would make the cursor stop twice on nameless arrows. Focus belongs to the control; the arrows are FINGER
+ * targets (`data-passo`), outside the accessibility tree — whoever listens gets the `aria-valuetext`.
+ *
+ * The control emits `passo` (`CustomEvent<number>`, -1 or +1): a tapped arrow emits it from here, and the keyboard's and
+ * controller's left and right emit it through `ui/menu-nav`. The user listens to a single event.
+ */
+export function mountSteps(ctx, spec) {
+    const el = ctx.create('div');
+    el.className = 'passos';
+    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 value = ctx.create('span');
+    value.className = 'passo-valor';
+    el.appendChild(arrow(-1, '◀'));
+    el.appendChild(value);
+    el.appendChild(arrow(1, '▶'));
+    updateSteps(el, spec);
+    return el;
+}
+/** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
+export function updateSteps(el, spec) {
+    const lastIndex = Math.max(0, spec.values.length - 1);
+    const from = Math.max(0, Math.min(lastIndex, spec.current));
+    const text = spec.values[from] ?? '';
+    el.setAttribute('aria-label', spec.label);
+    el.setAttribute('aria-valuemin', '0');
+    el.setAttribute('aria-valuemax', String(lastIndex));
+    el.setAttribute('aria-valuenow', String(from));
+    el.setAttribute('aria-valuetext', text);
+    const value = el.querySelector('.passo-valor');
+    // THE LABEL GOES INTO THE TEXT: the whole row is the control, «◀ Cantos arredondados: pequeno ▶». Whoever listens gets
+    // the same in two parts — the name in `aria-label` and the position in `aria-valuetext` —, without the name repeated.
+    if (value)
+        value.textContent = spec.label ? `${spec.label}: ${text}` : text;
+    // The end that no longer moves is marked — otherwise a wall's arrow looks like a broken button.
+    el.querySelector('[data-passo="-1"]')?.classList.toggle('no-limite', from === 0);
+    el.querySelector('[data-passo="1"]')?.classList.toggle('no-limite', from === lastIndex);
+}

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

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** One row of the per-screen pause menu. `letra` marks the label that ABC/abc rewrites live. */
+export interface PauseBtnDef {
+    readonly act: string;
+    /**
+     * RAW label, used only when the button has a dynamic label (`dynamicLabel`/`level`).
+     *
+     * Optional because `pmBtnMarkup` resolves every ordinary button through `t('pause.' + act)`, so text here would
+     * never reach a screen — it would be raw text inside an ENGINE module, waiting for someone to trust it. No entry
+     * today sets a dynamic label; the `pause.*` key is the source, and it exists in all three languages.
+     */
+    readonly lbl?: string;
+    readonly dynamicLabel?: boolean;
+    readonly level?: 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[];
+/**
+ * THE THIRD LIST: what belongs to THIS game (ADR-0146, ADR-0145).
+ *
+ * ⚠️ IT STARTS WITH THE BACK ITEM AND NOTHING ELSE, and the emptiness is the decision: the engine does not know what a
+ * game has of its own — the game declares it. A list the engine filled in would be the wheelchair in chess again.
+ *
+ * 📌 And that is why the door drops by itself: `rootThatActs` drops a door whose room is empty, and with this list
+ * reduced to `pmback` that is exactly the case of a game that declares nothing.
+ */
+export declare const PM_GAME_BTNS: readonly PauseBtnDef[];
+/**
+ * THE INCLUSION SETTINGS SUBMENU — the panels, in the order the Dev dictated (ADR-0151).
+ *
+ * The way out comes FIRST here too, for the same reason `resume` comes first there: ADR-0044's rule is about menus,
+ * not about one menu. A submenu you cannot leave is the same trap, one level down.
+ */
+export declare const PM_OPTIONS_BTNS: readonly PauseBtnDef[];

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

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/pause-buttons — the items of the pause card the engine mounts: root, the game's options and the inclusion settings.
+//
+// Menu data for `ui/pause-icons`. They lived in `ui/activities-menu`, the platformer's title menu, which left the engine
+// (ADR-0174, issue #171); the card is the engine's, so its buttons stay.
+/** 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 const PM_BTNS = [
+    // ===================== THE ORDER IS THE DECISION (ADR-0044 §2) =====================
+    // A menu you cannot leave is a trap, and the trap costs most to whoever cannot see it. `resume` comes FIRST because
+    // that is what a pause is for. `quit` comes LAST because it is its least wanted outcome — and, since the list is a
+    // RING, one key UP from `resume` reaches it: far in reading order, near to the finger.
+    //
+    // The settings panels live in `PM_OPTIONS_BTNS`.
+    //
+    // 🔴 SIX (ADR-0151), and the number is MEASURED, not taste: at 640×360, the target screen, seven items fit exactly
+    // and more overflow, while the target ruler is already at its floor (ADR-0095: «tela menor mostra menos itens, não
+    // alvos menores»).
+    //
+    // 📌 The accessibility bar and the print view are reached through SELECT — «basta apertar SELECT que se tem a visão
+    // apropriada pra print», in the Dev's words. Their `act`s still exist and work for whoever passes a list of their own.
+    { act: 'resume' },
+    // Help — how to play comes SECOND: it is the first thing someone who paused without knowing how to play looks for.
+    { act: 'ajuda' },
+    // ⚠️ The `act` stays `addplayer` and the LABEL is the number of players (ADR-0147 §3): `ui/shell.ts` implements
+    // `pauseActs.addplayer`, and cases in `shell.browser.test.js` call it.
+    { act: 'addplayer' },
+    // Inclusion settings: what the child CARRIES between games (ADR-0146, named by ADR-0151).
+    { act: 'options' },
+    // Game options: what belongs to THIS game. The door drops by itself when the game declares nothing of its own.
+    { act: 'opcoesdojogo' },
+    { act: 'quit' },
+];
+/**
+ * THE THIRD LIST: what belongs to THIS game (ADR-0146, ADR-0145).
+ *
+ * ⚠️ IT STARTS WITH THE BACK ITEM AND NOTHING ELSE, and the emptiness is the decision: the engine does not know what a
+ * game has of its own — the game declares it. A list the engine filled in would be the wheelchair in chess again.
+ *
+ * 📌 And that is why the door drops by itself: `rootThatActs` drops a door whose room is empty, and with this list
+ * reduced to `pmback` that is exactly the case of a game that declares nothing.
+ */
+export const PM_GAME_BTNS = [
+    { act: 'pmback' },
+];
+/**
+ * THE INCLUSION SETTINGS SUBMENU — the panels, in the order the Dev dictated (ADR-0151).
+ *
+ * The way out comes FIRST here too, for the same reason `resume` comes first there: ADR-0044's rule is about menus,
+ * not about one menu. A submenu you cannot leave is the same trap, one level down.
+ */
+export const PM_OPTIONS_BTNS = [
+    // 📌 Not here, and each has somewhere to go (ADR-0151): letter case walks the communication cycle of the bar's
+    // eleventh button, and typography — «quem escolhe a tipografia é o jogo, o jogador escolhe suas fontes via o menu de
+    // acessibilidade rápida».
+    // 📏 AND THE NUMBER IS WHAT FITS at 640×360; the submenu has its own case in the 44 px gate, not only the root.
+    // ✅ The audio panel (music, ambience, interaction, earcons), separate from hearing accessibility, is listed because
+    // the panel it opens exists — a door to a panel that does not exist would be ADR-0106 §5's dead button.
+    { act: 'pmback' },
+    { act: 'empatia' },
+    { act: 'audio' },
+    { act: 'som' },
+    { act: 'motora' },
+    { act: 'visual' },
+    { act: 'anim' },
+];