@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/screen-text.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * THE SONAR'S POSITION WHILE A MENU IS OPEN. In play the position is the game's (its `preset`); with a menu open the positions
+ * are the engine's, and there R1 reads the menu — the Dev's default for the sonar («Tecla padrão para o sonar deve ser R1»).
+ */
+const MENU_SONAR = 'rightShoulder';
+/** The engine's chrome the child did not ask about (see the header). */
+const NOT_ASKED_ABOUT = [
+    '.pause-icons', '.screen-a11y', '.rodape-da-tela', '.scan-now', '#touch-controls', '.touch', '.sr-only',
+    '.gaze-overlay', '.face-overlay', '.hand-overlay', '.hud-row-clock',
+].join(', ');
+/** What is open in front of the world. */
+const DIALOG = '[role="dialog"], [role="alertdialog"], [aria-modal="true"]';
+/** Elements whose content is not words on the screen (a `<select>` shows its chosen option only — see `spokenAs`). */
+const NOT_WORDS = /^(script|style|template|noscript|svg|canvas|video|audio|iframe|object|option|optgroup)$/i;
+/** A line that already ends a sentence is not given a full stop. */
+const ENDS_A_SENTENCE = /[.!?…:;]$/u;
+/**
+ * Is this one element drawn for the eye, and meant for everyone? Its ancestors are asked by whoever walks down to it.
+ * 📌 The RENDERING decides, not the `hidden` attribute: `hidden` hides by `display: none`, which is read here, and a stylesheet
+ * that shows a `[hidden]` element puts it on the screen.
+ */
+function isShown(el) {
+    if (el.hasAttribute('inert') || el.getAttribute('aria-hidden') === 'true')
+        return false;
+    const style = el.ownerDocument?.defaultView?.getComputedStyle(el);
+    return !style || (style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0');
+}
+/** Is it drawn, with every ancestor drawn too? For an element found by a query rather than walked down to. */
+function isOnScreen(el) {
+    for (let node = el; node; node = node.parentElement)
+        if (!isShown(node))
+            return false;
+    return true;
+}
+/**
+ * Can this node be walked and asked? A host double may hand elements without the DOM's questions; then there is nothing the
+ * engine can read, and it says nothing rather than throwing into the sonar (a capability of the environment, ADR-0169).
+ */
+function canBeRead(el) {
+    return !!el && typeof el.matches === 'function' && typeof el.querySelectorAll === 'function' && typeof el.hasAttribute === 'function';
+}
+/** The dialog in front, or `null`: the one holding the focus, else the last one open in the document. */
+function dialogInFront(doc) {
+    if (typeof doc.querySelectorAll !== 'function')
+        return null;
+    const open = [...doc.querySelectorAll(DIALOG)].filter((d) => canBeRead(d) && isOnScreen(d) && !d.matches(NOT_ASKED_ABOUT));
+    const focused = doc.activeElement;
+    return open.find((d) => !!focused && d.contains(focused)) ?? open[open.length - 1] ?? null;
+}
+/** The world's element, or `null` when the game declared none, its selector matches nothing, or it cannot be read. */
+function worldElement(ctx) {
+    const scope = ctx.world();
+    const el = scope.kind === 'element' && typeof ctx.doc.querySelector === 'function' ? ctx.doc.querySelector(scope.selector) : null;
+    return canBeRead(el) ? el : null;
+}
+/** Does the world draw on a canvas the engine did not put there? Then its words are pixels. */
+function drawsOnCanvas(world) {
+    const canvases = world.matches('canvas') ? [world] : [...world.querySelectorAll('canvas')];
+    return canvases.some((c) => !c.closest(NOT_ASKED_ABOUT) && isOnScreen(c));
+}
+/** The words an element stands for instead of its children, or `null` to read its children. */
+function spokenAs(el) {
+    if (el.getAttribute('role') === 'img')
+        return el.getAttribute('aria-label') ?? '';
+    if (el.localName === 'img')
+        return el.getAttribute('alt') ?? '';
+    if (el.localName === 'select')
+        return el.selectedOptions[0]?.textContent ?? '';
+    return null;
+}
+/** Does the element start a line of its own? Everything that is not inline does — a button, a heading, a row. */
+function breaksTheLine(el) {
+    const display = el.ownerDocument?.defaultView?.getComputedStyle(el).display ?? 'block';
+    return el.localName === 'br' || (display !== 'inline' && display !== 'contents');
+}
+/**
+ * The text under `root`, in DOM order, one line per block. Lines are joined as sentences, so the voice pauses between the
+ * statement and each option and the interpreter receives them apart.
+ */
+function textOf(root) {
+    const lines = [];
+    let line = '';
+    const endLine = () => {
+        const words = line.replace(/\s+/gu, ' ').trim();
+        if (words)
+            lines.push(words);
+        line = '';
+    };
+    const readChildren = (el) => {
+        for (const child of el.childNodes ?? []) {
+            if (child.nodeType === 3)
+                line += child.textContent ?? '';
+            else if (child.nodeType === 1)
+                visit(child);
+        }
+    };
+    const visit = (el) => {
+        if (!isShown(el) || el.matches(NOT_ASKED_ABOUT) || NOT_WORDS.test(el.localName))
+            return;
+        const own = breaksTheLine(el);
+        if (own)
+            endLine();
+        const said = spokenAs(el);
+        if (said === null)
+            readChildren(el);
+        else
+            line += ` ${said} `;
+        if (own)
+            endLine();
+    };
+    visit(root);
+    endLine();
+    return lines.map((l) => (ENDS_A_SENTENCE.test(l) ? l : `${l}.`)).join(' ');
+}
+/**
+ * WHAT IS ON THE SCREEN NOW, as the sonar reads it — `''` when there is nothing the engine can read: no world, an empty one,
+ * or a world drawn on a canvas.
+ */
+export function screenText(ctx) {
+    const front = dialogInFront(ctx.doc);
+    if (front)
+        return textOf(front);
+    const world = worldElement(ctx);
+    return world && !drawsOnCanvas(world) ? textOf(world) : '';
+}
+/**
+ * The `problems` line for a world the sonar cannot read — none, or one (ADR-0169: the subject, the child's cost, the fix).
+ * Measured at every read of `problems`: a canvas is often drawn after the boot.
+ */
+export function unreadableWorldProblems(ctx) {
+    const world = worldElement(ctx);
+    if (!world || !drawsOnCanvas(world))
+        return [];
+    return ['the sonar cannot read this game\'s screen: its world draws on a <canvas>, whose words are pixels to the engine, so '
+            + 'a child who presses the sonar hears only the nearest target\'s name and side instead of what is written on screen — '
+            + 'and in deaf mode the interpreter signs that, not the screen (ADR-0234). Write the words the child must read as text '
+            + 'in the page, inside the world; a contract field for a game to hand the engine its screen\'s text is a decision the '
+            + 'Dev has not taken'];
+}
+/**
+ * A press made WITH A MENU OPEN: the menu sonar's position reads what is in front (`read`) and takes the press. Any other
+ * position is left to the menus — answers whether this one was taken.
+ */
+export function menuSonarPress(action, ctx, read) {
+    if (action !== MENU_SONAR)
+        return false;
+    const text = screenText(ctx);
+    if (text)
+        read(text);
+    return true;
+}

package/dist-pkg/ui/session-clock.d.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+/**
+ * What the clock needs, all lent by the root. The three host ports are REQUIRED and may carry `undefined` — a host without
+ * them is answered here, not with a branch in the root (ADR-0232 erratum of 2026-09-25): with no clock or no tick there is no
+ * session to measure, and nothing is mounted, silently, as a capability of the environment (ADR-0169).
+ */
+export interface SessionClockCtx {
+    readonly doc: Document;
+    /** Where the clock goes: the HUD row's centre cell. Absent, or a node that takes no children, and nothing is mounted. */
+    readonly slot: HTMLElement | null;
+    readonly t: Translate;
+    /** The host's `performance`, milliseconds and monotonic. The session starts at the mount. */
+    readonly performance: {
+        now(): number;
+    } | undefined;
+    readonly setInterval: ((fn: () => void, ms: number) => number) | undefined;
+    readonly clearInterval: ((handle: number) => void) | undefined;
+    /** The polite announcer: said once, when the hour runs out. */
+    readonly announce: (text: string) => void;
+    /** Called after every redraw, so the root can measure the row again when the clock's size changed. */
+    readonly drawn: () => void;
+}
+export interface SessionClockMounted {
+    readonly el: HTMLElement;
+    /** Reads the time again and redraws what changed (the tick calls it; a language change too). */
+    refresh(): void;
+    /** Stops the tick and takes the clock off the page. */
+    remove(): void;
+}
+/** Mounts the clock in its slot, draws it now, and redraws it every second until `remove()`; `null` where it cannot. */
+export declare function mountSessionClock(ctx: SessionClockCtx): SessionClockMounted | null;

package/dist-pkg/ui/session-clock.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { readSession, clockWords, clockDigits } from '../core/session-clock.js';
+/** One tick a second: the digits move by the second, and the hour's pie by a tenth of a degree, which reads as continuous. */
+const TICK_MS = 1000;
+/** Writes `text` into `node` only when it changed — a rewrite is a repaint, and on school hardware a repaint costs. */
+function write(node, text) {
+    if (node.textContent !== text)
+        node.textContent = text;
+}
+/**
+ * Builds the clock's three parts: the label and the digits in a column, the pie to their right.
+ *
+ * 🔴 THE PARTS ARE `aria-hidden`: they are the picture, and the image's name is what a listener gets. ARIA calls an image's
+ * children presentational, but not every accessibility API prunes them — Gecko keeps a graphic's children unless it has exactly
+ * one text child, and NVDA then read «TEMPO. 56:07.» instead of the words (the Dev, 2026-09-25). Hidden here, no API has any
+ * text under the image to hand out. Gate: `tests/quiz-accessibility-tree.browser.test.js`, on the browser's own tree.
+ */
+function build(doc) {
+    const part = (cls) => { const n = doc.createElement('span'); n.className = cls; return n; };
+    const el = doc.createElement('div');
+    el.className = 'session-clock';
+    el.setAttribute('role', 'img');
+    const text = part('session-clock-text');
+    const label = part('session-clock-label');
+    const digits = part('session-clock-digits');
+    const pie = part('session-clock-pie');
+    text.setAttribute('aria-hidden', 'true');
+    pie.setAttribute('aria-hidden', 'true');
+    text.append(label, digits);
+    el.append(text, pie);
+    return { el, label, digits, pie };
+}
+/** Mounts the clock in its slot, draws it now, and redraws it every second until `remove()`; `null` where it cannot. */
+export function mountSessionClock(ctx) {
+    const { slot, performance: clock, setInterval: every } = ctx;
+    if (!slot || typeof slot.appendChild !== 'function' || !clock || typeof every !== 'function')
+        return null;
+    const { el, label, digits, pie } = build(ctx.doc);
+    slot.appendChild(el);
+    const timer = clock; // the guard's answer, kept for the tick
+    const start = timer.now();
+    let look = null;
+    function refresh() {
+        const reading = readSession(timer.now() - start);
+        const next = reading.over ? 'red' : 'running';
+        pie.style.setProperty('--left', reading.left.toFixed(4));
+        write(label, ctx.t('clock.label'));
+        write(digits, clockDigits(reading.leftMs));
+        const words = clockWords(reading);
+        const name = ctx.t(words.key, { minutes: words.minutes });
+        if (el.getAttribute('aria-label') !== name)
+            el.setAttribute('aria-label', name);
+        if (next !== 'running' && look === 'running')
+            ctx.announce(name);
+        if (next !== look)
+            el.dataset.look = next;
+        look = next;
+        ctx.drawn();
+    }
+    refresh();
+    const handle = every(refresh, TICK_MS);
+    return {
+        el,
+        refresh,
+        remove: () => { ctx.clearInterval?.(handle); el.remove(); },
+    };
+}

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

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { LetterCase } from '../core/state.js';
+import { type AacSet } from './aac-sets.js';
+import { type ControlRowSpec } from './panel-widgets.js';
+import type { PanelShellCtx } from './panel-shell.js';
+/**
+ * The LETTERS row is a SWITCH, not two options (the Dev's decision). On = upper case only; off = upper and lower case.
+ * A binary question presented as two rows makes the child compare both to discover they are the same question.
+ */
+export declare function upperCaseOn(letterCase: LetterCase): boolean;
+/** The id of a set's control. It comes from the catalogue `key`, unique by construction (`AAC_BY_KEY`). */
+export declare const aacControlId: (key: string) => string;
+/** The letters switch. Always available: it is the offline floor, and never depended on any file. */
+export declare function lettersRowSpec(t: Translate): ControlRowSpec;
+/**
+ * A menu row: a SHORT LABEL and nothing else in view.
+ *
+ * Everything that explains — note, licence, status — goes into a single `.opt-hint`, which the shell (`fillExplain`)
+ * recognises and MOVES to the footer. Prose hung inside the row turns the menu into a manual, closer to a configuration
+ * file than to a videogame menu — the Dev saw exactly that.
+ *
+ * `ariaLabel` carries the reason, so whoever navigates by keyboard hears why the row does not respond without hunting
+ * for the footer. `disabled` belongs to the CONTROL and not the text: the status leaves the label, never the button.
+ */
+export declare function aacRowSpec(t: Translate, s: AacSet): ControlRowSpec;
+/**
+ * The menu's two sections: what works now (the letters switch), and the pictogram sets, each only with a licence
+ * (ADR-0233). Whether a set row is locked is the row's own business (its reason and its `disabled`), so a licence that
+ * arrives changes one row, not the sections.
+ *
+ * 📌 Each produces its own rows instead of filtering the catalogue, because the first does not come from the catalogue
+ * — the letters are a switch and not a set, the Dev's decision that took them out of the list. A table whose first row
+ * is the exception to all the others lies about what it is.
+ */
+export declare const AAC_SECTIONS: ReadonlyArray<{
+    title: string;
+    tag: string;
+    rows: (t: Translate) => ControlRowSpec[];
+}>;
+/**
+ * Mounts the menu's inside ONCE. Called again, it RELABELS instead of rebuilding.
+ *
+ * ⚠️ Relabel and not rebuild, for the reason `labelRow` already states: listeners are wired at boot, and remaking the
+ * row would leave a control in the document with no listener — a dead button that looks alive (ADR-0106 §5). And the
+ * text may have been captured at boot, while the language was still the fallback.
+ */
+export declare function mountAacInside(t: Translate, ctx: PanelShellCtx, list: HTMLElement): void;
+export interface SettingsAacCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    $: <T extends Element = Element>(sel: string) => T | null;
+    srSay: (msg: string) => void;
+    /** Live read of core/state `letterCase` (the binding is reassigned by the setter). */
+    getLetterCase: () => LetterCase;
+    /** core/state `setLetterCaseValue` PLUS the reflection the game needs (re-rendering its text, labels). */
+    setLetterCase: (c: LetterCase) => void;
+    frontOverlay: (el: HTMLElement | null) => void;
+    /** Moves the rows' prose to the footer (ui/settings-panel `fillExplain`). Called on EVERY render, not only on open:
+     *  relabelling a row puts the hint back inside it, and without this call the menu turns into a manual again on the
+     *  first click. */
+    fillExplain: (card: HTMLElement | null) => void;
+    restoreFocus?: (id: string) => boolean;
+}
+export interface SettingsAacApi {
+    render: () => void;
+    open: () => void;
+    close: () => void;
+}
+export declare function initSettingsAac(ctx: SettingsAacCtx): SettingsAacApi;

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

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { DEFAULTS } from '../core/setting-defaults.js';
+import { AAC_SETS, AAC_BY_KEY, aacMenuLocked, aacReason, aacSelectable } from './aac-sets.js';
+import { markChanged, markMenuChanged } from './changed-mark.js';
+import { controlRow, labelRow, sectionHeader } from './panel-widgets.js';
+import { toggleLabel } from './dom.js';
+/**
+ * The LETTERS row is a SWITCH, not two options (the Dev's decision). On = upper case only; off = upper and lower case.
+ * A binary question presented as two rows makes the child compare both to discover they are the same question.
+ */
+export function upperCaseOn(letterCase) {
+    return letterCase === 'upper';
+}
+/** The id of a set's control. It comes from the catalogue `key`, unique by construction (`AAC_BY_KEY`). */
+export const aacControlId = (key) => `caa-set-${key}`;
+/** The letters switch. Always available: it is the offline floor, and never depended on any file. */
+export function lettersRowSpec(t) {
+    return { id: 'caa-caixa-alta', label: t('aac.letras'), hint: t('aac.letras.dica') };
+}
+/**
+ * A menu row: a SHORT LABEL and nothing else in view.
+ *
+ * Everything that explains — note, licence, status — goes into a single `.opt-hint`, which the shell (`fillExplain`)
+ * recognises and MOVES to the footer. Prose hung inside the row turns the menu into a manual, closer to a configuration
+ * file than to a videogame menu — the Dev saw exactly that.
+ *
+ * `ariaLabel` carries the reason, so whoever navigates by keyboard hears why the row does not respond without hunting
+ * for the footer. `disabled` belongs to the CONTROL and not the text: the status leaves the label, never the button.
+ */
+export function aacRowSpec(t, s) {
+    const reason = aacReason(s);
+    const explains = [s.note, s.license ? `Licença: ${s.license}` : '', reason ? t(reason) : '']
+        .filter(Boolean).join(' · ');
+    return {
+        id: aacControlId(s.key),
+        label: s.name,
+        ...(explains ? { hint: explains } : {}),
+        ariaLabel: `${s.name}${reason ? ', ' + t(reason) : ''}`,
+    };
+}
+/**
+ * The menu's two sections: what works now (the letters switch), and the pictogram sets, each only with a licence
+ * (ADR-0233). Whether a set row is locked is the row's own business (its reason and its `disabled`), so a licence that
+ * arrives changes one row, not the sections.
+ *
+ * 📌 Each produces its own rows instead of filtering the catalogue, because the first does not come from the catalogue
+ * — the letters are a switch and not a set, the Dev's decision that took them out of the list. A table whose first row
+ * is the exception to all the others lies about what it is.
+ */
+export const AAC_SECTIONS = [
+    { title: 'aac.secao.agora', tag: 'aac.secao.agoraTag', rows: (t) => [lettersRowSpec(t)] },
+    {
+        title: 'aac.section.pictograms',
+        tag: 'aac.section.pictogramsTag',
+        rows: (t) => AAC_SETS.map((s) => aacRowSpec(t, s)),
+    },
+];
+/**
+ * Mounts the menu's inside ONCE. Called again, it RELABELS instead of rebuilding.
+ *
+ * ⚠️ Relabel and not rebuild, for the reason `labelRow` already states: listeners are wired at boot, and remaking the
+ * row would leave a control in the document with no listener — a dead button that looks alive (ADR-0106 §5). And the
+ * text may have been captured at boot, while the language was still the fallback.
+ */
+export function mountAacInside(t, ctx, list) {
+    for (const section of AAC_SECTIONS) {
+        const specs = section.rows(t);
+        const header = sectionHeader(ctx, t(section.title), t(section.tag), specs.length);
+        if (header && !list.querySelector(`[data-caa-section="${section.title}"]`)) {
+            header.setAttribute('data-caa-section', section.title);
+            list.appendChild(header);
+        }
+        for (const spec of specs) {
+            const old = ctx.find('#' + spec.id)?.closest('.ctrl-row');
+            if (old)
+                labelRow(old, spec);
+            else
+                list.appendChild(newRow(ctx, spec));
+        }
+    }
+}
+/**
+ * A new row, with what the kit does not know about this panel: the set's key and the lock.
+ *
+ * No set is licensed today (ADR-0233). A button that does nothing is worse than absence, because it spends trust — so an
+ * unlicensed set comes locked, and the reason is already in `ariaLabel` for whoever navigates by keyboard.
+ */
+function newRow(ctx, spec) {
+    const { row: row, control: control } = controlRow(ctx, spec);
+    if (spec.id === 'caa-caixa-alta') {
+        row.id = 'caa-letras';
+        return row;
+    }
+    const key = spec.id.replace('caa-set-', '');
+    control.setAttribute('data-caa', key);
+    const set = AAC_BY_KEY[key];
+    if (!set || !aacSelectable(set))
+        control.setAttribute('disabled', '');
+    return row;
+}
+export function initSettingsAac(ctx) {
+    const { t } = ctx;
+    /*
+     * 📌 THE KIT'S CTX COMES FROM THE LIST NODE ITSELF, not from a global `document` nor a new contract field.
+     * `ownerDocument` is the document that list LIVES in — exactly the document the rows must be born in —, so this
+     * module's global reach stays ZERO (ADR-0221) and `SettingsAacCtx`, which is published surface, gains no required
+     * member (ADR-0172).
+     */
+    const panelCtx = (list) => ({
+        find: (sel) => ctx.$(sel),
+        create: (tag) => list.ownerDocument.createElement(tag),
+    });
+    function reflect() {
+        const b = ctx.$('#caa-caixa-alta');
+        if (!b)
+            return;
+        const on = upperCaseOn(ctx.getLetterCase());
+        b.classList.toggle('is-on', on);
+        b.setAttribute('aria-pressed', String(on));
+        // The switch's text is the STATE; its name is in the `<strong>` beside it and in the `aria-label`.
+        b.textContent = toggleLabel(t, on);
+    }
+    function render() {
+        const el = ctx.$('#caa-list');
+        if (!el)
+            return;
+        mountAacInside(t, panelCtx(el), el);
+        reflect();
+        ctx.fillExplain(ctx.$('#caa .overlay__card'));
+        refreshMarks();
+    }
+    /** The left-the-default mark (ADR-0029), on the chosen row and on the menu's button. */
+    function refreshMarks() {
+        const changed = ctx.getLetterCase() !== DEFAULTS.letterCase;
+        markChanged(t, ctx.$('#caa-letras'), changed);
+        markMenuChanged(t, ctx.$('[data-act="caa"]'), [changed]);
+    }
+    /**
+     * THE MENU'S DOOR IS DISABLED while no pictogram set is licensed (ADR-0233 erratum), with the pause card's lock
+     * (ADR-0161): `aria-disabled` and the reason in `data-motivo`, which the menu navigation speaks on reach and writes in
+     * the footer. The reason is ONLY «menu disabled»: the licence story is not the child's to hear. No unlock branch: the
+     * catalogue is static, so a licensed set means the door is never locked in the first place.
+     */
+    function lockDoor() {
+        const door = ctx.$('[data-act="caa"]');
+        if (!door || !aacMenuLocked())
+            return;
+        door.setAttribute('aria-disabled', 'true');
+        door.dataset.motivo = t('pause.motivo.caa');
+    }
+    function open() {
+        // A game that wires its own door to `open` meets the same lock: the reason is said and nothing opens, so no
+        // per-set licence row reaches the child.
+        if (aacMenuLocked()) {
+            lockDoor();
+            ctx.srSay(t('pause.motivo.caa'));
+            return;
+        }
+        const ov = ctx.$('#caa');
+        if (!ov)
+            return;
+        render();
+        ov.hidden = false;
+        ctx.frontOverlay(ov);
+        const f = ov.querySelector('button');
+        if (f)
+            f.focus();
+    }
+    function close() {
+        const ov = ctx.$('#caa');
+        if (!ov)
+            return;
+        ov.hidden = true;
+        ctx.restoreFocus?.('caa');
+    }
+    /*
+     * The listeners are wired ONCE, on the list, by delegation — which mounting once allows. What protects an
+     * unavailable set is its own button's `disabled`, written where it is born; a listener that only guards and then does
+     * nothing would be inert code dressed as protection.
+     */
+    const list = ctx.$('#caa-list');
+    if (list)
+        list.addEventListener('click', (ev) => {
+            const hit = ev.target?.closest('#caa-caixa-alta');
+            if (!hit)
+                return;
+            const turnOn = !upperCaseOn(ctx.getLetterCase());
+            ctx.setLetterCase(turnOn ? 'upper' : 'mixed');
+            render();
+            ctx.srSay(t(turnOn ? 'sr.aac.caixaAltaOn' : 'sr.aac.caixaAltaOff'));
+        });
+    const closeBtn = ctx.$('#caa-close');
+    if (closeBtn)
+        closeBtn.addEventListener('click', close);
+    lockDoor();
+    // ---- reset THIS menu's defaults (ADR-0028) ----
+    // The menu has one choice, so the reset is one line — but where it returns to is worth saying: the default case,
+    // where Brazilian literacy usually starts. A child who switched the case and can no longer read the screen needs a way
+    // back that ends at what their teacher uses.
+    const resetBtn = ctx.$('#caa-reset');
+    if (resetBtn)
+        resetBtn.addEventListener('click', () => {
+            ctx.setLetterCase(DEFAULTS.letterCase);
+            render();
+            ctx.srSay(t('sr.aac.reset'));
+        });
+    return { render, open, close };
+}