@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+export type AacTier = 
+/** A licence is RECORDED in `license`: the set may be chosen. */
+'licensed'
+/** No licence: the set appears in the menu, locked, with the reason. */
+ | 'unlicensed';
+interface AacSetBase {
+    readonly key: string;
+    readonly name: string;
+    /** Pictograms only: one line about the origin, when it changes what the choice means. */
+    readonly note?: string;
+}
+/**
+ * A pictogram set. The tier and the licence travel together BY TYPE: a licensed set names its licence (short text, to
+ * fit on screen), and an unlicensed one has none to name.
+ */
+export type AacSet = (AacSetBase & {
+    readonly tier: 'licensed';
+    readonly license: string;
+}) | (AacSetBase & {
+    readonly tier: 'unlicensed';
+    readonly license: null;
+});
+export declare const AAC_SETS: readonly AacSet[];
+export declare const AAC_BY_KEY: Readonly<Record<string, AacSet>>;
+/** Can the child choose this set? Only when it is licensed — the tier is the one fact the menu reads. */
+export declare function aacSelectable(s: AacSet): boolean;
+/** Which SETS the child can choose today: none, because no licence has been obtained (ADR-0233). */
+export declare function aacAvailable(): AacSet[];
+/**
+ * Is the AAC menu's DOOR disabled? Yes while no set is licensed (ADR-0233 erratum): the menu exists for pictogram
+ * exercises and a pictogram keyboard, and with no set it has nothing to offer. The door then says only that the menu is
+ * disabled (`pause.motivo.caa`) — never the licence reason. Letter case does not wait for it: it lives in the quick bar's
+ * communication cycle (ADR-0151).
+ */
+export declare function aacMenuLocked(): boolean;
+/**
+ * Why this set cannot be chosen — an i18n key, never finished text. One answer, because there is one reason: no
+ * licence. A selectable set has nothing to explain.
+ */
+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;
+export {};

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

@@ -0,0 +1,41 @@
+// 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. «PCS» is the Picture Communication
+// Symbols set (ADR-0233 reads the Dev's «PECS» as PCS: PECS is a teaching method, not a symbol set).
+export const AAC_SETS = [
+    { key: 'arasaac', name: 'ARASAAC', tier: 'unlicensed', license: null },
+    { key: 'pcs', name: 'PCS', tier: 'unlicensed', license: null },
+];
+export const AAC_BY_KEY = Object.fromEntries(AAC_SETS.map((s) => [s.key, s]));
+/** Can the child choose this set? Only when it is licensed — the tier is the one fact the menu reads. */
+export function aacSelectable(s) {
+    return s.tier === 'licensed';
+}
+/** Which SETS the child can choose today: none, because no licence has been obtained (ADR-0233). */
+export function aacAvailable() {
+    return AAC_SETS.filter(aacSelectable);
+}
+/**
+ * Is the AAC menu's DOOR disabled? Yes while no set is licensed (ADR-0233 erratum): the menu exists for pictogram
+ * exercises and a pictogram keyboard, and with no set it has nothing to offer. The door then says only that the menu is
+ * disabled (`pause.motivo.caa`) — never the licence reason. Letter case does not wait for it: it lives in the quick bar's
+ * communication cycle (ADR-0151).
+ */
+export function aacMenuLocked() {
+    return aacAvailable().length === 0;
+}
+/**
+ * Why this set cannot be chosen — an i18n key, never finished text. One answer, because there is one reason: no
+ * licence. A selectable set has nothing to explain.
+ */
+export function aacReason(s) {
+    return aacSelectable(s) ? null : 'aac.noLicence';
+}
+/** 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,68 @@
+// 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 — their master volume is separate from the game's sound. Only the sonar since `guard` and
+ * `guide` left (ADR-0258): the engine plays nothing in them since the guide moved to the platformer.
+ */
+export declare const NAV_CATS: readonly ["sonar"];
+/** 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, and ONLY those (ADR-0185): with none of them, none — the list then says there is
+ * no voice, and the speech rows lock.
+ *
+ * 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. 🔴 There is no fallback
+ * to the whole list: a voice of another language reads the text with the wrong phonetics, and ADR-0243 §3 decided that a wrong
+ * voice is worse than none — silence is noticed, a wrong accent is learned.
+ */
+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,98 @@
+// 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 — their master volume is separate from the game's sound. Only the sonar since `guard` and
+ * `guide` left (ADR-0258): the engine plays nothing in them since the guide moved to the platformer.
+ */
+export const NAV_CATS = ['sonar'];
+/** 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 (the sonar). 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 published path nothing imports — surface with no consumer
+ * (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, and ONLY those (ADR-0185): with none of them, none — the list then says there is
+ * no voice, and the speech rows lock.
+ *
+ * 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. 🔴 There is no fallback
+ * to the whole list: a voice of another language reads the text with the wrong phonetics, and ADR-0243 §3 decided that a wrong
+ * voice is worse than none — silence is noticed, a wrong accent is learned.
+ */
+export function pickVoicesFor(voices, lang) {
+    const pref = lang.slice(0, 2).toLowerCase();
+    return voices.filter((v) => v.lang.slice(0, 2).toLowerCase() === pref);
+}
+/** "<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,53 @@
+// 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;
+/** Why a camera mode did not start: its files are not on the device, its runtime did not load, or the camera did not open. */
+export type CameraStartFailure = 'files' | 'runtime' | 'camera';
+/** How one camera mode names itself when it cannot start. */
+export interface CameraWords {
+    /** Its name in `problems`: «gesture control». */
+    readonly subject: string;
+    /** What the child loses, after «the child cannot»: «play with gestures». */
+    readonly loses: string;
+    /**
+     * What the child hears for each failure, in the page's language at the moment it happens. Each is the mode's own `t('…')`
+     * with a literal key, so `tests/no-key-reaches-the-child-unresolved` still reads it — a key built here would not be checked.
+     */
+    readonly spoken: {
+        readonly [K in CameraStartFailure]: () => string;
+    };
+}
+export interface CameraStartDeps<T extends {
+    close(): void;
+}, F> {
+    /** The reader's loader (`platform/vision`), already given the page and the checked cache. */
+    readonly load: () => Promise<{
+        readonly ok: true;
+        readonly tracker: T;
+    } | {
+        readonly ok: false;
+        readonly missing: readonly string[];
+    }>;
+    readonly openFeed: () => Promise<F>;
+    /** Nothing started: the control says it, writes it once, and puts the 📷 back to off — if it is still wanted. */
+    readonly failed: (kind: CameraStartFailure, line: string, spoken: string) => void;
+}
+/**
+ * THE READER, THEN THE CAMERA — or the reason neither is running, said through `failed`; `null` when nothing started.
+ *
+ * 🔴 A LOADER THAT REJECTS IS A FAILURE LIKE ANY OTHER (ADR-0169). `platform/vision` answers the files it cannot find, but a
+ * runtime that cannot be IMPORTED (a server that sends `.mjs` as `text/plain`, an address that answers 404) or a vision task
+ * that cannot be built on the GPU nor on the CPU rejects instead, and the three controls awaited it with nothing around it: the
+ * rejection went up through `apply` into `followCameraMode`'s `void` and died unhandled, with the 📷 lit, nothing said and
+ * nothing in `problems` — measured in a real page on 2026-09-25. The 👄 had met the same defect on 2026-09-21
+ * (`ui/voice-control`); this is the one place the three camera modes now start through, so a fourth cannot miss it.
+ */
+export declare function startCameraReader<T extends {
+    close(): void;
+}, F>(words: CameraWords, d: CameraStartDeps<T, F>): Promise<{
+    tracker: T;
+    feed: F;
+} | null>;

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

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/camera-control — THE 📷 POSITION TO THE THREE CAMERA CONTROLS (ADR-0215; issue #199), AND HOW EACH ONE STARTS.
+//
+// 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);
+}
+/**
+ * THE READER, THEN THE CAMERA — or the reason neither is running, said through `failed`; `null` when nothing started.
+ *
+ * 🔴 A LOADER THAT REJECTS IS A FAILURE LIKE ANY OTHER (ADR-0169). `platform/vision` answers the files it cannot find, but a
+ * runtime that cannot be IMPORTED (a server that sends `.mjs` as `text/plain`, an address that answers 404) or a vision task
+ * that cannot be built on the GPU nor on the CPU rejects instead, and the three controls awaited it with nothing around it: the
+ * rejection went up through `apply` into `followCameraMode`'s `void` and died unhandled, with the 📷 lit, nothing said and
+ * nothing in `problems` — measured in a real page on 2026-09-25. The 👄 had met the same defect on 2026-09-21
+ * (`ui/voice-control`); this is the one place the three camera modes now start through, so a fourth cannot miss it.
+ */
+export async function startCameraReader(words, d) {
+    const { subject, loses, spoken } = words;
+    let load;
+    try {
+        load = await d.load();
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        d.failed('runtime', `${subject}: the vision runtime did not load (${why}) — the child cannot ${loses}; check that the delivery carries the vision files and that the server serves .mjs files with the MIME type text/javascript`, spoken.runtime());
+        return null;
+    }
+    if (!load.ok) {
+        d.failed('files', `${subject}: ${load.missing.join(', ')} not on this device — the child cannot ${loses}; open the game once online so the install fetches them`, spoken.files());
+        return null;
+    }
+    try {
+        return { tracker: load.tracker, feed: await d.openFeed() };
+    }
+    catch {
+        load.tracker.close();
+        d.failed('camera', `${subject}: the camera did not open — the child cannot ${loses}; allow the camera for this page, or plug one in`, spoken.camera());
+        return null;
+    }
+}

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;