@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/settings-controls.d.ts

@@ -1,17 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 import type { DomQuery } from '../core/dom-query.js';
 import type { KeyScheme } from '../core/entity.js';
 import { type Action } from '../core/actions.js';
 import type { KBDefaults } from '../input/keyboard.js';
 import type { KeydownEventLike } from '../input/keydown.js';
-/** Minimal DOM-selector shape (matches ui/dom.ts's `$`). */
-export type { DomQuery } from '../core/dom-query.js';
-/** action -> list of physical key codes (KeyboardEvent.code), e.g. {jump:['KeyJ','Space']}. */
-export type { KeyScheme } from '../core/entity.js';
 /** Opaque keyboard config (input/keyboard.ts's KBDefaults shape: {solo,p2,p3,p4}) — never indexed directly here;
  *  all per-player reads go through the injected `kbFor`, so this module stays decoupled from its exact shape. */
-/** O `KBDefaults` de `input/keyboard`, que é o dono. Este módulo continua NÃO INDEXANDO o valor — toda
- *  leitura por jogador passa pelo `kbFor` injetado —, e é essa disciplina que o desacopla, não um tipo largo. */
+/** `input/keyboard`'s `KBDefaults`, which is the owner. This module still does NOT INDEX the value — every per-player
+ *  read goes through the injected `kbFor` —, and that discipline is what decouples it, not a wide type. */
 export type KeyboardConfig = KBDefaults;
 /** Minimal persistence shape this module needs (input/keyboard.ts's saveKB/resetKB — no direct localStorage). */
 export interface ControlsStore {
@@ -19,19 +16,19 @@ export interface ControlsStore {
     resetKB(): KeyboardConfig;
 }
 export interface SettingsControlsCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
     /** DOM selector (querySelector), injected — never reaches `document` globally. */
     $: DomQuery;
     /**
-     * AS POSIÇÕES QUE ESTE JOGO USA, cada uma com a palavra dele, no idioma vigente.
+     * THE POSITIONS THIS GAME USES, each with its own word, in the current language.
      *
-     * ⚠️ É a fronteira do corte de 2026-09-06. A tela de remapeamento mostrava as OITO linhas de uma tabela
-     * deste ficheiro — quer dizer, a engine decidia que todo jogo tem exatamente pular, correr, trocar e
-     * especial. Um quiz mostraria quatro linhas para ações que não existem nele, e uma criança tentaria
-     * remapear um botão que não faz nada.
+     * ⚠️ The engine does not decide which positions a game has: a table here would give every game the same rows, and a
+     * quiz would show rows for actions that do not exist in it — a child would try to remap a button that does nothing.
      */
-    acoesDoJogo: () => readonly {
-        readonly acao: Action;
-        readonly rotulo: string;
+    gameActions: () => readonly {
+        readonly action: Action;
+        readonly label: string;
     }[];
     /** Screen-reader "polite" announcement (core/a11y-sr's srSay), injected. */
     srSay: (msg: string) => void;
@@ -39,122 +36,82 @@ export interface SettingsControlsCtx {
     srAlert: (msg: string) => void;
     /** Persistence (input/keyboard.ts's saveKB/resetKB), injected. */
     store: ControlsStore;
-    /** The live keyboard config object (game.js's `KB`). Mutated in place by successful remaps. */
+    /** The live keyboard config object. Mutated in place by successful remaps. */
     kb: KeyboardConfig;
-    /** Replaces game.js's `KB` binding wholesale — only used by "restaurar padrões" (reset reassigns, doesn't mutate). */
+    /** Replaces the host's keyboard config wholesale — only used by the reset (reset reassigns, doesn't mutate). */
     setKB: (kb: KeyboardConfig) => void;
-    /** Shared helper (game.js): the scheme for a given player index, given `kb`/numPlayers. Not owned by this panel —
-     *  other systems (gamepad binding, HUD) call the same game.js function. */
+    /** Shared helper (the host's): the scheme for a given player index, given `kb`/numPlayers. Not owned by this panel —
+     *  other systems (gamepad binding, HUD) call the same function. */
     kbFor: (playerIndex: number) => KeyScheme;
     /**
-     * O esquema DE FÁBRICA deste assento (ADR-0029) — o que ele teria se ninguém tivesse remapeado nada.
+     * This seat's FACTORY scheme (ADR-0029) — what it would have if nobody had remapped anything.
      *
-     * ⚠️ INJECTADO PELA MESMA RAZÃO QUE O `kbFor` LOGO ACIMA: o mapeamento «quantos jogadores → que balde»
-     * (`solo`/`p2`/`p3`/`p4`) é do consumidor, e uma segunda cópia dessa regra dentro da engine divergiria da
-     * primeira no dia em que um dos dois mudasse.
+     * ⚠️ INJECTED FOR THE SAME REASON AS `kbFor` JUST ABOVE: the "how many players → which bucket" mapping
+     * (`solo`/`p2`/`p3`/`p4`) is the consumer's, and a second copy of that rule inside the engine would drift from the
+     * first the day one of them changed.
      *
-     * 🎯 E NÃO SE OBTÉM CHAMANDO `store.resetKB()`, embora ele devolva exactamente a configuração de fábrica:
-     * o `input/keyboard.resetKB` faz `store.remove(CKEY)` ANTES de devolver a cópia. Usá-lo como leitor
-     * apagaria o remapeamento da criança a cada render, e o estrago só apareceria no arranque seguinte.
+     * 🎯 AND IT IS NOT OBTAINED BY CALLING `store.resetKB()`, although it returns exactly the factory configuration:
+     * `input/keyboard.resetKB` does `store.remove(CKEY)` BEFORE returning the copy. Using it as a reader would erase the
+     * child's remapping on every render, and the damage would only show at the next boot.
      */
-    kbPadraoFor: (playerIndex: number) => KeyScheme;
-    /** Shared: current player count (core/state.ts's numPlayers, read live via game.js). */
+    defaultSchemeFor: (playerIndex: number) => KeyScheme;
+    /** Shared: current player count, read live from the host. */
     getNumPlayers: () => number;
-    /** Shared: propagates `kb` -> the live control aliases (game.js's applyControls). Called after remap/reset. */
+    /** Shared: propagates `kb` -> the live control aliases (the host's applyControls). Called after remap/reset. */
     applyControls: () => void;
-    /** Shared: propagates `kb` -> each player's `p.ctrl` (game.js's assignControls). Called after remap/reset. */
+    /** Shared: propagates `kb` -> each player's `p.ctrl` (the host's assignControls). Called after remap/reset. */
     assignControls: () => void;
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
      *
-     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
-     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
-     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
-     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
-     * uma vez noutros painéis.
+     * ⚠️ This panel REBUILDS its rows, and the new rows come back with the prose inside — so without this call the
+     * explanation appears twice, in the footer and under the label, from the first click. `CLAUDE.md` §4 records exactly
+     * this (issue #109).
      *
-     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
-     * consumidor): sem casca não há rodapé para duplicar.
+     * Optional in the signature because a consumer can mount the panel without the shell (a test): without the shell
+     * there is no footer to duplicate.
      */
     fillExplain?: (card: HTMLElement | null) => void;
 }
 export interface SettingsControlsApi {
     /** Re-renders #ctrl-list for the given player index and (re)wires its "Alterar" buttons. Idempotent. */
     render: (selPlayer: number) => void;
-    /** True while a key capture is in progress (game.js's menuNavKey gates menu navigation on this). */
+    /** True while a key capture is in progress (menu navigation gates on this). */
     isCapturing: () => boolean;
     /** Cancels any in-progress capture without re-rendering (dialog is closing anyway). */
     cancelCapture: () => void;
     /**
      * Feeds a keydown to the in-progress capture, if any. Returns true when the event was consumed (capture was
-     * active — Escape/conflict/success all consume it) so game.js's own keydown handler can early-return exactly
-     * like the old inline `if(captureAction){...}` block did. Returns false (no-op) when nothing is being captured.
+     * active — Escape/conflict/success all consume it) so the caller's keydown handler can return early. Returns false
+     * (no-op) when nothing is being captured.
      */
-    /** `KeydownEventLike` de `input/keydown`, que é quem escuta o teclado e portanto é dono da forma do
-     *  evento nesta engine. Este manipulador lê só `e.code` e chama `preventDefault()` — um subconjunto —,
-     *  mas pedir o `KeyboardEvent` inteiro obrigava o despacho a entregar mais do que tem (ADR-0039). */
+    /** `KeydownEventLike` from `input/keydown`, which listens to the keyboard and so owns the event's shape in this
+     *  engine. This handler reads only `e.code` and calls `preventDefault()` — a subset —, and asking for the whole
+     *  `KeyboardEvent` would force the dispatch to deliver more than it has (ADR-0039). */
     handleCaptureKeydown: (e: KeydownEventLike) => boolean;
 }
 /**
- * As oito posições do jogo de plataforma, ligadas às chaves de i18n das palavras DELE.
+ * The platformer's eight positions, tied to the i18n keys of ITS words.
  *
- * ⚠️ ELA TEM CONSUMIDOR, e eu já disse aqui que não tinha. A afirmação anterior — «sem um único consumidor,
- * nem aqui nem no `game-platformer`» — vinha de uma varredura com um padrão que **excluía o `main.ts`** do
- * cartucho, por ele estar directamente em `app/js/` e o glob exigir um subdirectório. Medido de novo com
- * `git grep`: `game-platformer/app/js/main.ts` importa-a e usa-a na TELA DE AJUDA do menu de pausa (a linha
- * que lista posição ↔ tecla). O `openHelp()` que o cabeçalho original citava não morreu — mudou de
- * repositório com o cartucho (#111) e continua a ler daqui.
+ * ⚠️ DECLARED DEBT: the words of ONE game inside an engine module. Nothing in `app/js` reads it — the engine's help
+ * panel (`ui/help-panel`) and this remap panel ask the game for its words through `gameActions()`, because the engine
+ * knows a position exists and only the game knows what it is called (ADR-0086). It stays published only for a consumer
+ * that has not migrated; removing it is a change to published surface.
  *
- * ⚠️ E ELA CONTINUA A SER A CAUSA DA #125, o que é diferente de estar morta. O defeito era o `aria-label` da
- * tela de remapeamento ser montado a partir dela: oito posições contra as catorze do vocabulário, e as
- * palavras de UM jogo dentro do motor. Esse uso saiu. O que resta é um consumidor para quem a tabela está
- * certa — porque ele É o jogo de plataforma.
- *
- * ⚠️ REMOVÊ-LA NÃO É LIMPEZA, É MIGRAÇÃO. O cartucho já tem `acoesDoJogo()` (`main.ts:122`), derivado do
- * preset dele; a tela de ajuda passar a usá-lo é edição de lá, e só depois disso é que isto pode sair daqui.
- * Enquanto não sair, quem escrever código NOVO na engine pede a palavra ao jogo por `ctx.acoesDoJogo()` — a
- * engine sabe que a posição existe, só o jogo sabe como ela se chama (ADR-0086).
- *
- * Guarda CHAVES e não texto porque uma `const` de módulo é avaliada uma vez no import, e o `dict` do
- * `core/i18n` é um `let` que o `setLocale` reatribui — texto capturado aqui congelaria o idioma no boot.
+ * It holds KEYS and not text because a module `const` is evaluated once, on import, and `core/i18n`'s dictionary is
+ * reassigned by `setLocale` — text captured here would freeze the language at boot.
  */
 export declare const ACT_LABEL: Record<string, string>;
+/** The id of a position's button. It comes from the action's ABSTRACT name, unique by construction (`core/actions`). */
+export declare const ctrlControlId: (action: string) => string;
 /**
- * ⚠️ A TABELA ACIMA E DÍVIDA DECLARADA, e o cabeçalho dela ficou desatualizado no dia em que o corte
- * aconteceu: ela ainda diz quais são as palavras DESTE jogo — `act.run`, `act.jump` — dentro de um módulo de
- * engine. Continua exportada porque `openHelp()` (a tela de ajuda do menu de pausa) ainda a lê, e mover as
- * duas coisas no mesmo commit misturaria dois assuntos.
- *
- * O que MUDOU é quem manda: a lista de linhas e as palavras vêm agora de `ctx.acoesDoJogo()`, e esta tabela é
- * só o que sobra para o consumidor que ainda não migrou. Quando `openHelp` perguntar ao jogo, ela sai.
- */
-/** Physical key code -> short readable label. Only 'Space' has a word to translate; the rest are glyphs and
- *  bare letters, identical in every language (that is why this is a chain of replaces and not a table). */
-export declare function keyName(code: string): string;
-/**
- * Which OTHER player already owns `code`, among `schemes` (one entry per player, same order as player index) —
- * or -1 if free. `mapRef` (the scheme currently being edited) is excluded by reference, mirroring the original
- * `keyUsedByOther(code, mapRef)` closing over `kbFor`/numPlayers in game.js. Built over a Map (code -> owner
- * index) so a scheme with many bound keys doesn't cost a full re-scan per lookup.
- */
-export declare function keyUsedByOther(code: string, mapRef: KeyScheme, schemes: readonly KeyScheme[]): number;
-/**
- * Qual OUTRA ação DO MESMO esquema já tem `code` — ou `null` se nenhuma.
- *
- * ⚠️ O IRMÃO QUE FALTAVA AO `keyUsedByOther`, E A FALTA ERA INVISÍVEL NUM JOGO DE UM JOGADOR (#126). Aquele
- * exclui o esquema em edição **por referência**; com um jogador só, `schemesFor()` devolve exatamente esse
- * esquema, então a guarda varre uma lista vazia e **nunca pode disparar**. A criança que põe `W` numa ação
- * nova continua com `W` na antiga, e passa o jogo inteiro com as duas a disparar juntas.
- *
- * ⚠️ E O DEFEITO É O PIOR FEITIO POSSÍVEL, escrito no cabeçalho do `input/default-bindings` desde sempre:
- * «as duas ações disparam juntas, e a criança vê uma ação dupla intermitente que ninguém consegue reproduzir
- * de propósito». Numa tela que ela abriu **porque** não conseguia usar os controles padrão.
+ * THE BUTTON'S FACE: the current keys, one `<kbd>` each.
  *
- * ⚠️ A guarda entre JOGADORES não estava partida — estava inalcançável. Medido na auditoria: com dois
- * assentos ela funciona e recusa certo. O que faltava era a verificação dentro do mesmo esquema.
+ * ⚠️ With no key the button would have an empty face — a 44 px target with nothing to say —, so the change word comes
+ * back, which is where it still means something: there is no key to show, there is one to set.
  *
- * Devolve a AÇÃO e não um booleano, porque o anúncio tem de dizer qual — «essa tecla já está em uso» manda a
- * criança procurar o que a função já sabe.
+ * 📌 Through the DOM API and not a string: `keyName` returns a code's READABLE name, which may be translated tomorrow —
+ * translated text interpolated into markup is the door issue #106 closed.
  */
-export declare function acaoQueJaTem(code: string, mapRef: KeyScheme, exceto: Action): Action | null;
+export declare function drawKeys(t: Translate, button: HTMLElement, codes: readonly string[]): void;
 export declare function initSettingsControls(ctx: SettingsControlsCtx): SettingsControlsApi;