@the-inclusionist/engine 8.0.0 → 10.0.0

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

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { VirtualController } from '../input/virtual-controller.js';
+import { type FaceTrackerLoad, type VisionDeps } from '../platform/vision.js';
+import { type VisionLoopDeps } from '../platform/vision-loop.js';
+import type { SwitchableControl } from './switchable-control.js';
+/** A camera picture the tracker can read. */
+export interface CameraFeed {
+    readonly frame: unknown;
+    ready(): boolean;
+    close(): void;
+}
+export interface EyeControlDeps {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    readonly doc: Document;
+    /** Where the regions are drawn: `#game-region`. */
+    readonly region: HTMLElement;
+    /** The page's address, to reach `heavy/`. */
+    readonly base: string;
+    /** Whether a file is in the checked cache, handed to the tracker's loader (ADR-0232 D4: the root lends the cache). */
+    readonly hasFile: VisionDeps['hasFile'];
+    readonly loop: VisionLoopDeps;
+    /** Where the presses go: seat 0's virtual controller. */
+    readonly controller: VirtualController;
+    readonly say: (text: string) => void;
+    readonly alert: (text: string) => void;
+    /** A line for `problems`. */
+    readonly report: (line: string) => void;
+    /** Put the 📷 back to off: what cannot start must not show as on. */
+    readonly turnOff: () => void;
+    readonly loadTracker?: (deps: VisionDeps) => Promise<FaceTrackerLoad>;
+    readonly openFeed?: () => Promise<CameraFeed>;
+}
+export declare function videoFeed(doc: Document, media: MediaDevices): () => Promise<CameraFeed>;
+export declare function createEyeControl(d: EyeControlDeps): SwitchableControl;

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

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/eye-control — PLAYING WITH THE EYES, PUT TOGETHER (ADR-0213; issues #194, #196).
+//
+// The pieces are each tested apart; this joins them for the root: the camera and the face tracker (platform/vision), a frame loop that
+// cannot stop in silence (platform/vision-loop), the right eye's gaze read from its own rest (input/gaze-relative), the cycle that turns
+// zones into actions (input/gaze-cycle), the presses on the virtual controller with the source `olhos` (input/virtual-controller, ADR-0111:
+// never a disguised keyboard), and the regions drawn over the game
+// (ui/gaze-overlay). The 📷 at its eyes position drives it (ADR-0215); any other position lets the camera go.
+// · Nothing commands before the rest is measured: until then, and on a frame with no face or a head turning fast, the cycle is frozen.
+// · A reading that re-centres itself cancels the gesture in hand.
+// · Only the RIGHT eye is read (ADR-0213): the Dev's brain suppresses the left one, and a child's may too.
+// · What cannot work is said to the child and written in `problems`, once: the files not on the device, the camera refused, frames that
+//   stop or crawl. A 📷 that is on and does nothing is the defect this module exists not to ship.
+import { headPoseFromMatrix, scoresFromCategories, eyeGazeFromScores, bothEyesClosed } from '../input/face-signals.js';
+import { createGazeReader, GAZE_DEFAULTS } from '../input/gaze-relative.js';
+import { createGazeCycle } from '../input/gaze-cycle.js';
+import { loadFaceTracker, openCamera, closeCamera } from '../platform/vision.js';
+import { createVisionLoop } from '../platform/vision-loop.js';
+import { drawGazeOverlay } from './gaze-overlay.js';
+// 📌 THE SHAPE IS THE FAMILY'S (ADR-0221 step 7f): what this module returns IS a SwitchableControl — following the 📷: on in
+// the eyes position it opens the camera and the drawing, off it lets go of everything.
+export function videoFeed(doc, media) {
+    return async () => {
+        const stream = await openCamera(media);
+        const video = doc.createElement('video');
+        video.muted = true;
+        video.playsInline = true;
+        video.srcObject = stream;
+        await video.play();
+        return { frame: video, ready: () => video.readyState >= 2, close: () => { video.pause(); video.srcObject = null; closeCamera(stream); } };
+    };
+}
+/** What one detection says: the blendshapes (none without a face), the head's pose, and the RIGHT eye's gaze. */
+function readDetection(det) {
+    const cats = det?.faceBlendshapes?.[0]?.categories;
+    const scores = cats ? scoresFromCategories(cats) : null;
+    return { scores, pose: headPoseFromMatrix(det?.facialTransformationMatrixes?.[0]?.data), eye: scores ? eyeGazeFromScores(scores).right : null };
+}
+/** What the cycle is told: frozen while nothing can be trusted — no rest yet, no face, a head turning fast — and cancelled when
+ *  the reader re-centres under the gaze, because what was held was never a decision. */
+function cycleFrameOf(reading, scores) {
+    return {
+        zone: reading.zone,
+        eyesClosed: !!scores && bothEyesClosed(scores),
+        frozen: !reading.ready || !scores || reading.reason === 'head-moving',
+        cancel: reading.reason === 'recentring',
+    };
+}
+/** The reading, written on the drawing's own element: when a child's eyes are not answered, this says at which step it stops. */
+function writeDiagnosis(canvas, reading, out, face, delegate) {
+    const f2 = (n) => (n === undefined ? '' : n.toFixed(2));
+    Object.assign(canvas.dataset, {
+        face: String(face), ready: String(reading.ready), reason: reading.reason ?? '', zone: reading.zone ?? '',
+        tremorH: f2(reading.tremor?.h), tremorV: f2(reading.tremor?.v), dh: f2(reading.displacement?.h), dv: f2(reading.displacement?.v),
+        stillMs: String(Math.round(reading.stillMs ?? 0)), armed: String(out.armed), preparing: String(out.preparing), preview: out.preview?.item ?? '',
+        delegate,
+    });
+}
+/** The regions over the game at the region's size, the middle counting down while the rest is measured, and the face's lines. */
+function drawFrame(t, canvas, region, reading, out, det, lines) {
+    const w = canvas.width = region.clientWidth, h = canvas.height = region.clientHeight;
+    drawGazeOverlay(t, canvas.getContext('2d'), w, h, {
+        zone: reading.zone, armed: out.armed, preparing: out.preparing, preview: out.preview, restReady: reading.ready,
+        restLeftMs: reading.ready ? undefined : Math.max(0, GAZE_DEFAULTS.restMs - (reading.stillMs ?? 0)),
+    }, { face: det?.faceLandmarks?.[0] ? { landmarks: det.faceLandmarks[0], lines } : null });
+}
+export function createEyeControl(d) {
+    const { t } = d;
+    const loadTracker = d.loadTracker ?? loadFaceTracker;
+    const openFeed = d.openFeed ?? videoFeed(d.doc, d.doc.defaultView.navigator.mediaDevices);
+    const said = new Set();
+    const once = (kind, line, spoken) => {
+        if (!said.has(kind)) {
+            said.add(kind);
+            d.report(line);
+        }
+        d.alert(spoken);
+    };
+    let on = false, running = false, starting = null;
+    const current = () => on; // read through a call: `apply` awaits, and `on` can change meanwhile
+    let tracker = null, feed = null, canvas = null;
+    let pressed = null, wasReady = false;
+    let reader = createGazeReader(), cycle = createGazeCycle();
+    let loop = null;
+    const release = () => { if (pressed)
+        d.controller.release(pressed, 'olhos'); pressed = null; };
+    /** Only a change reaches the controller: the old action is let go, the new one pressed, from the eyes. */
+    const followPress = (next) => {
+        if (next === pressed)
+            return;
+        if (pressed)
+            d.controller.release(pressed, 'olhos');
+        if (next)
+            d.controller.press(next, 'olhos');
+        pressed = next;
+    };
+    const frame = (ms) => {
+        if (!tracker || !feed || !canvas || !feed.ready())
+            return;
+        const det = tracker.detect(feed.frame, ms);
+        const { scores, pose, eye } = readDetection(det);
+        const reading = reader(ms, { h: eye?.h, v: eye?.v, pose });
+        if (reading.ready && !wasReady)
+            d.say(t('sr.eyes.ready'));
+        wasReady = reading.ready;
+        const out = cycle(ms, cycleFrameOf(reading, scores));
+        followPress(out.pressed);
+        writeDiagnosis(canvas, reading, out, !!scores, tracker.delegate());
+        drawFrame(t, canvas, d.region, reading, out, det, tracker.eyeLines);
+    };
+    const health = (h, fps) => {
+        if (h === 'stalled')
+            once('stalled', 'eye control: a second without a camera frame — meanwhile the child\'s gaze commands nothing; keep the tab in front and the camera free', t('sr.eyes.stopped'));
+        if (h === 'slow')
+            once('slow', `eye control: ${fps} frames a second, under 8 — the reading misses movements and the child may not be answered; close other heavy tabs or use a lighter device`, t('sr.eyes.slow'));
+    };
+    const stop = () => {
+        loop?.stop();
+        loop = null;
+        release();
+        feed?.close();
+        feed = null;
+        tracker?.close();
+        tracker = null;
+        canvas?.remove();
+        canvas = null;
+        running = false;
+        wasReady = false;
+    };
+    const start = async () => {
+        const load = await loadTracker({ base: d.base, hasFile: d.hasFile });
+        if (!load.ok) {
+            once('files', `eye control: ${load.missing.join(', ')} not on this device — the child cannot play with the eyes; open the game once online so the install fetches them`, t('sr.eyes.needsInternet'));
+            d.turnOff();
+            return;
+        }
+        try {
+            feed = await openFeed();
+        }
+        catch {
+            load.tracker.close();
+            once('camera', 'eye control: the camera did not open — the child cannot play with the eyes; allow the camera for this page, or plug one in', t('sr.eyes.noCamera'));
+            d.turnOff();
+            return;
+        }
+        tracker = load.tracker;
+        canvas = d.doc.createElement('canvas');
+        canvas.className = 'gaze-overlay';
+        canvas.setAttribute('aria-hidden', 'true');
+        Object.assign(canvas.style, { position: 'absolute', inset: '0', width: '100%', height: '100%', pointerEvents: 'none', zIndex: '5' });
+        d.region.appendChild(canvas);
+        reader = createGazeReader();
+        cycle = createGazeCycle();
+        pressed = null;
+        loop = createVisionLoop(d.loop, { onFrame: frame, onError: (e) => once('frame', `eye control: a frame failed (${String(e)}) — the loop goes on, but a repeated failure means the child is not being read`, t('sr.eyes.stopped')), onHealth: health });
+        running = true;
+        d.say(t('sr.eyes.lookMiddle'));
+        loop.start();
+    };
+    return {
+        async apply(next) {
+            on = next;
+            if (starting)
+                await starting;
+            if (!on) {
+                if (running)
+                    stop();
+                return;
+            }
+            if (running)
+                return;
+            starting = start().finally(() => { starting = null; });
+            await starting;
+            if (!current() && running)
+                stop(); // turned off while the camera was opening
+        },
+    };
+}

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

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { VirtualController } from '../input/virtual-controller.js';
+import { type FaceTrackerLoad, type VisionDeps } from '../platform/vision.js';
+import { type VisionLoopDeps } from '../platform/vision-loop.js';
+import type { CameraFeed } from './eye-control.js';
+import type { SwitchableControl } from './switchable-control.js';
+export interface FaceControlDeps {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    readonly doc: Document;
+    readonly region: HTMLElement;
+    readonly base: string;
+    /** Whether a file is in the checked cache, handed to the tracker's loader (ADR-0232 D4: the root lends the cache). */
+    readonly hasFile: VisionDeps['hasFile'];
+    readonly loop: VisionLoopDeps;
+    readonly controller: VirtualController;
+    readonly say: (text: string) => void;
+    readonly alert: (text: string) => void;
+    readonly report: (line: string) => void;
+    readonly turnOff: () => void;
+    readonly openFeed: () => Promise<CameraFeed>;
+    readonly loadTracker?: (deps: VisionDeps) => Promise<FaceTrackerLoad>;
+}
+export declare function createFaceControl(d: FaceControlDeps): SwitchableControl;

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

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/face-control — PLAYING WITH THE FACE, PUT TOGETHER (ADR-0210 and its erratum, ADR-0212 §3; issue #191).
+//
+// The camera and the face tracker (platform/vision), the frame loop (platform/vision-loop), the Dev's face map (input/face-map), the
+// presses on the virtual controller with the source `rosto` (input/virtual-controller, ADR-0111), and what is drawn over the game. The
+// 📷 at its face position drives it (ADR-0215): it reads the face and draws the eyes, brows and lips — never the camera's picture
+// (ADR-0212); any other position lets the camera go.
+// · The rest measures itself (the Dev, 2026-09-16): the face still, looking at the middle, for 3 s in a row; until then the middle asks for
+//   it and nothing commands.
+// · A frame with no face lets go of every held action: a face that left the camera is not holding anything.
+// · What cannot start is said, written once in `problems`, and puts the 📷 back to off — the same promise as the eyes.
+import { faceScoresFromCategories, headTurn, createFaceMapReader, createFaceRest } from '../input/face-map.js';
+import { loadFaceTracker } from '../platform/vision.js';
+import { createVisionLoop } from '../platform/vision-loop.js';
+import { gazeFontPx } from './gaze-overlay.js';
+// 📌 THE SHAPE IS THE FAMILY'S (ADR-0221 step 7f): this module declares no `FaceControl` of its own — what it returns IS a
+// `SwitchableControl`, and the compiler sees it.
+const REST_MS = 3000;
+/** The middle's request while the rest is measured, and the face lines, mirrored so they move the way the child moves. */
+function draw(ctx, w, h, restLeftMs, lines, landmarks, say) {
+    ctx.clearRect(0, 0, w, h);
+    const f = gazeFontPx(w, h);
+    if (restLeftMs !== null) {
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'middle';
+        ctx.fillStyle = '#ffd23f';
+        ctx.shadowColor = '#000';
+        ctx.shadowBlur = 4;
+        ctx.font = `bold ${f}px system-ui`;
+        ctx.fillText(say('gaze.lookHere'), w / 2, h / 2 - f * 0.7);
+        ctx.font = `${f * 0.85}px system-ui`;
+        ctx.fillText(`${(restLeftMs / 1000).toFixed(1)} s`, w / 2, h / 2 + f * 0.8);
+        ctx.shadowBlur = 0;
+    }
+    if (lines && landmarks) {
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = Math.max(2, f / 8);
+        ctx.shadowColor = '#000';
+        ctx.shadowBlur = 3;
+        for (const { start, end } of [...lines.eyes, ...lines.brows, ...lines.lips]) {
+            const a = landmarks[start], b = landmarks[end];
+            if (!a || !b)
+                continue;
+            ctx.beginPath();
+            ctx.moveTo((1 - a.x) * w, a.y * h);
+            ctx.lineTo((1 - b.x) * w, b.y * h);
+            ctx.stroke();
+        }
+        ctx.shadowBlur = 0;
+    }
+}
+export function createFaceControl(d) {
+    const { t } = d;
+    const loadTracker = d.loadTracker ?? loadFaceTracker;
+    const said = new Set();
+    const once = (kind, line, spoken) => { if (!said.has(kind)) {
+        said.add(kind);
+        d.report(line);
+    } d.alert(spoken); };
+    let on = false, running = false, starting = null;
+    const current = () => on;
+    let tracker = null, feed = null, canvas = null;
+    let loop = null;
+    let rest = null, measure = createFaceRest({ restMs: REST_MS }), read = null;
+    const held = new Set();
+    const releaseAll = () => { for (const a of held)
+        d.controller.release(a, 'rosto'); held.clear(); };
+    const frame = (ms) => {
+        if (!tracker || !feed || !canvas || !feed.ready())
+            return;
+        const det = tracker.detect(feed.frame, ms);
+        const cats = det?.faceBlendshapes?.[0]?.categories;
+        const landmarks = det?.faceLandmarks?.[0];
+        const w = canvas.width = d.region.clientWidth, h = canvas.height = d.region.clientHeight;
+        const g = canvas.getContext('2d');
+        if (!cats) {
+            releaseAll();
+            draw(g, w, h, rest ? null : REST_MS, null, undefined, t);
+            return;
+        }
+        const scores = faceScoresFromCategories(cats);
+        const restLeft = measureRest(ms, scores, landmarks);
+        if (read)
+            holdExactly(new Set(read(ms, scores, landmarks).held)); // nothing commands before the rest: no reader yet
+        draw(g, w, h, restLeft, tracker.faceLines, landmarks, t);
+    };
+    /**
+     * Until the rest is measured, measure it on this frame — the head counts too — and answer how long the middle is still asked
+     * for. Once it is measured: the reader is made, «ready» is said ONCE, and the answer is `null` from then on.
+     */
+    const measureRest = (ms, scores, landmarks) => {
+        if (rest)
+            return null;
+        const m = measure(ms, scores, headTurn(landmarks).x);
+        if (!m.rest)
+            return Math.max(0, REST_MS - m.stillMs);
+        rest = m.rest;
+        read = createFaceMapReader({ rest });
+        d.say(t('sr.face.ready'));
+        return null;
+    };
+    /** Hold exactly what the reading holds now: let go of what left it, press what joined it — once. */
+    const holdExactly = (now) => {
+        for (const a of held)
+            if (!now.has(a)) {
+                d.controller.release(a, 'rosto');
+                held.delete(a);
+            }
+        for (const a of now)
+            if (!held.has(a)) {
+                d.controller.press(a, 'rosto');
+                held.add(a);
+            }
+    };
+    const health = (hh, fps) => {
+        if (hh === 'stalled')
+            once('stalled', 'face control: a second without a camera frame — meanwhile the child\'s face commands nothing; keep the tab in front and the camera free', t('sr.face.stopped'));
+        if (hh === 'slow')
+            once('slow', `face control: ${fps} frames a second, under 8 — expressions are missed and the child may not be answered; close other heavy tabs or use a lighter device`, t('sr.face.slow'));
+    };
+    const stop = () => {
+        loop?.stop();
+        loop = null;
+        releaseAll();
+        feed?.close();
+        feed = null;
+        tracker?.close();
+        tracker = null;
+        canvas?.remove();
+        canvas = null;
+        running = false;
+        rest = null;
+        read = null;
+    };
+    const start = async () => {
+        const load = await loadTracker({ base: d.base, hasFile: d.hasFile });
+        if (!load.ok) {
+            once('files', `face control: ${load.missing.join(', ')} not on this device — the child cannot play with the face; open the game once online so the install fetches them`, t('sr.face.needsInternet'));
+            d.turnOff();
+            return;
+        }
+        try {
+            feed = await d.openFeed();
+        }
+        catch {
+            load.tracker.close();
+            once('camera', 'face control: the camera did not open — the child cannot play with the face; allow the camera for this page, or plug one in', t('sr.face.noCamera'));
+            d.turnOff();
+            return;
+        }
+        tracker = load.tracker;
+        canvas = d.doc.createElement('canvas');
+        canvas.className = 'face-overlay';
+        canvas.setAttribute('aria-hidden', 'true');
+        Object.assign(canvas.style, { position: 'absolute', inset: '0', width: '100%', height: '100%', pointerEvents: 'none', zIndex: '5' });
+        d.region.appendChild(canvas);
+        rest = null;
+        read = null;
+        measure = createFaceRest({ restMs: REST_MS });
+        loop = createVisionLoop(d.loop, { onFrame: frame, onError: (e) => once('frame', `face control: a frame failed (${String(e)}) — the loop goes on, but a repeated failure means the child is not being read`, t('sr.face.stopped')), onHealth: health });
+        running = true;
+        d.say(t('sr.face.lookMiddle'));
+        loop.start();
+    };
+    return {
+        async apply(next) {
+            on = next;
+            if (starting)
+                await starting;
+            if (!on) {
+                if (running)
+                    stop();
+                return;
+            }
+            if (running)
+                return;
+            starting = start().finally(() => { starting = null; });
+            await starting;
+            if (!current() && running)
+                stop();
+        },
+    };
+}

package/dist-pkg/ui/focus-trap.d.ts

@@ -1,71 +1,61 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 /**
- * O que conta como focável. Deliberadamente SEM `[contenteditable]` e sem `tabindex` positivo: os dois
- * existem, mas não aparecem em nenhum diálogo desta engine (conferido), e um seletor que promete mais do que
- * foi verificado é um seletor que mente na próxima revisão.
+ * What counts as focusable. Deliberately WITHOUT `[contenteditable]` and without positive `tabindex`: both exist, but
+ * appear in no dialog of this engine, and a selector that promises more than was verified is a selector that lies at
+ * the next review.
  */
-export declare const SELETOR_FOCAVEL: string;
+export declare const FOCUSABLE_SELECTOR: string;
 /**
- * Para onde o foco tem de ir quando o Tab está prestes a sair do diálogo — ou `null` quando não há nada a
- * fazer e o navegador deve seguir sozinho.
+ * Where focus has to go when Tab is about to leave the dialog — or `null` when there is nothing to do and the browser
+ * should carry on by itself.
  *
- * Os quatro casos, e o terceiro é a razão de isto existir:
+ * The four cases, and the third is why this exists:
  *
- *   1. lista VAZIA → `null`. Um diálogo sem nada focável é um defeito do diálogo, e prender o foco nele
- *      deixaria a criança sem saída nenhuma. Melhor deixar sair do que trancar num lugar mudo.
- *   2. o foco está no ÚLTIMO e vai para a frente → volta ao primeiro; no PRIMEIRO e vai para trás → vai ao
- *      último. É o ciclo, que é o que «armadilha» quer dizer.
- *   3. ⚠️ o foco está FORA da lista → traz de volta. É o caso que os outros três não cobrem: o foco pode já
- *      ter escapado antes de esta armadilha existir, ou por um clique no tabuleiro, ou porque o diálogo
- *      abriu sem focar nada. Sem ele a armadilha só funciona para quem já estava dentro.
- *   4. o foco está no MEIO → `null`, e o navegador caminha. Ver o comentário do cabeçalho.
+ *   1. EMPTY list → `null`. A dialog with nothing focusable is the dialog's defect, and trapping focus in it would
+ *      leave the child with no way out at all. Better to let it leave than to lock it in a mute place.
+ *   2. focus on the LAST going forward → back to the first; on the FIRST going backwards → to the last. That is the
+ *      cycle, which is what "trap" means.
+ *   3. ⚠️ focus OUTSIDE the list → bring it back. The case the other three do not cover: focus may have escaped by a
+ *      click on the board, or because the dialog opened without focusing anything. Without it the trap only works for
+ *      whoever was already inside.
+ *   4. focus in the MIDDLE → `null`, and the browser walks. See the header.
  */
-export declare function proximoNaArmadilha<T>(focaveis: readonly T[], atual: T | null, paraTras: boolean): T | null;
-interface AlvoDeEvento {
-    addEventListener: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
-    removeEventListener?: (tipo: 'keydown', fn: (e: KeyboardEvent) => void, captura?: boolean) => void;
+export declare function nextInTrap<T>(focusables: readonly T[], current: T | null, backwards: boolean): T | null;
+interface KeydownTarget {
+    addEventListener: (kind: 'keydown', fn: (e: KeyboardEvent) => void, capture?: boolean) => void;
+    removeEventListener?: (kind: 'keydown', fn: (e: KeyboardEvent) => void, capture?: boolean) => void;
 }
 export interface FocusTrapCtx {
-    /** O diálogo VISÍVEL mais alto da pilha, ou `null`. É o `topVisibleOverlay` de `ui/settings-panel`. */
-    overlayDeCima: () => HTMLElement | null;
-    /** Quem tem o foco agora — `() => document.activeElement`. Injetado: o project node não tem documento. */
-    focoAtual: () => Element | null;
-    /** Os focáveis DENTRO do diálogo, na ordem do documento e já filtrados por visibilidade. */
-    focaveisDe: (dentro: HTMLElement) => HTMLElement[];
-    win: AlvoDeEvento;
+    /** The highest VISIBLE dialog in the stack, or `null`. It is `ui/settings-panel`'s `topVisibleOverlay`. */
+    topOverlay: () => HTMLElement | null;
+    /** Who has focus now — `() => document.activeElement`. Injected: the node project has no document. */
+    currentFocus: () => Element | null;
+    /** The focusables INSIDE the dialog, in document order and already filtered by visibility. */
+    focusablesIn: (isInside: HTMLElement) => HTMLElement[];
+    win: KeydownTarget;
 }
 export interface FocusTrapApi {
-    /** O manipulador, exposto para o teste o chamar sem instalar nada. */
-    aoTeclar: (e: KeyboardEvent) => void;
-    /** Instala na fase de CAPTURA, pelo mesmo motivo do `menu-nav`: ver a tecla antes de quem está por baixo. */
+    /** The handler, exposed so the test can call it without installing anything. */
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Installs in the CAPTURE phase, for the same reason as `menu-nav`: see the key before whoever is underneath. */
     attach: () => void;
     /**
-     * Desinstala.
+     * Uninstalls.
      *
-     * ⚠️ ELE NASCEU DE UM TESTE QUE REPROVOU, e não de simetria: dois casos no mesmo ficheiro instalaram duas
-     * armadilhas na mesma janela, e a primeira continuou a prender o foco durante o segundo — o caso «sem
-     * diálogo aberto o Tab é do jogo» ficou vermelho por causa de uma armadilha que já devia ter saído.
-     *
-     * O que isso mostra vale fora do teste: uma armadilha que não se desinstala é um vazamento para qualquer
-     * página que monte a engine duas vezes — o `demos`, que troca de jogo sem recarregar, é exatamente isso.
+     * ⚠️ A trap that does not uninstall is a leak for any page that mounts the engine twice — one that switches games
+     * without reloading is exactly that: the first trap keeps holding focus during the second.
      */
     detach: () => void;
 }
 export declare function initFocusTrap(ctx: FocusTrapCtx): FocusTrapApi;
 /**
- * Os focáveis de um contêiner, no navegador. Vive aqui e não na raiz para as duas raízes não escreverem duas
- * versões que divergiriam em silêncio — uma prenderia o foco e a outra deixaria escapar, no mesmo produto.
- *
- * ⚠️ A VISIBILIDADE É POR `getClientRects()`, e não por `offsetParent`.
- *
- * ⚠️ E A PRIMEIRA VERSÃO DESTE COMENTÁRIO ESTAVA ERRADA, o que vale mais registrar do que apagar: ele dizia
- * que `offsetParent` é `null` para «qualquer elemento em `position: fixed`». Não é — é `null` para o elemento
- * FIXO EM SI, e os descendentes dele devolvem o próprio contêiner. O teste de navegador reprovou a afirmação,
- * que é exatamente o que um teste tem de fazer com uma justificativa inventada.
+ * The focusables of a container, in the browser. It lives here and not in a root so that two roots do not write two
+ * versions that would drift silently — one trapping focus and the other letting it escape, in the same product.
  *
- * A razão verdadeira é mais simples e mais forte: `getClientRects()` responde *«isto desenha alguma caixa?»*,
- * o que cobre `display:none` em QUALQUER ancestral, elementos de tamanho zero e o caso do contêiner fixo —
- * sem que quem lê precise de saber em que casos `offsetParent` tem buracos.
+ * ⚠️ VISIBILITY IS BY `getClientRects()`, not by `offsetParent`: `getClientRects()` answers "does this draw any box?",
+ * which covers `display:none` on ANY ancestor, zero-size elements and the fixed-container case — without the reader
+ * needing to know where `offsetParent` has holes (it is `null` for a FIXED element itself, while its descendants return
+ * the container).
  */
-export declare function focaveisNoDom(dentro: HTMLElement): HTMLElement[];
+export declare function focusablesInDom(isInside: HTMLElement): HTMLElement[];
 export {};