@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/dom.js

@@ -1,38 +1,4 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/dom.ts — atalhos de seleção do DOM, usados em toda a UI (menus/HUD/pausa/quiz/opções). PURO no import:
-// só define as funções (não toca no DOM → importável em node). $ = querySelector; $$ = querySelectorAll
-// como Array. Genéricos: $<HTMLInputElement>('#x') já tipa o retorno. (Fase 2.27 / Tier 1)
-//
-// DEIXOU DE SER FOLHA no item 14, e de propósito: passou a importar `core/i18n` para que `toggleLabel` (o
-// texto do botão de alternância) more ao lado do `toggleBtn` (a classe e o `aria-pressed`). A propriedade que
-// importa — importável em node, sem I/O no import — continua valendo; o que se perdeu foi a contagem de zero
-// dependências, e o que se ganhou está escrito no comentário de `toggleLabel`.
-import { t } from '../core/i18n.js';
-// O PADRAO E `HTMLElement`, NAO `Element`, e a diferenca aparece em dezessete pontos de chamada: `.hidden`,
-// `.focus()` e `.value` nao existem em `Element`, e sao exatamente o que uma aplicacao faz com o que
-// seleciona. `Element` e o padrao do lib.dom porque `querySelector` tambem serve para SVG e MathML —
-// nenhum seletor deste projeto pega um desses (conferido). Quem precisar de um tipo mais estreito passa
-// o parametro: `$<HTMLSelectElement>('#pad-design')`.
-/**
- * ⚠️ RESOLVIDO POR `globalThis` E NÃO PELO GLOBAL CRU, e a diferença é entre devolver `null` e LANÇAR.
- *
- * `document.querySelector(...)` com `document` inexistente dá `ReferenceError` — não `undefined` —, e a
- * assinatura destas duas funções promete `T | null`. Uma consulta que lança onde promete `null` é um defeito
- * pela própria assinatura, e ele viajava longe: medido em 2026-09-08, o `core/a11y-sr.srAlert` chama o `$`
- * daqui, e o `createGame` chama o `srAlert` ao mostrar o aviso de alcance — logo bootar a engine contra um
- * documento INJECTADO (um iframe, um editor ao lado do jogo, um teste) rebentava o boot inteiro num anúncio.
- *
- * 📌 É o ACHADO 15 do `boot/create-game` outra vez, e sobreviveu pela mesma razão: enquanto toda raiz era um
- * `main.ts` num navegador, o global ERA o documento certo. `globalThis.document` é a mesma coisa onde ele
- * existe, e é `undefined` — em vez de explosão — onde não existe.
- *
- * ⚠️ E ELAS CONTINUAM A OLHAR PARA O GLOBAL, de propósito: quem precisa de consultar OUTRO documento injecta
- * o seu (`create-game` tem um `$` próprio ligado ao `doc` do hospedeiro, e o `ui/pause-icons` tem o
- * `docDaMontagem`). O que este conserto muda não é ONDE se procura — é o que acontece quando não há onde.
- */
-const docGlobal = () => globalThis.document;
-export const $ = (s) => docGlobal()?.querySelector(s) ?? null;
-export const $$ = (s) => [...(docGlobal()?.querySelectorAll(s) ?? [])];
 /**
  * Reflects an on/off state onto a toggle button: the visual class AND `aria-pressed`.
  * Lives here because the two must never drift apart — a button that looks pressed but does not
@@ -45,21 +11,18 @@ export function toggleBtn(b, on) {
     b.setAttribute('aria-pressed', String(on));
 }
 /**
- * O TEXTO do botão de alternância: '❚❚ Ligado' / '▶ Desligado'.
- *
- * Mora aqui pelo mesmo motivo do `toggleBtn` logo acima — os dois são as duas metades do mesmo gesto, e a
- * nota daquela função diz que elas "não podem se separar". Elas tinham se separado em TREZE cópias, em nove
- * arquivos, e dois deles declaravam um helper que se chamava compartilhado e servia um chamador só
- * (`settings-empathy.toggleLabel` e `settings-motor.onOffLabel`, ambos apagados agora).
+ * The TEXT of a toggle button: 'On' / 'Off' in English.
  *
- * O custo dessa dispersão não era estético: com o texto em treze lugares, traduzir o jogo exigiria achar os
- * treze, e esquecer um deixaria um botão em português no meio do inglês — sem erro, sem teste vermelho.
+ * It lives here for the same reason as `toggleBtn` just above — the two are halves of one gesture, and must not
+ * drift apart. A text copied into each panel is a text that translating the game has to find everywhere, and the
+ * one copy it misses leaves a button in the wrong language — with no error and no red test.
  */
-export function toggleLabel(on) {
+export function toggleLabel(t, on) {
     return t(on ? 'ui.toggle.on' : 'ui.toggle.off');
 }
-/** O `aria-label` da mesma alternância: '{alvo}: ligado'. Separado do rótulo visível porque o leitor de tela
- *  precisa do NOME do alvo junto, e a tela não (o nome já está na linha ao lado do botão). */
-export function toggleAria(alvo, on) {
-    return t(on ? 'ui.toggle.ariaOn' : 'ui.toggle.ariaOff', { alvo });
+/** The `aria-label` of the same toggle: '{alvo}: on' (`{alvo}` is the dictionary's interpolation key). Separate from
+ *  the visible label because a screen reader needs the NAME of the target with it, and the screen does not (the
+ *  name is already on the row beside the button). */
+export function toggleAria(t, target, on) {
+    return t(on ? 'ui.toggle.ariaOn' : 'ui.toggle.ariaOff', { alvo: target });
 }

package/dist-pkg/ui/drawing-problems.d.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Scale } from './layout.js';
+export interface DrawingProblemsCtx {
+    /** `#game-region`, read at EVERY call — see the note at the top of this file. */
+    readonly region: () => HTMLElement | null;
+    /** The accessibility bar, or `null` where the game declined it. Read at every call, for the same reason. */
+    readonly bar: () => Element | null;
+    /** The scale the engine forced, or `null` before the first layout has run. */
+    readonly scale: () => Scale | null;
+    /** `window.getComputedStyle`, absent in a host that has none — then a node is counted rather than guessed about. */
+    readonly computedStyle?: (el: Element) => CSSStyleDeclaration;
+}
+/**
+ * ADR-0163 rule 4, second half: the text and the targets the CARTRIDGE draws under the floor, named — read when `problems` is.
+ * `null` when there is nothing to say, which is what a clean page answers.
+ */
+export declare function drawnBelowTheFloor(ctx: DrawingProblemsCtx): string | null;
+/**
+ * The nodes that PAINT over the accessibility bar's rectangle (ADR-0148 §3).
+ *
+ * 📏 ONLY WHAT PAINTS, and it was measured in `dist/quiz.html`: the quiz was accused at every boot because `#quiz-app` — a
+ * transparent box the size of the region, whose top padding IS the bar's room — intersects the bar's rectangle and draws
+ * nothing there. A node counts when it has text of its own, is a control or a medium, or paints a background.
+ */
+export declare function barIntruderProblems(ctx: DrawingProblemsCtx): string[];

package/dist-pkg/ui/drawing-problems.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/drawing-problems — WHAT A CARTRIDGE DREW THAT THE CHILD PAYS FOR, named (ADR-0163 rule 4, ADR-0148 §3; issue #203).
+//
+// Two questions the engine asks about its own region, and both answer with the sentence a `problems` line needs: text and
+// targets drawn UNDER the floor, and the nodes drawn OVER the accessibility bar. They are one subject — the engine measuring
+// what somebody else drew — and they lived inside `boot/create-game`, which is why this module exists: 📏 that file reached
+// 2185 lines and 330 decision nodes (ADR-0221), and the debt is paid by SUBJECT, never by slicing.
+//
+// ⚠️ THE READERS ARE FUNCTIONS AND NOT VALUES, and that is the whole care in this file. `#game-region`, the bar and the applied
+// scale are all things the root REPLACES: a `mount()` swaps the cartridge and the bar is built after the root is. Taking them
+// as values here would freeze the first answer and report, forever, about a region that is no longer on the page — silently,
+// because a stale element still answers `getBoundingClientRect()`.
+import { barIntruders, belowFloor, minimumTarget } from './layout.js';
+/** The engine's OWN nodes inside the region — their sizes are held by their own gates — and what is not drawn for the eye. */
+const ENGINE_NODES = '#title-icons, .screen-pause, .overlay, #touch-controls, .rodape-da-tela, .pausa-rapida, #incl-parou, .sr-only, .hud-faixa, .hud-row';
+/** What a finger is meant to hit; anything else has no target floor to fail. */
+const TOUCH_TARGET = 'button, a[href], input:not([type="hidden"]), select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])';
+/**
+ * A node named the way a developer finds it: `tag#id.firstClass`.
+ *
+ * 📌 It is NOT exported, and the `exports-without-consumer` gate is what said so: exporting it would publish a name only this
+ * file uses, and an export with no consumer is surface somebody has to maintain with nobody needing it (ADR-0170 §3).
+ */
+function nodeName(el) {
+    return el.tagName.toLowerCase() + (el.id ? `#${el.id}` : '')
+        + (el.className ? `.${String(el.className).trim().split(/\s+/)[0]}` : '');
+}
+/**
+ * ADR-0163 rule 4, second half: the text and the targets the CARTRIDGE draws under the floor, named — read when `problems` is.
+ * `null` when there is nothing to say, which is what a clean page answers.
+ */
+export function drawnBelowTheFloor(ctx) {
+    const region = ctx.region();
+    const scale = ctx.scale();
+    if (!scale || !region || typeof region.querySelectorAll !== 'function' || !ctx.computedStyle)
+        return null;
+    const nodes = [...region.querySelectorAll('*')].map((el) => {
+        const b = el.getBoundingClientRect();
+        const hasText = [...el.childNodes].some((c) => c.nodeType === 3 && (c.textContent ?? '').trim() !== '');
+        return {
+            name: nodeName(el),
+            daEngine: el.closest(ENGINE_NODES) !== null,
+            fontPx: hasText && b.width > 0 && b.height > 0 ? parseFloat(ctx.computedStyle(el).fontSize) : null,
+            target: el.matches(TOUCH_TARGET) ? { w: b.width, h: b.height } : null,
+        };
+    });
+    const { text: smallText, targets: smallTargets } = belowFloor(nodes, scale.k);
+    if (!smallText.length && !smallTargets.length)
+        return null;
+    const k = minimumTarget(scale.k) / 22;
+    const parts = [
+        smallText.length ? `text under ${8 * k} px (${smallText.slice(0, 4).join(', ')})` : '',
+        smallTargets.length ? `targets under ${22 * k} px (${smallTargets.slice(0, 4).join(', ')})` : '',
+    ].filter(Boolean);
+    return `the cartridge draws ${parts.join(' and ')} in #game-region: a child with low vision or unsteady hands cannot `
+        + 'read or hit them — text and targets start at 16 and 44 px at 640×360 and grow with the scale (ADR-0163): size them '
+        + 'from `--ui-fs` and `--alvo-min`';
+}
+/**
+ * The nodes that PAINT over the accessibility bar's rectangle (ADR-0148 §3).
+ *
+ * 📏 ONLY WHAT PAINTS, and it was measured in `dist/quiz.html`: the quiz was accused at every boot because `#quiz-app` — a
+ * transparent box the size of the region, whose top padding IS the bar's room — intersects the bar's rectangle and draws
+ * nothing there. A node counts when it has text of its own, is a control or a medium, or paints a background.
+ */
+export function barIntruderProblems(ctx) {
+    const region = ctx.region();
+    const bar = ctx.bar();
+    if (!bar || !region || typeof bar.getBoundingClientRect !== 'function')
+        return [];
+    const boxOf = (el) => {
+        const b = el.getBoundingClientRect();
+        return { x: b.x, y: b.y, w: b.width, h: b.height };
+    };
+    const paints = (el) => {
+        if ([...el.childNodes].some((c) => c.nodeType === 3 && (c.textContent ?? '').trim() !== ''))
+            return true;
+        if (/^(img|canvas|svg|video|input|button|select|textarea)$/i.test(el.tagName))
+            return true;
+        if (!ctx.computedStyle)
+            return true; // no way to tell: count it, as before
+        const cs = ctx.computedStyle(el);
+        return (cs.backgroundColor !== '' && cs.backgroundColor !== 'transparent' && cs.backgroundColor !== 'rgba(0, 0, 0, 0)')
+            || (cs.backgroundImage !== '' && cs.backgroundImage !== 'none');
+    };
+    const nodes = [...region.querySelectorAll('*')].filter((el) => paints(el)).map((el) => ({
+        name: nodeName(el),
+        box: boxOf(el),
+        // the engine's HUD bands and HUD row are placed by the ENGINE: if one reaches the bar, that is the engine's defect and
+        // not the game's
+        isBar: el === bar || bar.contains(el) || el.closest('.hud-faixa, .hud-row') !== null,
+    }));
+    return barIntruders(boxOf(bar), nodes);
+}

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, a runtime that does not load,
+//   the camera refused, frames that stop or crawl (`ui/camera-control.startCameraReader` for the first three). 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';
+import { startCameraReader } from './camera-control.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;
+    };
+    /** Nothing started: said, written once, and the 📷 back to off — unless it already moved on, and then nobody is waiting (as the 👄). */
+    const failed = (kind, line, spoken) => {
+        if (!current())
+            return;
+        once(kind, line, spoken);
+        d.turnOff();
+    };
+    const start = async () => {
+        const opened = await startCameraReader({
+            subject: 'eye control', loses: 'play with the eyes',
+            spoken: { files: () => t('sr.eyes.needsInternet'), runtime: () => t('sr.eyes.failed'), camera: () => t('sr.eyes.noCamera') },
+        }, { load: () => loadTracker({ base: d.base, hasFile: d.hasFile }), openFeed, failed });
+        if (!opened)
+            return;
+        tracker = opened.tracker;
+        feed = opened.feed;
+        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';
+import { startCameraReader } from './camera-control.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;
+    };
+    /** Nothing started: said, written once, and the 📷 back to off — unless it already moved on, and then nobody is waiting (as the 👄). */
+    const failed = (kind, line, spoken) => {
+        if (!current())
+            return;
+        once(kind, line, spoken);
+        d.turnOff();
+    };
+    const start = async () => {
+        const opened = await startCameraReader({
+            subject: 'face control', loses: 'play with the face',
+            spoken: { files: () => t('sr.face.needsInternet'), runtime: () => t('sr.face.failed'), camera: () => t('sr.face.noCamera') },
+        }, { load: () => loadTracker({ base: d.base, hasFile: d.hasFile }), openFeed: d.openFeed, failed });
+        if (!opened)
+            return;
+        tracker = opened.tracker;
+        feed = opened.feed;
+        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();
+        },
+    };
+}