@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/ui/aac-sets.d.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+export type AacTier = 
+/** CC BY-SA or ours: it may travel inside the game and works with no network at all. */
+'bundled'
+/** The licence allows use, not redistribution: the person downloads it, once, and it stays cached. */
+ | 'fetched'
+/** Permission is missing. It appears in the menu and is not selectable. */
+ | 'negotiating';
+export interface AacSet {
+    readonly key: string;
+    readonly name: string;
+    readonly tier: AacTier;
+    /** The licence as it was VERIFIED, or null when there is none yet. Short text, to fit on screen. */
+    readonly license: string | null;
+    /** Does it work IN THIS build? The pictograms are files that have not arrived yet. */
+    readonly available: boolean;
+    /** Pictograms only: one line about the origin, when it changes what the choice means. */
+    readonly note?: string;
+}
+export declare const AAC_SETS: readonly AacSet[];
+export declare const AAC_BY_KEY: Readonly<Record<string, AacSet>>;
+/** Which SETS the child can choose today: none. The menu does not pretend otherwise — the pictograms are thousands
+ *  of files that have not entered the repository, and four of the sets depend on negotiation. */
+export declare function aacAvailable(): AacSet[];
+/**
+ * Why this set is not available — an i18n key, never finished text.
+ *
+ * The two answers tell the reader different things, which is why there are two: "in preparation" means the licence
+ * is settled and the work is OURS; "awaiting negotiation" means the permission belongs to SOMEONE ELSE and no effort
+ * of ours brings it forward.
+ *
+ * And that is why the unavailable ones are shown instead of hidden: they are exactly the sets a Brazilian school is
+ * most likely to already use in another product. The educator who looks for PCS and does not find it concludes the
+ * game cannot do it — when the obstacle is a licence, not a capability. Hiding would answer the wrong question, and
+ * answer it wrongly.
+ */
+export declare function aacReason(s: AacSet): string | null;
+/** A label ready for the menu row: the name + the reason, when there is one. */
+export declare function aacLabel(t: Translate, s: AacSet): string;

package/dist-pkg/ui/aac-sets.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// LETTERS ARE NOT IN THIS LIST, and the absence is the Dev's decision: letter case is ONE switch (upper case, on or
+// off, with off meaning both cases), not two entries. A binary choice presented as two options makes the child compare
+// two rows to discover they are the same question; a switch asks once.
+//
+// What remains here is genuinely a LIST: the pictogram sets, of which one is chosen.
+export const AAC_SETS = [
+    // --- PICTOGRAMS that MAY travel with the game (CC BY-SA, verified by the Dev). ---
+    { key: 'mulberry', name: 'Mulberry Symbols', tier: 'bundled', license: 'CC BY-SA', available: false },
+    { key: 'blissymbolics', name: 'Blissymbolics', tier: 'bundled', license: 'CC BY-SA 4.0', available: false,
+        note: 'Escrita simbólica própria: os símbolos se combinam para formar sentidos novos.' },
+    { key: 'tawasol', name: 'Tawasol', tier: 'bundled', license: 'CC BY-SA 4.0', available: false,
+        note: 'Desenhado na e para a cultura árabe. Um pictograma não é neutro — a criança reconhece mais depressa os objetos, as roupas e os rostos do próprio mundo.' },
+    // --- PICTOGRAMS that must be DOWNLOADED. ---
+    { key: 'arasaac', name: 'ARASAAC', tier: 'fetched', license: 'baixado à parte', available: false },
+    // --- AWAITING NEGOTIATION. Visible on purpose: see `aacReason`. ---
+    { key: 'sclera', name: 'Sclera', tier: 'negotiating', license: null, available: false },
+    { key: 'pcs', name: 'PCS', tier: 'negotiating', license: null, available: false },
+    { key: 'symbolstix', name: 'SymbolStix', tier: 'negotiating', license: null, available: false },
+    { key: 'widgit', name: 'Widgit Symbols', tier: 'negotiating', license: null, available: false },
+];
+export const AAC_BY_KEY = Object.fromEntries(AAC_SETS.map((s) => [s.key, s]));
+/** Which SETS the child can choose today: none. The menu does not pretend otherwise — the pictograms are thousands
+ *  of files that have not entered the repository, and four of the sets depend on negotiation. */
+export function aacAvailable() {
+    return AAC_SETS.filter((s) => s.available);
+}
+/**
+ * Why this set is not available — an i18n key, never finished text.
+ *
+ * The two answers tell the reader different things, which is why there are two: "in preparation" means the licence
+ * is settled and the work is OURS; "awaiting negotiation" means the permission belongs to SOMEONE ELSE and no effort
+ * of ours brings it forward.
+ *
+ * And that is why the unavailable ones are shown instead of hidden: they are exactly the sets a Brazilian school is
+ * most likely to already use in another product. The educator who looks for PCS and does not find it concludes the
+ * game cannot do it — when the obstacle is a licence, not a capability. Hiding would answer the wrong question, and
+ * answer it wrongly.
+ */
+export function aacReason(s) {
+    if (s.available)
+        return null;
+    return s.tier === 'negotiating' ? 'aac.aguardandoNegociacao' : 'aac.emPreparo';
+}
+/** A label ready for the menu row: the name + the reason, when there is one. */
+export function aacLabel(t, s) {
+    const reason = aacReason(s);
+    return reason ? `${s.name} — ${t(reason)}` : s.name;
+}

package/dist-pkg/ui/audio-choices.d.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+/** `lbl` is an i18n key (a key missing from the dictionaries is shown as written). */
+export interface AudioCatDef {
+    k: string;
+    lbl: string;
+}
+export interface AudioCatState {
+    on: boolean;
+    vol: number;
+}
+/** The SOUND-NAVIGATION categories (cane/sonar/guard/guide) — their master volume is separate from the game's sound. */
+export declare const NAV_CATS: readonly ["sonar", "guard", "guide"];
+/** The game's GENERAL categories (TTS lives in the Voice section, outside this list). */
+export declare const GEN_CATS: readonly ["music", "ambient", "interact", "earcons"];
+/** 0..1 -> 0..100 rounded (slider display value). */
+export declare function volPercent(v: number): number;
+/** #navsound-master's value: the loudest of the nav categories, as a 0..100 slider value. */
+export declare function navMasterVolume(state: Readonly<Record<string, AudioCatState>>, navCats?: readonly string[]): number;
+/** Cane-hit spacing select -> validated int (garbage/empty -> 1, "one tap per block"). */
+export declare function parseCaneDiv(raw: string): number;
+/** srSay text for a cane-hit spacing choice. The two halves are ONE sentence per case, not a shared prefix
+ *  plus a tail: a language that renders this as "One tap per block (cane)" needs to move the word "cane". */
+export declare function caneDivMessage(t: Translate, div: number): string;
+/** #tts-engine's option catalog: (value, i18n KEY of the label). The engine NAMES are proper nouns and stay
+ *  put; what translates is the parenthetical that explains each one. Keys, not text — see input/devices. */
+export declare const TTS_ENGINE_OPTIONS: readonly (readonly [string, string])[];
+/**
+ * The engines THIS assembly can offer (ADR-0094): the neural one arrives through the game's Kokoro port (ADR-0198, ADR-0207), so
+ * without it Kokoro is not offered — a choice that cannot work leaves whoever picks it waiting for a download that never starts.
+ * `kitten`/`espeak` are not built and stay as they were.
+ */
+export declare function voiceEngineOptions(neuralAvailable: boolean): readonly (readonly [string, string])[];
+export interface VoiceLike {
+    name: string;
+    lang: string;
+}
+/**
+ * The system voices in the language asked for; with none of them, the whole list.
+ *
+ * It was called `pickPtVoices` and filtered a hard-coded `/^pt/i`, so a game in English offered a child a list of PORTUGUESE
+ * voices to read English text. The name told the truth about what it did and lied about what it should do.
+ *
+ * The comparison is by language PREFIX and not by the whole tag: a child playing in pt-BR should also be able to choose a
+ * pt-PT voice if that is the only one installed, and a school's browser rarely has the exact variant. The fallback to the
+ * whole list stays: an empty list would be worse than a list in the wrong language, which at least she can hear and reject.
+ */
+export declare function pickVoicesFor<T extends VoiceLike>(voices: readonly T[], lang: string): readonly T[];
+/** "<name> (<lang>)" option label. */
+export declare function voiceLabel(v: VoiceLike): string;
+/** Whether the browser can list/switch audio outputs at all (gates the #audio-sinks hint copy). */
+export declare function sinksSupported(hasEnumerateDevices: boolean, hasAudioContextCtor: boolean): boolean;
+export interface SinkDeviceLike {
+    deviceId: string;
+    label?: string;
+}
+/** A device's option label, falling back to a 1-based "Output N" when the browser withholds the real label
+ *  (no getUserMedia permission granted yet). */
+export declare function sinkOptionLabel(t: Translate, d: SinkDeviceLike, index: number): string;
+/** A player's current sink select value ('' = default/shared). */
+export declare function sinkSelectValue(p: {
+    audioSink?: string | null;
+} | undefined): string;

package/dist-pkg/ui/audio-choices.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/audio-choices — WHAT THE AUDIO PANELS OFFER, computed without a document (ADR-0221; issue #203).
+//
+// The sound categories and their volumes, the cane's tap spacing, the speech engines, the system voices and the audio
+// outputs: each one answered as a value or a string, with no `document`, no ctx and no state. `ui/settings-audio` keeps the
+// other half — finding the thirteen controls, wiring them and reflecting what the child chose.
+//
+// 🔴 AND THE SUITE HAD ALREADY MADE THIS CUT, which is what made it obvious. `tests/settings-audio.node.test.js` imported
+// exactly these fifteen names and nothing else, while `settings-audio.browser.test.js` drove the DOM half: the file was two
+// modules wearing one name, and the only place that said so was the test folder. 📏 The module it left was 568 lines and 112
+// decision nodes, the third largest in the engine.
+//
+// 📌 WHY IT IS `ui/` AND NOT `core/`: half of these resolve i18n KEYS (`t`) into the words a child reads, and a label is
+// interface. What is genuinely free of language — the category lists and the volume arithmetic — stays here beside the rest
+// rather than being split again for the sake of a layer.
+/** The SOUND-NAVIGATION categories (cane/sonar/guard/guide) — their master volume is separate from the game's sound. */
+export const NAV_CATS = ['sonar', 'guard', 'guide'];
+/** The game's GENERAL categories (TTS lives in the Voice section, outside this list). */
+// ⚠️ THEY BELONG TO THE «AUDIO» PANEL since ADR-0151, not to the hearing one: what is taste (music, ambience) does not live
+// beside what is accessibility (sonar, guard, guide). And `other` left — it controlled no sound at all.
+export const GEN_CATS = ['music', 'ambient', 'interact', 'earcons'];
+/** 0..1 -> 0..100 rounded (slider display value). */
+export function volPercent(v) {
+    return Math.round(v * 100);
+}
+/*
+ * 🔴 NO CATEGORY-ROW MARKUP HERE (note BV): the audio panel's category list is built as NODES (ADR-0129), in
+ * `ui/settings-audio.buildCatRow`, where the row is also RECONCILED instead of reborn. A markup builder with no consumer is
+ * published debt — it is deleted, not moved.
+ *
+ * 📌 And no alias is left: a re-export would keep alive a path nothing imports and make the surface snapshot lie, because
+ * it does not see re-exports (issue #204).
+ */
+/** #navsound-master's value: the loudest of the nav categories, as a 0..100 slider value. */
+export function navMasterVolume(state, navCats = NAV_CATS) {
+    return volPercent(Math.max(...navCats.map((k) => state[k].vol)));
+}
+/** Cane-hit spacing select -> validated int (garbage/empty -> 1, "one tap per block"). */
+export function parseCaneDiv(raw) {
+    return (+raw) || 1;
+}
+/** srSay text for a cane-hit spacing choice. The two halves are ONE sentence per case, not a shared prefix
+ *  plus a tail: a language that renders this as "One tap per block (cane)" needs to move the word "cane". */
+export function caneDivMessage(t, div) {
+    return t(div === 2 ? 'sr.audio.caneHalfBlock' : 'sr.audio.canePerBlock');
+}
+/** #tts-engine's option catalog: (value, i18n KEY of the label). The engine NAMES are proper nouns and stay
+ *  put; what translates is the parenthetical that explains each one. Keys, not text — see input/devices. */
+export const TTS_ENGINE_OPTIONS = [
+    ['webspeech', 'tts.engine.webspeech'],
+    ['kokoro', 'tts.engine.kokoro'],
+    ['kitten', 'tts.engine.kitten'],
+    ['espeak', 'tts.engine.espeak'],
+];
+/**
+ * The engines THIS assembly can offer (ADR-0094): the neural one arrives through the game's Kokoro port (ADR-0198, ADR-0207), so
+ * without it Kokoro is not offered — a choice that cannot work leaves whoever picks it waiting for a download that never starts.
+ * `kitten`/`espeak` are not built and stay as they were.
+ */
+export function voiceEngineOptions(neuralAvailable) {
+    return neuralAvailable ? TTS_ENGINE_OPTIONS : TTS_ENGINE_OPTIONS.filter(([v]) => v !== 'kokoro');
+}
+/**
+ * The system voices in the language asked for; with none of them, the whole list.
+ *
+ * It was called `pickPtVoices` and filtered a hard-coded `/^pt/i`, so a game in English offered a child a list of PORTUGUESE
+ * voices to read English text. The name told the truth about what it did and lied about what it should do.
+ *
+ * The comparison is by language PREFIX and not by the whole tag: a child playing in pt-BR should also be able to choose a
+ * pt-PT voice if that is the only one installed, and a school's browser rarely has the exact variant. The fallback to the
+ * whole list stays: an empty list would be worse than a list in the wrong language, which at least she can hear and reject.
+ */
+export function pickVoicesFor(voices, lang) {
+    const pref = lang.slice(0, 2).toLowerCase();
+    const sameTag = voices.filter((v) => v.lang.slice(0, 2).toLowerCase() === pref);
+    return sameTag.length ? sameTag : voices;
+}
+/** "<name> (<lang>)" option label. */
+export function voiceLabel(v) {
+    return v.name + ' (' + v.lang + ')';
+}
+/** Whether the browser can list/switch audio outputs at all (gates the #audio-sinks hint copy). */
+export function sinksSupported(hasEnumerateDevices, hasAudioContextCtor) {
+    return hasEnumerateDevices && hasAudioContextCtor;
+}
+/** A device's option label, falling back to a 1-based "Output N" when the browser withholds the real label
+ *  (no getUserMedia permission granted yet). */
+export function sinkOptionLabel(t, d, index) {
+    return d.label || t('audio.sinkFallback', { n: index + 1 });
+}
+/** A player's current sink select value ('' = default/shared). */
+export function sinkSelectValue(p) {
+    return (p && p.audioSink) || '';
+}

package/dist-pkg/ui/audio-rows-that-apply.d.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { AccommodationWord } from '../core/accommodations.js';
+export interface AudioRowsThatApplyCtx {
+    /** The host's DOM query — this module never reaches a global (ADR-0221 step 7d). */
+    readonly find: <T extends Element>(selector: string) => T | null;
+    /** The word this cartridge gives the cane row, or `null` when nobody walks in this game. */
+    readonly caneWord: () => AccommodationWord | null;
+    /** Does sound navigation have a subject here? A world AND a direction — read NOW, because a game changes between phases. */
+    readonly hasNavigationSound: () => boolean;
+}
+/** Offers the rows this cartridge has a subject for, and hides the rest. Safe to call at every open. */
+export declare function showOnlyRowsThatApply(ctx: AudioRowsThatApplyCtx): void;

package/dist-pkg/ui/audio-rows-that-apply.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/audio-rows-that-apply — A ROW WITH NO SUBJECT IS NOT OFFERED, AND THE ONE THAT APPLIES CARRIES THE GAME'S WORD
+// (ADR-0153; ADR-0106 §5; ADR-0113 clause 3; ADR-0145).
+//
+// Two rows of the hearing panel, and two different ways of knowing whether this cartridge has anything to say with them:
+//
+//   · THE CANE. The cartridge ANSWERS for it (`acomodacoes.caneSpacing`), because whether anybody walks in this game is
+//     not derivable from a contract — a board game and a platformer both have a world. When the answer is a word, the row
+//     carries the GAME's word and the GAME's explanation; when it is `false`, nobody walks and the row is not offered.
+//   · THE SOUND NAVIGATION. DERIVED and never asked (ADR-0153): the sonar needs a world AND a bearing, and `bearing`
+//     answers `none` on `hotspots`. In a list-of-points game the sonar, the edge guard and the guide were three sliders
+//     with no subject, and asking the cartridge again would let the two answers disagree.
+//
+// ⚠️ `hidden` ON THE ROW, and never the row out of the document, and the reason is measured: `initSettingsAudio` wires
+// `#cane-div` ONCE, at boot. A row that did not exist then and that a later `mount()` brought in would arrive with no
+// listener — a dead control with the look of a live one. `hidden` takes it out of the accessibility tree entirely, which
+// is the «not offered» of ADR-0113 clause 3, and leaves the listener alive for the cartridge that does have it.
+//
+// 📌 THE ANSWERS ARRIVE AS QUESTIONS AND NOT AS A CARTRIDGE, so this module has no opinion about where they come from and
+// a case can drive it without a root. It is also what keeps the derivation in the composition root, where the contract
+// lives: 📏 measured on 2026-09-23, this rule asks the subject set for ONE membership, and two of the three fields that
+// set is built from cannot change that answer — passing them here would be carrying weight that never does anything.
+/** Offers the rows this cartridge has a subject for, and hides the rest. Safe to call at every open. */
+export function showOnlyRowsThatApply(ctx) {
+    const row = ctx.find('#cane-div')?.closest('.ctrl-row');
+    const cane = ctx.caneWord();
+    if (row) {
+        row.hidden = cane === null;
+        // 🔴 WHAT APPLIES CARRIES THE GAME'S WORD (ADR-0153's confirmation), and BOTH halves of it. `mountAudioInside`
+        // re-labels in the engine's own words at every open and this runs after it, so the game's label wins the `<strong>`
+        // and the game's explanation wins the `.opt-hint` the footer reads. ⚠️ An absent hint keeps the engine's sentence:
+        // «this game has nothing to add» is not «this row has nothing to say».
+        const label = row.querySelector('strong');
+        if (cane && label)
+            label.textContent = cane.label;
+        const hint = row.querySelector('.opt-hint');
+        if (cane?.hint && hint)
+            hint.textContent = cane.hint;
+    }
+    const navigation = ctx.find('#navsound-list');
+    if (navigation)
+        navigation.hidden = !ctx.hasNavigationSound();
+}

package/dist-pkg/ui/camera-control.d.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { CameraControl } from '../core/camera-cycle.js';
+import type { SwitchableControl } from './switchable-control.js';
+export declare function followCameraMode(mode: CameraControl, controls: {
+    readonly [M in Exclude<CameraControl, 'off'>]: SwitchableControl;
+}): void;

package/dist-pkg/ui/camera-control.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/camera-control — THE 📷 POSITION TO THE THREE CAMERA CONTROLS (ADR-0215; issue #199).
+//
+// One stored position (`core/state.cameraControl`): off · hands · face · eyes. Each control starts only at its own position, so one camera
+// mode at a time holds by construction (ADR-0197). The ones turning off are told first, so a camera is let go before the next mode asks.
+export function followCameraMode(mode, controls) {
+    const all = Object.entries(controls);
+    for (const [m, c] of all)
+        if (m !== mode)
+            void c.apply(false);
+    for (const [m, c] of all)
+        if (m === mode)
+            void c.apply(true);
+}

package/dist-pkg/ui/changed-mark.d.ts

@@ -1,15 +1,16 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
 export declare const CHANGED_CLASS = "is-changed";
 /**
- * Marca (ou desmarca) UM controle. Idempotente por construção: limpa e só então aplica. Os painéis chamam
- * isto de dentro do mesmo `reflect*` que já redesenha o controle, então ele roda muitas vezes seguidas.
+ * Marks (or unmarks) ONE control. Idempotent by construction: clears and only then applies. The panels call this from
+ * inside the same `reflect*` that already redraws the control, so it runs many times in a row.
  */
-export declare function markChanged(el: HTMLElement | null, changed: boolean): void;
+export declare function markChanged(t: Translate, el: HTMLElement | null, changed: boolean): void;
 /**
- * Sobe a marca um nível: o botão que ABRE o menu fica marcado enquanto qualquer opção dentro dele estiver.
- * Sem isso a trilha começaria dentro do menu, e achar o menu certo continuaria custando abrir os sete.
+ * Raises the mark one level: the button that OPENS the menu stays marked while any option inside it is. Without this
+ * the trail would start inside the menu, and finding the right menu would still cost opening every one.
  *
- * `changes` é uma lista de booleanos e não de elementos porque quem sabe comparar com o padrão é o painel;
- * este módulo não deve ter opinião sobre o que é padrão — há uma fonte só, e é o DEFAULTS do ADR-0028.
+ * `changes` is a list of booleans and not of elements because the panel is the one that knows how to compare with the
+ * default; this module must have no opinion on what the default is — there is one source, ADR-0028's DEFAULTS.
  */
-export declare function markMenuChanged(opener: HTMLElement | null, changes: readonly boolean[]): void;
+export declare function markMenuChanged(t: Translate, opener: HTMLElement | null, changes: readonly boolean[]): void;

package/dist-pkg/ui/changed-mark.js

@@ -1,56 +1,25 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/changed-mark.ts — MARCA O QUE SAIU DO PADRÃO (ADR-0029). Módulo-folha: só DOM e i18n, nenhuma dep de
-// estado. Quem sabe o que é padrão é cada painel, que já leu DEFAULTS (ADR-0028); aqui mora só o COMO marcar.
-//
-// O problema que ele resolve: o reset por menu do ADR-0028 só serve a quem sabe que há algo para desfazer.
-// Sete menus, ~40 controles, e o que a criança mexeu tem exatamente a mesma aparência do que ela não mexeu.
-// Os menus não estavam mal rotulados — estavam IMPESQUISÁVEIS.
-//
-// TRÊS CANAIS, e nenhum é enfeite. O ADR-0029 explica por quê; em resumo: a moldura branca sozinha não serve
-// a quem não distingue cores, some no alto contraste (onde `--ink-soft` JÁ é branco) e não existe para quem
-// não enxerga. Então:
-//
-//   1. COR   — `--changed` na moldura (CSS; troca sozinha no alto contraste).
-//   2. FORMA — anel interno, uma moldura dupla. Sobrevive a escala de cinza e a qualquer paleta, porque é uma
-//              CONTAGEM DE ANÉIS e não uma matiz.
-//   3. NOME  — o nome acessível do controle ganha um sufixo. É o canal que faz mais trabalho pelo menor preço:
-//              a criança cega PERCORRE o menu e OUVE, em ordem, o que saiu do padrão.
-//
-// O canal 3 tem dois caminhos porque os painéis constroem o nome de duas formas, e um `aria-label` vence o
-// conteúdo do botão. Marcar só um deles deixaria metade dos controles mudos — em silêncio, que é o pior jeito
-// de uma marca de acessibilidade falhar, porque nada na tela denuncia a falta.
-//
-// O sufixo NUNCA toca o `textContent`. A primeira versão pendurava um `<span class="sr-only">` dentro do
-// botão, e um teste que aferia o rótulo visível caiu — mostrando o problema real: os painéis reescrevem
-// `textContent` inteiro a cada reflect, então o sufixo vivia à mercê da ordem das chamadas. Agora o caminho
-// sem `aria-label` CRIA um, a partir do conteúdo, e o desmarcar simplesmente o remove.
-//
-// E a idempotência é ESTRUTURAL, não caso a caso: toda chamada primeiro devolve o controle ao estado
-// original — tirando qualquer rastro nosso, dos dois caminhos — e só então aplica. Uma marca que só soubesse
-// acrescentar acabaria em tudo, e uma marca em tudo não é marca.
-import { t } from '../core/i18n.js';
 export const CHANGED_CLASS = 'is-changed';
-/** Guarda o `aria-label` ORIGINAL quando ele é do painel, para devolvê-lo sem adivinhar por texto. */
+/** Keeps the ORIGINAL `aria-label` when it is the panel's, to give it back without guessing from text. */
 const BASE_ATTR = 'markBase';
-/** Marca que o `aria-label` foi criado por NÓS: desmarcar tira o atributo inteiro em vez de restaurar algo. */
+/** Marks that the `aria-label` was created by US: unmarking removes the whole attribute instead of restoring one. */
 const OWNED_ATTR = 'markOwnsLabel';
 /**
- * O nó cujo NOME acessível recebe o sufixo: o PRIMEIRO controle da linha em ordem de documento, ou a própria
- * linha quando ela não tem controle dentro.
+ * The node whose accessible NAME gets the suffix: the row's FIRST control in document order, or the row itself when it
+ * has no control inside.
  *
- * "O primeiro" é decisão, não acaso — e ela apareceu ao verificar no jogo. Uma linha do mixer tem DOIS
- * controles: o volume e o liga/desliga. O sufixo foi para o volume, que vem antes no markup, e isso está
- * certo por dois motivos: é o controle que a criança alcança primeiro ao tabular, então ela ouve "alterado"
- * ANTES de decidir se para nesta linha; e repetir o sufixo nos dois faria o leitor de tela dizer a mesma
- * coisa duas vezes ao atravessar uma linha só, que é ruído com cara de informação.
+ * "The first" is a decision, not chance. A mixer row has TWO controls: the volume and the on/off. The suffix goes on the
+ * volume, which comes first in the markup, for two reasons: it is the control the child reaches first when tabbing, so
+ * they hear the mark BEFORE deciding whether to stop on this row; and repeating the suffix on both would make the
+ * screen reader say the same thing twice across one row, which is noise dressed as information.
  *
- * O que isto deixa frágil, e por isso está preso por teste: reordenar o markup move o sufixo de controle sem
- * quebrar nada visível.
+ * What this leaves fragile, and why a test holds it: reordering the markup moves the suffix to another control without
+ * breaking anything visible.
  */
 function namedNode(el) {
     return el.querySelector('button, select, input, [role="button"]') ?? el;
 }
-/** Devolve o controle ao estado original, venha o rótulo do painel ou de nós. Base de toda chamada. */
+/** Returns the control to its original state, whether the label came from the panel or from us. The base of every call. */
 function clearMark(node) {
     if (node.dataset[OWNED_ATTR] !== undefined) {
         node.removeAttribute('aria-label');
@@ -62,10 +31,10 @@ function clearMark(node) {
     }
 }
 /**
- * Marca (ou desmarca) UM controle. Idempotente por construção: limpa e só então aplica. Os painéis chamam
- * isto de dentro do mesmo `reflect*` que já redesenha o controle, então ele roda muitas vezes seguidas.
+ * Marks (or unmarks) ONE control. Idempotent by construction: clears and only then applies. The panels call this from
+ * inside the same `reflect*` that already redraws the control, so it runs many times in a row.
  */
-export function markChanged(el, changed) {
+export function markChanged(t, el, changed) {
     if (!el)
         return;
     el.classList.toggle(CHANGED_CLASS, changed);
@@ -76,21 +45,21 @@ export function markChanged(el, changed) {
     const suffix = t('a11y.changed');
     const label = node.getAttribute('aria-label');
     if (label !== null) {
-        node.dataset[BASE_ATTR] = label; // rótulo do painel: guardamos e devolvemos depois
+        node.dataset[BASE_ATTR] = label; // the panel's label: keep it and give it back later
         node.setAttribute('aria-label', label + ', ' + suffix);
     }
     else {
-        node.dataset[OWNED_ATTR] = '1'; // rótulo vinha do conteúdo: criamos um e o assumimos
+        node.dataset[OWNED_ATTR] = '1'; // the label came from the content: create one and own it
         node.setAttribute('aria-label', (node.textContent ?? '').trim() + ', ' + suffix);
     }
 }
 /**
- * Sobe a marca um nível: o botão que ABRE o menu fica marcado enquanto qualquer opção dentro dele estiver.
- * Sem isso a trilha começaria dentro do menu, e achar o menu certo continuaria custando abrir os sete.
+ * Raises the mark one level: the button that OPENS the menu stays marked while any option inside it is. Without this
+ * the trail would start inside the menu, and finding the right menu would still cost opening every one.
  *
- * `changes` é uma lista de booleanos e não de elementos porque quem sabe comparar com o padrão é o painel;
- * este módulo não deve ter opinião sobre o que é padrão — há uma fonte só, e é o DEFAULTS do ADR-0028.
+ * `changes` is a list of booleans and not of elements because the panel is the one that knows how to compare with the
+ * default; this module must have no opinion on what the default is — there is one source, ADR-0028's DEFAULTS.
  */
-export function markMenuChanged(opener, changes) {
-    markChanged(opener, changes.some(Boolean));
+export function markMenuChanged(t, opener, changes) {
+    markChanged(t, opener, changes.some(Boolean));
 }

package/dist-pkg/ui/control-choices.d.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import { type Action } from '../core/actions.js';
+import type { KeyScheme } from '../core/entity.js';
+/**
+ * Physical key code → short readable label.
+ *
+ * `Space` is the only one with a word to translate; the arrows are glyphs and the rest are the bare letter or
+ * digit, identical in every language.
+ *
+ * ⚠️ A TABLE AND A LADDER, and not a chain of replacements, which leaks the MACHINE's name whenever a prefix is not
+ * foreseen (`Digit1`, `Numpad5`). What is not recognised still passes through untouched on purpose: `Comma` is ugly
+ * and honest, and inventing a name for it would be guessing.
+ */
+export declare function keyName(t: Translate, 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. Built over a Map (code →
+ * owner index) so a scheme with many bound keys does not cost a full re-scan per lookup.
+ */
+export declare function keyUsedByOther(code: string, mapRef: KeyScheme, schemes: readonly KeyScheme[]): number;
+/**
+ * Which OTHER action OF THE SAME scheme already has `code` — or `null` if none.
+ *
+ * ⚠️ THE SIBLING `keyUsedByOther` NEEDS, AND ITS ABSENCE IS INVISIBLE IN A ONE-PLAYER GAME (#126). That function
+ * excludes the scheme being edited **by reference**; with a single player, `schemesFor()` returns exactly that
+ * scheme, so its guard scans an empty list and **can never fire**. A child who puts `W` on a new action would keep
+ * `W` on the old one too, and play the whole game with both firing together.
+ *
+ * ⚠️ AND THAT IS THE WORST SHAPE A DEFECT CAN TAKE, as the `input/default-bindings` header says: the two actions fire
+ * together, and the child sees an intermittent double action nobody can reproduce on purpose — on a screen they
+ * opened **because** they could not use the default controls.
+ *
+ * Returns the ACTION and not a boolean, because the announcement has to say which one — saying only that the key is
+ * in use sends the child looking for what the function already knows.
+ */
+export declare function actionAlreadyBound(code: string, mapRef: KeyScheme, except: Action): Action | null;

package/dist-pkg/ui/control-choices.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { ACTIONS } from '../core/actions.js';
+/**
+ * THE FOUR ARROWS, one per direction.
+ *
+ * 🔴 The Dev asked for exactly these: «Por que está escrevendo "↔Up", "↔Down" etc ao invés de simplesmente "↑",
+ * "↓", "←" e "→"? Não escolha poluir a UI.» A chain of `replace` calls over the physical code is a hidden table, and a
+ * hidden table writes what nobody chose — so the table is written out.
+ *
+ * 📌 And there is nothing to translate here: an arrow is the same in pt, en and es, which is exactly why it is a
+ * glyph and not a word. The child who remaps sees the key they have in hand.
+ */
+const GLYPH = {
+    ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→',
+};
+/**
+ * Physical key code → short readable label.
+ *
+ * `Space` is the only one with a word to translate; the arrows are glyphs and the rest are the bare letter or
+ * digit, identical in every language.
+ *
+ * ⚠️ A TABLE AND A LADDER, and not a chain of replacements, which leaks the MACHINE's name whenever a prefix is not
+ * foreseen (`Digit1`, `Numpad5`). What is not recognised still passes through untouched on purpose: `Comma` is ugly
+ * and honest, and inventing a name for it would be guessing.
+ */
+export function keyName(t, code) {
+    const c = String(code);
+    if (GLYPH[c])
+        return GLYPH[c];
+    if (c === 'Space')
+        return t('key.space');
+    if (c.startsWith('Shift'))
+        return 'Shift';
+    if (c.startsWith('Key'))
+        return c.slice(3);
+    if (c.startsWith('Digit'))
+        return c.slice(5);
+    // «Num 5», «Num Add»: the numeric keypad is a different PHYSICAL place, and saying only «5» would make two
+    // distinct keys show the same label in the same list.
+    if (c.startsWith('Numpad'))
+        return `Num ${c.slice(6)}`;
+    return c;
+}
+/**
+ * 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. Built over a Map (code →
+ * owner index) so a scheme with many bound keys does not cost a full re-scan per lookup.
+ */
+export function keyUsedByOther(code, mapRef, schemes) {
+    const owners = new Map();
+    schemes.forEach((m, i) => {
+        if (m === mapRef)
+            return;
+        for (const a of ACTIONS)
+            for (const c of m[a] || [])
+                if (!owners.has(c))
+                    owners.set(c, i);
+    });
+    return owners.get(code) ?? -1;
+}
+/**
+ * Which OTHER action OF THE SAME scheme already has `code` — or `null` if none.
+ *
+ * ⚠️ THE SIBLING `keyUsedByOther` NEEDS, AND ITS ABSENCE IS INVISIBLE IN A ONE-PLAYER GAME (#126). That function
+ * excludes the scheme being edited **by reference**; with a single player, `schemesFor()` returns exactly that
+ * scheme, so its guard scans an empty list and **can never fire**. A child who puts `W` on a new action would keep
+ * `W` on the old one too, and play the whole game with both firing together.
+ *
+ * ⚠️ AND THAT IS THE WORST SHAPE A DEFECT CAN TAKE, as the `input/default-bindings` header says: the two actions fire
+ * together, and the child sees an intermittent double action nobody can reproduce on purpose — on a screen they
+ * opened **because** they could not use the default controls.
+ *
+ * Returns the ACTION and not a boolean, because the announcement has to say which one — saying only that the key is
+ * in use sends the child looking for what the function already knows.
+ */
+export function actionAlreadyBound(code, mapRef, except) {
+    for (const a of ACTIONS) {
+        if (a === except)
+            continue;
+        if ((mapRef[a] || []).includes(code))
+            return a;
+    }
+    return null;
+}