@woosh/meep-engine 2.169.1 → 2.169.2

package/src/engine/input/devices/gamepad/prototypeGamepadTester.js

@@ -0,0 +1,2124 @@
+import Vector2 from "../../../../core/geom/Vector2.js";
+import { EngineHarness } from "../../../EngineHarness.js";
+import { apply_radial_dead_zone } from "../../analog/apply_radial_dead_zone.js";
+import { GamepadAxes } from "./GamepadAxes.js";
+import { GamepadButtons } from "./GamepadButtons.js";
+import { GAMEPAD_LAYOUT_ABSENT, GAMEPAD_STANDARD_LAYOUT } from "./GamepadLayout.js";
+import { gamepad_write_dpad_vector } from "./gamepad_write_dpad_vector.js";
+import { GAMEPAD_STANDARD_AXIS_COUNT, GAMEPAD_STANDARD_BUTTON_COUNT } from "./GamepadStandardMapping.js";
+
+/**
+ * Gamepad tester.
+ *
+ * Two layers over the same hardware, drawn one above the other so they can be read against each other:
+ *
+ *  - Layer 1 is {@link GamepadDevice}, reached through `engine.devices.gamepad`. It shows what a consumer of the
+ *    engine sees: the persistent {@link GamepadDevice#main} handle, switches and their press counts, raw axes,
+ *    per-stick calibration, and the composition the device documents (dead zone + D-pad vector + fusion).
+ *  - Layer 2 is `navigator.getGamepads()` read directly, with no engine in the path. It shows what the browser
+ *    reports, unfiltered.
+ *
+ * Between them sits a parity strip that diffs the two, because the device layer's contract is that `axes` and
+ * button values are a byte-exact mirror of the hardware snapshot. Anything that layer changes shows up there.
+ *
+ * Both layers are read from one animation frame, and the device's own poll runs earlier in that same frame
+ * (it registers its callback when the engine is constructed), so the two views describe the same instant.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Button index -> name of the standard mapping, derived so the two never drift apart
+ * @readonly
+ * @type {string[]}
+ */
+const BUTTON_NAMES = [];
+
+for (const name in GamepadButtons) {
+    BUTTON_NAMES[GamepadButtons[name]] = name;
+}
+
+/**
+ * Axis index -> name of the standard mapping
+ * @readonly
+ * @type {string[]}
+ */
+const AXIS_NAMES = [];
+
+for (const name in GamepadAxes) {
+    AXIS_NAMES[GamepadAxes[name]] = name;
+}
+
+/**
+ * Edge length of a stick scope, in CSS pixels
+ * @type {number}
+ */
+const SCOPE_SIZE = 176;
+
+/**
+ * How many past raw samples a scope draws as a trail. At 60Hz this is about 1.5 seconds, enough to see a
+ * snap-back overshoot or a slow drift walk.
+ * @type {number}
+ */
+const TRAIL_SAMPLE_COUNT = 90;
+
+const TIMELINE_WIDTH = 680;
+const TIMELINE_HEIGHT = 150;
+
+/**
+ * About 8 seconds at 60Hz
+ * @type {number}
+ */
+const TIMELINE_SAMPLE_COUNT = 480;
+
+/**
+ * Channels plotted by {@link AxisTimelineView}. Triggers are included because they are the analog inputs that
+ * are not axes, and their travel is exactly what a tester is here to look at.
+ * @readonly
+ */
+const TIMELINE_CHANNELS = [
+    { label: "left stick x", color: "#4ade80" },
+    { label: "left stick y", color: "#22d3ee" },
+    { label: "right stick x", color: "#f472b6" },
+    { label: "right stick y", color: "#fbbf24" },
+    { label: "left trigger", color: "#a78bfa" },
+    { label: "right trigger", color: "#fb923c" }
+];
+
+const MAX_LOG_ENTRIES = 200;
+
+/**
+ * Standard button indices that form the D-pad, which a non-standard pad may drive from a hat axis instead
+ * @readonly
+ * @type {number[]}
+ */
+const DPAD_BUTTONS = [
+    GamepadButtons.dpad_up,
+    GamepadButtons.dpad_right,
+    GamepadButtons.dpad_down,
+    GamepadButtons.dpad_left
+];
+
+const STYLE = `
+.gpt-root {
+    position: fixed;
+    left: 0;
+    top: 0;
+    width: 100%;
+    height: 100%;
+    overflow: auto;
+    box-sizing: border-box;
+    padding: 16px;
+    background: #0f1216;
+    color: #d7dee8;
+    font: 12px/1.45 "Consolas", "Menlo", monospace;
+    z-index: 100;
+}
+.gpt-root h1 {
+    margin: 0 0 2px 0;
+    font-size: 17px;
+    font-weight: 600;
+    letter-spacing: 0.4px;
+}
+.gpt-root h2 {
+    margin: 0;
+    font-size: 13px;
+    font-weight: 600;
+    letter-spacing: 0.4px;
+}
+.gpt-muted {
+    color: #7d8899;
+}
+.gpt-header {
+    margin-bottom: 14px;
+}
+.gpt-layer {
+    border: 1px solid #262d38;
+    border-radius: 6px;
+    background: #161a21;
+    margin-bottom: 12px;
+}
+.gpt-layer-head {
+    display: flex;
+    align-items: baseline;
+    gap: 10px;
+    padding: 8px 12px;
+    border-bottom: 1px solid #262d38;
+    background: #1a1f28;
+    border-radius: 6px 6px 0 0;
+}
+.gpt-layer-badge {
+    padding: 1px 7px;
+    border-radius: 10px;
+    background: #2b3442;
+    color: #9fb0c6;
+    font-size: 11px;
+}
+.gpt-layer-body {
+    padding: 12px;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+}
+.gpt-panel {
+    border: 1px solid #232a35;
+    border-radius: 5px;
+    padding: 9px 10px;
+    background: #12161c;
+}
+.gpt-panel-title {
+    color: #8fa0b6;
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.7px;
+    margin-bottom: 7px;
+}
+.gpt-kv {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: 1px 10px;
+}
+.gpt-kv > .gpt-k {
+    color: #7d8899;
+}
+.gpt-kv > .gpt-v {
+    color: #d7dee8;
+    word-break: break-all;
+}
+.gpt-buttons {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(112px, 1fr));
+    gap: 5px;
+    width: 480px;
+}
+.gpt-button {
+    border: 1px solid #232a35;
+    border-radius: 4px;
+    padding: 4px 6px;
+    background: #12161c;
+}
+.gpt-button.gpt-down {
+    border-color: #4ade80;
+    background: #16241c;
+}
+.gpt-button-head {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+}
+.gpt-pip {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: #2b3442;
+    flex: none;
+}
+.gpt-down .gpt-pip {
+    background: #4ade80;
+    box-shadow: 0 0 6px #4ade80;
+}
+.gpt-button-name {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.gpt-button-index, .gpt-button-count {
+    color: #7d8899;
+    font-size: 10px;
+}
+.gpt-bar {
+    position: relative;
+    height: 5px;
+    margin-top: 4px;
+    border-radius: 3px;
+    background: #1e242e;
+    overflow: hidden;
+}
+.gpt-bar-fill {
+    position: absolute;
+    top: 0;
+    height: 100%;
+    background: #4ade80;
+}
+.gpt-bar-fill.gpt-signed {
+    background: #22d3ee;
+}
+.gpt-axis {
+    display: grid;
+    grid-template-columns: 92px 1fr 64px;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 3px;
+}
+.gpt-axis .gpt-bar {
+    margin-top: 0;
+    height: 8px;
+}
+.gpt-axis-value {
+    text-align: right;
+    color: #b9c4d3;
+}
+.gpt-sticks {
+    display: flex;
+    gap: 12px;
+}
+.gpt-stick canvas {
+    display: block;
+    border: 1px solid #232a35;
+    border-radius: 4px;
+    background: #0d1014;
+}
+.gpt-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-top: 5px;
+    font-size: 11px;
+}
+.gpt-legend span:before {
+    content: "";
+    display: inline-block;
+    width: 7px;
+    height: 7px;
+    border-radius: 50%;
+    margin-right: 4px;
+    background: currentColor;
+}
+.gpt-controls {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+}
+.gpt-control {
+    display: grid;
+    grid-template-columns: 96px 1fr 44px;
+    align-items: center;
+    gap: 8px;
+}
+.gpt-root input[type="range"] {
+    width: 100%;
+}
+.gpt-root button {
+    font: inherit;
+    color: #d7dee8;
+    background: #232a35;
+    border: 1px solid #303a48;
+    border-radius: 4px;
+    padding: 3px 9px;
+    cursor: pointer;
+}
+.gpt-root button:hover {
+    background: #2c3543;
+}
+.gpt-log {
+    height: 150px;
+    overflow: auto;
+    background: #0d1014;
+    border: 1px solid #232a35;
+    border-radius: 4px;
+    padding: 6px 8px;
+    width: 100%;
+    box-sizing: border-box;
+}
+.gpt-log-entry {
+    white-space: pre;
+}
+.gpt-sync {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 7px 12px;
+    margin-bottom: 12px;
+    border: 1px solid #262d38;
+    border-radius: 6px;
+    background: #161a21;
+}
+.gpt-status {
+    padding: 1px 8px;
+    border-radius: 10px;
+    font-size: 11px;
+    background: #2b3442;
+    color: #9fb0c6;
+}
+.gpt-status.gpt-ok {
+    background: #16351f;
+    color: #4ade80;
+}
+.gpt-status.gpt-bad {
+    background: #3a1b1b;
+    color: #f87171;
+}
+.gpt-native-pads {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+    width: 100%;
+}
+.gpt-native-buttons {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(84px, 1fr));
+    gap: 3px;
+}
+.gpt-native-button {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    padding: 2px 4px;
+    border-radius: 3px;
+    background: #12161c;
+    border: 1px solid #232a35;
+    font-size: 11px;
+}
+.gpt-native-button.gpt-down {
+    border-color: #4ade80;
+    color: #4ade80;
+}
+.gpt-native-button.gpt-touched {
+    border-color: #fbbf24;
+}
+.gpt-pads-summary {
+    width: 100%;
+}
+.gpt-pad-row {
+    display: grid;
+    grid-template-columns: 46px 90px 1fr;
+    gap: 10px;
+    padding: 2px 0;
+    border-top: 1px solid #1c222b;
+}
+`;
+
+/**
+ *
+ * @param {string} tag
+ * @param {string} className
+ * @param {HTMLElement} [parent]
+ * @returns {HTMLElement}
+ */
+function make_element(tag, className, parent) {
+    const el = document.createElement(tag);
+
+    if (className !== "") {
+        el.className = className;
+    }
+
+    if (parent !== undefined) {
+        parent.appendChild(el);
+    }
+
+    return el;
+}
+
+/**
+ *
+ * @param {HTMLElement} el
+ * @param {string} text
+ * @returns {void}
+ */
+function write_text(el, text) {
+    if (el.textContent !== text) {
+        el.textContent = text;
+    }
+}
+
+/**
+ * Key/value grid where values are addressed by key, saving every panel from holding a field per row.
+ */
+class PropertyTableView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {Map<string,HTMLElement>}
+     */
+    #values = new Map();
+
+    /**
+     *
+     * @param {string[]} keys
+     */
+    constructor(keys) {
+        this.el = make_element("div", "gpt-kv");
+
+        const n = keys.length;
+
+        for (let i = 0; i < n; i++) {
+            const key = keys[i];
+
+            const k = make_element("div", "gpt-k", this.el);
+            k.textContent = key;
+
+            const v = make_element("div", "gpt-v", this.el);
+            v.textContent = "-";
+
+            this.#values.set(key, v);
+        }
+    }
+
+    /**
+     *
+     * @param {string} key one of the keys this table was built with
+     * @param {string} value
+     * @returns {void}
+     */
+    write(key, value) {
+        write_text(this.#values.get(key), value);
+    }
+}
+
+/**
+ * One button of {@link GamepadHandle}: state, analog travel, and how many times it has been pressed.
+ *
+ * The press count comes from the switch's own signal rather than from comparing frames, so a button that
+ * chatters - firing two presses for one physical push - shows up as a count climbing faster than the presses,
+ * which polling this view every frame could not tell you.
+ */
+class ButtonView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #fill;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #value;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #count;
+
+    /**
+     * @type {number}
+     */
+    #pressCount = 0;
+
+    /**
+     * @type {InputDeviceSwitch}
+     */
+    #source;
+
+    /**
+     *
+     * @param {number} index
+     * @param {InputDeviceSwitch} button
+     */
+    constructor(index, button) {
+        this.#source = button;
+
+        this.el = make_element("div", "gpt-button");
+
+        const head = make_element("div", "gpt-button-head", this.el);
+
+        make_element("div", "gpt-pip", head);
+
+        const name = make_element("div", "gpt-button-name", head);
+        name.textContent = BUTTON_NAMES[index] !== undefined ? BUTTON_NAMES[index] : "extra";
+
+        const indexLabel = make_element("div", "gpt-button-index", head);
+        indexLabel.textContent = String(index);
+
+        const bar = make_element("div", "gpt-bar", this.el);
+        this.#fill = make_element("div", "gpt-bar-fill", bar);
+
+        const foot = make_element("div", "gpt-button-head", this.el);
+
+        this.#value = make_element("div", "gpt-button-name gpt-muted", foot);
+        this.#count = make_element("div", "gpt-button-count", foot);
+
+        button.down.add(this.#handleDown);
+    }
+
+    #handleDown = () => {
+        this.#pressCount++;
+    }
+
+    /**
+     * Stop counting presses. Used when the grid is rebuilt for a handle with a different button count.
+     * @returns {void}
+     */
+    dispose() {
+        this.#source.down.remove(this.#handleDown);
+    }
+
+    /**
+     *
+     * @param {number} value analog travel in [0,1]
+     * @returns {void}
+     */
+    update(value) {
+        const is_down = this.#source.is_down;
+
+        this.el.classList.toggle("gpt-down", is_down);
+
+        const width = `${(value * 100).toFixed(1)}%`;
+
+        if (this.#fill.style.width !== width) {
+            this.#fill.style.width = width;
+        }
+
+        write_text(this.#value, value.toFixed(3));
+        write_text(this.#count, `x${this.#pressCount}`);
+    }
+}
+
+/**
+ * A signed [-1,1] bar with a numeric readout, drawn from the middle out.
+ */
+class AxisView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #fill;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #value;
+
+    /**
+     *
+     * @param {string} label
+     */
+    constructor(label) {
+        this.el = make_element("div", "gpt-axis");
+
+        const name = make_element("div", "", this.el);
+        name.textContent = label;
+
+        const bar = make_element("div", "gpt-bar", this.el);
+        this.#fill = make_element("div", "gpt-bar-fill gpt-signed", bar);
+
+        this.#value = make_element("div", "gpt-axis-value", this.el);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @returns {void}
+     */
+    update(value) {
+        const half = Math.min(Math.abs(value), 1) * 50;
+
+        const left = value < 0 ? `${50 - half}%` : "50%";
+        const width = `${half}%`;
+
+        if (this.#fill.style.left !== left) {
+            this.#fill.style.left = left;
+        }
+
+        if (this.#fill.style.width !== width) {
+            this.#fill.style.width = width;
+        }
+
+        write_text(this.#value, value.toFixed(4));
+    }
+}
+
+/**
+ * 2D scope for one {@link GamepadStick}.
+ *
+ * Drawn in the hardware frame, so +y is down and the canvas needs no flip. Four things are plotted on top of
+ * each other, and the point of the view is that they are usually not in the same place:
+ *
+ *  - the raw hardware value, with a trail of where it has just been;
+ *  - the learned rest position and noise radius, which is the correction the device applies;
+ *  - the calibrated value the engine hands to gameplay;
+ *  - the same value after a gameplay dead zone, which is what a game would actually move on.
+ */
+class StickScopeView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {CanvasRenderingContext2D}
+     */
+    #ctx;
+
+    /**
+     * @type {PropertyTableView}
+     */
+    #properties;
+
+    /**
+     * Interleaved x,y of past raw samples, used as a ring buffer
+     * @type {Float32Array}
+     */
+    #trail = new Float32Array(TRAIL_SAMPLE_COUNT * 2);
+
+    /**
+     * @type {number}
+     */
+    #trailCursor = 0;
+
+    /**
+     * @type {number}
+     */
+    #trailCount = 0;
+
+    /**
+     * @type {Vector2}
+     */
+    #shaped = new Vector2();
+
+    /**
+     *
+     * @param {string} label
+     */
+    constructor(label) {
+        this.el = make_element("div", "gpt-panel gpt-stick");
+
+        const title = make_element("div", "gpt-panel-title", this.el);
+        title.textContent = label;
+
+        const canvas = make_element("canvas", "", this.el);
+
+        const dpr = window.devicePixelRatio;
+
+        canvas.width = SCOPE_SIZE * dpr;
+        canvas.height = SCOPE_SIZE * dpr;
+        canvas.style.width = `${SCOPE_SIZE}px`;
+        canvas.style.height = `${SCOPE_SIZE}px`;
+
+        this.#ctx = canvas.getContext("2d");
+        this.#ctx.scale(dpr, dpr);
+
+        const legend = make_element("div", "gpt-legend", this.el);
+
+        const raw = make_element("span", "", legend);
+        raw.textContent = "raw";
+        raw.style.color = "#7d8899";
+
+        const value = make_element("span", "", legend);
+        value.textContent = "calibrated";
+        value.style.color = "#4ade80";
+
+        const shaped = make_element("span", "", legend);
+        shaped.textContent = "dead zoned";
+        shaped.style.color = "#fbbf24";
+
+        this.#properties = new PropertyTableView([
+            "raw",
+            "value",
+            "magnitude",
+            "dead zoned",
+            "center",
+            "noise radius",
+            "locked"
+        ]);
+
+        this.el.appendChild(this.#properties.el);
+    }
+
+    /**
+     *
+     * @param {GamepadStick} stick
+     * @param {number} inner gameplay dead zone, inner bound
+     * @param {number} outer gameplay dead zone, outer bound
+     * @returns {void}
+     */
+    update(stick, inner, outer) {
+        const raw = stick.raw;
+        const value = stick.value;
+        const calibration = stick.calibration;
+
+        apply_radial_dead_zone(this.#shaped, value.x, value.y, inner, outer);
+
+        const trail = this.#trail;
+
+        trail[this.#trailCursor * 2] = raw.x;
+        trail[this.#trailCursor * 2 + 1] = raw.y;
+
+        this.#trailCursor = (this.#trailCursor + 1) % TRAIL_SAMPLE_COUNT;
+        this.#trailCount = Math.min(this.#trailCount + 1, TRAIL_SAMPLE_COUNT);
+
+        this.#draw(stick);
+
+        this.#properties.write("raw", `${raw.x.toFixed(4)}, ${raw.y.toFixed(4)}`);
+        this.#properties.write("value", `${value.x.toFixed(4)}, ${value.y.toFixed(4)}`);
+        this.#properties.write("magnitude", value.length().toFixed(4));
+        this.#properties.write("dead zoned", `${this.#shaped.x.toFixed(4)}, ${this.#shaped.y.toFixed(4)}`);
+        this.#properties.write("center", `${calibration.center.x.toFixed(4)}, ${calibration.center.y.toFixed(4)}`);
+        this.#properties.write("noise radius", calibration.noiseRadius.toFixed(4));
+        this.#properties.write("locked", String(calibration.locked));
+    }
+
+    /**
+     *
+     * @param {number} v stick coordinate in [-1,1]
+     * @returns {number} canvas coordinate
+     */
+    #project(v) {
+        return (v + 1) * 0.5 * SCOPE_SIZE;
+    }
+
+    /**
+     *
+     * @param {GamepadStick} stick
+     */
+    #draw(stick) {
+        const ctx = this.#ctx;
+
+        const half = SCOPE_SIZE / 2;
+
+        ctx.clearRect(0, 0, SCOPE_SIZE, SCOPE_SIZE);
+
+        // gate
+        ctx.strokeStyle = "#232a35";
+        ctx.lineWidth = 1;
+
+        ctx.beginPath();
+        ctx.moveTo(0, half);
+        ctx.lineTo(SCOPE_SIZE, half);
+        ctx.moveTo(half, 0);
+        ctx.lineTo(half, SCOPE_SIZE);
+        ctx.stroke();
+
+        ctx.beginPath();
+        ctx.arc(half, half, half - 1, 0, Math.PI * 2);
+        ctx.stroke();
+
+        // learned rest position and noise radius
+        const calibration = stick.calibration;
+
+        const cx = this.#project(calibration.center.x);
+        const cy = this.#project(calibration.center.y);
+
+        ctx.strokeStyle = "#556070";
+        ctx.setLineDash([3, 3]);
+
+        ctx.beginPath();
+        ctx.arc(cx, cy, Math.max(calibration.noiseRadius * half, 1.5), 0, Math.PI * 2);
+        ctx.stroke();
+
+        ctx.setLineDash([]);
+
+        // trail of raw samples, oldest first
+        const trail = this.#trail;
+        const count = this.#trailCount;
+
+        ctx.lineWidth = 1;
+
+        for (let i = 1; i < count; i++) {
+            const previous = (this.#trailCursor - count + i - 1 + TRAIL_SAMPLE_COUNT * 2) % TRAIL_SAMPLE_COUNT;
+            const current = (this.#trailCursor - count + i + TRAIL_SAMPLE_COUNT * 2) % TRAIL_SAMPLE_COUNT;
+
+            ctx.strokeStyle = `rgba(125, 136, 153, ${(i / count) * 0.8})`;
+
+            ctx.beginPath();
+            ctx.moveTo(this.#project(trail[previous * 2]), this.#project(trail[previous * 2 + 1]));
+            ctx.lineTo(this.#project(trail[current * 2]), this.#project(trail[current * 2 + 1]));
+            ctx.stroke();
+        }
+
+        this.#dot(this.#project(stick.raw.x), this.#project(stick.raw.y), 4, "#9fb0c6");
+        this.#dot(this.#project(this.#shaped.x), this.#project(this.#shaped.y), 3, "#fbbf24");
+        this.#dot(this.#project(stick.value.x), this.#project(stick.value.y), 3, "#4ade80");
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} radius
+     * @param {string} color
+     */
+    #dot(x, y, radius, color) {
+        const ctx = this.#ctx;
+
+        ctx.fillStyle = color;
+
+        ctx.beginPath();
+        ctx.arc(x, y, radius, 0, Math.PI * 2);
+        ctx.fill();
+    }
+}
+
+/**
+ * Scrolling plot of the analog channels over the last few seconds.
+ *
+ * A scope shows where a stick is, this shows how it got there: snap-back overshoot, trigger travel, and the
+ * flat line of a calibrated stick at rest are all shapes in time rather than positions.
+ */
+class AxisTimelineView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {CanvasRenderingContext2D}
+     */
+    #ctx;
+
+    /**
+     * One row per channel of {@link TIMELINE_CHANNELS}, each a ring buffer sharing {@link #cursor}
+     * @type {Float32Array[]}
+     */
+    #channels = [];
+
+    /**
+     * @type {number}
+     */
+    #cursor = 0;
+
+    /**
+     * @type {number}
+     */
+    #count = 0;
+
+    constructor() {
+        this.el = make_element("div", "gpt-panel");
+
+        const title = make_element("div", "gpt-panel-title", this.el);
+        title.textContent = "analog channels over time";
+
+        const canvas = make_element("canvas", "", this.el);
+
+        const dpr = window.devicePixelRatio;
+
+        canvas.width = TIMELINE_WIDTH * dpr;
+        canvas.height = TIMELINE_HEIGHT * dpr;
+        canvas.style.width = `${TIMELINE_WIDTH}px`;
+        canvas.style.height = `${TIMELINE_HEIGHT}px`;
+        canvas.style.display = "block";
+        canvas.style.background = "#0d1014";
+        canvas.style.borderRadius = "4px";
+
+        this.#ctx = canvas.getContext("2d");
+        this.#ctx.scale(dpr, dpr);
+
+        const legend = make_element("div", "gpt-legend", this.el);
+
+        const n = TIMELINE_CHANNELS.length;
+
+        for (let i = 0; i < n; i++) {
+            const channel = TIMELINE_CHANNELS[i];
+
+            this.#channels[i] = new Float32Array(TIMELINE_SAMPLE_COUNT);
+
+            const entry = make_element("span", "", legend);
+            entry.textContent = channel.label;
+            entry.style.color = channel.color;
+        }
+    }
+
+    /**
+     *
+     * @param {GamepadHandle} pad
+     * @returns {void}
+     */
+    update(pad) {
+        const axes = pad.axes;
+        const buttonValues = pad.buttonValues;
+
+        const cursor = this.#cursor;
+
+        this.#channels[0][cursor] = axes[GamepadAxes.left_stick_x];
+        this.#channels[1][cursor] = axes[GamepadAxes.left_stick_y];
+        this.#channels[2][cursor] = axes[GamepadAxes.right_stick_x];
+        this.#channels[3][cursor] = axes[GamepadAxes.right_stick_y];
+        this.#channels[4][cursor] = buttonValues[GamepadButtons.left_trigger];
+        this.#channels[5][cursor] = buttonValues[GamepadButtons.right_trigger];
+
+        this.#cursor = (cursor + 1) % TIMELINE_SAMPLE_COUNT;
+        this.#count = Math.min(this.#count + 1, TIMELINE_SAMPLE_COUNT);
+
+        this.#draw();
+    }
+
+    #draw() {
+        const ctx = this.#ctx;
+
+        ctx.clearRect(0, 0, TIMELINE_WIDTH, TIMELINE_HEIGHT);
+
+        // zero line and unit bounds
+        ctx.strokeStyle = "#232a35";
+        ctx.lineWidth = 1;
+
+        ctx.beginPath();
+        ctx.moveTo(0, TIMELINE_HEIGHT * 0.5);
+        ctx.lineTo(TIMELINE_WIDTH, TIMELINE_HEIGHT * 0.5);
+        ctx.stroke();
+
+        const count = this.#count;
+
+        if (count < 2) {
+            return;
+        }
+
+        const step = TIMELINE_WIDTH / (TIMELINE_SAMPLE_COUNT - 1);
+
+        const n = this.#channels.length;
+
+        for (let i = 0; i < n; i++) {
+            const samples = this.#channels[i];
+
+            ctx.strokeStyle = TIMELINE_CHANNELS[i].color;
+            ctx.beginPath();
+
+            for (let j = 0; j < count; j++) {
+                const index = (this.#cursor - count + j + TIMELINE_SAMPLE_COUNT * 2) % TIMELINE_SAMPLE_COUNT;
+
+                const x = j * step;
+                const y = (1 - samples[index]) * 0.5 * TIMELINE_HEIGHT;
+
+                if (j === 0) {
+                    ctx.moveTo(x, y);
+                } else {
+                    ctx.lineTo(x, y);
+                }
+            }
+
+            ctx.stroke();
+        }
+    }
+}
+
+/**
+ * Newest-first log of the device's signals.
+ *
+ * Everything here arrives by subscription rather than by sampling, so it records what a consumer bound to these
+ * signals would have received - including presses too short to survive being sampled once a frame.
+ */
+class EventLogView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #entries;
+
+    /**
+     * @type {number}
+     */
+    #startTime = performance.now();
+
+    /**
+     * Axis signals fire at hardware sample rate on a drifting pad, so they are counted rather than logged
+     * @type {number}
+     */
+    #axisEventCount = 0;
+
+    /**
+     * @type {PropertyTableView}
+     */
+    #counters;
+
+    /**
+     * @type {number}
+     */
+    #downCount = 0;
+
+    /**
+     * @type {number}
+     */
+    #upCount = 0;
+
+    /**
+     *
+     * @param {GamepadDevice} device
+     */
+    constructor(device) {
+        this.el = make_element("div", "gpt-panel gpt-pads-summary");
+
+        const title = make_element("div", "gpt-panel-title", this.el);
+        title.textContent = "device signals";
+
+        this.#counters = new PropertyTableView(["down", "up", "axis"]);
+        this.el.appendChild(this.#counters.el);
+
+        this.#entries = make_element("div", "gpt-log", this.el);
+
+        device.on.connected.add(pad => {
+            this.#write(`connected      pad ${pad.index} "${pad.id}" mapping="${pad.mapping}"`);
+        });
+
+        device.on.disconnected.add(pad => {
+            this.#write(`disconnected   pad ${pad.index} "${pad.id}"`);
+        });
+
+        device.on.down.add((buttonIndex, pad) => {
+            this.#downCount++;
+            this.#write(`down           pad ${pad.index} button ${buttonIndex} ${this.#buttonName(buttonIndex)}`);
+        });
+
+        device.on.up.add((buttonIndex, pad) => {
+            this.#upCount++;
+            this.#write(`up             pad ${pad.index} button ${buttonIndex} ${this.#buttonName(buttonIndex)}`);
+        });
+
+        device.on.axis.add(() => {
+            this.#axisEventCount++;
+        });
+    }
+
+    /**
+     *
+     * @param {number} index
+     * @returns {string}
+     */
+    #buttonName(index) {
+        return BUTTON_NAMES[index] !== undefined ? BUTTON_NAMES[index] : "";
+    }
+
+    /**
+     *
+     * @param {string} text
+     */
+    #write(text) {
+        const seconds = (performance.now() - this.#startTime) / 1000;
+
+        const entry = make_element("div", "gpt-log-entry");
+        entry.textContent = `${seconds.toFixed(3).padStart(9)}  ${text}`;
+
+        this.#entries.insertBefore(entry, this.#entries.firstChild);
+
+        while (this.#entries.childElementCount > MAX_LOG_ENTRIES) {
+            this.#entries.removeChild(this.#entries.lastChild);
+        }
+    }
+
+    /**
+     *
+     * @returns {void}
+     */
+    update() {
+        this.#counters.write("down", String(this.#downCount));
+        this.#counters.write("up", String(this.#upCount));
+        this.#counters.write("axis", String(this.#axisEventCount));
+    }
+}
+
+/**
+ * Which device input each standard input is being read from.
+ *
+ * The thing you want when a pad misbehaves: a browser that has not recognised a device reports its inputs in
+ * the device's own order, and this is the translation being applied to get back to the standard mapping.
+ * Read it against layer 2's raw indices to check an entry, or to write a new one.
+ */
+class LayoutView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #body;
+
+    /**
+     * Layout the body was built for, so it is rebuilt only when the pad starts being read differently
+     * @type {GamepadLayout|undefined}
+     */
+    #rendered = undefined;
+
+    constructor() {
+        this.el = make_element("div", "gpt-panel");
+
+        const title = make_element("div", "gpt-panel-title", this.el);
+        title.textContent = "resolved layout";
+
+        this.#body = make_element("div", "gpt-kv", this.el);
+    }
+
+    /**
+     *
+     * @param {GamepadHandle} pad
+     * @returns {void}
+     */
+    update(pad) {
+        const layout = pad.layout;
+
+        if (this.#rendered === layout) {
+            return;
+        }
+
+        this.#rendered = layout;
+
+        this.#body.textContent = "";
+
+        this.#write("layout", layout.name);
+
+        if (layout === GAMEPAD_STANDARD_LAYOUT) {
+            this.#write("", "the browser mapped this pad, every index is passed through unchanged");
+
+            return;
+        }
+
+        for (let i = 0; i < GAMEPAD_STANDARD_AXIS_COUNT; i++) {
+            const source = layout.axisSource(i);
+
+            this.#write(AXIS_NAMES[i], source === GAMEPAD_LAYOUT_ABSENT ? "-" : `axis ${source}`);
+        }
+
+        for (let i = 0; i < GAMEPAD_STANDARD_BUTTON_COUNT; i++) {
+            this.#write(BUTTON_NAMES[i], this.#describeButtonSource(layout, i));
+        }
+    }
+
+    /**
+     *
+     * @param {GamepadLayout} layout
+     * @param {number} index standard button index
+     * @returns {string}
+     */
+    #describeButtonSource(layout, index) {
+        const button = layout.buttonSource(index);
+
+        if (button !== GAMEPAD_LAYOUT_ABSENT) {
+            return `button ${button}`;
+        }
+
+        const axis = layout.buttonAxisSource(index);
+
+        if (axis !== GAMEPAD_LAYOUT_ABSENT) {
+            return `axis ${axis}`;
+        }
+
+        if (DPAD_BUTTONS.indexOf(index) !== -1 && layout.hatAxis !== GAMEPAD_LAYOUT_ABSENT) {
+            return `hat on axis ${layout.hatAxis}`;
+        }
+
+        return "-";
+    }
+
+    /**
+     *
+     * @param {string} key
+     * @param {string} value
+     */
+    #write(key, value) {
+        const k = make_element("div", "gpt-k", this.#body);
+        k.textContent = key;
+
+        const v = make_element("div", "gpt-v", this.#body);
+        v.textContent = value;
+    }
+}
+
+/**
+ * Layer 1 - everything read through {@link GamepadDevice}.
+ */
+class EngineLayerView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {GamepadDevice}
+     */
+    #device;
+
+    /**
+     * @type {PropertyTableView}
+     */
+    #summary;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #buttonGrid;
+
+    /**
+     * @type {ButtonView[]}
+     */
+    #buttons = [];
+
+    /**
+     * @type {HTMLElement}
+     */
+    #axisList;
+
+    /**
+     * @type {AxisView[]}
+     */
+    #axes = [];
+
+    /**
+     * @type {StickScopeView}
+     */
+    #stickLeft = new StickScopeView("left stick");
+
+    /**
+     * @type {StickScopeView}
+     */
+    #stickRight = new StickScopeView("right stick");
+
+    /**
+     * @type {AxisTimelineView}
+     */
+    #timeline = new AxisTimelineView();
+
+    /**
+     * @type {EventLogView}
+     */
+    #log;
+
+    /**
+     * @type {LayoutView}
+     */
+    #layout = new LayoutView();
+
+    /**
+     * @type {PropertyTableView}
+     */
+    #composition;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #padRows;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #pressedList;
+
+    /**
+     * @type {HTMLInputElement}
+     */
+    #innerInput;
+
+    /**
+     * @type {HTMLInputElement}
+     */
+    #outerInput;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #innerValue;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #outerValue;
+
+    /**
+     * @type {Vector2}
+     */
+    #dpad = new Vector2();
+
+    /**
+     * @type {Vector2}
+     */
+    #stick = new Vector2();
+
+    /**
+     * @type {Vector2}
+     */
+    #move = new Vector2();
+
+    /**
+     *
+     * @param {GamepadDevice} device
+     */
+    constructor(device) {
+        this.#device = device;
+
+        this.el = make_element("div", "gpt-layer");
+
+        const head = make_element("div", "gpt-layer-head", this.el);
+
+        const badge = make_element("div", "gpt-layer-badge", head);
+        badge.textContent = "layer 1";
+
+        const title = make_element("h2", "", head);
+        title.textContent = "engine.devices.gamepad";
+
+        const subtitle = make_element("div", "gpt-muted", head);
+        subtitle.textContent = "GamepadDevice.main - calibrated, edge-detected, stable across pad swaps";
+
+        const body = make_element("div", "gpt-layer-body", this.el);
+
+        // main handle
+        const summaryPanel = make_element("div", "gpt-panel", body);
+
+        const summaryTitle = make_element("div", "gpt-panel-title", summaryPanel);
+        summaryTitle.textContent = "main handle";
+
+        /*
+        No connection index here on purpose - main is not a member of pads and is never stamped with one, so
+        the field would read -1 for the whole session. The pad it mirrors carries the real value, and the known
+        pads panel below shows it.
+         */
+        this.#summary = new PropertyTableView([
+            "connected",
+            "index",
+            "id",
+            "mapping",
+            "read as",
+            "buttons",
+            "axes",
+            "known pads"
+        ]);
+
+        summaryPanel.appendChild(this.#summary.el);
+
+        this.#pressedList = make_element("div", "gpt-muted", summaryPanel);
+        this.#pressedList.style.marginTop = "7px";
+
+        // buttons
+        const buttonPanel = make_element("div", "gpt-panel", body);
+
+        const buttonTitle = make_element("div", "gpt-panel-title", buttonPanel);
+        buttonTitle.textContent = "buttons - x is the press count from the switch signal";
+
+        this.#buttonGrid = make_element("div", "gpt-buttons", buttonPanel);
+
+        body.appendChild(this.#layout.el);
+
+        // axes
+        const axisPanel = make_element("div", "gpt-panel", body);
+
+        const axisTitle = make_element("div", "gpt-panel-title", axisPanel);
+        axisTitle.textContent = "axes - standard slots, values as reported";
+
+        this.#axisList = make_element("div", "", axisPanel);
+
+        // sticks
+        const sticks = make_element("div", "gpt-sticks", body);
+        sticks.appendChild(this.#stickLeft.el);
+        sticks.appendChild(this.#stickRight.el);
+
+        // composition
+        const compositionPanel = make_element("div", "gpt-panel", body);
+
+        const compositionTitle = make_element("div", "gpt-panel-title", compositionPanel);
+        compositionTitle.textContent = "documented composition";
+
+        this.#composition = new PropertyTableView([
+            "dpad vector",
+            "shaped stick",
+            "fused move (y up)"
+        ]);
+
+        compositionPanel.appendChild(this.#composition.el);
+
+        const controls = make_element("div", "gpt-controls", compositionPanel);
+        controls.style.marginTop = "8px";
+
+        const inner = this.#makeSlider(controls, "dead zone inner", 0.15);
+        const outer = this.#makeSlider(controls, "dead zone outer", 0.95);
+
+        this.#innerInput = inner.input;
+        this.#innerValue = inner.value;
+        this.#outerInput = outer.input;
+        this.#outerValue = outer.value;
+
+        const forget = make_element("button", "", controls);
+        forget.textContent = "forget calibration";
+        forget.addEventListener("click", () => {
+            device.main.forgetCalibration();
+        });
+
+        body.appendChild(this.#timeline.el);
+
+        // other pads
+        const padPanel = make_element("div", "gpt-panel gpt-pads-summary", body);
+
+        const padTitle = make_element("div", "gpt-panel-title", padPanel);
+        padTitle.textContent = "known pads - GamepadDevice.pads, indexed by hardware slot";
+
+        this.#padRows = make_element("div", "", padPanel);
+
+        this.#log = new EventLogView(device);
+        body.appendChild(this.#log.el);
+    }
+
+    /**
+     *
+     * @param {HTMLElement} parent
+     * @param {string} label
+     * @param {number} initial
+     * @returns {{input:HTMLInputElement, value:HTMLElement}}
+     */
+    #makeSlider(parent, label, initial) {
+        const row = make_element("div", "gpt-control", parent);
+
+        const name = make_element("div", "gpt-muted", row);
+        name.textContent = label;
+
+        const input = make_element("input", "", row);
+        input.type = "range";
+        input.min = "0";
+        input.max = "1";
+        input.step = "0.01";
+        input.value = String(initial);
+
+        const value = make_element("div", "gpt-axis-value", row);
+        value.textContent = initial.toFixed(2);
+
+        return { input, value };
+    }
+
+    /**
+     * Rebuild the per-button views when the handle grows past the standard mapping
+     *
+     * @param {GamepadHandle} pad
+     */
+    #syncButtonViews(pad) {
+        const count = pad.buttons.length;
+
+        if (this.#buttons.length === count) {
+            return;
+        }
+
+        const previous = this.#buttons;
+        const n = previous.length;
+
+        for (let i = 0; i < n; i++) {
+            previous[i].dispose();
+        }
+
+        this.#buttons = [];
+        this.#buttonGrid.textContent = "";
+
+        for (let i = 0; i < count; i++) {
+            const view = new ButtonView(i, pad.buttons[i]);
+
+            this.#buttons[i] = view;
+            this.#buttonGrid.appendChild(view.el);
+        }
+    }
+
+    /**
+     *
+     * @param {GamepadHandle} pad
+     */
+    #syncAxisViews(pad) {
+        const count = pad.axes.length;
+
+        if (this.#axes.length === count) {
+            return;
+        }
+
+        this.#axes = [];
+        this.#axisList.textContent = "";
+
+        for (let i = 0; i < count; i++) {
+            const name = AXIS_NAMES[i] !== undefined ? AXIS_NAMES[i] : `axis ${i}`;
+
+            const view = new AxisView(`${i} ${name}`);
+
+            this.#axes[i] = view;
+            this.#axisList.appendChild(view.el);
+        }
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get deadZoneInner() {
+        return Number.parseFloat(this.#innerInput.value);
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get deadZoneOuter() {
+        return Number.parseFloat(this.#outerInput.value);
+    }
+
+    /**
+     *
+     * @returns {void}
+     */
+    update() {
+        const device = this.#device;
+        const pad = device.main;
+
+        this.#syncButtonViews(pad);
+        this.#syncAxisViews(pad);
+
+        this.#layout.update(pad);
+
+        this.#summary.write("connected", String(pad.connected));
+        this.#summary.write("index", String(pad.index));
+        this.#summary.write("id", pad.id !== "" ? pad.id : "-");
+        this.#summary.write("mapping", pad.mapping !== "" ? pad.mapping : "- (browser did not map this pad)");
+        this.#summary.write("read as", pad.layout.name);
+        this.#summary.write("buttons", `${pad.buttons.length} (standard ${GAMEPAD_STANDARD_BUTTON_COUNT})`);
+        this.#summary.write("axes", `${pad.axes.length} (standard ${GAMEPAD_STANDARD_AXIS_COUNT})`);
+        this.#summary.write("known pads", String(device.pads.filter(p => p !== undefined).length));
+
+        const pressed = [];
+
+        const buttonCount = this.#buttons.length;
+
+        for (let i = 0; i < buttonCount; i++) {
+            this.#buttons[i].update(pad.buttonValues[i]);
+
+            if (pad.buttons[i].is_down) {
+                pressed.push(BUTTON_NAMES[i] !== undefined ? BUTTON_NAMES[i] : String(i));
+            }
+        }
+
+        write_text(this.#pressedList, pressed.length > 0 ? `pressed: ${pressed.join(", ")}` : "pressed: nothing");
+
+        const axisCount = this.#axes.length;
+
+        for (let i = 0; i < axisCount; i++) {
+            this.#axes[i].update(pad.axes[i]);
+        }
+
+        const inner = this.deadZoneInner;
+        const outer = this.deadZoneOuter;
+
+        write_text(this.#innerValue, inner.toFixed(2));
+        write_text(this.#outerValue, outer.toFixed(2));
+
+        this.#stickLeft.update(pad.stickLeft, inner, outer);
+        this.#stickRight.update(pad.stickRight, inner, outer);
+
+        this.#timeline.update(pad);
+
+        this.#updateComposition(pad, inner, outer);
+        this.#updatePadRows();
+
+        this.#log.update();
+    }
+
+    /**
+     * The locomotion example from the {@link GamepadDevice} class doc, evaluated live
+     *
+     * @param {GamepadHandle} pad
+     * @param {number} inner
+     * @param {number} outer
+     */
+    #updateComposition(pad, inner, outer) {
+        const left = pad.stickLeft.value;
+
+        gamepad_write_dpad_vector(this.#dpad, pad);
+        apply_radial_dead_zone(this.#stick, left.x, left.y, inner, outer);
+
+        const stick = this.#stick;
+        const dpad = this.#dpad;
+
+        const x = stick.x !== 0 || stick.y !== 0 ? stick.x : dpad.x;
+        const y = stick.x !== 0 || stick.y !== 0 ? stick.y : dpad.y;
+
+        this.#move.set(x, -y);
+
+        this.#composition.write("dpad vector", `${dpad.x.toFixed(0)}, ${dpad.y.toFixed(0)}`);
+        this.#composition.write("shaped stick", `${stick.x.toFixed(4)}, ${stick.y.toFixed(4)}`);
+        this.#composition.write("fused move (y up)", `${this.#move.x.toFixed(4)}, ${this.#move.y.toFixed(4)}`);
+    }
+
+    #updatePadRows() {
+        const pads = this.#device.pads;
+
+        const rows = this.#padRows;
+
+        const n = pads.length;
+
+        let index = 0;
+
+        for (let i = 0; i < n; i++) {
+            const pad = pads[i];
+
+            if (pad === undefined) {
+                continue;
+            }
+
+            let row = rows.children[index];
+
+            if (row === undefined) {
+                row = make_element("div", "gpt-pad-row", rows);
+
+                make_element("div", "", row);
+                make_element("div", "", row);
+                make_element("div", "", row);
+            }
+
+            const held = [];
+
+            const buttonCount = pad.buttons.length;
+
+            for (let j = 0; j < buttonCount; j++) {
+                if (pad.buttons[j].is_down) {
+                    held.push(BUTTON_NAMES[j] !== undefined ? BUTTON_NAMES[j] : String(j));
+                }
+            }
+
+            write_text(row.children[0], `slot ${pad.index}`);
+            write_text(row.children[1], pad.connected ? `connected #${pad.connectionIndex}` : "disconnected");
+            write_text(row.children[2], `${pad.id} ${held.length > 0 ? `[${held.join(" ")}]` : ""}`);
+
+            index++;
+        }
+
+        while (rows.childElementCount > index) {
+            rows.removeChild(rows.lastChild);
+        }
+    }
+}
+
+/**
+ * One native {@link Gamepad}, straight from `navigator.getGamepads()`.
+ */
+class NativeGamepadCard {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {PropertyTableView}
+     */
+    #summary;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #buttonGrid;
+
+    /**
+     * @type {HTMLElement[]}
+     */
+    #buttonCells = [];
+
+    /**
+     * @type {HTMLElement}
+     */
+    #axisList;
+
+    /**
+     * @type {AxisView[]}
+     */
+    #axes = [];
+
+    /**
+     * @type {HTMLElement}
+     */
+    #rumble;
+
+    constructor() {
+        this.el = make_element("div", "gpt-panel");
+
+        this.#summary = new PropertyTableView([
+            "index",
+            "id",
+            "mapping",
+            "connected",
+            "timestamp",
+            "buttons",
+            "axes",
+            "vibration"
+        ]);
+
+        this.el.appendChild(this.#summary.el);
+
+        this.#buttonGrid = make_element("div", "gpt-native-buttons", this.el);
+        this.#buttonGrid.style.marginTop = "8px";
+
+        this.#axisList = make_element("div", "", this.el);
+        this.#axisList.style.marginTop = "8px";
+
+        this.#rumble = make_element("button", "", this.el);
+        this.#rumble.textContent = "rumble";
+        this.#rumble.style.marginTop = "8px";
+    }
+
+    /**
+     *
+     * @param {Gamepad} gamepad
+     * @returns {void}
+     */
+    update(gamepad) {
+        const buttons = gamepad.buttons;
+        const axes = gamepad.axes;
+
+        const actuator = gamepad.vibrationActuator;
+
+        this.#summary.write("index", String(gamepad.index));
+        this.#summary.write("id", gamepad.id);
+        this.#summary.write("mapping", gamepad.mapping);
+        this.#summary.write("connected", String(gamepad.connected));
+        this.#summary.write("timestamp", gamepad.timestamp.toFixed(1));
+        this.#summary.write("buttons", String(buttons.length));
+        this.#summary.write("axes", String(axes.length));
+        this.#summary.write("vibration", actuator !== undefined && actuator !== null ? actuator.type : "none");
+
+        this.#syncButtonCells(buttons.length);
+
+        for (let i = 0; i < buttons.length; i++) {
+            const button = buttons[i];
+            const cell = this.#buttonCells[i];
+
+            cell.classList.toggle("gpt-down", button.pressed);
+            cell.classList.toggle("gpt-touched", !button.pressed && button.touched);
+
+            write_text(cell, `${i} ${button.value.toFixed(2)}`);
+        }
+
+        this.#syncAxisViews(axes.length);
+
+        for (let i = 0; i < axes.length; i++) {
+            this.#axes[i].update(axes[i]);
+        }
+
+        const canRumble = actuator !== undefined && actuator !== null && typeof actuator.playEffect === "function";
+
+        this.#rumble.disabled = !canRumble;
+
+        if (canRumble) {
+            this.#rumble.onclick = () => {
+                actuator.playEffect("dual-rumble", {
+                    duration: 400,
+                    strongMagnitude: 1,
+                    weakMagnitude: 1
+                });
+            };
+        }
+    }
+
+    /**
+     *
+     * @param {number} count
+     */
+    #syncButtonCells(count) {
+        if (this.#buttonCells.length === count) {
+            return;
+        }
+
+        this.#buttonCells = [];
+        this.#buttonGrid.textContent = "";
+
+        for (let i = 0; i < count; i++) {
+            this.#buttonCells[i] = make_element("div", "gpt-native-button", this.#buttonGrid);
+        }
+    }
+
+    /**
+     *
+     * @param {number} count
+     */
+    #syncAxisViews(count) {
+        if (this.#axes.length === count) {
+            return;
+        }
+
+        this.#axes = [];
+        this.#axisList.textContent = "";
+
+        for (let i = 0; i < count; i++) {
+            const view = new AxisView(`axis ${i}`);
+
+            this.#axes[i] = view;
+            this.#axisList.appendChild(view.el);
+        }
+    }
+}
+
+/**
+ * Layer 2 - `navigator.getGamepads()` with nothing in front of it.
+ *
+ * Polled from the same animation frame as layer 1 and holding no state of its own, so a difference between the
+ * two panels is a difference the device layer introduced, not a difference in when they looked.
+ */
+class NativeLayerView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #pads;
+
+    /**
+     * @type {Map<number,NativeGamepadCard>}
+     */
+    #cards = new Map();
+
+    /**
+     * @type {HTMLElement}
+     */
+    #status;
+
+    constructor() {
+        this.el = make_element("div", "gpt-layer");
+
+        const head = make_element("div", "gpt-layer-head", this.el);
+
+        const badge = make_element("div", "gpt-layer-badge", head);
+        badge.textContent = "layer 2";
+
+        const title = make_element("h2", "", head);
+        title.textContent = "navigator.getGamepads()";
+
+        const subtitle = make_element("div", "gpt-muted", head);
+        subtitle.textContent = "browser Gamepad API, read directly - no engine in the path";
+
+        this.#status = make_element("div", "gpt-status", head);
+
+        const body = make_element("div", "gpt-layer-body", this.el);
+
+        this.#pads = make_element("div", "gpt-native-pads", body);
+    }
+
+    /**
+     *
+     * @param {(Gamepad|null)[]} gamepads
+     * @returns {void}
+     */
+    update(gamepads) {
+        let live = 0;
+
+        const seen = new Set();
+
+        const n = gamepads.length;
+
+        for (let i = 0; i < n; i++) {
+            const gamepad = gamepads[i];
+
+            if (gamepad === null || gamepad === undefined) {
+                continue;
+            }
+
+            live++;
+            seen.add(gamepad.index);
+
+            let card = this.#cards.get(gamepad.index);
+
+            if (card === undefined) {
+                card = new NativeGamepadCard();
+
+                this.#cards.set(gamepad.index, card);
+                this.#pads.appendChild(card.el);
+            }
+
+            card.update(gamepad);
+        }
+
+        for (const [index, card] of this.#cards) {
+            if (!seen.has(index)) {
+                this.#pads.removeChild(card.el);
+                this.#cards.delete(index);
+            }
+        }
+
+        write_text(this.#status, `${live} of ${n} slots occupied`);
+    }
+}
+
+/**
+ * Diff of the two layers.
+ *
+ * {@link GamepadHandle} promises it presents the hardware's own values in the standard mapping's slots, with
+ * the only correction applied further along in {@link GamepadStick#value}. This asserts that promise against
+ * the hardware every frame, which is the one thing neither layer can show on its own.
+ *
+ * The comparison goes through {@link GamepadHandle#layout}, because on a pad the browser did not map, slot
+ * `i` deliberately does not come from device index `i` - that translation is the whole point of the layout.
+ * What is being checked is that nothing else changed the values on the way through.
+ */
+class LayerParityView {
+
+    /**
+     * @readonly
+     * @type {HTMLElement}
+     */
+    el;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #status;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #detail;
+
+    constructor() {
+        this.el = make_element("div", "gpt-sync");
+
+        const title = make_element("div", "", this.el);
+        title.textContent = "layer 1 vs layer 2";
+
+        this.#status = make_element("div", "gpt-status", this.el);
+        this.#detail = make_element("div", "gpt-muted", this.el);
+    }
+
+    /**
+     *
+     * @param {GamepadHandle} main
+     * @param {(Gamepad|null)[]} gamepads
+     * @returns {void}
+     */
+    update(main, gamepads) {
+        if (!main.connected) {
+            this.#write("", "idle", "main is not bound to any pad");
+
+            return;
+        }
+
+        const source = gamepads[main.index];
+
+        if (source === null || source === undefined) {
+            this.#write("gpt-bad", "no source", `main is bound to slot ${main.index}, which the browser reports as empty`);
+
+            return;
+        }
+
+        const layout = main.layout;
+
+        const mismatches = [];
+
+        const buttonCount = layout.presentedButtonCount(source);
+
+        for (let i = 0; i < buttonCount; i++) {
+            const pressed = layout.isButtonPressed(i, source);
+
+            if (main.buttons[i].is_down !== pressed) {
+                mismatches.push(`button ${i} pressed ${main.buttons[i].is_down} vs ${pressed}`);
+            }
+
+            const value = layout.readButtonValue(i, source);
+
+            if (main.buttonValues[i] !== value) {
+                mismatches.push(`button ${i} value ${main.buttonValues[i]} vs ${value}`);
+            }
+        }
+
+        const axisCount = layout.presentedAxisCount(source);
+
+        for (let i = 0; i < axisCount; i++) {
+            const value = layout.readAxis(i, source);
+
+            if (main.axes[i] !== value) {
+                mismatches.push(`axis ${i} ${main.axes[i]} vs ${value}`);
+            }
+        }
+
+        const through = layout === GAMEPAD_STANDARD_LAYOUT ? "passed through" : `via ${layout.name}`;
+
+        if (mismatches.length === 0) {
+            this.#write("gpt-ok", "mirrored", `slot ${main.index} ${through}: ${buttonCount} buttons and ${axisCount} axes identical`);
+        } else {
+            this.#write("gpt-bad", `${mismatches.length} differ`, mismatches.slice(0, 3).join("   "));
+        }
+    }
+
+    /**
+     *
+     * @param {string} modifier
+     * @param {string} status
+     * @param {string} detail
+     */
+    #write(modifier, status, detail) {
+        this.#status.className = `gpt-status ${modifier}`;
+
+        write_text(this.#status, status);
+        write_text(this.#detail, detail);
+    }
+}
+
+/**
+ * @param {Engine} engine
+ */
+function main(engine) {
+    const style = make_element("style", "", document.head);
+    style.textContent = STYLE;
+
+    const root = make_element("div", "gpt-root", document.body);
+
+    const header = make_element("div", "gpt-header", root);
+
+    const title = make_element("h1", "", header);
+    title.textContent = "gamepad tester";
+
+    const subtitle = make_element("div", "gpt-muted", header);
+    subtitle.textContent = "press buttons and move sticks. hardware frame throughout: +x is right, +y is down.";
+
+    const supported = typeof navigator.getGamepads === "function";
+
+    if (!supported) {
+        const warning = make_element("div", "gpt-status gpt-bad", header);
+        warning.textContent = "navigator.getGamepads is not available in this browser";
+    }
+
+    const device = engine.devices.gamepad;
+
+    const engineLayer = new EngineLayerView(device);
+    const parity = new LayerParityView();
+    const nativeLayer = new NativeLayerView();
+
+    root.appendChild(engineLayer.el);
+    root.appendChild(parity.el);
+    root.appendChild(nativeLayer.el);
+
+    /*
+    The device registers its own poll when the engine is constructed, so it has already refreshed by the time
+    this callback runs in the same frame - both layers describe one instant
+     */
+    function update() {
+        const gamepads = supported ? navigator.getGamepads() : [];
+
+        engineLayer.update();
+        parity.update(device.main, gamepads);
+        nativeLayer.update(gamepads);
+
+        requestAnimationFrame(update);
+    }
+
+    requestAnimationFrame(update);
+
+    window.__gamepad_tester = {
+        engine,
+        device,
+        engineLayer,
+        nativeLayer,
+        parity
+    };
+}
+
+EngineHarness.bootstrap().then(main);