@the-inclusionist/engine 10.0.0 → 11.0.0

package/dist-pkg/ui/footer-scroll-driver.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+export interface FooterScrollHost {
+    readonly doc: Pick<Document, 'createRange' | 'createTreeWalker' | 'createElement'>;
+    readonly getComputedStyle: (el: Element) => CSSStyleDeclaration;
+    readonly MutationObserver: typeof MutationObserver;
+    readonly setTimeout: (fn: () => void, ms: number) => number;
+    readonly clearTimeout: (id: number) => void;
+    /** The child's caption rate (ADR-0183 §4), read at every start. */
+    readonly ppm: () => number;
+    /** Reduced motion — the system's or the child's — read at every start. */
+    readonly reduced: () => boolean;
+}
+/** Starts watching `root`. Returns the way to stop: every animation cancelled and timer cleared, the observer disconnected. */
+export declare function watchFooterScroll(root: HTMLElement, host: FooterScrollHost): () => void;

package/dist-pkg/ui/footer-scroll-driver.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/footer-scroll-driver — A FOOTER EXPLANATION LONGER THAN ITS LINES MOVES INSIDE THEM (ADR-0245): the DOM half of
+// `ui/footer-scroll`, which holds the pace.
+//
+// Watches the region for the two explanation footers — the screen's band (`.barra-explicacao`) and a panel's
+// (`.opt-explain`). A NEW text, or a footer that comes into view, starts from the top; a text that fits is measured once and
+// left alone, its DOM untouched. The box does not change: `[data-scroll]` swaps the two-line clamp for a block of the same
+// lines (style.css).
+//   · GLIDE: the words rise continuously (ADR-0245 erratum, 2026-09-26 — a line at a time was what the Dev rejected). They are
+//     moved into one `.footer-scroll-text` block, and a Web Animation translates it: sub-pixel and on the compositor, where
+//     `scrollTop` stands on whole pixels. The text node the game wrote is MOVED, not copied, in the same task as the write and
+//     before a frame is drawn, and nothing is written into the live region after — narration and the screen reader still get
+//     the whole text once (§4).
+//   · PAGES (reduced motion): no slide, so `scrollTop` and a timer per page, as the plan says.
+// Pointer over it or focus in it holds the motion where it is (§3, WCAG 2.2.2): the animation paused, or the page timer
+// cleared. A footer that leaves the screen keeps no animation and no timer.
+//
+// 📌 Everything it reaches arrives through the host (ADR-0232): the document, the timers, the styles and the observer.
+import { footerScrollPlan, readLines } from './footer-scroll.js';
+const FOOTERS = '.barra-explicacao, .opt-explain';
+/** The block the words glide in (style.css makes it a block while the footer scrolls). */
+const TEXT = 'footer-scroll-text';
+/** Starts watching `root`. Returns the way to stop: every animation cancelled and timer cleared, the observer disconnected. */
+export function watchFooterScroll(root, host) {
+    const seen = new Map();
+    const held = new WeakSet();
+    const wired = new WeakSet();
+    const visible = (el) => el.isConnected && el.getClientRects().length > 0;
+    const linesShown = (el) => parseInt(host.getComputedStyle(el).getPropertyValue('--footer-lines'), 10) || 2;
+    function wordTops(el) {
+        const tops = [];
+        const walker = host.doc.createTreeWalker(el, 4); // NodeFilter.SHOW_TEXT
+        const range = host.doc.createRange();
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            for (const m of (n.textContent ?? '').matchAll(/\S+/g)) {
+                range.setStart(n, m.index);
+                range.setEnd(n, m.index + m[0].length);
+                const box = range.getClientRects()[0];
+                if (box)
+                    tops.push(box.top);
+            }
+        }
+        return tops;
+    }
+    function forget(el) {
+        const s = seen.get(el);
+        if (s?.timer != null)
+            host.clearTimeout(s.timer);
+        if (s?.glide) {
+            s.glide.anim.onfinish = null;
+            s.glide.anim.cancel();
+        }
+        seen.delete(el);
+        delete el.dataset.scroll;
+        delete el.dataset.topLine;
+        el.scrollTop = 0;
+    }
+    /**
+     * The words inside the one block that glides, MOVED there (never copied: the game's text node stays the one it wrote). The
+     * block a footer already has is kept — a restart, or the same text written again, goes on in it.
+     */
+    function gather(el, text) {
+        let block = text;
+        if (!block) {
+            const only = el.childNodes.length === 1 ? el.firstElementChild : null;
+            if (only instanceof HTMLElement && only.classList.contains(TEXT))
+                return only;
+            block = host.doc.createElement('span');
+            block.className = TEXT;
+        }
+        const loose = [...el.childNodes].filter((n) => n !== block);
+        if (loose.length)
+            block.replaceChildren(...loose);
+        if (block.parentNode !== el)
+            el.append(block);
+        return block;
+    }
+    /** Paces a footer as it is now: held, it stays where it is; free, it goes on from there. */
+    function pace(el, s) {
+        if (s.glide) {
+            if (held.has(el))
+                s.glide.anim.pause();
+            else
+                s.glide.anim.play();
+            return;
+        }
+        arm(el, s);
+    }
+    function glide(el, s, plan) {
+        const text = gather(el);
+        const rise = `translateY(${-s.lines.starts[plan.toLine]}px)`;
+        const total = plan.waitMs + plan.travelMs + plan.holdMs;
+        // still while the first view is read, one speed to the last view, still while it is read
+        const anim = text.animate([
+            { transform: 'translateY(0)', offset: 0 },
+            { transform: 'translateY(0)', offset: plan.waitMs / total },
+            { transform: rise, offset: (plan.waitMs + plan.travelMs) / total },
+            { transform: rise, offset: 1 },
+        ], { duration: total, easing: 'linear' });
+        anim.onfinish = () => start(el, true); // the end: again from the top, measured again
+        s.glide = { text, anim };
+        pace(el, s);
+    }
+    const pagesOf = (s) => (s.plan?.mode === 'pages' ? s.plan : null);
+    function arm(el, s) {
+        if (s.timer != null)
+            host.clearTimeout(s.timer);
+        s.timer = null;
+        const pages = pagesOf(s);
+        if (!pages || held.has(el))
+            return;
+        s.timer = host.setTimeout(() => {
+            s.timer = null;
+            if (s.step + 1 < pages.steps.length)
+                show(el, s, pages, s.step + 1);
+            else
+                start(el, true); // the end: again from the top, measured again
+        }, pages.steps[s.step].holdMs);
+    }
+    function show(el, s, pages, step) {
+        s.step = step;
+        const line = pages.steps[step].line;
+        el.dataset.topLine = String(line);
+        el.scrollTop = s.lines.starts[line];
+        arm(el, s);
+    }
+    function wire(el) {
+        if (wired.has(el))
+            return;
+        wired.add(el);
+        const hold = () => { held.add(el); const s = seen.get(el); if (s)
+            pace(el, s); };
+        const release = () => { held.delete(el); const s = seen.get(el); if (s)
+            pace(el, s); };
+        el.addEventListener('pointerenter', hold);
+        el.addEventListener('pointerleave', release);
+        el.addEventListener('focusin', hold);
+        el.addEventListener('focusout', (e) => { if (!el.contains(e.relatedTarget))
+            release(); });
+    }
+    /** A footer whose text or lines changed, or that came into view: measured, and moved only if it does not fit. */
+    function start(el, again = false) {
+        const key = `${linesShown(el)}|${el.textContent ?? ''}`;
+        const had = seen.get(el);
+        if (!again && had?.key === key) {
+            // the same text written again is not a new text: it goes on gliding, in the block it was in
+            if (had.glide)
+                gather(el, had.glide.text);
+            return;
+        }
+        forget(el);
+        if (!visible(el))
+            return;
+        el.dataset.scroll = ''; // measured as it will scroll: a block, no clamp
+        const lines = readLines(wordTops(el), parseFloat(host.getComputedStyle(el).lineHeight));
+        // a page without Web Animations turns pages: the text still passes whole, at the same pace
+        const reduced = host.reduced() || typeof el.animate !== 'function';
+        const plan = footerScrollPlan(lines.words, linesShown(el), host.ppm(), reduced);
+        const s = { key, plan, lines, step: 0, timer: null, glide: null };
+        seen.set(el, s);
+        if (!plan) {
+            delete el.dataset.scroll;
+            return;
+        }
+        el.dataset.scroll = plan.mode;
+        wire(el);
+        if (plan.mode === 'glide')
+            glide(el, s, plan);
+        else
+            show(el, s, plan, 0);
+    }
+    function footersIn(node, into) {
+        const el = node.nodeType === 1 ? node : node.parentElement;
+        const own = el?.closest(FOOTERS);
+        if (own)
+            into.add(own);
+        if (node.nodeType === 1)
+            el.querySelectorAll(FOOTERS).forEach((f) => into.add(f));
+    }
+    const observer = new host.MutationObserver((records) => {
+        const touched = new Set();
+        for (const r of records) {
+            footersIn(r.target, touched);
+            r.addedNodes.forEach((n) => footersIn(n, touched));
+        }
+        // a `hidden` changed somewhere: every footer may have come into view, or changed its number of lines
+        if (records.some((r) => r.type === 'attributes'))
+            footersIn(root, touched);
+        for (const el of [...seen.keys()])
+            if (!visible(el))
+                forget(el);
+        touched.forEach((el) => start(el));
+    });
+    observer.observe(root, { childList: true, characterData: true, subtree: true, attributes: true, attributeFilter: ['hidden'] });
+    root.querySelectorAll(FOOTERS).forEach((el) => start(el));
+    return () => {
+        observer.disconnect();
+        for (const el of [...seen.keys()])
+            forget(el);
+    };
+}

package/dist-pkg/ui/footer-scroll.d.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** One page: the first line on show, and how long it stays before the next. */
+export interface FooterScrollStep {
+    readonly line: number;
+    readonly holdMs: number;
+}
+/**
+ * Rises continuously: still for `waitMs`, then up at one speed for `travelMs` until `toLine` tops the view (the last view),
+ * held there `holdMs`.
+ */
+export interface FooterGlidePlan {
+    readonly mode: 'glide';
+    readonly waitMs: number;
+    readonly travelMs: number;
+    readonly holdMs: number;
+    readonly toLine: number;
+}
+/** Turns a whole view at a time, without sliding (reduced motion). */
+export interface FooterPagesPlan {
+    readonly mode: 'pages';
+    readonly steps: readonly FooterScrollStep[];
+}
+export type FooterScrollPlan = FooterGlidePlan | FooterPagesPlan;
+/** The rendered lines: how many words each holds, and where each starts, from the top of the first. */
+export interface FooterLines {
+    readonly words: readonly number[];
+    readonly starts: readonly number[];
+}
+/**
+ * The lines, from the TOP of each word as laid out. A word lower than the line's top by more than half a line opens a new one;
+ * a word broken across two lines counts where it starts.
+ */
+export declare function readLines(wordTops: readonly number[], lineHeight: number): FooterLines;
+/**
+ * The plan for a text of `wordsPerLine.length` lines shown `shown` at a time, or `null` when it fits — a text that fits never
+ * moves. The rate is one of the three the child can choose; any other number reads as the slowest (`isCaptionRate`).
+ */
+export declare function footerScrollPlan(wordsPerLine: readonly number[], shown: number, ppm: number, reduced: boolean): FooterScrollPlan | null;

package/dist-pkg/ui/footer-scroll.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/footer-scroll — WHEN A LONG FOOTER EXPLANATION MOVES, AND FOR HOW LONG (ADR-0245).
+//
+// The footer shows its lines (two; one while the button legend shares the column, ADR-0164). A text that needs more moves
+// INSIDE them, at the child's caption rate — the arithmetic of `core/caption-duration`, 60000 / ppm ms a word:
+//   · GLIDE (ADR-0245 erratum, 2026-09-26: «suave e contínua, lentamente»): it waits for the first view to be read, then rises
+//     at ONE constant speed until its last line is in view — the distance passes in the time the words below the first view
+//     take, so the last line arrives when every word has been read —, holds the last view for its words, and the caller starts
+//     again from the top;
+//   · PAGES, with reduced motion: no slide — a whole view at a time, each page held for the words it brings.
+//
+// 📌 PURE: word positions and numbers in, a plan out. The DOM half (`ui/footer-scroll-driver`) measures and moves.
+import { isCaptionRate } from '../core/caption-duration.js';
+/**
+ * The lines, from the TOP of each word as laid out. A word lower than the line's top by more than half a line opens a new one;
+ * a word broken across two lines counts where it starts.
+ */
+export function readLines(wordTops, lineHeight) {
+    const words = [];
+    const starts = [];
+    let top = -Infinity;
+    for (const t of wordTops) {
+        if (t > top + lineHeight / 2) {
+            top = t;
+            words.push(0);
+            starts.push(t - (wordTops[0] ?? 0));
+        }
+        words[words.length - 1] += 1;
+    }
+    return { words, starts };
+}
+/**
+ * The plan for a text of `wordsPerLine.length` lines shown `shown` at a time, or `null` when it fits — a text that fits never
+ * moves. The rate is one of the three the child can choose; any other number reads as the slowest (`isCaptionRate`).
+ */
+export function footerScrollPlan(wordsPerLine, shown, ppm, reduced) {
+    const last = wordsPerLine.length - shown; // the first line of the last view
+    if (shown < 1 || last <= 0)
+        return null;
+    const msPerWord = 60_000 / isCaptionRate(ppm);
+    const read = (from, to) => Math.round(wordsPerLine.slice(from, to).reduce((a, b) => a + b, 0) * msPerWord);
+    // the last view is held as long as its lines take to read
+    const endHold = read(last, last + shown);
+    if (!reduced) {
+        return { mode: 'glide', waitMs: read(0, shown), travelMs: read(shown, wordsPerLine.length), holdMs: endHold, toLine: last };
+    }
+    const steps = [{ line: 0, holdMs: read(0, shown) }];
+    for (let line = shown; steps[steps.length - 1].line < last; line += shown) {
+        const top = Math.min(line, last);
+        const before = steps[steps.length - 1].line;
+        // every other page, as long as the lines it brought
+        steps.push({ line: top, holdMs: top === last ? endHold : read(before + shown, top + shown) });
+    }
+    return { mode: 'pages', steps };
+}

package/dist-pkg/ui/game-options.d.ts

@@ -1,21 +1,24 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import type { Translate } from '../core/i18n.js';
 import type { PanelShellCtx } from './panel-shell.js';
-/** One position of a steps or list row: the value the cartridge reads and writes, and its label in the interface language. */
+/** One position of a steps or list row: the value the cartridge reads and writes, and the key of its label. */
 export interface GameOptionValue {
     readonly value: string;
-    readonly label: string;
+    readonly labelKey: string;
 }
 interface GameOptionBase {
     /** Stable and unique among the game's rows; the control is `#game-option-<id>`. */
     readonly id: string;
-    /** The row's short name, in the interface language. */
-    readonly label: string;
-    /** The explanation, shown in the footer (CLAUDE.md §4). */
-    readonly hint?: string;
+    /** The key of the row's short name, in the game's dictionary. */
+    readonly labelKey: string;
+    /** The key of the explanation, shown in the footer (CLAUDE.md §4). */
+    readonly hintKey?: string;
 }
 export type GameOption = (GameOptionBase & {
-    /** Steps «◀ Label: value ▶», up to five positions; a list, any number (ADR-0130 erratum). */
+    /**
+     * An exclusive choice. The engine draws it by its SIZE (ADR-0130 rule 3): five positions or fewer are one row «◀ Label:
+     * value ▶», more a dropdown — whichever kind is declared. `steps` still refuses more than five, since the game asked for a cycle.
+     */
     readonly kind: 'steps' | 'list';
     readonly values: readonly GameOptionValue[];
     /** The value in use. Read at every opening and after every write: what shows is what the cartridge keeps. */
@@ -29,14 +32,16 @@ export type GameOption = (GameOptionBase & {
 /** Why a `gameOptions` declaration is malformed; empty when it is well formed. Absent is well formed: no options of its own. */
 export declare function gameOptionsProblems(options: unknown): string[];
 export interface GameOptionsDrawCtx extends PanelShellCtx {
-    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    /** Translates the engine's own words in the page's language — the root's translator (ADR-0232 D3). */
     t: Translate;
+    /** Resolves a key the GAME declared, in the page's language; `null` when its dictionaries lack it (`Translator.word`). */
+    readonly word: (key: string) => string | null;
     /** Where a change is said (the polite live region). */
     readonly say: (text: string) => void;
 }
 /**
  * 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.
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, and every word RESOLVED, at drawing and after each write.
  */
 export declare function drawGameOptions(ctx: GameOptionsDrawCtx, list: HTMLElement, options: readonly GameOption[]): void;
 export {};

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

@@ -1,9 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { controlRow, mountSteps, updateSteps, nextStep } from './panel-widgets.js';
+import { controlRow, mountSteps, updateSteps, nextStep, MAX_CYCLE_POSITIONS } 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)
@@ -31,20 +29,22 @@ function idProblems(o, at, ids) {
     ids.add(o.id);
     return [];
 }
+/** A key: text that is not blank. */
+const isKey = (k) => typeof k === 'string' && !!k.trim();
 /** 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) => isKey(o.labelKey), "labelKey must name the row by a key of the game's dictionary"],
+    [(o) => o.hintKey === undefined || isKey(o.hintKey), "hintKey must be a key of the game's dictionary"],
     [(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. */
+/** The positions of a steps or list row: at least two, at most five for steps, each with a value and a label key, 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
+    const out = o.kind === 'steps' && values.length > MAX_CYCLE_POSITIONS
         ? [`${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) => {
@@ -55,25 +55,44 @@ function valuesProblems(o, at) {
     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 (!v || typeof v.value !== 'string' || !isKey(v.labelKey))
+        return `${at} must have a value and a labelKey`;
     if (seen.has(v.value))
         return `${at} «${v.value}» repeats an earlier position`;
     seen.add(v.value);
     return null;
 }
+function rowWords(o, word) {
+    const label = word(o.labelKey);
+    if (!label)
+        return null;
+    const hint = o.hintKey ? word(o.hintKey) : null;
+    const values = new Map();
+    if (o.kind !== 'switch') {
+        for (const v of o.values) {
+            const positionLabel = word(v.labelKey);
+            if (!positionLabel)
+                return null;
+            values.set(v.value, positionLabel);
+        }
+    }
+    return { label, ...(hint ? { hint } : {}), values };
+}
 /**
  * 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.
+ * swapped it (ADR-0142). Every value shown is READ from the cartridge, and every word RESOLVED, 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 words = rowWords(o, ctx.word);
+        if (!words)
+            continue;
         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 { row: rowNode, control: switchButton } = controlRow(ctx, { id, label: words.label, hint: words.hint });
             const reflect = () => {
                 const on = o.read();
                 switchButton.classList.toggle('is-on', on);
@@ -84,40 +103,41 @@ export function drawGameOptions(ctx, list, options) {
             reflect();
             switchButton.addEventListener('click', () => {
                 o.write(!o.read());
-                ctx.say(`${o.label}: ${toggleLabel(t, reflect())}`);
+                ctx.say(`${words.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 labelOf = (chosen) => words.values.get(chosen) ?? '';
+        // ⚠️ BY SIZE, NOT BY KIND (ADR-0130 rule 3): a `list` of five or fewer is a cycle row like `steps`, below
+        if (o.values.length > MAX_CYCLE_POSITIONS) {
+            const { row: rowNode, control: control } = controlRow(ctx, { id, label: words.label, hint: words.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;
+                op.textContent = labelOf(v.value);
                 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)}`);
+                ctx.say(`${words.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 spec = () => ({ label: words.label, values: o.values.map((v) => labelOf(v.value)), current: selectedIndex() });
         const rowNode = ctx.create('div');
         rowNode.className = 'ctrl-row ctrl-row--passos';
         const envelope = ctx.create('span');
-        if (o.hint) {
+        if (words.hint) {
             const explanation = ctx.create('span');
             explanation.className = 'opt-hint';
-            explanation.textContent = o.hint;
+            explanation.textContent = words.hint;
             envelope.appendChild(explanation);
         }
         rowNode.appendChild(envelope);
@@ -131,7 +151,7 @@ export function drawGameOptions(ctx, list, options) {
                 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())}`);
+            ctx.say(`${words.label}: ${labelOf(o.read())}`);
         });
         list.appendChild(rowNode);
     }

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

@@ -11,6 +11,7 @@ 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) {
@@ -94,23 +95,22 @@ export function createHandControl(d) {
         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();
+    /** 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;
-        }
-        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();
+        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 = load.tracker;
+        tracker = opened.tracker;
+        feed = opened.feed;
         canvas = d.doc.createElement('canvas');
         canvas.className = 'hand-overlay';
         canvas.setAttribute('aria-hidden', 'true');

package/dist-pkg/ui/help-panel.d.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { type Action, type ActionPreset } from '../core/actions.js';
+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;
@@ -18,12 +18,12 @@ export interface HelpRow {
  * 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 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: ActionPreset | null | undefined, keysOf: (a: Action) => readonly string[] | null | undefined, keyName: (code: string) => string): HelpRow[];
+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. */
@@ -39,13 +39,24 @@ export interface HowToPlaySurface {
 }
 /**
  * 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.
+ * 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 text: () => string;
+    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. */
@@ -59,7 +70,7 @@ export interface FigureClock {
  * 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;
+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;
 /**
@@ -67,7 +78,7 @@ export declare function mountSlides(ctx: SlideCtx): HTMLElement;
  * 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 & {
+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;
 }): {