@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/input/pad-reading.d.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PadTable } from './pad-defaults.js';
+export interface PadButtonLike {
+    pressed: boolean;
+}
+export interface PadLike {
+    id: string;
+    index: number;
+    mapping: string;
+    buttons: readonly (PadButtonLike | null | undefined)[];
+    axes: readonly number[];
+}
+/** Adapter for `navigator.getGamepads()` — the DI point that lets tests feed a fake pad without a browser. */
+export type GetGamepads = () => readonly (PadLike | null | undefined)[] | null | undefined;
+/** One binding captured by the wizard: a digital button, a signed analog threshold, or an exact hat/POV value.
+ *  Loosely-shaped (all fields optional) rather than a strict union: bindings round-trip through JSON in
+ *  localStorage, so `bindActive` must stay defensive against malformed/partial saved data, same as the original. */
+export interface PadBinding {
+    b?: number;
+    ax?: number;
+    s?: number;
+    av?: number;
+    v?: number;
+}
+/** action -> binding, keyed by the 9 wizard steps (left/right/up/down/jump/run/swap/especial/start), PLUS the
+ *  `_skip: true` sentinel meaning "user cancelled the wizard for this model — use the default mapping, don't
+ *  ask again this session" (not persisted). A flat index signature (not `Partial<Record<..>> & {_skip}`) so the
+ *  boolean `_skip` and the PadBinding action values can coexist under TS's index-signature rule; `bindingAt`
+ *  narrows a lookup back down to a PadBinding for `bindActive`. */
+export type PadMap = Record<string, PadBinding | boolean | undefined>;
+export type ActionKey = 'left' | 'right' | 'up' | 'down' | 'action2' | 'action1' | 'action4' | 'action3';
+export interface Dirs {
+    left: boolean;
+    right: boolean;
+    up: boolean;
+    down: boolean;
+}
+export interface PadActions extends Dirs {
+    [key: string]: boolean;
+    action2: boolean;
+    action1: boolean;
+    action4: boolean;
+    action3: boolean;
+    _start: boolean;
+    _pause: boolean;
+}
+/** Directions from the STANDARD SOURCES: stick 0/1 (dead zone PAD_DEAD), D-pad 12-15, and the "hat" on axes >=6
+ *  (DirectInput's POV). A pad with both directionals mapped keeps both alive (a thumb on the stick does not kill the D-pad). */
+export declare function stdDirs(gp: PadLike): Dirs;
+/** Is binding `bd` active now on this gamepad? Digital = pressed; analogue ({ax,s}) = threshold by sign (half the
+ *  travel); hat ({av,v}) = the step's exact value (±0.13 — the 8 steps are ~0.286 apart). */
+export declare function bindActive(gp: PadLike, bd: PadBinding | null | undefined): boolean;
+/** This frame's actions for this gamepad. `custom` = the map the wizard saved for this `gp.id` (null/`_skip` = the
+ *  declared table). ⚠️ The table decides only in the second branch, which is right: a game's default does not override
+ *  a choice the child recorded. */
+export declare function padActions(gp: PadLike, custom: PadMap | null, table?: PadTable): PadActions;
+/**
+ * ONE BUTTON AT A TIME, APPLIED TO THE PAD — the missing half of the motor empathy simulation (issue #120).
+ *
+ * ⚠️ IT USED TO HOLD ONLY ON THE KEYBOARD. The keyboard transport releases every other game key when a new one arrives
+ * with the simulation on; the pad polling had no equivalent. A child who turned it on with a pad in hand **was not in
+ * it** — no error, no warning, no symptom, because the settings kept saying it was on.
+ *
+ * ⚠️ THE DIRECTIONS COUNT, which is what makes the rule faithful to the keyboard: there, the game keys include the four
+ * directions — walking and jumping do not coexist. A filter that spared the directions would be more comfortable and
+ * would be simulating another disability.
+ *
+ * ⚠️ AND WHO SURVIVES DIFFERS FROM THE KEYBOARD, BY NECESSITY. On the keyboard the new arrival wins, because there IS an
+ * arrival: the event says which. A pad is read by POLLING — what arrives is a snapshot, without order. So the one that
+ * already held stays, and only when it lets go does the next take over. That keeps the run button from being cut because
+ * the thumb brushed another, and it is the reading of "holding" ADR-0077 gives.
+ *
+ * The POLICY is the keyboard's; the IMPLEMENTATION cannot be shared today because the state's shapes differ — there a
+ * `Set` of key codes, here a snapshot of booleans by position.
+ */
+export declare function oneButtonAtOnce(wasDown: Readonly<Record<string, boolean | undefined>>, reading: PadActions, on: boolean): PadActions;

package/dist-pkg/input/pad-reading.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/pad-reading — WHAT A GAMEPAD IS DOING RIGHT NOW, and nothing else.
+//
+// 🔴 WHY IT IS ITS OWN MODULE. `input/gamepad` carried two jobs under one name: this one — buttons and axes in,
+// positions out, no host, no state, no clock — and the DI runtime that polls the pads every frame and decides
+// where the reading goes (title, pause, seat, play, wizard). The second is the engine's wiring and can only be
+// read with a ctx in hand; the first is arithmetic over a snapshot, and every one of its rules is a promise to a
+// child whose controller the browser does not recognise: a D-pad on a DirectInput POV hat, an analogue axis used
+// as a button, a map the child recorded in the wizard.
+//
+// 📌 Nothing here reads or writes state. The frame-to-frame memory (`padCur`, `padPrevAct`) belongs to whoever
+// polls — one root's `input/state` (ADR-0232 D4).
+import { GAMEPAD_STANDARD } from './default-bindings.js';
+/**
+ * THE STICK'S DEAD ZONE = the first HALF of its travel (ergonomics — the Dev's decision). A constant, and so it lives
+ * here with the reading that uses it, not in `input/state`, which is a factory now (ADR-0232 D4). Internal: nothing
+ * outside this reading asks for it, in this repository or in the games.
+ */
+const PAD_DEAD = 0.5;
+function bindingAt(map, key) {
+    const v = map[key];
+    return typeof v === 'object' && v !== null ? v : undefined;
+}
+// [axisValue, up, down, left, right] — the 8 steps of a "POV hat" D-pad (DirectInput's high axis), resting at ~1.286.
+const HAT_STEPS = [
+    [-1, 1, 0, 0, 0], [-0.7143, 1, 0, 0, 1], [-0.4286, 0, 0, 0, 1], [-0.1429, 0, 1, 0, 1],
+    [0.1429, 0, 1, 0, 0], [0.4286, 0, 1, 1, 0], [0.7143, 0, 0, 1, 0], [1, 1, 0, 1, 0],
+];
+/** The hat step this axis value IS, or `null` — the eight are ~0.286 apart, and the tolerance is ±0.09. */
+function hatStepAt(v) {
+    if (typeof v !== 'number' || Math.abs(v) > 1.001)
+        return null; // the hat's rest, outside the steps
+    return HAT_STEPS.find(([hv]) => Math.abs(v - hv) <= 0.09) ?? null;
+}
+/** A hat step LIGHTS directions and never puts them out — which keeps the stick and the D-pad alive at once. */
+function applyHatStep(d, step) {
+    const [, up, down, left, right] = step;
+    if (up)
+        d.up = true;
+    if (down)
+        d.down = true;
+    if (left)
+        d.left = true;
+    if (right)
+        d.right = true;
+}
+/** Directions from the STANDARD SOURCES: stick 0/1 (dead zone PAD_DEAD), D-pad 12-15, and the "hat" on axes >=6
+ *  (DirectInput's POV). A pad with both directionals mapped keeps both alive (a thumb on the stick does not kill the D-pad). */
+export function stdDirs(gp) {
+    const b = (i) => !!(gp.buttons[i] && gp.buttons[i].pressed);
+    const ax = (i) => gp.axes[i] || 0;
+    const d = { left: ax(0) < -PAD_DEAD || b(14), right: ax(0) > PAD_DEAD || b(15), up: ax(1) < -PAD_DEAD || b(12), down: ax(1) > PAD_DEAD || b(13) };
+    for (let i = 6; i < gp.axes.length; i++) {
+        const step = hatStepAt(gp.axes[i]);
+        if (step)
+            applyHatStep(d, step);
+    }
+    return d;
+}
+/** Is binding `bd` active now on this gamepad? Digital = pressed; analogue ({ax,s}) = threshold by sign (half the
+ *  travel); hat ({av,v}) = the step's exact value (±0.13 — the 8 steps are ~0.286 apart). */
+export function bindActive(gp, bd) {
+    if (!bd)
+        return false;
+    if (bd.b != null)
+        return !!(gp.buttons[bd.b] && gp.buttons[bd.b].pressed);
+    if (bd.ax != null)
+        return ((gp.axes[bd.ax] || 0) * (bd.s ?? 0)) > 0.5;
+    if (bd.av != null)
+        return Math.abs((gp.axes[bd.av] || 0) - (bd.v ?? 0)) <= 0.13;
+    return false;
+}
+/** The snapshot when the CHILD recorded a map in the wizard: their directions fall back to the standard ones when the
+ *  binding is not active, so the D-pad and the stick stay alive beside what they chose.
+ *  ⚠️ `start` and `select` are read AS POSITIONS, as the table's reading does: the wizard asks them and stores them, and a
+ *  map read without `select` left a mapped pad with no door to the menus — not even as the one-button scan's switch
+ *  (ADR-0155, ADR-0218 §4). */
+function actionsFromTheSavedMap(gp, custom) {
+    const A = (k) => bindActive(gp, bindingAt(custom, k));
+    const sd = stdDirs(gp);
+    return {
+        left: A('left') || sd.left, right: A('right') || sd.right, up: A('up') || sd.up, down: A('down') || sd.down,
+        action2: A('action2'), action1: A('action1'), action4: A('action4'), action3: A('action3'),
+        start: A('start'), select: A('select'),
+        _start: A('action2') || A('start'), _pause: A('start'),
+    };
+}
+/**
+ * The snapshot by the declared TABLE — the engine's factory with this game's default on top (ADR-0115), resolved in
+ * `input/pad-defaults`.
+ *
+ * ⚠️ THE INDICES COME FROM THE TABLE, not from literals here. While they were literals, this line and
+ * `input/default-bindings` DISAGREED and nothing noticed — the defect the touch gate caught: two tables agreeing with
+ * each other prove nothing about a third that reads them.
+ *
+ * ⚠️ AND THE DISAGREEMENT WAS REAL: here `action1` was `b(2) || b(5) || b(7)` — X, R1 and R2 all running — while the table
+ * declares R1 as `rightShoulder` and R2 as `rightTrigger`. ADR-0086 recorded it as the asterisk of its "zero movement": no
+ * VERB changes button, but that one loses two of its three.
+ */
+function actionsFromTheTable(gp, table) {
+    const b = (i) => !!(gp.buttons[i] && gp.buttons[i].pressed);
+    const sd = stdDirs(gp);
+    const at = (a) => { const i = table[a]; return typeof i === 'number' ? b(i) : false; };
+    return {
+        left: sd.left, right: sd.right, up: sd.up, down: sd.down,
+        action1: at('action1'), action2: at('action2'), action3: at('action3'), action4: at('action4'),
+        leftShoulder: at('leftShoulder'), leftTrigger: at('leftTrigger'),
+        rightShoulder: at('rightShoulder'), rightTrigger: at('rightTrigger'),
+        // ⚠️ `start` AS A POSITION, not only as the derived ones below. It was missing, and the table's gate found it:
+        // whoever wanted to know "is START pressed?" had to read `_start`, which starts with an underscore and means
+        // something else (closes a dialog, and accepts action 2 too).
+        start: at('start'), select: at('select'),
+        // `_start` and `_pause` are DERIVED, not positions: "close dialog" accepts action 2 or START, "pause" only START.
+        // They are written here because they describe what the root does with two positions, not a third one.
+        _start: at('action2') || at('start'), _pause: at('start'),
+    };
+}
+/** This frame's actions for this gamepad. `custom` = the map the wizard saved for this `gp.id` (null/`_skip` = the
+ *  declared table). ⚠️ The table decides only in the second branch, which is right: a game's default does not override
+ *  a choice the child recorded. */
+export function padActions(gp, custom, table = GAMEPAD_STANDARD) {
+    return custom && !custom._skip ? actionsFromTheSavedMap(gp, custom) : actionsFromTheTable(gp, table);
+}
+/**
+ * THE POSITIONS THE ONE-BUTTON SIMULATION DOES NOT CUT. Pausing is the WAY OUT, not a move.
+ *
+ * ⚠️ Cutting START would trap the child inside the match — the reasoning that puts "the way out first" in ADR-0044 and
+ * made the focus trap exist in ADR-0090. An accommodation that locks is not an accommodation. The derived ones (`_start`,
+ * `_pause`) pass too: they describe what the root does with these two positions, not a third.
+ */
+const OUTSIDE_CUT = new Set(['start', 'select', '_start', '_pause']);
+/**
+ * ONE BUTTON AT A TIME, APPLIED TO THE PAD — the missing half of the motor empathy simulation (issue #120).
+ *
+ * ⚠️ IT USED TO HOLD ONLY ON THE KEYBOARD. The keyboard transport releases every other game key when a new one arrives
+ * with the simulation on; the pad polling had no equivalent. A child who turned it on with a pad in hand **was not in
+ * it** — no error, no warning, no symptom, because the settings kept saying it was on.
+ *
+ * ⚠️ THE DIRECTIONS COUNT, which is what makes the rule faithful to the keyboard: there, the game keys include the four
+ * directions — walking and jumping do not coexist. A filter that spared the directions would be more comfortable and
+ * would be simulating another disability.
+ *
+ * ⚠️ AND WHO SURVIVES DIFFERS FROM THE KEYBOARD, BY NECESSITY. On the keyboard the new arrival wins, because there IS an
+ * arrival: the event says which. A pad is read by POLLING — what arrives is a snapshot, without order. So the one that
+ * already held stays, and only when it lets go does the next take over. That keeps the run button from being cut because
+ * the thumb brushed another, and it is the reading of "holding" ADR-0077 gives.
+ *
+ * The POLICY is the keyboard's; the IMPLEMENTATION cannot be shared today because the state's shapes differ — there a
+ * `Set` of key codes, here a snapshot of booleans by position.
+ */
+export function oneButtonAtOnce(
+// ⚠️ THE PREVIOUS FRAME IS TYPED BY WHAT THIS FUNCTION READS, not by `PadActions`: the loop's previous-frame state is
+// looser, and demanding the full shape would force the caller into a mould that does not describe what happens here —
+// the only question is "was this key down?".
+wasDown, reading, on) {
+    if (!on)
+        return reading;
+    const cuttable = Object.keys(reading).filter((k) => !OUTSIDE_CUT.has(k));
+    const active = cuttable.filter((k) => reading[k] === true);
+    if (active.length <= 1)
+        return reading;
+    // The one that already held has priority; with none, the snapshot's first takes over.
+    const kept = active.find((k) => wasDown[k] === true) ?? active[0];
+    const onlyOne = { ...reading };
+    for (const k of active)
+        if (k !== kept)
+            onlyOne[k] = false;
+    return onlyOne;
+}

package/dist-pkg/input/pad-wizard.d.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Translate } from '../core/i18n.js';
+import type { Store } from '../platform/storage.js';
+interface PadLike {
+    readonly id: string;
+    readonly index: number;
+    readonly buttons: readonly ({
+        pressed: boolean;
+    } | null | undefined)[];
+    readonly axes: readonly number[];
+}
+type GetGamepads = () => readonly (PadLike | null | undefined)[] | null | undefined;
+interface PadBinding {
+    b?: number;
+    ax?: number;
+    s?: number;
+    av?: number;
+    v?: number;
+}
+type PadMap = Record<string, PadBinding | boolean | undefined>;
+/** This pad's resting pose: which buttons were already down and where each axis rested. */
+interface Baseline {
+    b: boolean[];
+    a: number[];
+}
+interface WizState {
+    gi: number;
+    id: string;
+    step: number;
+    base: Baseline | null;
+    map: PadMap;
+    release: boolean;
+    baseWait: boolean;
+    axTrack: {
+        i: number;
+        v: number;
+        last: number;
+        changes: number;
+        ticks: number;
+    } | null;
+    timer: ReturnType<typeof setInterval> | null;
+}
+export declare const PADWIZ_ORDER: readonly string[];
+/** What this module reads and writes the maps through: the page's store, built by the root (ADR-0232, issue #207). */
+export type PadMapStore = Pick<Store, 'getJSON' | 'setJSON'>;
+/** ONE ROOT'S STORED PAD MAPS, per pad id — what `createPadMaps` returns. */
+export interface PadMaps {
+    /**
+     * The stored map of pad `id`, or `null`. Read through the vocabulary translator: a map saved before ADR-0086 has the old
+     * action keys, and a custom pad would otherwise stop answering with no word said.
+     */
+    padMap(id: string): PadMap | null;
+    /** Stores the map of pad `id` and makes it the one read from now on. */
+    store(id: string, map: PadMap): void;
+    /** A cancelled wizard: the DEFAULT map for this session, not stored, so the wizard does not reopen in a loop. */
+    skip(id: string): void;
+}
+/**
+ * THE CACHE OF STORED MAPS, one per ROOT (ADR-0232 D4). ⚠️ Not safe to share: two roots on two stores would read each
+ * other's map, and the one the page's first wizard saved would answer in a root whose child never recorded it. The root
+ * builds ONE and hands it to both readers — its own wizard and `initGamepad` — so a map saved by the wizard is the one the
+ * pad reads on the next frame, not a copy cached before.
+ */
+export declare function createPadMaps(store: PadMapStore): PadMaps;
+export interface PadWizardCtx {
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** Where the finished map is stored — this root's maps (`createPadMaps`). Required: a wizard that saved nowhere would ask
+     *  the child the fourteen questions again at every visit, in silence. */
+    maps: PadMaps;
+    getGamepads: GetGamepads;
+    /**
+     * The position's name in the GAME's word and the language of now; `null` = the game does not use it (the step is skipped).
+     * ⚠️ Not asked about `start` and `select`: the wizard always asks them, in the engine's words (`SYSTEM_WORDS`).
+     */
+    actionLabel: (action: string) => string | null;
+    /** Shows and says the wizard's sentence. */
+    say: (phrase: string) => void;
+    /** Shows what is mapped so far. */
+    progress: (text: string) => void;
+    srAlert: (phrase: string) => void;
+    /** The step that starts (`null` while waiting for a pad) — the host's demonstration, when it has one. */
+    onStep?: (action: string | null) => void;
+    /** Every tick while open — the host's animation, when it has one. */
+    onTick?: () => void;
+    /** After closing: the pad index mapped (-1 if none was identified) and whether the map was saved. */
+    onClose?: (gi: number, saved: boolean) => void;
+}
+export interface PadWizard {
+    /** Opens waiting for any pad to press a button. */
+    open(): void;
+    /** Opens for a pad already identified. */
+    openFor(gp: PadLike): void;
+    close(save: boolean): void;
+    tick(): void;
+    state(): WizState | null;
+}
+export declare function createPadWizard(ctx: PadWizardCtx): PadWizard;
+export {};

package/dist-pkg/input/pad-wizard.js

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { SYSTEM } from '../core/actions.js';
+import { migrateControlMap } from './vocabulary-migration.js';
+import { buttonName } from './touch.js';
+export const PADWIZ_ORDER = [
+    // Directions first: they are what the child finds without thinking, and getting all four right gives confidence for
+    // the other ten.
+    'up', 'down', 'left', 'right',
+    // The diamond, in the order the finger walks it in this project (ADR-0086 §2).
+    'action2', 'action1', 'action4', 'action3',
+    // The four shoulders: the wizard exists FOR pads that are not "standard" — generic, adapted, one-handed — and a game
+    // that declares `leftShoulder` needs a way for the child to map it.
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger',
+    // System last: `start` and `select` are usually the smallest and most hidden buttons.
+    'start', 'select',
+];
+/**
+ * 🔴 THE SYSTEM'S TWO ARE ALWAYS ASKED, IN THE ENGINE'S WORDS (ADR-0122, ADR-0144 §1 and its erratum of 2026-09-26, ADR-0155).
+ * A game's preset may not name `start` or `select` (ADR-0144 §4, ADR-0155 §4 — refused at boot), so a wizard that asked only
+ * what the game names never asked them, and every pad it mapped had no quick pause and no menus: the pause no game may decline,
+ * declined by the pad. They are the system's, and `core/actions` (`SYSTEM`) says the engine may name them — the legend printed
+ * on the pad. The host's labeller is not asked about them.
+ * 📌 Each carries its QUESTION and its NAME: the name is the word the question says (START, SELECT), and it is how the progress
+ * line lists the position once mapped — never its id (ADR-0074: no abstract name reaches a person).
+ */
+const SYSTEM_WORDS = {
+    start: { question: 'pad.wiz.stepStart', name: 'touch.start' },
+    select: { question: 'pad.wiz.stepSelect', name: 'touch.select' },
+};
+const systemWords = (action) => (SYSTEM.includes(action) ? SYSTEM_WORDS[action] : null);
+/**
+ * 🔴 THE DEFAULT POSITIONS (ADR-0144, erratum of 2026-09-26 — the Dev: «as posições padrões são up, down, left, right, 1, 2, 3, 4,
+ * L1, L2, R1, R2, START e SELECT»). A game that names no position still gets a pad the child can map: these fourteen, in this
+ * order, each asked by its button's name (`input/touch.buttonName`, ADR-0165 — the names printed on the virtual pad).
+ */
+const DEFAULT_ORDER = [
+    'up', 'down', 'left', 'right', 'action1', 'action2', 'action3', 'action4',
+    'leftShoulder', 'leftTrigger', 'rightShoulder', 'rightTrigger', 'start', 'select',
+];
+const KEY = (id) => 'incl_padmap_' + id;
+/**
+ * THE CACHE OF STORED MAPS, one per ROOT (ADR-0232 D4). ⚠️ Not safe to share: two roots on two stores would read each
+ * other's map, and the one the page's first wizard saved would answer in a root whose child never recorded it. The root
+ * builds ONE and hands it to both readers — its own wizard and `initGamepad` — so a map saved by the wizard is the one the
+ * pad reads on the next frame, not a copy cached before.
+ */
+export function createPadMaps(store) {
+    const maps = new Map();
+    return {
+        padMap(id) {
+            if (!maps.has(id))
+                maps.set(id, migrateControlMap(store.getJSON(KEY(id), null)));
+            return maps.get(id) ?? null;
+        },
+        store(id, map) {
+            store.setJSON(KEY(id), map);
+            maps.set(id, map);
+        },
+        skip(id) {
+            if (!maps.get(id))
+                maps.set(id, { _skip: true });
+        },
+    };
+}
+export function createPadWizard(ctx) {
+    const { t } = ctx;
+    let padWiz = null;
+    /**
+     * THIS WIZARD'S STEPS, decided when it opens: the game's positions (`PADWIZ_ORDER`, those it names) and then START and SELECT;
+     * or, where the game names none, the fourteen defaults (`DEFAULT_ORDER`), all asked, in the engine's words.
+     */
+    let defaults = false;
+    let order = PADWIZ_ORDER;
+    const gameNamesAnyPosition = () => PADWIZ_ORDER.some((action) => systemWords(action) === null && !!ctx.actionLabel(action));
+    /** Is this step asked? Every default; else the game's positions when it names them; the system's two always (`SYSTEM_WORDS`). */
+    const asked = (action) => defaults || systemWords(action) !== null || !!ctx.actionLabel(action);
+    /**
+     * A position's word, the one its question said: the engine's for START and SELECT and for every default, the game's for the
+     * rest. ⚠️ A position the game no longer names (a cartridge mounted mid-wizard) has no word, and is left out rather than shown
+     * by its id.
+     */
+    const wordFor = (action) => {
+        const system = systemWords(action);
+        if (system)
+            return t(system.name);
+        return defaults ? buttonName(ctx.t, action) : ctx.actionLabel(action);
+    };
+    /**
+     * Walks to the next step asked, or closes if there is none left. ONE function: after the last step the wizard does not stay
+     * open pointing at a position nobody asks.
+     */
+    function advance() {
+        if (!padWiz)
+            return;
+        while (padWiz.step < order.length && !asked(order[padWiz.step]))
+            padWiz.step++;
+        if (padWiz.step >= order.length)
+            closeWizard(true);
+    }
+    function ask() {
+        if (!padWiz)
+            return;
+        advance();
+        if (!padWiz)
+            return; // it closed while advancing
+        const action = order[padWiz.step];
+        const n = padWiz.step + 1, total = order.length;
+        const system = systemWords(action);
+        ctx.say(t(system?.question ?? 'pad.wiz.step', { n, total, acao: system ? '' : wordFor(action) }));
+        ctx.onStep?.(action);
+        // What is mapped, in the words it was asked with (ADR-0074) — the map's keys are position ids. The empty list's dash stays
+        // raw on purpose: it is punctuation, not language.
+        const words = Object.keys(padWiz.map).map(wordFor).filter((word) => !!word);
+        ctx.progress(t('pad.wiz.mapped', { lista: words.join(' · ') || '—' }));
+    }
+    function wire(bd) {
+        if (!padWiz)
+            return;
+        padWiz.map[order[padWiz.step]] = bd;
+        padWiz.step++;
+        padWiz.release = true; // requires letting go before the next step
+        advance();
+    }
+    function begin(gi, id, phrase) {
+        defaults = !gameNamesAnyPosition();
+        order = defaults ? DEFAULT_ORDER : PADWIZ_ORDER;
+        padWiz = { gi, id, step: -1, base: null, map: {}, release: false, baseWait: gi >= 0, axTrack: null, timer: null };
+        ctx.say(phrase);
+        ctx.onStep?.(null);
+        ctx.progress('');
+        padWiz.timer = setInterval(tickWizard, 30);
+    }
+    function openAny() { begin(-1, '', t('pad.wiz.pressAny')); }
+    function openForPad(gp) { begin(gp.index, gp.id, t('pad.wiz.detected', { id: gp.id })); }
+    function closeWizard(save) {
+        if (!padWiz)
+            return;
+        if (padWiz.timer != null)
+            clearInterval(padWiz.timer);
+        if (save && padWiz.id) {
+            ctx.maps.store(padWiz.id, padWiz.map);
+            ctx.srAlert(t('sr.pad.mapSaved', { id: padWiz.id }));
+        }
+        else if (padWiz.id) {
+            ctx.maps.skip(padWiz.id);
+        }
+        const gi = padWiz.gi;
+        const saved = save && !!padWiz.id;
+        padWiz = null;
+        ctx.onClose?.(gi, saved);
+    }
+    /* ===================== the five moments of a frame =====================
+     *
+     * 🔴 This is a STATE MACHINE, and the order below is what it is: no pad adopted · waiting for the resting pose ·
+     * waiting for the hand to let go · an axis under watch · reading what moved. Each moment is a function named for what
+     * it waits for, and `tickWizard` is their list.
+     *
+     * ⚠️ AND IT IS NOT A TABLE, unlike `input/keydown`'s chain, because the moments are not symmetric: the first runs
+     * WITHOUT a pad in hand (it is the one that picks it) and the other four need one. A list of equal rows would have to
+     * pretend the first receives what does not exist yet.
+     *
+     * 📌 Each moment receives the state instead of reaching for it, which is what lets them be read one at a time — and
+     * what removes the non-null assertions a closure looking at `padWiz` would need.
+     */
+    /** 1 · No pad adopted: the FIRST button pressed on any pad picks the pad the hand is holding. */
+    function adoptTheHandsPad(w, pads) {
+        for (const gp of pads) {
+            if (gp && gp.buttons.some((b) => b && b.pressed)) {
+                w.gi = gp.index;
+                w.id = gp.id;
+                w.baseWait = true;
+                ctx.say(t('pad.wiz.releaseAll', { id: gp.id }));
+                break;
+            }
+        }
+    }
+    /** 2 · This pad's RESTING pose, measured on the one frame in which nothing is pressed. */
+    function takeTheRestingPose(w, gp) {
+        if (gp.buttons.some((b) => b && b.pressed))
+            return;
+        w.baseWait = false;
+        w.base = { b: gp.buttons.map((x) => !!(x && x.pressed)), a: gp.axes.slice() };
+        w.step = 0;
+        ask();
+    }
+    /** 3 · The hand has to LET GO before the next question — and letting go has two halves, the buttons and the axes. */
+    function waitForTheHandToLetGo(w, gp, base) {
+        const idle = !gp.buttons.some((b, i) => b && b.pressed && !base.b[i]) && gp.axes.every((v, i) => Math.abs((v || 0) - base.a[i]) < 0.35);
+        if (idle) {
+            w.release = false;
+            ask();
+        }
+    }
+    /**
+     * 4 · An axis under watch (~240 ms): classified by BEHAVIOUR — varies continuously = analogue (threshold by sign);
+     * jumps and STAYS CONSTANT = a D-pad/POV hat (exact value, ±0.13).
+     */
+    function classifyTheWatchedAxis(w, gp, base) {
+        const tr = w.axTrack;
+        const v = gp.axes[tr.i] || 0;
+        if (Math.abs(v - tr.last) > 0.03)
+            tr.changes++;
+        tr.last = v;
+        if (Math.abs(v - base.a[tr.i]) > Math.abs(tr.v - base.a[tr.i]))
+            tr.v = v;
+        if (++tr.ticks < 8)
+            return;
+        const pv = tr.v;
+        w.axTrack = null;
+        wire(tr.changes >= 2 ? { ax: tr.i, s: pv > 0 ? 1 : -1 } : { av: tr.i, v: Math.round(pv * 10000) / 10000 });
+    }
+    /** 5 · What moved since rest: a button first, and only then an axis that really left. */
+    function readWhatMoved(w, gp, base) {
+        for (let i = 0; i < gp.buttons.length; i++) {
+            if (gp.buttons[i] && gp.buttons[i].pressed && !base.b[i]) {
+                wire({ b: i });
+                return;
+            }
+        }
+        for (let i = 0; i < gp.axes.length; i++) {
+            const v = gp.axes[i] || 0;
+            if (Math.abs(v - base.a[i]) > 0.45) {
+                w.axTrack = { i, v, last: v, changes: 0, ticks: 0 };
+                return;
+            }
+        }
+    }
+    function tickWizard() {
+        if (!padWiz)
+            return;
+        ctx.onTick?.();
+        const pads = ctx.getGamepads() ?? [];
+        if (padWiz.gi < 0) {
+            adoptTheHandsPad(padWiz, pads);
+            return;
+        }
+        const gp = pads[padWiz.gi];
+        if (!gp)
+            return; // pad disconnected (or its index not populated yet): freezes until it comes back
+        if (padWiz.baseWait) {
+            takeTheRestingPose(padWiz, gp);
+            return;
+        }
+        const base = padWiz.base;
+        if (padWiz.release) {
+            waitForTheHandToLetGo(padWiz, gp, base);
+            return;
+        }
+        if (padWiz.axTrack) {
+            classifyTheWatchedAxis(padWiz, gp, base);
+            return;
+        }
+        readWhatMoved(padWiz, gp, base);
+    }
+    return { open: openAny, openFor: openForPad, close: closeWizard, tick: tickWizard, state: () => padWiz };
+}