@the-inclusionist/engine 9.0.0 → 11.0.0

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';
+import { startCameraReader } from './camera-control.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;
+    };
+    /** 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: 'gesture control', loses: 'play with gestures',
+            spoken: { files: () => t('sr.hands.needsInternet'), runtime: () => t('sr.hands.failed'), camera: () => t('sr.hands.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 = '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,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { type Action, type ActionWords } 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  this game's positions and their words, RESOLVED now in the page's language (`core/actions.wordsOf`).
+ * @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: ActionWords | 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.» Its text is a KEY of the game's dictionary, resolved by the root's translator at every showing, so it follows the
+ * language (ADR-0232 D3, erratum of 2026-09-25); 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 textKey: string;
+    readonly figure?: (surface: HowToPlaySurface) => void;
+}
+/** A «how to play» slide as it is SHOWN: its text resolved now (`playSlidesOf`), and its figure. */
+export interface PlaySlide {
+    readonly text: string;
+    readonly figure?: (surface: HowToPlaySurface) => void;
+}
+/**
+ * The cartridge's slides, their texts resolved NOW through `word` (`Translator.word`). A slide whose text the game's
+ * dictionaries lack is left out — never shown as its key — and `problems` names it (`ui/declared-words`).
+ */
+export declare function playSlidesOf(slides: readonly HowToPlaySlide[], word: (key: string) => string | null): PlaySlide[];
+/** 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: Pick<PlaySlide, 'figure'>, 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 | PlaySlide)[], i: number, ctx: SlideCtx & {
+    readonly t: (k: string, p?: Record<string, string>) => string;
+    readonly title: string;
+}): {
+    readonly index: number;
+    readonly spoken: string;
+};

package/dist-pkg/ui/help-panel.js

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/help-panel — WHICH BUTTON DOES WHAT, in this game, on this child's keyboard: a slide show, one slide per button.
+//
+// ========================= WHY THIS MODULE EXISTS =========================
+// 🔴 MEASURED 2026-09-12: the pause card carries a `ajuda` item and NOTHING in the engine can action it, so
+// `itemsThatAct` hides it in every game. The help screen that used to fill it — `openHelp()` — did not
+// die: it LEFT WITH THE CARTRIDGE (#111) and now lives in `game-platformer/app/js/main.ts`. So each of the
+// three hundred games would have to write its own, which is the arrangement ADR-0139 measured failing in five
+// games of six.
+//
+// 🎯 AND THE ENGINE ALREADY HAS EVERY INGREDIENT, which is what makes this cheap rather than new:
+//   · WHICH positions this game uses, and the game's own WORD for each — `ActionPreset` (ADR-0085).
+//   · The sentence that explains one — the `hint` of that preset, a field declared, typed, documented and,
+//     until this module, never displayed anywhere.
+//   · WHICH KEY reaches it FOR THIS CHILD — `input/keyboard-runtime.kbFor(seat)`, i.e. her remap and not the
+//     factory default.
+//
+// ⚠️ THE ENGINE NEVER NAMES AN ACTION HERE, and that is the whole boundary (ADR-0074, ADR-0086). It knows a
+// POSITION exists; only the game knows the word. A row whose word is missing is therefore ABSENT — never a
+// row reading «action2», which is the defect `labellerFrom` returns `null` to prevent.
+//
+// 📌 AND THIS IS THE MIGRATION `ui/settings-controls.ACT_LABEL` HAS BEEN WAITING FOR. That table holds ONE
+// game's words — `act.run`, `act.jump` — inside the engine, and its own header says it can only leave once
+// the help screen asks the GAME instead. This module is a help screen that asks the game.
+import { ACTIONS } from '../core/actions.js';
+/**
+ * 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  this game's positions and their words, RESOLVED now in the page's language (`core/actions.wordsOf`).
+ * @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 function helpRows(preset, keysOf, keyName) {
+    if (!preset)
+        return [];
+    const rows = [];
+    for (const action of ACTIONS) {
+        const word = preset[action];
+        // ⚠️ A BLANK LABEL IS THE SAME AS NO LABEL, and it is the case `presetProblems` already names: a row
+        // whose word is whitespace reads, to a screen reader, as a button with no name.
+        if (!word || !word.label.trim())
+            continue;
+        // 📌 THE FIRST CODE, and the rest are not lost — they are the same position, and a help screen that listed
+        // every alias would spend the child's attention on the keyboard instead of on the game. The remap screen
+        // is where all of them are visible, because THERE they are the subject.
+        const codes = keysOf(action);
+        const key = codes && codes.length ? keyName(codes[0]) : null;
+        rows.push({ action, key, word: word.label, ...(word.hint ? { hint: word.hint } : {}) });
+    }
+    return rows;
+}
+/** What the slide says where the keyboard reaches nothing. A KEY, not a sentence — the caller translates it. */
+export const NO_KEY = 'help.noKey';
+/**
+ * The cartridge's slides, their texts resolved NOW through `word` (`Translator.word`). A slide whose text the game's
+ * dictionaries lack is left out — never shown as its key — and `problems` names it (`ui/declared-words`).
+ */
+export function playSlidesOf(slides, word) {
+    return slides.flatMap((s) => {
+        const text = word(s.textKey);
+        return text ? [{ text, ...(s.figure ? { figure: s.figure } : {}) }] : [];
+    });
+}
+/** Why a `howToPlay` declaration is malformed; empty when well formed. Absent is well formed: the help shows the buttons alone. */
+export function howToPlayProblems(slides) {
+    if (slides === undefined)
+        return [];
+    if (!Array.isArray(slides))
+        return ['howToPlay must be a list of slides'];
+    const out = [];
+    slides.forEach((s, i) => {
+        const at = `howToPlay[${i}]`;
+        if (!s || typeof s !== 'object') {
+            out.push(`${at} must be a slide`);
+            return;
+        }
+        if (typeof s.textKey !== 'string' || !s.textKey.trim())
+            out.push(`${at}.textKey must name the slide's text by a key of the game's dictionary`);
+        if (s.figure !== undefined && typeof s.figure !== 'function')
+            out.push(`${at}.figure must be a function drawing on the surface it is given`);
+    });
+    return out;
+}
+const isFromGame = (s) => typeof s.text === 'string';
+/**
+ * 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 function animateFigure(el, slide, clock) {
+    const screen = el.querySelector('.slide-figura');
+    const ctx = screen?.getContext('2d');
+    if (!screen || !ctx || !slide.figure)
+        return () => { };
+    const figureFn = slide.figure;
+    // the drawing surface is the size it is shown at, in CSS pixels, so a figure's coordinates are the ones the child sees
+    const screenBox = screen.getBoundingClientRect();
+    if (screenBox.width > 0 && screenBox.height > 0) {
+        screen.width = Math.round(screenBox.width);
+        screen.height = Math.round(screenBox.height);
+    }
+    let id = 0, still = false, start = -1;
+    const draw = (ms) => {
+        if (still || !el.isConnected)
+            return;
+        if (start < 0)
+            start = ms;
+        const time = clock.reduced ? 0 : (ms - start) / 1000;
+        ctx.clearRect(0, 0, screen.width, screen.height);
+        try {
+            figureFn({ ctx, width: screen.width, height: screen.height, time });
+        }
+        catch {
+            still = true;
+            return;
+        }
+        if (!clock.reduced)
+            id = clock.requestFrame(draw);
+    };
+    draw(0);
+    return () => { still = true; clock.cancelFrame(id); };
+}
+/** Builds the slide show's frame: the stop, its two arrows, the slide and the dots. `showSlide` fills it. */
+export function mountSlides(ctx) {
+    const el = ctx.create('div');
+    el.className = 'slides';
+    el.setAttribute('role', 'spinbutton');
+    el.setAttribute('tabindex', '0');
+    el.setAttribute('data-passos', '');
+    const arrow = (delta, glyph) => {
+        const s = ctx.create('span');
+        s.className = 'passo-seta';
+        s.setAttribute('data-passo', String(delta));
+        s.setAttribute('aria-hidden', 'true');
+        s.textContent = glyph;
+        s.addEventListener('click', () => el.dispatchEvent(new CustomEvent('passo', { detail: delta, bubbles: true })));
+        return s;
+    };
+    const slide = ctx.create('div');
+    slide.className = 'slide';
+    slide.setAttribute('aria-hidden', 'true'); // heard through the stop's value, once
+    const figureFn = ctx.create('canvas');
+    figureFn.className = 'slide-figura';
+    figureFn.hidden = true;
+    const keyGlyphOf = ctx.create('kbd');
+    keyGlyphOf.className = 'slide-tecla';
+    const word = ctx.create('p');
+    word.className = 'slide-palavra';
+    const text = ctx.create('p');
+    text.className = 'slide-texto';
+    const dots = ctx.create('div');
+    dots.className = 'slide-pontos';
+    for (const child of [figureFn, keyGlyphOf, word, text, dots])
+        slide.appendChild(child);
+    el.appendChild(arrow(-1, '◀'));
+    el.appendChild(slide);
+    el.appendChild(arrow(1, '▶'));
+    return el;
+}
+/**
+ * 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 function showSlide(el, rows, i, ctx) {
+    const last = Math.max(0, rows.length - 1);
+    const shown = Math.max(0, Math.min(last, i));
+    const r = rows[shown];
+    const parts = slidePartsOf(el);
+    if (!r || !parts)
+        return { index: shown, spoken: '' };
+    drawDots(parts.dots, rows.length, shown, ctx);
+    const spokenText = isFromGame(r) ? showPlaySlide(parts, r) : showButtonSlide(parts, r, ctx.t);
+    el.setAttribute('aria-label', ctx.title);
+    el.setAttribute('aria-valuemin', '0');
+    el.setAttribute('aria-valuemax', String(last));
+    el.setAttribute('aria-valuenow', String(shown));
+    el.setAttribute('aria-valuetext', spokenText);
+    el.querySelector('[data-passo="-1"]')?.classList.toggle('no-limite', shown === 0);
+    el.querySelector('[data-passo="1"]')?.classList.toggle('no-limite', shown === last);
+    return { index: shown, spoken: spokenText };
+}
+function slidePartsOf(el) {
+    const slide = el.querySelector('.slide');
+    const figure = el.querySelector('.slide-figura');
+    const keyCap = el.querySelector('.slide-tecla');
+    const word = el.querySelector('.slide-palavra');
+    const text = el.querySelector('.slide-texto');
+    const dots = el.querySelector('.slide-pontos');
+    if (!slide || !figure || !keyCap || !word || !text || !dots)
+        return null;
+    return { slide, figure, keyCap, word, text, dots };
+}
+/** One dot per slide, the current one filled — the place without a number (ADR-0167). */
+function drawDots(dots, count, current, ctx) {
+    while (dots.firstChild)
+        dots.removeChild(dots.firstChild);
+    Array.from({ length: count }, (_, n) => {
+        const dot = ctx.create('span');
+        dot.className = n === current ? 'slide-ponto is-on' : 'slide-ponto';
+        return dots.appendChild(dot);
+    });
+}
+/** What is heard, the parts joined — a sentence that already ends in a full stop is not given a second one. */
+const joinParts = (parts) => parts.filter(Boolean).map((part) => part.replace(/[.!?…]+\s*$/, '')).join('. ');
+/**
+ * A cartridge's «how to play» slide (ADR-0195): its text and, if it has one, its figure — no key cap, no word, and no action,
+ * whatever the slide before it was.
+ */
+function showPlaySlide(p, r) {
+    p.slide.setAttribute('data-kind', 'play');
+    p.slide.removeAttribute('data-act');
+    p.figure.hidden = !r.figure;
+    p.keyCap.hidden = true;
+    p.word.hidden = true;
+    const phrase = r.text;
+    p.text.textContent = phrase;
+    p.text.hidden = false;
+    return joinParts([phrase]);
+}
+/** A button's slide: the child's key (or that the keyboard does not reach it, marked), the game's word, and its sentence. */
+function showButtonSlide(p, r, t) {
+    p.slide.setAttribute('data-kind', 'button');
+    p.slide.setAttribute('data-act', r.action);
+    p.figure.hidden = true;
+    p.keyCap.hidden = false;
+    p.word.hidden = false;
+    p.keyCap.textContent = r.key ?? t(NO_KEY);
+    if (r.key)
+        p.keyCap.removeAttribute('data-sem-tecla');
+    else
+        p.keyCap.setAttribute('data-sem-tecla', '1');
+    p.word.textContent = r.word;
+    p.text.textContent = r.hint ?? '';
+    p.text.hidden = !r.hint;
+    return joinParts([r.word, r.hint, r.key ? t('help.slide.tecla', { k: r.key }) : t(NO_KEY)]);
+}