@the-inclusionist/engine 8.0.0 → 10.0.0

package/dist-pkg/input/gaze-cycle.d.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+import type { GazeZone } from './gaze-relative.js';
+/** The safe item: leaving on it commands nothing. */
+export declare const CANCEL = "cancel";
+export type CycleItem = Action | typeof CANCEL;
+/** Each zone's group: the direction, the face button on that side, the shoulder (ADR-0213). */
+export declare const GAZE_GROUPS: {
+    readonly [Z in GazeZone]: readonly [Action, Action, Action];
+};
+export interface GazeCycleOptions {
+    readonly entryMs?: number;
+    readonly stepMs?: number;
+    readonly closeMs?: number;
+    readonly pulseMs?: number;
+    readonly cancelFirst?: boolean;
+    readonly repeat?: boolean;
+    readonly requireOpposite?: boolean;
+    readonly oppositeMs?: number;
+    readonly deadMs?: number;
+}
+/** The defaults the lab settled on (ADR-0213). */
+export declare const GAZE_CYCLE_DEFAULTS: {
+    readonly entryMs: 800;
+    readonly stepMs: 1000;
+    readonly closeMs: 2000;
+    readonly pulseMs: 400;
+    readonly cancelFirst: true;
+    readonly repeat: true;
+    readonly requireOpposite: true;
+    readonly oppositeMs: 2000;
+    readonly deadMs: 700;
+};
+export interface GazeFrame {
+    readonly zone?: GazeZone | null;
+    readonly eyesClosed?: boolean;
+    /** Nothing could be read this frame. */
+    readonly frozen?: boolean;
+    /** Drop the gesture in hand without commanding. */
+    readonly cancel?: boolean;
+}
+export interface GazePreview {
+    readonly zone: GazeZone;
+    readonly item: CycleItem;
+    readonly index: number;
+}
+export interface GazeCycleOutput {
+    /** The action being pressed, for `pulseMs` after it was commanded. */
+    readonly pressed: Action | null;
+    /** The action commanded on THIS frame. */
+    readonly commanded: Action | null;
+    /** What leaving the zone now would command. */
+    readonly preview: GazePreview | null;
+    /** How long both eyes have been closed. */
+    readonly closedMs: number;
+    /** The zone in hand came from its opposite, so it can command. */
+    readonly armed: boolean;
+    /** The zone in hand did not arm, and will prepare the opposite one. */
+    readonly preparing: boolean;
+}
+export interface GazeCycle {
+    (nowMs: number, frame: GazeFrame): GazeCycleOutput;
+}
+export declare function createGazeCycle(options?: GazeCycleOptions): GazeCycle;

package/dist-pkg/input/gaze-cycle.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/gaze-cycle — TWELVE ACTIONS AND START FROM FOUR GAZE ZONES (ADR-0213; issue #194).
+//
+// Four zones is all the eye signal can separate, so the second dimension is TIME: the zone says which group, how long the gaze stays says
+// which action of the group. Each group is a direction, the face button on that side and a shoulder, and the child sees the action of the
+// moment before anything is pressed.
+//
+// · A zone ARMS only when the gaze came from the OPPOSITE zone within `oppositeMs` — the movement is the command, not the position, and that
+//   is what separates a decision from a gaze walking around. The visit that did not arm becomes the PREPARATION for the next; an armed visit
+//   that reached the preview spends it, so going back and forth does not command both ways, and a flicker through the target does not.
+// · While the gaze stays, the preview walks: cancel → direction → button → shoulder, every `stepMs` after `entryMs`, and round again. Cancel
+//   comes first, so a look that lands and leaves commands nothing.
+// · The action leaves when the gaze LEAVES the zone, as a pulse of `pulseMs` — otherwise reaching the shoulder would press the direction on
+//   the way.
+// · For `deadMs` after any action no visit becomes a preparation: the way back from a command overshoots into the opposite zone, and that
+//   rebound must not become the next gesture.
+// · Both eyes closed for `closeMs` press START; while they are closed the cycle freezes, because with the lids down the gaze reading is noise.
+// · A frame that could not be read (`frozen`: the head moving, no eyes) freezes the cycle too and commands nothing, not even START, and its
+//   time is given back — a frame with no reading must never look like the gaze leaving. `cancel` drops the gesture without commanding (the
+//   reader re-centred under the gaze, so what was held was never a decision).
+/** The safe item: leaving on it commands nothing. */
+export const CANCEL = 'cancel';
+/** Each zone's group: the direction, the face button on that side, the shoulder (ADR-0213). */
+export const GAZE_GROUPS = {
+    up: ['up', 'action4', 'rightShoulder'],
+    right: ['right', 'action3', 'rightTrigger'],
+    down: ['down', 'action2', 'leftTrigger'],
+    left: ['left', 'action1', 'leftShoulder'],
+};
+const OPPOSITE = { up: 'down', down: 'up', left: 'right', right: 'left' };
+/** The defaults the lab settled on (ADR-0213). */
+export const GAZE_CYCLE_DEFAULTS = {
+    entryMs: 800, stepMs: 1000, closeMs: 2000, pulseMs: 400,
+    cancelFirst: true, repeat: true, requireOpposite: true, oppositeMs: 2000, deadMs: 700,
+};
+export function createGazeCycle(options = {}) {
+    const o = { ...GAZE_CYCLE_DEFAULTS, ...options };
+    let zone = null, since = 0, index = -1, closedSince = null, frozenSince = null;
+    let pressed = null, pressedAt = 0, startGiven = false, armed = false;
+    let preparation = null, commandedAt = -Infinity;
+    const items = (z) => (o.cancelFirst ? [CANCEL, ...GAZE_GROUPS[z]] : [...GAZE_GROUPS[z], CANCEL]);
+    const preview = () => (zone && index >= 0 ? { zone, item: items(zone)[index], index } : null);
+    const mayPrepare = () => since - commandedAt >= o.deadMs;
+    const clear = (now) => { zone = null; since = 0; index = -1; frozenSince = null; armed = false; preparation = null; commandedAt = now; };
+    /** A frame with no reading: nothing moves, and the moment it began is kept, to give the time back. Returns the closed time. */
+    const holdFrozen = (now) => {
+        frozenSince ??= now;
+        return closedSince === null ? 0 : frozenSince - closedSince;
+    };
+    /** The reading is back: the time spent frozen is given back to the zone and to the closed eyes. */
+    const resumeFromFreeze = (now) => {
+        if (frozenSince === null)
+            return;
+        const paused = now - frozenSince;
+        since += paused;
+        if (closedSince !== null)
+            closedSince += paused;
+        frozenSince = null;
+    };
+    /** Both eyes closed: the cycle waits, and after `closeMs` presses START — once per closing. Returns the closed time. */
+    const whileClosed = (now, command) => {
+        closedSince ??= now;
+        if (!startGiven && now - closedSince >= o.closeMs) {
+            startGiven = true;
+            command('start');
+            clear(now);
+        }
+        return now - closedSince;
+    };
+    /** The eyes open again: the time they were closed is given back to the zone, and START may come again. */
+    const reopen = (now) => {
+        if (closedSince === null)
+            return;
+        since += now - closedSince;
+        closedSince = null;
+        startGiven = false;
+    };
+    /** Leaving a zone: an armed visit commands what its preview showed and spends the preparation; an unarmed one prepares. */
+    const leave = (now, command) => {
+        if (!zone)
+            return;
+        if (!armed) {
+            if (mayPrepare())
+                preparation = { zone, at: now };
+            return;
+        }
+        if (index < 0)
+            return; // left before the preview showed anything
+        const item = items(zone)[index];
+        if (item !== CANCEL)
+            command(item);
+        preparation = null;
+    };
+    /** Entering a zone: it arms from its opposite, prepared inside the window — or at once when that rule is off. */
+    const enter = (next, now) => {
+        zone = next;
+        since = now;
+        index = -1;
+        armed = !next || !o.requireOpposite || (!!preparation && preparation.zone === OPPOSITE[next] && now - preparation.at <= o.oppositeMs);
+    };
+    /** While an armed gaze stays, the preview walks: −1 while the look settles, then one item every `stepMs`. */
+    const walk = (now) => {
+        if (!zone || !armed)
+            return;
+        const steps = Math.floor((now - since - o.entryMs) / o.stepMs), n = items(zone).length;
+        index = o.repeat ? steps % n : Math.min(n - 1, steps);
+    };
+    return (now, { zone: next = null, eyesClosed = false, frozen = false, cancel = false }) => {
+        let commanded = null;
+        const command = (action) => { commanded = action; pressed = action; pressedAt = now; commandedAt = now; };
+        const out = (closedMs) => {
+            if (pressed && now - pressedAt >= o.pulseMs)
+                pressed = null;
+            return { pressed, commanded, preview: preview(), closedMs, armed, preparing: !!zone && !armed && mayPrepare() };
+        };
+        if (cancel) {
+            clear(now);
+            return out(0);
+        }
+        if (frozen)
+            return out(holdFrozen(now));
+        resumeFromFreeze(now);
+        if (eyesClosed)
+            return out(whileClosed(now, command));
+        reopen(now);
+        if (next !== zone) {
+            leave(now, command);
+            enter(next, now);
+        }
+        walk(now);
+        return out(0);
+    };
+}

package/dist-pkg/input/gaze-relative.d.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { EyeGaze } from './face-signals.js';
+/** The four zones, as the gaze moves on the screen. */
+export type GazeZone = 'up' | 'down' | 'left' | 'right';
+/** Why a frame gave no zone, or what the reader is doing; null when it is simply reading. */
+export type GazeReason = 'no-eyes' | 'gaze-moving' | 'measuring-rest' | 'rest-measured' | 'head-moving' | 'recentring' | null;
+export interface GazeReaderOptions {
+    readonly restMs?: number;
+    /** The threshold up and down, in tremors of the rest. */
+    readonly vertical?: number;
+    /** The threshold to the sides, in tremors of the rest. */
+    readonly sideways?: number;
+    readonly exit?: number;
+    readonly axisSwitch?: number;
+    readonly tremorFloor?: number;
+    readonly tremorMax?: number;
+    readonly followMs?: number;
+    readonly parkedMs?: number;
+    readonly parkedFollowMs?: number;
+    readonly headMaxDegPerSecond?: number;
+}
+/** The defaults the lab settled on (ADR-0213): 4 tremors vertically, 8 sideways, a rest of three still seconds. */
+export declare const GAZE_DEFAULTS: {
+    readonly restMs: 3000;
+    readonly vertical: 4;
+    readonly sideways: 8;
+    readonly exit: 0.6;
+    readonly axisSwitch: 1.3;
+    readonly tremorFloor: 0.02;
+    readonly tremorMax: 0.05;
+    readonly followMs: 12000;
+    readonly parkedMs: 10000;
+    readonly parkedFollowMs: 1500;
+    readonly headMaxDegPerSecond: 60;
+};
+export interface GazeSample {
+    readonly h: number | null | undefined;
+    readonly v: number | null | undefined;
+    readonly pose?: {
+        readonly yaw: number;
+        readonly pitch: number;
+    } | null;
+}
+export interface GazeReading {
+    readonly zone: GazeZone | null;
+    readonly ready: boolean;
+    readonly reason: GazeReason;
+    readonly rest?: EyeGaze | null;
+    readonly tremor?: EyeGaze | null;
+    /** Displacement from the rest, in tremors of each axis (the horizontal NOT scaled). */
+    readonly displacement?: EyeGaze;
+    /** The larger displacement, in vertical units. */
+    readonly strength?: number;
+    readonly parked?: boolean;
+    /** While measuring: how long the gaze has been still. */
+    readonly stillMs?: number;
+}
+export interface GazeReader {
+    (nowMs: number, sample: GazeSample): GazeReading;
+    state(): {
+        readonly rest: EyeGaze | null;
+        readonly tremor: EyeGaze | null;
+        readonly zone: GazeZone | null;
+    };
+    /** Forget the rest, so the next frames measure a new one. */
+    reset(): void;
+}
+export declare function createGazeReader(options?: GazeReaderOptions): GazeReader;

package/dist-pkg/input/gaze-relative.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/gaze-relative — WHERE THE GAZE WENT, MEASURED FROM ITS OWN REST (ADR-0213; issue #194).
+//
+// Nothing here knows where the screen is, and there is no calibration: the reader knows where the eye RESTS and how far it has moved from
+// there, and four zones need only the direction of the movement.
+//
+// · The rest is the median of `restMs` of frames that were CONTINUOUSLY still, and its scatter (MAD × 1.4826) is measured at the same time.
+//   While the gaze keeps moving the stretch restarts, so nothing is read before a real rest — the rest must never be taken while the child
+//   reads or looks around, or the threshold is born from a moving gaze and no look can reach it.
+// · A zone is reached when the eye leaves the rest by more than `vertical` of its own tremors; the sides have their own threshold
+//   (`sideways`), because for the same intent the eyes move further sideways. The horizontal displacement is scaled into vertical units
+//   before anything looks at it, so the threshold, the exit and the contest between the axes all speak the same unit.
+// · The zone is the axis that moved further. It holds while the displacement stays above `exit` of the threshold, and the other axis must
+//   beat it by `axisSwitch` to take it — a gaze between two zones would otherwise flicker, and every flicker restarts the command cycle.
+// · The rest follows slowly while the gaze is near it, so a drifting sensor does not command by itself.
+// · A gaze PARKED (range within ±2 tremors, not the MAD — a MAD shrugs off a gaze that keeps coming back) for `parkedMs` re-centres the rest
+//   onto itself: a rest that went stale leaves a zone marked after the eyes came back to the middle, and nothing else can unmark it.
+// · A frame where the head turned fast is not read: a head turn imitates an eye movement.
+/** The defaults the lab settled on (ADR-0213): 4 tremors vertically, 8 sideways, a rest of three still seconds. */
+export const GAZE_DEFAULTS = {
+    restMs: 3000, vertical: 4, sideways: 8, exit: 0.6, axisSwitch: 1.3, tremorFloor: 0.02, tremorMax: 0.05,
+    followMs: 12000, parkedMs: 10000, parkedFollowMs: 1500, headMaxDegPerSecond: 60,
+};
+const AXIS_OF = { up: 'v', down: 'v', left: 'h', right: 'h' };
+const median = (xs) => {
+    const a = [...xs].sort((x, y) => x - y);
+    return a.length % 2 ? a[(a.length - 1) / 2] : (a[a.length / 2 - 1] + a[a.length / 2]) / 2;
+};
+const spread = (xs, m) => median(xs.map((x) => Math.abs(x - m))) * 1.4826;
+const range = (xs) => Math.max(...xs) - Math.min(...xs);
+export function createGazeReader(options = {}) {
+    const o = { ...GAZE_DEFAULTS, ...options };
+    let stillSince = null, rest = null, tremor = null, zone = null;
+    let lastPose = null, lastMs = null, parkedSince = null;
+    const restH = [], restV = [];
+    const recentH = [], recentV = [], recentT = [];
+    /*
+     * The reading is SIX QUESTIONS asked in order, and each one is a step below instead of a paragraph inside `read`:
+     * did the head move · is there a rest yet · is the gaze still · is it parked · which zone did it reach · where does
+     * the rest go next. They are steps and not helpers: the order is the reading, and each answer feeds the next.
+     */
+    /** What the head did since the last frame. A turn imitates an eye movement, so the frame it happens in is not read. */
+    const headMotion = (now, pose) => {
+        const dtMs = lastMs === null ? 0 : Math.max(0, now - lastMs);
+        const headMoving = pose && lastPose && dtMs > 0
+            ? Math.hypot(pose.yaw - lastPose.yaw, pose.pitch - lastPose.pitch) / (dtMs / 1000) > o.headMaxDegPerSecond
+            : false;
+        lastPose = pose;
+        lastMs = now;
+        return { dtMs, headMoving };
+    };
+    /** The rest, while it is still being taken: a gaze that keeps moving restarts the stretch instead of widening it. */
+    const measureRest = (now, h, v) => {
+        stillSince ??= now;
+        restH.push(h);
+        restV.push(v);
+        const mh = median(restH), mv = median(restV), sh = spread(restH, mh), sv = spread(restV, mv);
+        if (restH.length > 4 && Math.max(sh, sv) > o.tremorMax) {
+            stillSince = now;
+            restH.length = 0;
+            restV.length = 0;
+            return { zone: null, ready: false, reason: 'gaze-moving', stillMs: 0 };
+        }
+        if (now - stillSince < o.restMs)
+            return { zone: null, ready: false, reason: 'measuring-rest', stillMs: now - stillSince };
+        rest = { h: mh, v: mv };
+        tremor = { h: Math.max(o.tremorFloor, sh), v: Math.max(o.tremorFloor, sv) };
+        return { zone: null, ready: true, reason: 'rest-measured', rest, tremor, stillMs: now - stillSince };
+    };
+    /** Was the gaze still over the LAST SECOND? The window forgets on purpose — a gaze that moved and then held must be able to settle. */
+    const stillOverTheLastSecond = (now, h, v, scatter) => {
+        recentH.push(h);
+        recentV.push(v);
+        recentT.push(now);
+        while (recentT.length && now - recentT[0] > 1000) {
+            recentH.shift();
+            recentV.shift();
+            recentT.shift();
+        }
+        return recentH.length > 5 && range(recentH) <= 4 * scatter.h && range(recentV) <= 4 * scatter.v;
+    };
+    /** A gaze still for `parkedMs` is a rest by definition: nothing is pushing it, so the rest may move onto it. */
+    const parkedFor = (now, still, headMoving) => {
+        if (!still || headMoving)
+            parkedSince = null;
+        else
+            parkedSince ??= now;
+        return parkedSince !== null && now - parkedSince >= o.parkedMs;
+    };
+    /** Which axis owns the movement: the one that went further, unless the zone in hand keeps it by `axisSwitch`. */
+    const axisThatWon = (ah, av, threshold, held) => {
+        const further = ah >= av ? 'h' : 'v';
+        if (!held)
+            return further;
+        const mine = AXIS_OF[held] === 'h' ? ah : av, other = AXIS_OF[held] === 'h' ? av : ah;
+        return mine >= threshold && other < mine * o.axisSwitch ? AXIS_OF[held] : further;
+    };
+    /** The zone the displacement reached, and how far it went — in vertical units, which is what both axes speak. */
+    const zoneReached = (dh, dv, headMoving, held) => {
+        const threshold = held ? o.vertical * o.exit : o.vertical;
+        const strength = Math.max(Math.abs(dh), Math.abs(dv));
+        if (headMoving || strength < threshold)
+            return { zone: null, strength };
+        const axis = axisThatWon(Math.abs(dh), Math.abs(dv), threshold, held);
+        return { zone: axis === 'h' ? (dh > 0 ? 'left' : 'right') : (dv > 0 ? 'down' : 'up'), strength };
+    };
+    /** Where the rest goes next: slowly towards a gaze that is near it, quickly onto one that has parked. */
+    const restFollowing = (at, h, v, dtMs, headMoving, near, parked) => {
+        if (headMoving || (!near && !parked))
+            return at;
+        const k = Math.min(1, dtMs / (parked ? o.parkedFollowMs : o.followMs));
+        return { h: at.h + (h - at.h) * k, v: at.v + (v - at.v) * k };
+    };
+    const read = (now, { h, v, pose = null }) => {
+        if (typeof h !== 'number' || typeof v !== 'number')
+            return { zone: null, ready: !!rest, reason: 'no-eyes' };
+        const { dtMs, headMoving } = headMotion(now, pose);
+        if (!rest || !tremor)
+            return measureRest(now, h, v);
+        const parked = parkedFor(now, stillOverTheLastSecond(now, h, v, tremor), headMoving);
+        const dhRaw = (h - rest.h) / tremor.h, dv = (v - rest.v) / tremor.v;
+        const { zone: reached, strength } = zoneReached(dhRaw * (o.vertical / o.sideways), dv, headMoving, zone);
+        zone = reached;
+        rest = restFollowing(rest, h, v, dtMs, headMoving, !zone && strength < o.vertical / 2, parked);
+        return {
+            zone, ready: true, displacement: { h: dhRaw, v: dv }, strength, parked, rest, tremor,
+            reason: headMoving ? 'head-moving' : parked ? 'recentring' : null,
+        };
+    };
+    return Object.assign(read, {
+        state: () => ({ rest, tremor, zone }),
+        reset: () => {
+            stillSince = null;
+            parkedSince = null;
+            rest = null;
+            tremor = null;
+            zone = null;
+            for (const a of [restH, restV, recentH, recentV, recentT])
+                a.length = 0;
+        },
+    });
+}

package/dist-pkg/input/hand-map.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { Action } from '../core/actions.js';
+export type HandGesture = 'indexUp' | 'indexDown' | 'indexLeft' | 'indexRight' | 'iLoveYou' | 'dog' | 'victory' | 'fist' | 'openPalm' | 'zero' | 'thumbUp' | 'thumbDown' | 'threeFingers' | 'fourFingers';
+/** The Dev's map (ADR-0210). */
+export declare const HAND_MAP: {
+    readonly [G in HandGesture]: Action;
+};
+/** MediaPipe Gesture Recognizer category names the map uses, and what they are here. */
+export declare const CANNED_GESTURES: {
+    readonly [name: string]: HandGesture;
+};
+export interface HandPoint {
+    readonly x: number;
+    readonly y: number;
+    readonly z?: number;
+}
+/** The gestures this module reads from the landmarks (usually none or one). */
+export declare function customGestures(m: readonly HandPoint[] | null | undefined): HandGesture[];
+/** Every gesture seen in a frame: the recognizer's categories plus the landmark rules. */
+export declare function gesturesSeen(landmarks: readonly HandPoint[] | null | undefined, cannedNames: Iterable<string>): Set<HandGesture>;
+/** The whole reader: a frame's gestures in, the actions held and the ones that just started out. */
+export declare function createHandMapReader({ fullMs, mark }?: {
+    fullMs?: number;
+    mark?: number;
+}): (ms: number, seen: ReadonlySet<HandGesture>) => {
+    held: Action[];
+    started: Action[];
+};

package/dist-pkg/input/hand-map.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/hand-map — THE HANDS AS A CONTROLLER: FOURTEEN GESTURES AND THE ACTIONS THEY PRESS (ADR-0210, ADR-0206; issue #191).
+//
+// The Dev's map, measured in the lab's bar rounds (14 of 14 read, the exclusions below taken from those runs). Six gestures are MediaPipe's
+// Gesture Recognizer's own; eight are read here from the 21 hand landmarks, in an orientation-free form — a finger is out when its tip is
+// farther from the wrist than its middle joint, distances in palm sizes (cvzone's `fingersUp` idea without its x test, which flips with the
+// hand). A gesture presses once it has been seen for 300 ms (its level, seen time over 600 ms, reaches 0.5), and stays pressed while seen.
+// · Exclusions: an index pointing down brings MediaPipe's Thumb_Down, an open hand reads as four fingers (the thumb seen folded), a fist as a
+//   zero — the specific one clears the other.
+// · Directions are the CHILD'S: the video a child sees is mirrored, so the child's right is the image's −x.
+// ⚠️ Levels are keyed by gesture, never by action (ADR-0112); HAND_MAP turns the held gestures into actions.
+/** The Dev's map (ADR-0210). */
+export const HAND_MAP = {
+    indexUp: 'up', indexDown: 'down', indexLeft: 'left', indexRight: 'right', iLoveYou: 'start', dog: 'select',
+    victory: 'action1', fist: 'action2', openPalm: 'action3', zero: 'action4',
+    thumbUp: 'leftShoulder', thumbDown: 'leftTrigger', threeFingers: 'rightShoulder', fourFingers: 'rightTrigger',
+};
+const GESTURES = Object.keys(HAND_MAP);
+/** MediaPipe Gesture Recognizer category names the map uses, and what they are here. */
+export const CANNED_GESTURES = {
+    ILoveYou: 'iLoveYou', Victory: 'victory', Closed_Fist: 'fist', Open_Palm: 'openPalm', Thumb_Up: 'thumbUp', Thumb_Down: 'thumbDown',
+};
+// The landmark numbers MediaPipe hands out, named where the rules use them: a rule that reads `apart(MIDDLE_TIP,
+// THUMB_TIP)` says what it is looking at, and `dist(m[12], m[4])` makes the reader count on their fingers.
+const WRIST = 0, THUMB_JOINT = 3, THUMB_TIP = 4, INDEX_BASE = 5, INDEX_JOINT = 7, INDEX_TIP = 8;
+const MIDDLE_BASE = 9, MIDDLE_TIP = 12, RING_TIP = 16, LITTLE_TIP = 20;
+const FINGERS = { index: [5, 6, 8], middle: [9, 10, 12], ring: [13, 14, 16], little: [17, 18, 20] };
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+/** Where the index points, as the CHILD sees it: the video a child watches is mirrored, so the child's right is −x. */
+const wayOfTheIndex = (m) => {
+    const dx = -(m[INDEX_TIP].x - m[INDEX_BASE].x), dy = m[INDEX_TIP].y - m[INDEX_BASE].y;
+    return Math.abs(dx) > Math.abs(dy) ? (dx > 0 ? 'Right' : 'Left') : (dy > 0 ? 'Down' : 'Up');
+};
+const readHand = (m, palm) => {
+    const out = {};
+    for (const [name, [base, joint, tip]] of Object.entries(FINGERS)) {
+        // BOTH halves, and each catches a hand the other lets through: a finger curled SIDEWAYS reaches away from its
+        // base without passing its joint, and one pointing AT THE CAMERA passes its joint without reaching anywhere.
+        out[name] = dist(m[tip], m[WRIST]) > dist(m[joint], m[WRIST]) * 1.1 && dist(m[tip], m[base]) > palm * 0.55;
+    }
+    return {
+        out,
+        // far from the index AND leading its own joint: the second half is what tells an out thumb from one tucked
+        // across the palm, which is how a hand rests
+        thumbOut: dist(m[THUMB_TIP], m[INDEX_BASE]) > palm * 0.75
+            && dist(m[THUMB_TIP], m[WRIST]) > dist(m[THUMB_JOINT], m[WRIST]),
+        way: wayOfTheIndex(m),
+        apart: (a, b) => dist(m[a], m[b]) / palm,
+        folded: (...fs) => fs.every((f) => !out[f]),
+    };
+};
+/** A fingertip this close to the thumb, in palms, is ON it. */
+const NEAR = 0.35;
+/*
+ * ONE ROW PER GESTURE, in the order they are answered — a table because that is what this already was: a gesture is
+ * a predicate over the hand plus the name it gives itself. The six `if`s these rows replace all reached for the same
+ * six locals, which is what made this the worst function of the tree outside the composition root (33 paths against
+ * McCabe's 10). A gesture the Dev adds is now a LINE.
+ */
+const RULES = [
+    {
+        name: (h) => `index${h.way}`,
+        // the thumb AWAY from the index joint is what keeps a pinch from commanding a direction — the lab dropped the
+        // pinch from the map (ADR-0206), and without this half a pinch would come back in as a direction
+        reads: (h) => h.out.index && h.folded('middle', 'ring', 'little') && h.apart(THUMB_TIP, INDEX_JOINT) >= 0.3,
+    },
+    { name: () => 'victory', reads: (h) => h.out.index && h.out.middle && h.folded('ring', 'little') && h.way === 'Up' },
+    { name: () => 'threeFingers', reads: (h) => h.out.index && h.out.middle && h.out.ring && !h.out.little && !h.thumbOut },
+    { name: () => 'fourFingers', reads: (h) => h.out.index && h.out.middle && h.out.ring && h.out.little && !h.thumbOut },
+    {
+        name: () => 'dog',
+        reads: (h) => h.apart(MIDDLE_TIP, THUMB_TIP) < NEAR && h.apart(RING_TIP, THUMB_TIP) < NEAR && h.out.index && h.out.little,
+    },
+    {
+        name: () => 'zero',
+        reads: (h) => [INDEX_TIP, MIDDLE_TIP, RING_TIP, LITTLE_TIP].every((i) => h.apart(i, THUMB_TIP) < 0.6)
+            && h.apart(INDEX_TIP, THUMB_TIP) < NEAR,
+    },
+];
+/** The gestures this module reads from the landmarks (usually none or one). */
+export function customGestures(m) {
+    if (!m || m.length < 21)
+        return [];
+    /*
+     * 🔴 A HAND WITH NO SIZE IS NOT A HAND, and the floor this line used to carry (`|| 1e-6`) got that backwards. It was
+     * there to keep the divisions safe, and it did — but it also gave every ratio an answer: 📏 measured on 2026-09-23,
+     * a frame whose 21 landmarks all collapsed onto one point read as a `zero`, because every fingertip then sits ZERO
+     * palms from the thumb. A detection that failed pressed action4. Refusing the frame is what «not readable» means.
+     *
+     * ⚠️ And the honest note about the line below: with the floor gone it is EQUIVALENT today — a palm of zero makes
+     * every ratio NaN, and `NaN < 0.6` is false, so every rule declines on its own. That is correctness by accident:
+     * it holds only while every rule compares with `<`. The line says the refusal where a reader looks for it, and
+     * the mutation that proves it is not decoration is putting the floor back, which goes red.
+     */
+    const palm = dist(m[WRIST], m[MIDDLE_BASE]);
+    if (!(palm > 0))
+        return [];
+    const hand = readHand(m, palm);
+    return RULES.filter((r) => r.reads(hand)).map((r) => r.name(hand));
+}
+/** Every gesture seen in a frame: the recognizer's categories plus the landmark rules. */
+export function gesturesSeen(landmarks, cannedNames) {
+    const seen = new Set(customGestures(landmarks));
+    for (const n of cannedNames) {
+        const g = CANNED_GESTURES[n];
+        if (g)
+            seen.add(g);
+    }
+    return seen;
+}
+const DOMINATES = { indexDown: 'thumbDown', openPalm: 'fourFingers', fist: 'zero' };
+/** The whole reader: a frame's gestures in, the actions held and the ones that just started out. */
+export function createHandMapReader({ fullMs = 600, mark = 0.5 } = {}) {
+    const since = new Map(), held = new Set();
+    return (ms, seen) => {
+        const level = (g) => {
+            if (!seen.has(g)) {
+                since.delete(g);
+                return 0;
+            }
+            if (!since.has(g))
+                since.set(g, ms);
+            return Math.min(1, (ms - since.get(g)) / fullMs);
+        };
+        const levels = new Map(GESTURES.map((g) => [g, level(g)]));
+        for (const [strong, weak] of Object.entries(DOMINATES))
+            if (levels.get(strong) >= mark)
+                levels.set(weak, 0);
+        const started = [];
+        for (const g of GESTURES) {
+            if (levels.get(g) >= mark) {
+                if (!held.has(g)) {
+                    held.add(g);
+                    started.push(HAND_MAP[g]);
+                }
+            }
+            else
+                held.delete(g);
+        }
+        return { held: [...held].map((g) => HAND_MAP[g]), started };
+    };
+}

package/dist-pkg/input/input-cooldown.d.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** What the root does with the press: let it through, or drop it as an accident. */
+export type CooldownDecision = 'accept' | 'refuse';
+export interface InputCooldown {
+    /**
+     * A game key goes down. `held` is whether this same key is already down — the auto-repeat of a hand that is holding, which is
+     * one input and not a second.
+     */
+    keydown(code: string, now: number, ms: number, held: boolean): CooldownDecision;
+    /** A game key comes up. Always accepted, and it does not start a new wait. */
+    keyup(code: string): CooldownDecision;
+    /** Forgets the wait. The root calls it when the child turns the setting off, so the next press is not refused by an old one. */
+    reset(): void;
+}
+/** The GAG's number, and the only one offered until somebody measures another on a real hand (ADR-0217 §3). */
+export declare const COOLDOWN_MS = 500;
+export declare function createInputCooldown(): InputCooldown;

package/dist-pkg/input/input-cooldown.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// input/input-cooldown — A TREMOR IS NOT A SECOND PRESS (ADR-0217; GAG Advanced/Motor, issue #182).
+//
+// A hand that shakes, a spasm, a finger that bounces off a key: the same press arrives twice, the game hears two, and the child
+// who could not avoid the second one loses the turn. After a key is accepted, this refuses a press that STARTS for as long as
+// the cool-down runs.
+//
+// ⚠️ IT IS AN ACCOMMODATION AND NOT A SIMULATION, which is why it is not in `input/empathy-filter`: that module's first
+// paragraph draws the line — a simulation makes play harder on purpose, to show an adult what a disability costs — and a rule
+// that HELPS living beside them would blur it for whoever reads either one.
+//
+// WHAT IT NEVER REFUSES, and each one is a way a child would lose the game instead of being helped:
+//   · A RELEASE. A key refused on the way down is still held by a hand; if its release were refused too, a character would walk
+//     on after the child let go, and she would have no way to stop.
+//   · THE REPEAT OF A KEY SHE IS HOLDING. Holding is one input, however many times the system says so.
+//   · A PRESS ONCE THE TIME HAS PASSED — and the time is counted from the last press ACCEPTED, not from the last one seen, or a
+//     tremor of ten bounces would push the window forward ten times and the child would never be heard again.
+//
+// Pure: it is told the time, it answers a decision. No clock, no document, no keyboard.
+/** The GAG's number, and the only one offered until somebody measures another on a real hand (ADR-0217 §3). */
+export const COOLDOWN_MS = 500;
+export function createInputCooldown() {
+    let lastAccepted = null;
+    return {
+        keydown(_code, now, ms, held) {
+            if (held)
+                return 'accept'; // the system repeating a key the hand never let go of
+            // 📌 «Off» needs no line of its own: with `ms` at 0 no elapsed time is ever less than it, so the comparison below answers
+            // «accept» for every press. A guard saying the same thing was here and was removed — a mutation proved it changed nothing,
+            // which is the definition of a line that only looks like a decision.
+            if (lastAccepted !== null && now - lastAccepted < ms)
+                return 'refuse';
+            lastAccepted = now;
+            return 'accept';
+        },
+        keyup() { return 'accept'; },
+        reset() { lastAccepted = null; },
+    };
+}