@the-inclusionist/engine 9.0.0 → 10.0.0

package/dist-pkg/ui/game-options.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { controlRow, mountSteps, updateSteps, nextStep } from './panel-widgets.js';
+import { toggleLabel } from './dom.js';
+const KINDS = ['steps', 'list', 'switch'];
+/** ADR-0130 erratum, rule 3: steps cycle among FEW positions — up to five; past that, a list. */
+const MAX_STEPS = 5;
+/** Why a `gameOptions` declaration is malformed; empty when it is well formed. Absent is well formed: no options of its own. */
+export function gameOptionsProblems(options) {
+    if (options === undefined)
+        return [];
+    if (!Array.isArray(options))
+        return ['gameOptions must be a list of rows'];
+    // a repeated id is only wrong the second time, so the ids seen so far travel from row to row
+    const ids = new Set();
+    return options.flatMap((o, i) => rowProblems(o, `gameOptions[${i}]`, ids));
+}
+/** What is wrong with one row, in the order a reader of the declaration meets it: the row, its id, its fields, its positions. */
+function rowProblems(o, at, ids) {
+    if (!o || typeof o !== 'object')
+        return [`${at} must be a row`];
+    const out = [...idProblems(o, at, ids), ...FIELD_CHECKS.filter(([holds]) => !holds(o)).map(([, says]) => `${at}.${says}`)];
+    if (o.kind === 'steps' || o.kind === 'list')
+        out.push(...valuesProblems(o, at));
+    return out;
+}
+function idProblems(o, at, ids) {
+    if (typeof o.id !== 'string' || !o.id.trim())
+        return [`${at}.id must name the row`];
+    if (ids.has(o.id))
+        return [`${at}.id «${o.id}» repeats an earlier row's`];
+    ids.add(o.id);
+    return [];
+}
+/** Each field a row must have, and what is said when it does not: a row comes from outside the engine, so its TYPE is checked. */
+const FIELD_CHECKS = [
+    [(o) => KINDS.includes(o.kind), `kind must be one of ${KINDS.join(', ')}`],
+    [(o) => typeof o.label === 'string' && !!o.label.trim(), "label must say what the row is, in the game's words"],
+    [(o) => o.hint === undefined || typeof o.hint === 'string', 'hint must be text'],
+    [(o) => typeof o.read === 'function', 'read must be a function returning the value in use'],
+    [(o) => typeof o.write === 'function', 'write must be a function taking the new value'],
+];
+/** The positions of a steps or list row: at least two, at most five for steps, each with a value and a label, none repeated. */
+function valuesProblems(o, at) {
+    const values = o.values;
+    if (!Array.isArray(values) || values.length < 2)
+        return [`${at}.values must hold at least two positions`];
+    const out = o.kind === 'steps' && values.length > MAX_STEPS
+        ? [`${at}.values holds ${values.length} steps: steps hold at most five positions — past that, declare a list (ADR-0130)`] : [];
+    const seen = new Set();
+    values.forEach((v, j) => {
+        const problem = positionProblem(v, `${at}.values[${j}]`, seen);
+        if (problem)
+            out.push(problem);
+    });
+    return out;
+}
+function positionProblem(v, at, seen) {
+    if (!v || typeof v.value !== 'string' || typeof v.label !== 'string' || !v.label.trim())
+        return `${at} must have a value and a label`;
+    if (seen.has(v.value))
+        return `${at} «${v.value}» repeats an earlier position`;
+    seen.add(v.value);
+    return null;
+}
+/**
+ * Draws the rows into `list`, replacing what was there — the rows are the CURRENT cartridge's, and `mount()` may have
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, at drawing and after each write.
+ */
+export function drawGameOptions(ctx, list, options) {
+    const { t } = ctx;
+    while (list.firstChild)
+        list.removeChild(list.firstChild); // node by node: no markup sink, and a host without `replaceChildren` still clears
+    for (const o of options) {
+        const id = `game-option-${o.id}`;
+        if (o.kind === 'switch') {
+            const { row: rowNode, control: switchButton } = controlRow(ctx, { id, label: o.label, hint: o.hint });
+            const reflect = () => {
+                const on = o.read();
+                switchButton.classList.toggle('is-on', on);
+                switchButton.setAttribute('aria-pressed', String(on));
+                switchButton.textContent = toggleLabel(t, on);
+                return on;
+            };
+            reflect();
+            switchButton.addEventListener('click', () => {
+                o.write(!o.read());
+                ctx.say(`${o.label}: ${toggleLabel(t, reflect())}`);
+            });
+            list.appendChild(rowNode);
+            continue;
+        }
+        const labelOf = (chosen) => o.values.find((v) => v.value === chosen)?.label ?? chosen;
+        if (o.kind === 'list') {
+            const { row: rowNode, control: control } = controlRow(ctx, { id, label: o.label, hint: o.hint, shape: 'escolha' });
+            const sel = control;
+            for (const v of o.values) {
+                const op = ctx.create('option');
+                op.value = v.value;
+                op.textContent = v.label;
+                sel.appendChild(op);
+            }
+            sel.value = o.read();
+            sel.addEventListener('change', () => {
+                o.write(sel.value);
+                sel.value = o.read();
+                ctx.say(`${o.label}: ${labelOf(sel.value)}`);
+            });
+            list.appendChild(rowNode);
+            continue;
+        }
+        // steps: the row IS the control, «◀ Label: value ▶» (ADR-0130 erratum); the hint rides in the row for the footer
+        const selectedIndex = () => Math.max(0, o.values.findIndex((v) => v.value === o.read()));
+        const spec = () => ({ label: o.label, values: o.values.map((v) => v.label), current: selectedIndex() });
+        const rowNode = ctx.create('div');
+        rowNode.className = 'ctrl-row ctrl-row--passos';
+        const envelope = ctx.create('span');
+        if (o.hint) {
+            const explanation = ctx.create('span');
+            explanation.className = 'opt-hint';
+            explanation.textContent = o.hint;
+            envelope.appendChild(explanation);
+        }
+        rowNode.appendChild(envelope);
+        const stepper = mountSteps(ctx, spec());
+        stepper.id = id;
+        rowNode.appendChild(stepper);
+        stepper.addEventListener('passo', (ev) => {
+            const currentIndex = selectedIndex();
+            const nextIndex = nextStep(currentIndex, o.values.length, ev.detail);
+            if (nextIndex === currentIndex)
+                return; // at the wall nothing moved, and nothing is said
+            o.write(o.values[nextIndex].value);
+            updateSteps(stepper, spec());
+            ctx.say(`${o.label}: ${labelOf(o.read())}`);
+        });
+        list.appendChild(rowNode);
+    }
+}

package/dist-pkg/ui/gaze-overlay.d.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { GazeZone } from '../input/gaze-relative.js';
+import { type GazePreview } from '../input/gaze-cycle.js';
+import type { EyeLines } from '../platform/vision.js';
+export type GazeRegion = GazeZone | 'middle';
+/** Centre x, centre y, width, height — fractions of the game region. */
+export declare const GAZE_REGIONS: {
+    readonly [R in GazeRegion]: readonly [number, number, number, number];
+};
+export type ButtonShape = 'triangle' | 'circle' | 'cross' | 'square';
+/** Each zone's face button: the Xbox letter and the PlayStation shape of the button on that side (ADR-0213 erratum: north is «Y»). */
+export declare const FACE_BUTTON: {
+    readonly [Z in GazeZone]: readonly [string, ButtonShape];
+};
+export declare const SHOULDER: {
+    readonly [Z in GazeZone]: string;
+};
+/**
+ * Lucide `arrow-up`, `arrow-right`, `arrow-down`, `arrow-left`, 24×24 path data. Lucide's LICENSE lists these four as derived from Feather,
+ * so the notice they carry is Feather's MIT (Cole Bemis), not Lucide's ISC — credited in docs/CREDITS.md.
+ */
+export declare const LUCIDE_ARROWS: {
+    readonly [Z in GazeZone]: readonly string[];
+};
+export interface GazeView {
+    readonly zone: GazeZone | null;
+    readonly armed: boolean;
+    readonly preparing: boolean;
+    readonly preview: GazePreview | null;
+    readonly restReady: boolean;
+    /** While the rest is being measured: how long it still needs. */
+    readonly restLeftMs?: number;
+}
+export type RegionShows = {
+    readonly kind: 'nothing';
+} | {
+    readonly kind: 'text';
+    readonly key: string;
+} | {
+    readonly kind: 'arrow';
+} | {
+    readonly kind: 'button';
+} | {
+    readonly kind: 'shoulder';
+    readonly label: string;
+};
+export declare function whatRegionShows(region: GazeRegion, v: GazeView): RegionShows;
+/** 16 px on a 720×360 game region, in proportion to it, bounded by the tighter side. */
+export declare const gazeFontPx: (width: number, height: number) => number;
+type Ctx = CanvasRenderingContext2D;
+export interface GazeOverlayOptions {
+    /** The face of this frame, to highlight the eyes and brows. */
+    readonly face?: {
+        readonly landmarks: ReadonlyArray<{
+            readonly x: number;
+            readonly y: number;
+        }>;
+        readonly lines: EyeLines;
+    } | null;
+}
+/** Draws the five regions and the face's lines. 	 is the root's translator (ADR-0232 D3): the regions' words are its keys. */
+export declare function drawGazeOverlay(t: Translate, ctx: Ctx, width: number, height: number, view: GazeView, { face }?: GazeOverlayOptions): void;
+export {};

package/dist-pkg/ui/gaze-overlay.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/gaze-overlay — HOW THE EYE CONTROL SHOWS ITSELF OVER THE GAME (ADR-0213 §6; issue #194).
+//
+// Five regions: four at the edges the eyes travel to, and the middle, where the child looks to measure the rest. A region says something
+// only while the gaze is in it, so the text is always where the eyes already are:
+// · a look that PREPARES (it did not come from the opposite side) says where to go now — up «go down!», right «go left!», and so on;
+// · a look that came from the opposite side walks its cycle: «Loading...» (settling, and the cancel step) → the direction's Lucide arrow →
+//   the face button, as the Xbox letter and the PlayStation shape each inside a circle → the shoulder inside a square → round again;
+// · the middle asks to be looked at, with the seconds left, while the rest is being measured.
+// Text is 16 px on a 720×360 game region and grows with it. The regions are outlined, never hatched (ADR-0215: the 📷's eyes position);
+// the eyes and brows are the landmark lines only — never the camera's picture (ADR-0212) — mirrored, so they move the way the child moves.
+// What a region shows is decided by `whatRegionShows`, plain data; `drawGazeOverlay` only follows it. Places and colours: interface-log.
+import { GAZE_GROUPS, CANCEL } from '../input/gaze-cycle.js';
+/** Centre x, centre y, width, height — fractions of the game region. */
+export const GAZE_REGIONS = {
+    up: [0.5, 0.1, 0.26, 0.18], right: [0.87, 0.5, 0.24, 0.24], down: [0.5, 0.9, 0.26, 0.18], left: [0.13, 0.5, 0.24, 0.24],
+    middle: [0.5, 0.5, 0.24, 0.26],
+};
+/** Each zone's face button: the Xbox letter and the PlayStation shape of the button on that side (ADR-0213 erratum: north is «Y»). */
+export const FACE_BUTTON = {
+    up: ['Y', 'triangle'], right: ['B', 'circle'], down: ['A', 'cross'], left: ['X', 'square'],
+};
+export const SHOULDER = { up: 'R1', right: 'R2', down: 'L2', left: 'L1' };
+/**
+ * Lucide `arrow-up`, `arrow-right`, `arrow-down`, `arrow-left`, 24×24 path data. Lucide's LICENSE lists these four as derived from Feather,
+ * so the notice they carry is Feather's MIT (Cole Bemis), not Lucide's ISC — credited in docs/CREDITS.md.
+ */
+export const LUCIDE_ARROWS = {
+    up: ['m5 12 7-7 7 7', 'M12 19V5'], right: ['M5 12h14', 'm12 5 7 7-7 7'], down: ['M12 5v14', 'm19 12-7 7-7-7'], left: ['m12 19-7-7 7-7', 'M19 12H5'],
+};
+const NOTHING = { kind: 'nothing' };
+/**
+ * What a preview shows, by its place in the zone's group (`GAZE_GROUPS`): the direction, the face button, the shoulder. The
+ * ORDER is the group's, so a place the table has no row for — an item from another zone's group — shows nothing.
+ */
+const PREVIEW_SHOWS = [
+    () => ({ kind: 'arrow' }),
+    () => ({ kind: 'button' }),
+    (region) => ({ kind: 'shoulder', label: SHOULDER[region] }),
+];
+export function whatRegionShows(region, v) {
+    if (region === 'middle')
+        return v.restReady ? { kind: 'nothing' } : { kind: 'text', key: 'gaze.lookHere' };
+    if (region !== v.zone)
+        return { kind: 'nothing' };
+    if (!v.armed)
+        return v.preparing ? { kind: 'text', key: `gaze.prepare.${region}` } : { kind: 'nothing' };
+    if (!v.preview || v.preview.item === CANCEL)
+        return { kind: 'text', key: 'gaze.loading' };
+    const i = GAZE_GROUPS[region].indexOf(v.preview.item);
+    return PREVIEW_SHOWS[i]?.(region) ?? NOTHING;
+}
+/** 16 px on a 720×360 game region, in proportion to it, bounded by the tighter side. */
+export const gazeFontPx = (width, height) => 16 * Math.min(width / 720, height / 360);
+const FAINT = 'rgba(234,242,248,0.35)', PREPARE = '#ffd23f', ARMED = '#3ddc84', LINES = '#ffffff';
+function shape(ctx, s, x, y, r) {
+    ctx.beginPath();
+    if (s === 'triangle') {
+        ctx.moveTo(x, y - r);
+        ctx.lineTo(x + r * 0.87, y + r * 0.5);
+        ctx.lineTo(x - r * 0.87, y + r * 0.5);
+        ctx.closePath();
+    }
+    else if (s === 'circle')
+        ctx.arc(x, y, r, 0, 2 * Math.PI);
+    else if (s === 'square')
+        ctx.rect(x - r * 0.75, y - r * 0.75, r * 1.5, r * 1.5);
+    else {
+        ctx.moveTo(x - r * 0.7, y - r * 0.7);
+        ctx.lineTo(x + r * 0.7, y + r * 0.7);
+        ctx.moveTo(x + r * 0.7, y - r * 0.7);
+        ctx.lineTo(x - r * 0.7, y + r * 0.7);
+    }
+    ctx.stroke();
+}
+/** Draws the five regions and the face's lines. 	 is the root's translator (ADR-0232 D3): the regions' words are its keys. */
+export function drawGazeOverlay(t, ctx, width, height, view, { face = null } = {}) {
+    ctx.clearRect(0, 0, width, height);
+    const f = gazeFontPx(width, height);
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+    for (const region of Object.keys(GAZE_REGIONS))
+        drawRegion(ctx, region, width, height, f, view, t);
+    if (face)
+        drawFaceLines(ctx, face, width, height, f);
+}
+/** One region: its outline — faint when it shows nothing, green when armed (never the middle), yellow otherwise — and what it shows. */
+function drawRegion(ctx, region, width, height, f, view, say) {
+    const [fx, fy, fw, fh] = GAZE_REGIONS[region];
+    const w = fw * width, h = fh * height, cx = fx * width, cy = fy * height;
+    const shows = whatRegionShows(region, view);
+    const active = shows.kind !== 'nothing';
+    const colour = !active ? FAINT : view.armed && region !== 'middle' ? ARMED : PREPARE;
+    ctx.strokeStyle = colour;
+    ctx.lineWidth = active ? 3 : 1;
+    ctx.strokeRect(cx - w / 2, cy - h / 2, w, h);
+    ctx.fillStyle = colour;
+    ctx.lineWidth = Math.max(1.5, f / 8);
+    ctx.shadowColor = '#000';
+    ctx.shadowBlur = 4;
+    DRAW_SHOWS[shows.kind](ctx, { region, cx, cy, f }, shows, view, say);
+    ctx.shadowBlur = 0;
+}
+/** How each thing a region can show is drawn — one row per kind, so a new kind is a new row and a missing one does not compile. */
+const DRAW_SHOWS = {
+    nothing: () => { },
+    // only the middle counts down, and its words step up to make room for the seconds
+    text: (ctx, { region, cx, cy, f }, shows, view, say) => {
+        const counting = region === 'middle' && view.restLeftMs !== undefined;
+        ctx.font = `bold ${f}px system-ui`;
+        ctx.fillText(say(shows.key), cx, counting ? cy - f * 0.7 : cy);
+        if (counting) {
+            ctx.font = `${f * 0.85}px system-ui`;
+            ctx.fillText(`${((view.restLeftMs ?? 0) / 1000).toFixed(1)} s`, cx, cy + f * 0.8);
+        }
+    },
+    arrow: (ctx, { region, cx, cy, f }) => {
+        const side = f * 2.6;
+        ctx.save();
+        ctx.translate(cx - side / 2, cy - side / 2);
+        ctx.scale(side / 24, side / 24);
+        ctx.lineWidth = 2;
+        for (const d of LUCIDE_ARROWS[region])
+            ctx.stroke(new Path2D(d));
+        ctx.restore();
+    },
+    // the Xbox letter in one circle, the PlayStation shape in the other
+    button: (ctx, { region, cx, cy, f }) => {
+        const r = f * 1.15, dx = r * 1.35, [letter, s] = FACE_BUTTON[region];
+        ctx.beginPath();
+        ctx.arc(cx - dx, cy, r, 0, 2 * Math.PI);
+        ctx.stroke();
+        ctx.font = `bold ${f * 1.1}px system-ui`;
+        ctx.fillText(letter, cx - dx, cy + f * 0.05);
+        ctx.beginPath();
+        ctx.arc(cx + dx, cy, r, 0, 2 * Math.PI);
+        ctx.stroke();
+        shape(ctx, s, cx + dx, cy, r * 0.55);
+    },
+    shoulder: (ctx, { cx, cy, f }, shows) => {
+        const side = f * 2.4;
+        ctx.strokeRect(cx - side / 2, cy - side / 2, side, side);
+        ctx.font = `bold ${f * 1.05}px system-ui`;
+        ctx.fillText(shows.label, cx, cy + f * 0.05);
+    },
+};
+/** The eyes and brows from the landmarks, mirrored so they move the way the child moves; a line naming a missing landmark is skipped. */
+function drawFaceLines(ctx, face, width, height, f) {
+    ctx.strokeStyle = LINES;
+    ctx.lineWidth = Math.max(2, f / 8);
+    ctx.shadowColor = '#000';
+    ctx.shadowBlur = 3;
+    for (const { start, end } of [...face.lines.eyes, ...face.lines.brows]) {
+        const a = face.landmarks[start], b = face.landmarks[end];
+        if (!a || !b)
+            continue;
+        ctx.beginPath();
+        ctx.moveTo((1 - a.x) * width, a.y * height);
+        ctx.lineTo((1 - b.x) * width, b.y * height);
+        ctx.stroke();
+    }
+    ctx.shadowBlur = 0;
+}

package/dist-pkg/ui/hand-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 HandTrackerLoad, 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 HandControlDeps {
+    /** 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<HandTrackerLoad>;
+}
+export declare function createHandControl(d: HandControlDeps): SwitchableControl;

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

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/hand-control — PLAYING WITH HAND GESTURES, PUT TOGETHER (ADR-0210, ADR-0206, ADR-0212 §2; issue #191).
+//
+// The camera and MediaPipe's Gesture Recognizer (platform/vision), the frame loop, the Dev's hands map (input/hand-map), the presses on the
+// virtual controller with the source `gestos` (input/virtual-controller, ADR-0111), and the hands' lines over the game. The 📷 at its
+// hands position drives it (ADR-0215): it reads the hand and draws its bones — never the camera's picture; any other position lets go.
+// · No rest to measure: a gesture is a shape, not a movement from a rest, and presses once seen for 300 ms.
+// · A frame with no hand lets go of every held action.
+// · What cannot start is said, written once in `problems`, and puts the 📷 back to off.
+import { gesturesSeen, createHandMapReader } from '../input/hand-map.js';
+import { loadHandTracker } 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): what this module returns is a SwitchableControl, not a fourth copy of it.
+/** The hand's bones, mirrored so they move the way the child moves; a bone to a landmark the hand does not have is skipped. */
+function drawBones(g, w, h, bones, hand) {
+    g.strokeStyle = '#ffffff';
+    g.lineWidth = Math.max(2, gazeFontPx(w, h) / 6);
+    g.shadowColor = '#000';
+    g.shadowBlur = 3;
+    for (const { start, end } of bones) {
+        const a = hand[start], b = hand[end];
+        if (!a || !b)
+            continue;
+        g.beginPath();
+        g.moveTo((1 - a.x) * w, a.y * h);
+        g.lineTo((1 - b.x) * w, b.y * h);
+        g.stroke();
+    }
+    g.shadowBlur = 0;
+}
+export function createHandControl(d) {
+    const { t } = d;
+    const loadTracker = d.loadTracker ?? loadHandTracker;
+    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 read = createHandMapReader();
+    const held = new Set();
+    const releaseAll = () => { for (const a of held)
+        d.controller.release(a, 'gestos'); held.clear(); };
+    const frame = (ms) => {
+        if (!tracker || !feed || !canvas || !feed.ready())
+            return;
+        const det = tracker.detect(feed.frame, ms);
+        const hand = det?.landmarks?.[0];
+        const w = canvas.width = d.region.clientWidth, h = canvas.height = d.region.clientHeight;
+        const g = canvas.getContext('2d'); // setting the width above already cleared the layer
+        // a hand that leaves starts the reading over: one that flickers out for a frame must be held again when it comes back
+        if (!hand) {
+            releaseAll();
+            read = createHandMapReader();
+            return;
+        }
+        // only the recognizer's TOP answer is a gesture; its «None» is a name the map does not know, and reads nothing
+        const names = (det?.gestures?.[0] ?? []).slice(0, 1).map((c) => c.categoryName);
+        holdExactly(new Set(read(ms, gesturesSeen(hand, names)).held));
+        drawBones(g, w, h, tracker.handLines, hand);
+    };
+    /** 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, 'gestos');
+                held.delete(a);
+            }
+        for (const a of now)
+            if (!held.has(a)) {
+                d.controller.press(a, 'gestos');
+                held.add(a);
+            }
+    };
+    const health = (hh, fps) => {
+        if (hh === 'stalled')
+            once('stalled', 'gesture control: a second without a camera frame — meanwhile the child\'s gestures command nothing; keep the tab in front and the camera free', t('sr.hands.stopped'));
+        if (hh === 'slow')
+            once('slow', `gesture control: ${fps} frames a second, under 8 — gestures are missed and the child may not be answered; close other heavy tabs or use a lighter device`, t('sr.hands.slow'));
+    };
+    const stop = () => {
+        loop?.stop();
+        loop = null;
+        releaseAll();
+        feed?.close();
+        feed = null;
+        tracker?.close();
+        tracker = null;
+        canvas?.remove();
+        canvas = null;
+        running = false;
+    };
+    const start = async () => {
+        const load = await loadTracker({ base: d.base, hasFile: d.hasFile });
+        if (!load.ok) {
+            once('files', `gesture control: ${load.missing.join(', ')} not on this device — the child cannot play with gestures; open the game once online so the install fetches them`, t('sr.hands.needsInternet'));
+            d.turnOff();
+            return;
+        }
+        try {
+            feed = await d.openFeed();
+        }
+        catch {
+            load.tracker.close();
+            once('camera', 'gesture control: the camera did not open — the child cannot play with gestures; allow the camera for this page, or plug one in', t('sr.hands.noCamera'));
+            d.turnOff();
+            return;
+        }
+        tracker = load.tracker;
+        canvas = d.doc.createElement('canvas');
+        canvas.className = 'hand-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);
+        read = createHandMapReader();
+        loop = createVisionLoop(d.loop, { onFrame: frame, onError: (e) => once('frame', `gesture control: a frame failed (${String(e)}) — the loop goes on, but a repeated failure means the child is not being read`, t('sr.hands.stopped')), onHealth: health });
+        running = true;
+        d.say(t('sr.hands.ready'));
+        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/help-panel.d.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Action, type ActionPreset } from '../core/actions.js';
+/** One line of the help table. `key` is `null` when this child's keyboard does not reach the position. */
+export interface HelpRow {
+    readonly action: Action;
+    /** Already human-readable (`keyName`), or `null` — «this transport does not reach it» is information. */
+    readonly key: string | null;
+    /** The GAME's word. Never an identifier: a position without one produces no row at all. */
+    readonly word: string;
+    /** The game's own sentence for this position, when it declared one. */
+    readonly hint?: string;
+}
+/**
+ * The help table for one seat.
+ *
+ * ⚠️ WALKS `ACTIONS` AND NOT THE PRESET'S OWN KEYS, for the reason `presetActions` already carries: the
+ * canonical order is the one the child meets everywhere else — the remap screen, the pad wizard, the
+ * on-screen legend. A help screen ordered by whatever order the game happened to write its object in would
+ * teach a different order from every other surface.
+ *
+ * @param preset  what this game declares — positions, words, hints.
+ * @param keysOf  the codes bound to a position FOR THIS SEAT. `kbFor(seat)[action]`, so a child who remapped
+ *                sees her own key. `null`/empty means the keyboard does not reach it.
+ * @param keyName code → readable label (`ui/settings-controls.keyName`), injected so this half stays pure.
+ */
+export declare function helpRows(preset: ActionPreset | null | undefined, keysOf: (a: Action) => readonly string[] | null | undefined, keyName: (code: string) => string): HelpRow[];
+/** What the slide says where the keyboard reaches nothing. A KEY, not a sentence — the caller translates it. */
+export declare const NO_KEY = "help.noKey";
+/** What building the slide show needs from the document — injected, as the panel shell takes it. */
+export interface SlideCtx {
+    readonly create: (tag: string) => HTMLElement;
+}
+/** The surface a «how to play» figure draws on, and the time in seconds since the slide showed (still under reduced motion). */
+export interface HowToPlaySurface {
+    readonly ctx: CanvasRenderingContext2D;
+    readonly width: number;
+    readonly height: number;
+    readonly time: number;
+}
+/**
+ * One «how to play» slide, declared by the cartridge (ADR-0195; issue #188): «O "Como jogar" é justamente algo a ser feito pelo
+ * cartucho.» The text is resolved at every showing, so it follows the language; the figure is drawn by the game on the engine's
+ * surface — art stays data the game draws, never an embedded picture — and may animate by the time it is given.
+ */
+export interface HowToPlaySlide {
+    readonly text: () => string;
+    readonly figure?: (surface: HowToPlaySurface) => void;
+}
+/** Why a `howToPlay` declaration is malformed; empty when well formed. Absent is well formed: the help shows the buttons alone. */
+export declare function howToPlayProblems(slides: unknown): string[];
+/** What the engine's frame loop gives an animated figure; injected, so the loop is the page's. */
+export interface FigureClock {
+    readonly requestFrame: (cb: (ms: number) => void) => number;
+    readonly cancelFrame: (id: number) => void;
+    /** Reduced motion: the figure is drawn once, at time 0, and never again. */
+    readonly reduced: boolean;
+}
+/**
+ * Draws the shown slide's figure, and keeps drawing it while the slide show is in the document and the same slide is shown.
+ * Returns a stop. A figure that throws is a cartridge defect: it stops drawing and the text stays.
+ */
+export declare function animateFigure(el: HTMLElement, slide: HowToPlaySlide, clock: FigureClock): () => void;
+/** Builds the slide show's frame: the stop, its two arrows, the slide and the dots. `showSlide` fills it. */
+export declare function mountSlides(ctx: SlideCtx): HTMLElement;
+/**
+ * Shows slide `i` (held at the ends, like every steps control: the last slide is a wall, not a way back to the first) and returns
+ * the index shown, and what a screen reader hears of it. A slide is a button row (`helpRows`) or a cartridge's «how to play» slide
+ * (ADR-0195), which the help puts first.
+ */
+export declare function showSlide(el: HTMLElement, rows: readonly (HelpRow | HowToPlaySlide)[], i: number, ctx: SlideCtx & {
+    readonly t: (k: string, p?: Record<string, string>) => string;
+    readonly title: string;
+}): {
+    readonly index: number;
+    readonly spoken: string;
+};