@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/core/a11y-sr.d.ts

@@ -1,4 +1,26 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-export declare function setVlibrasSay(fn: (text: string) => void): void;
-export declare const srSay: (t: string) => void;
-export declare const srAlert: (t: string) => void;
+/** What an announcer writes through: the document holding the two regions, and the host's next frame. */
+export interface AnnouncerPorts {
+    /** The document whose `#sr-status` and `#sr-alert` are written. A document without them announces nothing, silently. */
+    readonly doc: Pick<Document, 'querySelector'>;
+    /**
+     * The host's `requestAnimationFrame`, AS THE HOST HAS IT: the clear-then-write dance needs one frame between. REQUIRED, and
+     * `undefined` is an answer — a host with no frames (a test double): the announcer then writes at once,
+     * which is the only honest thing left to do. The absence is answered HERE so that no composition root grows a branch for it
+     * (ADR-0221: the root carries wiring, not decisions).
+     */
+    readonly raf: ((cb: FrameRequestCallback) => number) | undefined;
+}
+/** One root's announcer. */
+export interface Announcer {
+    /** "Polite" announcement (status): does not interrupt what the reader is saying. */
+    readonly say: (text: string) => void;
+    /** "Assertive" announcement (alert): interrupts and speaks now (errors, important warnings). */
+    readonly alert: (text: string) => void;
+    /**
+     * Sends every announcement of THIS announcer also to `sink` (the Libras interpreter's `say`), until the returned release
+     * is called. One sink at a time: a second call replaces the first, and releasing a replaced sink changes nothing.
+     */
+    readonly mirrorTo: (sink: (text: string) => void) => () => void;
+}
+export declare function createAnnouncer({ doc, raf }: AnnouncerPorts): Announcer;

package/dist-pkg/core/a11y-sr.js

@@ -1,20 +1,41 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// core/a11y-sr.ts — anúncios para LEITOR DE TELA (Estágio 4, Tier 1). srSay = região aria-live "polite" (status);
-// srAlert = região "assertive" (alertas). O padrão limpar→requestAnimationFrame→escrever força o leitor a
-// reanunciar mesmo texto repetido. Também espelha a fala em LIBRAS: como ui/vlibras ainda não foi extraído, o
-// vlibrasSay entra por INJEÇÃO (setVlibrasSay) — no-op até o game.js registrá-lo no boot (evita inverter a ordem
-// do Tier 1). Depende só de ui/dom ($). As regiões #sr-status/#sr-alert vivem no index.html.
-import { $ } from '../ui/dom.js';
-let _vlibrasSay = () => { };
-// Registra a fala em Libras (chamado no boot do game.js, quando vlibrasSay existe). Ver ui/vlibras (futuro).
-export function setVlibrasSay(fn) { _vlibrasSay = fn; }
-// Anúncio "polite" (status): não interrompe o que o leitor está falando.
-export const srSay = (t) => { const el = $('#sr-status'); if (el) {
-    el.textContent = '';
-    requestAnimationFrame(() => { el.textContent = t; });
-} _vlibrasSay(t); };
-// Anúncio "assertive" (alerta): interrompe e fala já (erros/avisos importantes).
-export const srAlert = (t) => { const el = $('#sr-alert'); if (el) {
-    el.textContent = '';
-    requestAnimationFrame(() => { el.textContent = t; });
-} _vlibrasSay(t); };
+// core/a11y-sr.ts — announcements for the SCREEN READER. `say` = the "polite" aria-live region (`#sr-status`);
+// `alert` = the "assertive" region (`#sr-alert`). Clear → next frame → write forces the reader to announce the same text
+// again when it repeats.
+//
+// 🔴 A FACTORY (ADR-0232 D4, issue #207): the announcer used to be two module functions over the GLOBAL document, the
+// global `requestAnimationFrame` and a module-level Libras mirror a host registered — so a root building in another
+// document (an iframe, an editor beside the game) announced into the page's regions, and two roots shared one mirror.
+// Now each root builds its own over the document and the frames its host lends. The factory stays PUBLISHED for a game
+// that must announce with no root at all — its boot failed before `createGame` returned (game-chess's rootless alert).
+//
+// THE LIBRAS MIRROR IS AN EXPLICIT SINK OF EACH ANNOUNCER, and nothing connects it by default. Today a game that wants
+// its announcements signed connects it (`Engine.mirrorAnnouncements(engine.libras.say)`); the games that do not, do not
+// sign — the behaviour before this factory, kept on purpose until the Dev decides (D4 decision DD1). Having the root
+// mirror everything is the one line `announcer.mirrorTo(libras.say)` in the root. The sink arrives by injection so this
+// core module never imports ui/ (ADR-0173).
+const NO_MIRROR = () => { };
+export function createAnnouncer({ doc, raf }) {
+    const nextFrame = (cb) => { if (raf)
+        raf(() => { cb(); });
+    else
+        cb(); };
+    let mirror = NO_MIRROR;
+    const write = (region, text) => {
+        const el = doc.querySelector(region);
+        if (el) {
+            el.textContent = '';
+            nextFrame(() => { el.textContent = text; });
+        }
+        mirror(text);
+    };
+    return {
+        say: (text) => { write('#sr-status', text); },
+        alert: (text) => { write('#sr-alert', text); },
+        mirrorTo: (sink) => {
+            mirror = sink;
+            return () => { if (mirror === sink)
+                mirror = NO_MIRROR; };
+        },
+    };
+}

package/dist-pkg/core/accessible-label.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** The minimal slice of `Element` this module reads. Structural, so a node test needs no real DOM. */
+export interface LabelledElement {
+    getAttribute(name: string): string | null;
+    textContent: string | null;
+}
+/**
+ * The control's name: `aria-label` when there is one, the visible text when not.
+ *
+ * THE ORDER IS THE DECISION, and it is not arbitrary: `aria-label` is what the accessibility platform is ALREADY going
+ * to announce. Narrating something else adds no information — it creates a second version of the same item, and whoever
+ * hears both has no way to know which is true.
+ *
+ * The visible text comes in when no label is declared, which is most buttons: there the two sources agree by
+ * construction.
+ */
+export declare function accessibleLabel(el: LabelledElement | null | undefined): string;

package/dist-pkg/core/accessible-label.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/accessible-label — WHAT A CONTROL IS CALLED, and one answer for whoever sees and whoever listens.
+//
+// ========================= THE DEFECT THIS CLOSES =========================
+// MEASURED in the built game, with the cursor on the menu's number-of-players button:
+//
+//     the game narrated:        "◀ Number of players: 1 ▶, 1 of 4"
+//     the screen reader said:   "Number of players: 1. Click on the left for fewer, on the right for more."
+//
+// Two different sentences for the SAME item at the same instant. A child using a screen reader AND the game's
+// narration hears the item twice, two ways — and the game's version reads the `◀` and `▶` glyphs, the very noise
+// item 4 of ADR-0044 took out of the pause legend. The rule already existed for the bar's icons (hovering or focusing
+// says the SAME truth a screen reader would announce); here it becomes one function every menu calls.
+//
+// ========================= WHY A LEAF MODULE =========================
+// Its consumers sit in different modules of `ui/`, and `ui/menu-nav` already reaches `ui/pause-icons` — putting the rule
+// in one of them would close a cycle or make someone import from where it should not. The lesson of `core/ring`: a
+// cycle in ESM does not blow up at once, it blows up at boot in the TDZ, once, in production.
+//
+// No dependencies, no I/O, no global `document`: it takes the element and returns text.
+/** Markup whitespace becomes ONE space; the ends go. */
+const tidy = (s) => (s || '').replace(/\s+/g, ' ').trim();
+/**
+ * The control's name: `aria-label` when there is one, the visible text when not.
+ *
+ * THE ORDER IS THE DECISION, and it is not arbitrary: `aria-label` is what the accessibility platform is ALREADY going
+ * to announce. Narrating something else adds no information — it creates a second version of the same item, and whoever
+ * hears both has no way to know which is true.
+ *
+ * The visible text comes in when no label is declared, which is most buttons: there the two sources agree by
+ * construction.
+ */
+export function accessibleLabel(el) {
+    if (!el)
+        return '';
+    return tidy(el.getAttribute('aria-label')) || tidy(el.textContent);
+}

package/dist-pkg/core/accommodation-subjects.d.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { GameDeclaration } from './contract.js';
+import type { Action } from './actions.js';
+import { CONTRACT_KEYED } from './accommodations.js';
+export type ContractKeyedAccommodation = (typeof CONTRACT_KEYED)[number];
+/** What the derivation reads — and only that. */
+export interface SubjectInputs {
+    readonly declaration: Pick<GameDeclaration, 'tick' | 'holdsKeys' | 'needsPointer' | 'world' | 'topology'>;
+    /** The positions this game's preset names (`presetActions`). Empty = the game is not played by actions. */
+    readonly actions: readonly Action[];
+    /** How many seats (`players().length` — a game that declares none has one child playing). */
+    readonly players: number;
+}
+/**
+ * The contract-keyed accommodations with a subject in this game, NOW.
+ *
+ * The rules, each one the study's key (`docs/1-Discovery/study-accommodations-by-genre.md` §0.1) read off the contract:
+ *   · `gameSpeed` ← time runs on its own (`tick === 'clock'`) — WCAG 2.2.1, GAG Basic «adjust the game speed»
+ *   · `moveLatch`, `holdLatch` ← the game holds keys
+ *   · `virtualPad`, `oneButton`, `inputCooldown`, `macros` ← the game is played by actions
+ *   · `pointerSmoothing`, `pointerSensitivity`, `pointerStyle` ← the game needs a continuous pointer
+ *   · `visionSimulation`, `audioDescription` ← there is a world (`world: none` refuses empathy and sonar, contract §8)
+ *   · `blindMode`, `navigationSound` ← a world AND a direction: `bearing` answers `none` on `hotspots`
+ *   · `perPlayerAudioOutput` ← more than one seat
+ */
+export declare function contractSubjects(i: SubjectInputs): ReadonlySet<ContractKeyedAccommodation>;

package/dist-pkg/core/accommodation-subjects.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { CONTRACT_KEYED } from './accommodations.js';
+/**
+ * The contract-keyed accommodations with a subject in this game, NOW.
+ *
+ * The rules, each one the study's key (`docs/1-Discovery/study-accommodations-by-genre.md` §0.1) read off the contract:
+ *   · `gameSpeed` ← time runs on its own (`tick === 'clock'`) — WCAG 2.2.1, GAG Basic «adjust the game speed»
+ *   · `moveLatch`, `holdLatch` ← the game holds keys
+ *   · `virtualPad`, `oneButton`, `inputCooldown`, `macros` ← the game is played by actions
+ *   · `pointerSmoothing`, `pointerSensitivity`, `pointerStyle` ← the game needs a continuous pointer
+ *   · `visionSimulation`, `audioDescription` ← there is a world (`world: none` refuses empathy and sonar, contract §8)
+ *   · `blindMode`, `navigationSound` ← a world AND a direction: `bearing` answers `none` on `hotspots`
+ *   · `perPlayerAudioOutput` ← more than one seat
+ */
+export function contractSubjects(i) {
+    const d = i.declaration;
+    const hasWorld = d.world().kind === 'element';
+    const hasDirection = hasWorld && d.topology().kind !== 'hotspots';
+    const byActions = i.actions.length > 0;
+    const pointer = d.needsPointer?.() === true;
+    const holds = d.holdsKeys();
+    const rule = {
+        gameSpeed: d.tick === 'clock',
+        moveLatch: holds, holdLatch: holds,
+        virtualPad: byActions, oneButton: byActions, inputCooldown: byActions, macros: byActions,
+        pointerSmoothing: pointer, pointerSensitivity: pointer, pointerStyle: pointer,
+        visionSimulation: hasWorld, audioDescription: hasWorld,
+        blindMode: hasDirection, navigationSound: hasDirection,
+        perPlayerAudioOutput: i.players > 1,
+    };
+    return new Set(CONTRACT_KEYED.filter((k) => rule[k]));
+}

package/dist-pkg/core/accommodations.d.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Every accommodation the engine knows by name. None of these ids is a word a child reads. */
+export declare const ACCOMMODATIONS: readonly ["typography", "letterCase", "narration", "spokenMenuIndex", "signLanguage", "soundMix", "hearingLossSimulation", "highContrast", "colorVisionCorrection", "reducedSceneMotion", "remapControls", "targetSize", "controlsHelp", "objectiveReminder", "repeatInstruction", "soundCaptions", "screenReader", "monoAudio", "interfaceScale", "interfaceLayout", "difficulty", "skipSection", "settingsProfiles", "visionSimulation", "audioDescription", "virtualPad", "oneButton", "inputCooldown", "macros", "gameSpeed", "blindMode", "navigationSound", "moveLatch", "holdLatch", "pointerSmoothing", "pointerSensitivity", "pointerStyle", "perPlayerAudioOutput", "cameraSway", "easyMode", "wheelchairMode", "detectionLeniency", "intensity", "hints", "reducedCharacterMotion", "caneSpacing", "textPace", "lexicalDifficulty", "wordHighlight", "pieceSets", "distinguishableSuits", "timingWindow", "aimAssist", "repeatedInput", "ownerColors", "contrastOutlines"];
+export type Accommodation = (typeof ACCOMMODATIONS)[number];
+/**
+ * Subject in EVERY game: there is text, sound, a screen, a menu and a way to confirm in all of them.
+ *
+ * 📌 `difficulty`, `skipSection` and `objectiveReminder` are here although the engine cannot make a game
+ * easier: what it can do is keep, persist and announce the choice, and the game reads it. The GAG asks for
+ * difficulty at Basic level, and «wide choice of difficulty levels» has a subject in any game with a goal.
+ */
+export declare const GENERAL: readonly ["typography", "letterCase", "narration", "spokenMenuIndex", "signLanguage", "soundMix", "hearingLossSimulation", "highContrast", "colorVisionCorrection", "reducedSceneMotion", "remapControls", "targetSize", "controlsHelp", "objectiveReminder", "repeatInstruction", "soundCaptions", "screenReader", "monoAudio", "interfaceScale", "interfaceLayout", "difficulty", "skipSection", "settingsProfiles"];
+/**
+ * Subject answered by something the contract ALREADY asks, so the engine can derive it with no genre:
+ *
+ *   · `gameSpeed` ← `tick === 'clock'` (WCAG 2.2.1; the GAG's Basic «adjust the game speed»)
+ *   · `moveLatch`, `holdLatch` ← `holdsKeys()` and the positions the preset declares
+ *   · `virtualPad`, `oneButton`, `inputCooldown`, `macros` ← action input (`needsPointer()` false)
+ *   · `pointerSmoothing`, `pointerSensitivity`, `pointerStyle` ← `needsPointer()` true
+ *   · `visionSimulation`, `audioDescription` ← `world().kind === 'element'`
+ *   · `blindMode`, `navigationSound` ← a world AND a direction: `bearing` is `none` on `hotspots`
+ *   · `perPlayerAudioOutput` ← more than one entry in `CreateGameOptions.players`
+ */
+export declare const CONTRACT_KEYED: readonly ["visionSimulation", "audioDescription", "virtualPad", "oneButton", "inputCooldown", "macros", "gameSpeed", "blindMode", "navigationSound", "moveLatch", "holdLatch", "pointerSmoothing", "pointerSensitivity", "pointerStyle", "perPlayerAudioOutput"];
+/**
+ * Subject nothing in the engine can answer: the game declares it.
+ *
+ * ⚠️ `easyMode` and `wheelchairMode` are PLATFORM vocabulary — lower gravity, coins on the ground, no jump —
+ * and that is why they sit here and not in GENERAL: in a chess game they are switches with no subject, the
+ * exact defect ADR-0145 was written about.
+ */
+export declare const GAME_KEYED: readonly ["cameraSway", "easyMode", "wheelchairMode", "detectionLeniency", "intensity", "hints", "reducedCharacterMotion", "caneSpacing", "textPace", "lexicalDifficulty", "wordHighlight", "pieceSets", "distinguishableSuits", "timingWindow", "aimAssist", "repeatedInput", "ownerColors", "contrastOutlines"];
+/** What the child reads and hears for an accommodation: the name, and the sentence that explains it. */
+export interface AccommodationWord {
+    /** «Wheelchair mode», «Board pieces». NEVER `wheelchairMode` — an id that reaches a person is a defect. */
+    readonly label: string;
+    /** The SHORT form, for where the long one does not fit. Falls back to `label` when absent. */
+    readonly short?: string;
+    /** Optional: what this setting does, in one sentence — the footer text of the menu row (`CLAUDE.md` §4). */
+    readonly hint?: string;
+}
+/**
+ * One game's vocabulary: for each accommodation it names, its word.
+ *
+ * ⚠️ PARTIAL ON PURPOSE, as `ActionPreset` is. Requiring all entries would make a quiz invent a word for a
+ * wheelchair it has no concept of, and an invented word ends up in a menu in front of a child.
+ *
+ * 📌 A game's OWN accommodation — one the catalogue does not contain (ADR-0145 §2) — is not declared here: a
+ * closed record cannot hold it, and that is what keeps an id typo from passing as an addition. The addition
+ * has its own place in the declaration (phase 2c).
+ */
+export type AccommodationPreset = Partial<Readonly<Record<Accommodation, AccommodationWord>>>;
+/** Is it a known accommodation? Boundary guard for data that came from outside (a saved setting, a game). */
+export declare function isAccommodation(x: unknown): x is Accommodation;
+/** The accommodations this preset names, in the canonical order of `ACCOMMODATIONS`. */
+export declare function presetAccommodations(p: AccommodationPreset): Accommodation[];
+/**
+ * The question the engine asks a game when it must SHOW an accommodation: «what is this called here?».
+ *
+ * ⚠️ Returns `null` for an entry the game does not name, never the id — the `labellerFrom` rule. Whoever calls
+ * decides; for a GAME_KEYED entry the answer is not to mount the row, because a game that has no word for it
+ * has no subject for it either.
+ */
+export declare function accommodationLabellerFrom(p: AccommodationPreset): (a: Accommodation) => string | null;
+/**
+ * Is a preset well formed? Returns the problems — EMPTY means conformant.
+ *
+ * ⚠️ AN ABSENT PRESET IS NOT A PROBLEM, and that is the difference from `presetProblems`. A game with no
+ * action cannot be played; a game that names no accommodation still gets every GENERAL one in the engine's
+ * words. What IS a problem is the silent kind: a blank label (a row with no name for a screen reader) and an
+ * unknown key (a typo that would vanish instead of mounting — or a game's own accommodation put in the wrong
+ * place, which the message says).
+ */
+export declare function accommodationPresetProblems(p: AccommodationPreset | null | undefined): string[];
+/** The accommodations only the game can answer. */
+export type GameKeyedAccommodation = (typeof GAME_KEYED)[number];
+/**
+ * THE CARTRIDGE'S ANSWER, for every GAME_KEYED accommodation: its WORD when the accommodation has a subject in this
+ * game, or `false` when it has none.
+ *
+ * 🔴 COMPLETE, NOT PARTIAL — and that is the difference from `AccommodationPreset`, and the decision. The Dev:
+ * «Gênero não precisa responder todas as acomodações, mas sim o cartucho, obrigatoriamente.» A partial map lets
+ * SILENCE answer, and silence here decides for the child: it would mount a wheelchair in chess, or hide one from a
+ * platformer, with nothing anywhere to say which. So a missing key is not «no»; it is a malformed declaration.
+ *
+ * 📌 `false` and not `null`/absence, so a «no» is always something somebody wrote. GENERAL accommodations mount
+ * always and CONTRACT_KEYED ones are derived from the contract, so neither is asked here — asking twice would let
+ * the two answers disagree.
+ */
+export type AccommodationAnswers = Readonly<Record<GameKeyedAccommodation, AccommodationWord | false>>;
+/** Is it one of the accommodations the cartridge must answer? */
+export declare function isGameKeyed(x: unknown): x is GameKeyedAccommodation;
+/**
+ * Is the cartridge's answer well formed? Returns the problems — EMPTY means conformant.
+ *
+ * ⚠️ UNLIKE `accommodationPresetProblems`, AN ABSENT ANSWER IS A PROBLEM: the answer is mandatory (ADR-0153), and a
+ * boot that accepted its absence would be the optional field the Dev refused. The messages go to whoever INTEGRATES
+ * the engine; each one names the accommodation and what to write.
+ */
+export declare function accommodationAnswersProblems(a: unknown): string[];
+/**
+ * Does this accommodation have a subject in this game? The question a panel asks before mounting a row.
+ *
+ * 📌 It returns the WORD, or `null` — never the id, never `true`: a row that mounts must have a name to show, and
+ * «has a subject» without a word is the `action2` defect one level up.
+ */
+export declare function subjectWord(answers: AccommodationAnswers, k: GameKeyedAccommodation): AccommodationWord | null;

package/dist-pkg/core/accommodations.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// core/accommodations — THE ACCOMMODATION CATALOGUE. The closed vocabulary of what the engine can adapt.
+//
+// ========================= WHAT THIS IS =========================
+// ADR-0145 decided that the catalogue is GENERAL and that a game declares which entries have a subject in it,
+// with its own words — «this record is that contract [`ActionPreset`] one level up». This module is the list
+// and the partial map over it, and nothing else: zero imports, zero I/O, importable from both sides of the
+// engine boundary. It is `core/actions.ts` copied shape for shape, on purpose.
+//
+// ========================= WHERE THE LIST COMES FROM =========================
+// Not from what the engine happened to build. It is the catalogue of the study
+// `docs/1-Discovery/study-accommodations-by-genre.md` — 380 games in 35 categories, keyed one accommodation at
+// a time (section 0.1) and cross-checked against all 105 Game Accessibility Guidelines (section 0.2). The
+// study scripts keep Portuguese ids; `tests/accommodations.node.test.js` ties the two by family size, so an
+// accommodation added to one and not the other fails a gate instead of drifting.
+//
+// ========================= THE THREE FAMILIES — the study's finding, as types =========================
+// What decides whether an accommodation has a SUBJECT in a game is not always the genre. Keyed one by one, the
+// catalogue fell into three families, and they need three different answers from the engine:
+//
+//   · GENERAL — there is text, sound, a screen and a menu in every game. The engine mounts these always.
+//   · CONTRACT_KEYED — the subject is answered by a declaration the contract ALREADY asks every game
+//     (`tick`, `holdsKeys()`, `needsPointer()`, `world()` × `topology()`, the players list). The engine can
+//     derive these without a genre, which is the `sonarPlayers` precedent: absent ⇒ derive from the contract.
+//   · GAME_KEYED — nothing the engine holds answers it (genre, perspective, avatar, text, pieces, timing).
+//     The game — or the template of its genre — declares it.
+//
+// ⚠️ Being in the catalogue is NOT being built. `macros` is here and no writer exists; the row mounts when
+// the action works, and not before (ADR-0106 §5). The catalogue names what can be asked for.
+/** Every accommodation the engine knows by name. None of these ids is a word a child reads. */
+export const ACCOMMODATIONS = [
+    // — general —
+    'typography', 'letterCase', 'narration', 'spokenMenuIndex', 'signLanguage', 'soundMix',
+    'hearingLossSimulation', 'highContrast', 'colorVisionCorrection', 'reducedSceneMotion', 'remapControls',
+    'targetSize', 'controlsHelp', 'objectiveReminder', 'repeatInstruction', 'soundCaptions', 'screenReader',
+    'monoAudio', 'interfaceScale', 'interfaceLayout', 'difficulty', 'skipSection', 'settingsProfiles',
+    // — keyed by the contract —
+    'visionSimulation', 'audioDescription', 'virtualPad', 'oneButton', 'inputCooldown', 'macros', 'gameSpeed',
+    'blindMode', 'navigationSound', 'moveLatch', 'holdLatch', 'pointerSmoothing', 'pointerSensitivity',
+    'pointerStyle', 'perPlayerAudioOutput',
+    // — keyed by the game —
+    'cameraSway', 'easyMode', 'wheelchairMode', 'detectionLeniency', 'intensity', 'hints',
+    'reducedCharacterMotion', 'caneSpacing', 'textPace', 'lexicalDifficulty', 'wordHighlight', 'pieceSets',
+    'distinguishableSuits', 'timingWindow', 'aimAssist', 'repeatedInput',
+    // ADR-0188, the Dev: «Criar os dois assuntos.» Only the game knows whether items have an owner, or a drawing to outline.
+    'ownerColors', 'contrastOutlines',
+];
+/**
+ * Subject in EVERY game: there is text, sound, a screen, a menu and a way to confirm in all of them.
+ *
+ * 📌 `difficulty`, `skipSection` and `objectiveReminder` are here although the engine cannot make a game
+ * easier: what it can do is keep, persist and announce the choice, and the game reads it. The GAG asks for
+ * difficulty at Basic level, and «wide choice of difficulty levels» has a subject in any game with a goal.
+ */
+export const GENERAL = [
+    'typography', 'letterCase', 'narration', 'spokenMenuIndex', 'signLanguage', 'soundMix',
+    'hearingLossSimulation', 'highContrast', 'colorVisionCorrection', 'reducedSceneMotion', 'remapControls',
+    'targetSize', 'controlsHelp', 'objectiveReminder', 'repeatInstruction', 'soundCaptions', 'screenReader',
+    'monoAudio', 'interfaceScale', 'interfaceLayout', 'difficulty', 'skipSection', 'settingsProfiles',
+];
+/**
+ * Subject answered by something the contract ALREADY asks, so the engine can derive it with no genre:
+ *
+ *   · `gameSpeed` ← `tick === 'clock'` (WCAG 2.2.1; the GAG's Basic «adjust the game speed»)
+ *   · `moveLatch`, `holdLatch` ← `holdsKeys()` and the positions the preset declares
+ *   · `virtualPad`, `oneButton`, `inputCooldown`, `macros` ← action input (`needsPointer()` false)
+ *   · `pointerSmoothing`, `pointerSensitivity`, `pointerStyle` ← `needsPointer()` true
+ *   · `visionSimulation`, `audioDescription` ← `world().kind === 'element'`
+ *   · `blindMode`, `navigationSound` ← a world AND a direction: `bearing` is `none` on `hotspots`
+ *   · `perPlayerAudioOutput` ← more than one entry in `CreateGameOptions.players`
+ */
+export const CONTRACT_KEYED = [
+    'visionSimulation', 'audioDescription', 'virtualPad', 'oneButton', 'inputCooldown', 'macros', 'gameSpeed',
+    'blindMode', 'navigationSound', 'moveLatch', 'holdLatch', 'pointerSmoothing', 'pointerSensitivity',
+    'pointerStyle', 'perPlayerAudioOutput',
+];
+/**
+ * Subject nothing in the engine can answer: the game declares it.
+ *
+ * ⚠️ `easyMode` and `wheelchairMode` are PLATFORM vocabulary — lower gravity, coins on the ground, no jump —
+ * and that is why they sit here and not in GENERAL: in a chess game they are switches with no subject, the
+ * exact defect ADR-0145 was written about.
+ */
+export const GAME_KEYED = [
+    'cameraSway', 'easyMode', 'wheelchairMode', 'detectionLeniency', 'intensity', 'hints',
+    'reducedCharacterMotion', 'caneSpacing', 'textPace', 'lexicalDifficulty', 'wordHighlight', 'pieceSets',
+    'distinguishableSuits', 'timingWindow', 'aimAssist', 'repeatedInput',
+    'ownerColors', 'contrastOutlines',
+];
+/** Is it a known accommodation? Boundary guard for data that came from outside (a saved setting, a game). */
+export function isAccommodation(x) {
+    return typeof x === 'string' && ACCOMMODATIONS.includes(x);
+}
+/** The accommodations this preset names, in the canonical order of `ACCOMMODATIONS`. */
+export function presetAccommodations(p) {
+    return ACCOMMODATIONS.filter((a) => p[a] !== undefined);
+}
+/**
+ * The question the engine asks a game when it must SHOW an accommodation: «what is this called here?».
+ *
+ * ⚠️ Returns `null` for an entry the game does not name, never the id — the `labellerFrom` rule. Whoever calls
+ * decides; for a GAME_KEYED entry the answer is not to mount the row, because a game that has no word for it
+ * has no subject for it either.
+ */
+export function accommodationLabellerFrom(p) {
+    return (a) => {
+        const w = p[a];
+        return w && w.label.trim() ? w.label : null;
+    };
+}
+/**
+ * Is a preset well formed? Returns the problems — EMPTY means conformant.
+ *
+ * ⚠️ AN ABSENT PRESET IS NOT A PROBLEM, and that is the difference from `presetProblems`. A game with no
+ * action cannot be played; a game that names no accommodation still gets every GENERAL one in the engine's
+ * words. What IS a problem is the silent kind: a blank label (a row with no name for a screen reader) and an
+ * unknown key (a typo that would vanish instead of mounting — or a game's own accommodation put in the wrong
+ * place, which the message says).
+ */
+export function accommodationPresetProblems(p) {
+    if (p === null || p === undefined)
+        return [];
+    if (!isKeyed(p))
+        return [NOT_KEYED];
+    const strangers = Object.keys(p).filter((key) => !isAccommodation(key)).map((key) => `accommodations: «${key}» is not in the catalogue - a game's own accommodation is an addition (ADR-0145 §2), not a preset entry`);
+    const nameless = presetAccommodations(p).filter((a) => !isWord(p[a])).map((a) => `accommodations: ${a} has an empty label - the menu would show a nameless row`);
+    return [...strangers, ...nameless];
+}
+const NOT_KEYED = 'accommodations: must be an object keyed by accommodation';
+/** An object keyed by name, and not a list: the one shape a preset and an answer both take. */
+function isKeyed(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+/** A WORD: an object whose label is text and not blank — a row that mounts must have a name to show. */
+function isWord(v) {
+    return !!v && typeof v === 'object' && typeof v.label === 'string'
+        && v.label.trim() !== '';
+}
+/** Is it one of the accommodations the cartridge must answer? */
+export function isGameKeyed(x) {
+    return typeof x === 'string' && GAME_KEYED.includes(x);
+}
+/**
+ * Is the cartridge's answer well formed? Returns the problems — EMPTY means conformant.
+ *
+ * ⚠️ UNLIKE `accommodationPresetProblems`, AN ABSENT ANSWER IS A PROBLEM: the answer is mandatory (ADR-0153), and a
+ * boot that accepted its absence would be the optional field the Dev refused. The messages go to whoever INTEGRATES
+ * the engine; each one names the accommodation and what to write.
+ */
+export function accommodationAnswersProblems(a) {
+    if (a === null || a === undefined) {
+        return ['accommodations: missing - the cartridge must answer every game-keyed accommodation (ADR-0153): its word, or false'];
+    }
+    if (!isKeyed(a))
+        return [NOT_KEYED];
+    const unanswered = GAME_KEYED.map((k) => answerProblem(a, k)).filter((p) => p !== null);
+    const strangers = Object.keys(a).filter((k) => !isGameKeyed(k)).map((k) => (isAccommodation(k)
+        ? `accommodations: ${k} is not the cartridge's to answer - general ones mount always and contract ones are derived`
+        : `accommodations: «${k}» is not in the catalogue - a game's own accommodation is an addition (ADR-0145 §2)`));
+    return [...unanswered, ...strangers];
+}
+/** What is wrong with the cartridge's answer to ONE accommodation, or `null`: it must be written, and be `false` or a word. */
+function answerProblem(answers, k) {
+    if (!(k in answers))
+        return `accommodations: ${k} is not answered - write its word if it has a subject in this game, or false`;
+    const v = answers[k];
+    return v === false || isWord(v) ? null : `accommodations: ${k} must be false or a word with a non-empty label`;
+}
+/**
+ * Does this accommodation have a subject in this game? The question a panel asks before mounting a row.
+ *
+ * 📌 It returns the WORD, or `null` — never the id, never `true`: a row that mounts must have a name to show, and
+ * «has a subject» without a word is the `action2` defect one level up.
+ */
+export function subjectWord(answers, k) {
+    const v = answers[k];
+    return v && v.label.trim() ? v : null;
+}