@woosh/meep-engine 2.165.6 → 2.165.7

package/src/engine/input/GAMEPAD_API_PROPOSAL.md

@@ -0,0 +1,717 @@
+# Gamepad API — proposal
+
+Response to the external review *"how convenient is the meep gamepad API? (UX)"*.
+
+> **Revision 2.** P1, P4, P5, P6 accepted as written. **P2 replaced** with a persistent `main` handle (better than
+> slot pre-population — see §4.2). **P3 replaced** with learned per-stick calibration and a `GamepadStick`
+> abstraction, grounded in the survey in Appendix A. Revision 1's fixed `axisNoiseFloor` is withdrawn.
+>
+> **Revision 3 — implemented.** All of P1–P6 have landed. §4 describes the design **as shipped**: names,
+> constants and signatures there match the code. §6 records what changed between the proposal and the
+> implementation, and why. §1, §2 and §5 are unchanged — they are the argument, not the design.
+
+## 0. Summary
+
+The review grades a hardware abstraction layer by how little game code the consumer had to write. That is the
+wrong axis, and it leads to the wrong headline recommendation.
+
+Checked against the source:
+
+* one papercut (**sparse `buttons`**) does not reproduce through any supported access path — the guard the
+  reviewer wrote is dead code;
+* one technical claim (**"full-diagonal magnitude ~0.99"**) is not producible by this code at all — there is no
+  rescaling path in `GamepadHandle#update`;
+* one papercut (**"the `.d.ts` doesn't carry the frame"**) is about a file that does not exist — `engine/input`
+  contains zero `.d.ts` files, and the frame *is* documented, on the enum that defines it;
+* the headline recommendation (**`pad.getMovement({radialDeadzone})`**) moves gameplay policy, a coordinate
+  convention, an options bag, and a per-frame allocation into the driver.
+
+The review did, however, bump into a **real structural gap and misdiagnose it**: the gamepad is effectively
+invisible to the engine's input binding layer (`InputSystem` / `InputControllerSystem`). That is *why* the
+reviewer ended up hand-fusing raw device state — not because the device lacks convenience methods. Closing that
+gap removes the "boilerplate every consumer will duplicate" without adding a single convenience method to
+`GamepadHandle`.
+
+Two of the underlying observations are worth acting on, in a different shape than proposed.
+
+### Dispositions
+
+| # | Review item | Disposition |
+|---|---|---|
+| 1 | `buttons` sparse → add `pad.isDown(i)` | **Reject the mechanism, accept the goal.** Claim doesn't reproduce; fix uniformity at the source (P1), don't add a third accessor. |
+| 2 | `pad.getMovement({radialDeadzone})` | **Reject.** Policy in the driver. Decomposed into two device-agnostic primitives instead (P4, P5). |
+| 3 | Per-axis dead-zone leaks diagonals; shortens full diagonal to ~0.99 | **Half accept.** The `~0.99` claim is fabricated. The genuine defect is different and worse: the gate is destructive, misnamed, and *guesses* a number that varies 6× across hardware. Replaced by learned calibration (P3). |
+| 4 | Frame undocumented "at the type level" | **Reject as stated, accept a sliver.** No `.d.ts` exists; frame is documented in `GamepadAxes.js`. Add a cross-reference on `axes`/`stickLeft`/`stickRight` (P6). |
+| 5 | No digital view of stick / analog view of D-pad; fusion is on the caller | **Accept the observation, keep fusion on the caller.** Ship the two primitives, not the fused result (P5). |
+| 6 | Analog-vs-digital speed is game policy | **Agree, no action.** |
+| — | *(missed)* Gamepad is unbindable through the ISM path layer | **New work.** The actual defect (P1 + P2). |
+
+---
+
+## 1. The layering premise the review is missing
+
+meep input devices are **state mirrors of hardware**. They report what the hardware reports, plus the minimum
+hygiene needed to make polled hardware observable (edge detection, stuck-input release on disconnect/stop). They
+contain no game policy. This is not an accident of the gamepad implementation — it is the shape of the whole
+package:
+
+* `KeyboardDevice` exposes `keys.w.is_down`. It does not expose `keyboard.getMovement()` from WASD.
+* Nobody asks it to, because the layer that owns that question already exists:
+  [`KeyboardCameraController.js`](ecs/controllers/KeyboardCameraController.js) — a *controller* that reads device
+  switches and produces a camera-frame pan vector.
+
+`pad.getMovement()` is a request to put `KeyboardCameraController`'s job inside `KeyboardDevice`. Five concrete
+reasons it does not belong there:
+
+1. **The game frame is not a property of the stick.** The reviewer wants `+y = up`. Up in *what*? meep's world is
+   3D; "stick up" maps to a world direction that depends on the camera yaw, the projection, and whether the game
+   is top-down or third-person. `KeyboardCameraController` resolves exactly this and it needs a
+   `TopDownCameraController` to do it. A `Vector2` on a driver cannot know the answer, so any answer it bakes in
+   is wrong for some consumer — who then must un-negate it. That is strictly worse than never negating.
+
+2. **Dead-zoning is not one policy.** Radial-with-rescale is right for locomotion; per-axis is right for menu
+   navigation; inner+outer with a response curve is right for aiming; square-gate normalization is right for
+   pads that report a square gate. `{radialDeadzone}` picks one and demotes the rest to "off the golden path".
+
+3. **`{radialDeadzone}` is an options bag.** The codebase's position is typed and verbose over magic-looking
+   configuration. An options object on a per-frame hot call is the opposite of that, and it grows monotonically
+   — the next request is `{radialDeadzone, outerDeadzone, curve, squareGate}`.
+
+4. **It allocates.** `getMovement()` returning a fresh `Vector2` allocates once per consumer per frame. The
+   engine's convention for vector-producing calls is `f(result, ...)` writing into a caller-owned target.
+
+5. **It creates a dual-mode API.** With `getMovement()` present, `stickLeft` becomes "the raw one" and
+   `getMovement()` "the good one" — two ways to ask the same question with a silent policy difference between
+   them. Uniform control flow means picking the common case as the *only* case at each layer, and letting
+   callers who want something else drop to the lower-level primitive.
+
+What the reviewer actually wants is real. It just belongs one layer up, and it should be *composable functions*,
+not a method on the driver.
+
+---
+
+## 2. Item-by-item
+
+*Line references in this section point at the code **as reviewed**, before any of P1–P6 landed. They are part of
+the argument about what the reviewer was looking at, not navigation aids for the current tree.*
+
+### 2.1 "`buttons` is lazily populated and sparse, so I wrote a guard"
+
+**This does not reproduce.** Trace the code:
+
+* [`GamepadHandle.js:140`](devices/gamepad/GamepadHandle.js:140) — `update()` iterates **every** button in the
+  native snapshot and calls `getButton(i)` on each. After one update, `buttons[0 … n-1]` are all populated.
+* [`GamepadDevice.js:130`](devices/GamepadDevice.js:130) — `#connect()` calls `pad.update(...)` **before**
+  setting `pad.connected = true`.
+* [`GamepadDevice.js:86`](devices/GamepadDevice.js:86) — `main` only returns pads with `connected === true`.
+
+So every handle reachable through `gamepad.main` has already had its full button set materialised.
+`pad.buttons[GamepadButtons.a].is_down` is safe, and the `button !== undefined &&` half of the reviewer's guard
+never evaluates false in a connected-pad path. The `?.` in the existing `@example` is belt-and-braces, and reads
+as a warning it isn't.
+
+The one residual hole is real but different: a **non-standard mapping** pad reporting fewer than 17 buttons.
+`buttons[GamepadButtons.dpad_up]` is genuinely `undefined` there, because the button does not exist.
+`pad.isDown(15)` would return `false` for it — converting "this hardware has no D-pad" into "the D-pad is not
+pressed", silently, forever. That is a worse API than the honest `undefined`, and it is the reason to reject the
+proposed mechanism specifically.
+
+**The goal is still right.** Keyboard/gamepad symmetry should not have an asterisk, and `pads`/`buttons`
+sparseness has a second, much more serious consequence (§3). Fix it at the source: pre-populate (P1/P2), so
+there is nothing to guard and no third accessor.
+
+### 2.2 `getMovement()` — rejected
+
+See §1. Replaced by P4 + P5.
+
+### 2.3 "Per-axis dead-zoning leaks diagonal drift and shortens the full diagonal to ~0.99"
+
+**First half: correct.** A per-axis gate at 0.1 admits up to `sqrt(0.1² + 0.1²) ≈ 0.141` of resting magnitude,
+and its boundary is anisotropic — a stick pushed to `(0.09, 0.09)` reads dead, `(0.11, 0.0)` reads live.
+
+**Second half: not producible by this code.** The gate is
+[`GamepadHandle.js:169`](devices/gamepad/GamepadHandle.js:169):
+
+```js
+if (Math.abs(value) < deadZone) {
+    value = 0;
+}
+```
+
+There is no rescale, no normalization, no magnitude clamp anywhere in `update()`. A full-deflection axis passes
+through byte-identical to what the hardware reported. If the reviewer measured 0.99 at full diagonal, that was
+their pad's gate, not ours. This matters because it is the tell that the section was reasoned about rather than
+read — and the actual defect sitting three lines away was missed.
+
+**The actual defect** is threefold and worse than "leaks diagonals":
+
+1. **It is destructive.** The gated value is what gets *stored* in `axes`, so a consumer who wants radial
+   dead-zoning cannot recover the raw signal — the information is gone before they see it. Policy applied in a
+   mirror layer is not just misplaced, it is lossy.
+2. **It is discontinuous.** `0.0999 → 0`, `0.1001 → 0.1001`. Input magnitude jumps by the full dead-zone width
+   the instant the threshold is crossed. Any consumer mapping magnitude to speed gets a visible speed pop.
+3. **It is named for a policy it should not be implementing.** `deadZone` at `0.1` reads as "the engine has
+   decided your gameplay dead-zone", which is precisely how the reviewer read it.
+
+There is a fourth problem the review could not have seen without measuring hardware, and it is the one that
+kills the whole "pick a good constant" approach: **the right number varies by more than 6× across pads.** XInput
+ships 0.24 (left stick) and 0.265 (right); SDL treats ±0.098 as at-rest; hall-effect and TMR pads need 0.02–0.03
+and stay there for life; a worn potentiometer pad needs 0.2+ and gets worse over time. Any single constant is
+sized for the worst pad in the population, and every good pad pays for it with lost range.
+
+Fixed in P3 + P4: the device *measures* its own stick instead of guessing (learned center + noise radius), and
+gameplay dead-zoning becomes a continuous, rescaling, radial primitive applied by the consumer.
+
+### 2.4 "Frame is undocumented at the type level — the `.d.ts` doesn't carry it"
+
+Two problems.
+
+* **The frame is documented**, in the file that owns the concept —
+  [`GamepadAxes.js:5`](devices/gamepad/GamepadAxes.js:5): *"Negative values are left/up, positive values are
+  right/down"*. The review cites having read it, then calls it undocumented.
+* **There is no `.d.ts`.** `find src/engine/input -name "*.d.ts"` returns nothing. Hand-written `.d.ts` are not
+  maintained in this project; whatever the reviewer was reading was IDE inference or a stale tree. If a `.d.ts`
+  for this package appears, deleting it is the fix.
+
+**Accepted sliver:** the frame note lives on the *enum*, and a consumer touching `stickLeft` may never open
+`GamepadAxes.js`. One-line cross-references on `axes`, `stickLeft`, `stickRight` (P6).
+
+### 2.5 "No digital view of the stick, no analog view of the D-pad; fusion is on the caller"
+
+Correct, and **fusion stays on the caller** — which of stick and D-pad wins, whether they sum or the last-touched
+device latches, and whether a held D-pad suppresses stick drift are all game decisions with no defensible
+default. What *is* mechanical and duplicated is the conversion on each side, so ship both directions as
+primitives (P5) and leave the `max`/`or`/`latch` to the consumer.
+
+### 2.6 "Analog-vs-digital speed is a caller concern"
+
+Agreed, explicitly. No action.
+
+---
+
+## 3. What the review missed: the gamepad is unbindable through the ISM
+
+The engine's action-mapping layer resolves bindings by *path* against the device tree —
+[`InputSystem.js:18`](ecs/systems/InputSystem.js:18) and
+[`InputControllerSystem.js:159`](ecs/systems/InputControllerSystem.js:159), both via
+[`resolvePath`](../../core/json/resolvePath.js), which **throws when a path cannot be resolved**.
+
+Keyboard works because `KeyboardDevice` pre-populates every key from `KeyCodes` in its constructor, so
+`keyboard/keys/w/down` resolves at load time, before anyone touches the hardware.
+
+The gamepad cannot do this:
+
+* `pads` is sparse and keyed on the hardware slot, so `gamepad/pads/0/...` throws until a pad connects;
+* `buttons` is sparse until first poll, so `gamepad/pads/0/buttons/0/down` throws until the pad has been read.
+
+Consequences: an `InputController` carrying a gamepad binding **cannot be linked until the player has already
+plugged in and pressed something**; whether a given binding works depends on which physical slot the pad landed
+in; and a serialized `InputBinding` referencing a gamepad path is a load-order landmine. (Unlink is safe once
+link succeeded — handles are retained across disconnect — but that is the only part of the lifecycle that is.)
+
+This — not the absence of `getMovement()` — is why the integration was "entirely on the caller". The blessed
+mapping mechanism was unavailable, so the reviewer polled raw state and fused by hand, then reported the
+symptoms of doing so as API friction. P1 and P2 close it as a side effect of fixing uniformity.
+
+*(Separately: axis bindings have no per-axis granularity — only the aggregate `on.axis`, forcing listeners to
+filter by index. Noted, not proposed. The string-path ISM is already the odd one out against the codebase's
+typed-over-magic position; make it work, don't grow it. Direct typed state access — `pad.buttons[GamepadButtons.a].is_down`
+— remains the blessed path.)*
+
+---
+
+## 4. Proposed work
+
+### P1 — `GamepadHandle` pre-populates the standard mapping
+
+```js
+// gamepad/GamepadStandardMapping.js
+export const GAMEPAD_STANDARD_BUTTON_COUNT = 17;
+export const GAMEPAD_STANDARD_AXIS_COUNT = 4;
+```
+
+`GamepadHandle` materialises those in its constructor: 17 `InputDeviceSwitch`, 17 zeroed `buttonValues`, 4 zeroed
+`axes`. `getButton` stays as-is and keeps growing the array for hardware exposing more than 17 buttons.
+
+Effect: `pad.buttons[GamepadButtons.dpad_up].is_down` is total. No guard, no `?.`, no `isDown()`. Exactly the
+keyboard's contract.
+
+**Tradeoff, stated explicitly:** on a non-standard pad with 6 buttons, `buttons[12]` now reads "up" rather than
+"absent". Absence is signalled by `pad.mapping !== "standard"`, which is where the Gamepad API puts it, not by
+holes in an array. Uniform beats expressive here — a hole is not a usable absence signal anyway, since the
+consumer sees a hole for "no such button" and (previously) also for "not polled yet".
+
+Cost: 17 small objects per handle, allocated once.
+
+### P2 — `main` becomes a persistent handle bound to the active pad
+
+*(Replaces revision 1's slot pre-population. This is the better design: it gives the binding layer a stable path
+without pretending four pads exist, and it matches what a single-player consumer actually means by "the
+gamepad".)*
+
+`GamepadDevice.main` becomes a `GamepadHandle` constructed with the device, living **outside** `pads[]`, starting
+disconnected:
+
+* it binds to the first pad that connects;
+* when its bound pad disconnects, it rebinds to the **oldest still-connected** pad (connection order);
+* when nothing is connected, it stays present and `connected === false`, with all switches released.
+
+Mechanically `main` is a real handle fed the *same* native snapshot as its bound pad during `poll()` — not a
+proxy or a getter chain. That matters: `gamepad/main/buttons/0/down` is a stable `Signal` **object** that
+resolves at engine construction and never changes identity, which is exactly what `resolvePath` needs (§3).
+
+```js
+// GamepadDevice
+#connection_sequence = 0;
+
+/**
+ * The active gamepad. Always present; check {@link GamepadHandle#connected}.
+ * Mirrors the first connected pad, falling back to the oldest remaining one when that pad is lost.
+ * Not a member of {@link pads}.
+ */
+main = new GamepadHandle();
+```
+
+Notes on the implementation:
+
+* **Do not** forward `main.on.*` into the device-level `on.*` signals. The pad it mirrors already forwards, so
+  wiring both would double-fire every press for every listener.
+* On unbind, `main.reset()` — releases everything, so a yank-the-cable never leaves input stuck. The next
+  `update()` from the new source re-presses whatever is genuinely held. Free correctness from the existing edge
+  detection.
+* `main.index` / `.id` / `.mapping` follow the mirrored pad, because `update()` already copies them. Useful:
+  a settings screen can name the active pad without touching `pads`.
+* Connection order needs one counter — stamp `pad.connectionIndex = this.#connectionSequence++` inside
+  `#connect`, pick the smallest among connected on rebind.
+* Binding, rebinding and refreshing all happen in one place at the end of `poll()`. Splitting them across
+  `#connect`/`#disconnect` leaves `main` a frame stale on a swap — see §6.3.
+
+Cost: one extra handle update per poll (17 buttons + 4 axes) — noise.
+
+**Breaking, and an improvement:** `main` was `GamepadHandle | undefined`. It is now always a handle. Existing
+`if (pad !== undefined)` guards still compile and simply never trigger; the check becomes `main.connected`. This
+removes the only sentinel in the gamepad API, which is the direction the codebase wants anyway.
+
+**Deliberately unresolved:** per-slot paths (`gamepad/pads/1/...`) still don't resolve, because `pads` keeps its
+honest sparse hardware-slot semantics. Local multiplayer binds through the device-level `on.down`, which already
+dispatches `(buttonIndex, pad)`, or holds handles from the `connected` signal. If per-player path binding is ever
+wanted, the shape is an ordered player-assignment list of which `main` is element 0 — this design doesn't
+preclude it, and I'd rather add it when there's a consumer than guess the assignment policy now.
+
+### P3 — Learned per-stick calibration, and a `GamepadStick` abstraction
+
+*(Replaces revision 1's fixed `axisNoiseFloor`. Appendix A is the supporting survey.)*
+
+Three findings drive this:
+
+1. **In a browser there is no factory calibration, so learning is the only calibration available.** Native stacks
+   can read hardware calibration — a Switch pad stores per-axis min/center/max in SPI flash, XInput and SDL apply
+   vendor-tuned constants. The Gamepad API exposes none of it: normalized floats and nothing else. Every native
+   stack calibrates; we're the only ones who'd be guessing.
+2. **The dominant error is a center offset, not symmetric noise.** This is what "stick drift" *is*, and it is why
+   every consumer calibration tool works by sampling the resting position and subtracting it. A fixed dead zone
+   responds to an offset center by widening the dead area — asymmetrically, so you lose range on one side and
+   still drift on the other. Learning the center fixes the actual defect; a dead zone only hides it.
+3. **The right radius varies 6×+ across the installed base** (§2.3). Measuring is the only way to give a TMR pad
+   its 0.02 and a worn pad its 0.15 from one code path.
+
+**Layering — why this doesn't contradict §1.** Calibration is *hardware characterization*: learning that this
+stick rests at `(0.03, -0.01)` with `0.018` of dispersion makes the mirror **more accurate**, which is squarely
+the device layer's job. Gameplay dead zone, response curve, and frame conversion remain policy and stay with the
+consumer via `apply_radial_dead_zone`. The line is: *the device removes what the hardware got wrong; the game
+decides what to do with what's left.* Getting this backwards is a known failure mode — SDL applying its own dead
+zone under a game that applies another is a long-standing complaint, and the result is exactly the doubled dead
+zone with all precision gone.
+
+#### The abstraction
+
+```js
+export class GamepadStick {
+    /** Indices into {@link GamepadHandle#axes} that this stick reads. */
+    axisX = 0;
+    axisY = 1;
+
+    /** Hardware value, exactly as reported. */
+    raw = new Vector2();
+
+    /** Calibrated value: center-corrected and noise-gated. This is what gameplay should read. */
+    value = new Vector2();
+
+    /** @type {GamepadStickCalibration} */
+    calibration = new GamepadStickCalibration();
+
+    on = {
+        /** Fires when {@link value} changes. A calibrated stick at rest is silent. */
+        changed: new Signal()
+    };
+
+    /** Refresh from raw axis values, feeding the calibrator on the way through. */
+    update(axes) {}
+
+    /** Return to neutral, keeping the calibration — the hardware has not changed. */
+    reset() {}
+
+    /** Discard what was learned. For when the handle starts representing *different* hardware. */
+    forgetCalibration() {}
+}
+
+export class GamepadStickCalibration {
+    /** Learned rest position. */
+    center = new Vector2();
+
+    /** Learned dispersion around {@link center}; magnitudes inside this read as 0. */
+    noiseRadius = 0;
+
+    /** When true, learning is suspended and the current values are used as-is. */
+    locked = false;
+}
+```
+
+`stickLeft` / `stickRight` become `GamepadStick` rather than `Vector2`. **Breaking:** `pad.stickLeft.x` →
+`pad.stickLeft.value.x`. Changelog line; this is public surface.
+
+**Opt-out without a mode flag.** You asked for an opt-out, and the obvious form of it — a boolean that switches
+between two code paths — is the dual-mode shape we rejected for `getMovement()`. It isn't needed here: the
+transform is *always* applied, and an identity calibration (`center = (0,0)`, `noiseRadius = 0`, `locked =
+true`) is a bit-exact passthrough. One code path, and "no filtering" is just a particular calibration. The same
+mechanism covers a settings-screen manual dead zone and a saved per-controller profile — `GamepadStickCalibration`
+gets `to/fromBinaryBuffer`, keyed on `pad.id`.
+
+**Calibration belongs to hardware, not to a handle.** A handle outlives the pad it represents: slots get
+re-occupied, and `main` moves between pads. Carrying an estimate across that would apply one pad's correction to
+another — and because the calibrator only ever moves its estimate *closer* to the origin (below), a new pad
+resting further out could never adopt its own rest position at all. So `forgetCalibration()` is called on a fresh
+connection and when `main` binds a new source. It is a no-op on a locked calibration: a supplied profile is not
+ours to discard.
+
+#### The learning algorithm
+
+**Phase A — rest estimation.** Runs continuously and unattended; there is no separate "on connect" mode.
+
+* Collect `REST_SAMPLE_COUNT = 60` raw samples (≈1 s at rAF) as a fixed, non-overlapping window.
+* **Reject the whole window** if any sample magnitude exceeds `REST_CANDIDATE_MAX = 0.08`, or if per-axis spread
+  (max − min) exceeds `REST_SPREAD_MAX = 0.015`. Resting and holding cannot be told apart inside one window —
+  both are steady — so the bounds are biased hard toward rejection, on the asymmetry that failing to calibrate
+  leaves an exact passthrough while calibrating wrongly injects phantom deflection. The spread bound is the
+  primary defence, and it exploits a physical difference: a held stick carries hand tremor, a settled one
+  carries only sensor noise, and the two differ by roughly an order of magnitude. (§6.1 and §6.4 record how
+  these numbers were arrived at — the first version of this section got the reasoning wrong.)
+* **Center = per-axis median** of the window. Median, not mean: one spike shifts a 60-sample mean by 1.7% of its
+  amplitude, and shifts the median by nothing.
+* **`noiseRadius` = median(d) + `NOISE_RADIUS_DEVIATIONS`·MAD(d)** where `d` are the sample distances from the
+  learned center and MAD is the median absolute deviation. MAD is the standard robust dispersion estimator — a
+  high quantile computed from 60 samples is dominated by its own tail, which is precisely the outliers we're
+  trying not to fit. No clamp: the spread bound already constrains the result structurally, to
+  `NOISE_RADIUS_MAX = REST_SPREAD_MAX · √2 · (1 + NOISE_RADIUS_DEVIATIONS)` ≈ 0.106.
+* **Adopt only if closer in.** A window is written to the calibration only when its center is nearer the origin
+  than the accepted one. This is what makes a wrong estimate self-correcting: a stick that was being held when
+  sampling started is superseded the moment it is released, with no separate recovery path. The trade is that
+  drift *growing* within a session is not followed — a wear process measured in weeks, and calibration restarts
+  whenever the pad reconnects.
+* **Recovery takes up to two windows.** Windows are fixed and non-overlapping, so the one straddling a release
+  or a rebind still holds pre-transition samples and is rejected on spread; only the window after it is clean.
+  This affects how quickly a correct estimate is found, never whether it is correct.
+
+**Phase B — range estimation.** Proposed as **optional and off by default.** Pads differ in gate shape (square
+gates reach ~1.41 at full diagonal, circular ones ~1.0), so a learned per-direction max would let us normalize to
+a unit circle. But a running max is a self-poisoning estimator — one spike raises the ceiling permanently and
+silently compresses everything afterwards. If we do it: require K consecutive samples above the current maximum
+before raising it, clamp to `[0.8, 1.5]`, and decay slowly. I'd rather ship Phase A, which is high-value and
+low-risk, and leave this behind a flag until a real pad demands it.
+
+**Not proposed, but worth knowing about:** dead-zoning only addresses error *near center*. Jitter while the stick
+is **deflected** is a separate problem, and the state of the art for it is the 1€ filter (Casiez et al., CHI
+2012) — a speed-adaptive low-pass with two parameters: low cutoff at low speed kills jitter, rising cutoff at
+speed kills lag. It's ~30 lines and would slot in as an optional stage on `GamepadStick` between `raw` and
+`value`. I'd hold it until someone reports jitter that calibration doesn't fix, but the abstraction should leave
+room for it — which it does, since the stage lives inside the stick and consumers only see `value`.
+
+#### Consequences for `axes` and `deadZone`
+
+* **`pad.axes` becomes raw** — a true mirror, no destructive gating (fixes §2.3's real defect). Non-stick axes on
+  exotic mappings are unaffected by stick calibration, as they should be.
+* **`GamepadDevice.deadZone` is removed**, replaced by a `@deprecated` accessor whose setter writes
+  `noiseRadius` into every stick — existing and subsequently connected — and locks them. That is a faithful
+  migration: the old behaviour *was* a manually-specified fixed gate, and a locked calibration is exactly that.
+  Locking also means such a value survives reconnection, unlike a learned one.
+* **`on.axis` now fires at hardware sample rate on a drifting pad**, where the gate used to silence it. Decided
+  in favour of leaving it: the raw layer is honest, and the recommended path (`stick.on.changed`) is silent at
+  rest because the calibrated value genuinely doesn't change. The rejected alternative was gating `on.axis` at
+  an epsilon, which is the destructive gate creeping back in under a smaller number. This is a behaviour change
+  for anything bound to `on.axis`.
+
+### P4 — `apply_radial_dead_zone(result, x, y, inner, outer)`
+
+`engine/input/analog/apply_radial_dead_zone.js` — device-agnostic, no allocation, no options bag, continuous:
+
+```js
+export function apply_radial_dead_zone(result, x, y, inner, outer) {
+    const m = Math.sqrt(x * x + y * y);
+
+    if (m <= inner) {
+        result.set(0, 0);
+        return;
+    }
+
+    const scale = Math.min((m - inner) / (outer - inner), 1) / m;
+
+    result.set(x * scale, y * scale);
+}
+```
+
+Isotropic boundary (no diagonal leak), continuous at `inner` (no speed pop), saturates to unit magnitude at
+`outer` (no `>1` from square-gate pads). Applies equally to a stick, a touch nub, or a mouse delta.
+
+### P5 — `gamepad_write_dpad_vector(result, pad)`
+
+`engine/input/devices/gamepad/gamepad_write_dpad_vector.js` — the D-pad as an analog vector, **in hardware
+frame** (`+y` down), so it composes with `stickLeft` without the consumer tracking which of the two is flipped:
+
+```js
+export function gamepad_write_dpad_vector(result, pad) {
+    const buttons = pad.buttons;
+
+    const up = buttons[GamepadButtons.dpad_up].is_down;
+    const down = buttons[GamepadButtons.dpad_down].is_down;
+    const left = buttons[GamepadButtons.dpad_left].is_down;
+    const right = buttons[GamepadButtons.dpad_right].is_down;
+
+    result.set(
+        (right ? 1 : 0) - (left ? 1 : 0),
+        (down ? 1 : 0) - (up ? 1 : 0)
+    );
+}
+```
+
+(Total only because of P1.) The digital view of the stick is the caller's threshold on
+`apply_radial_dead_zone`'s output, which is a comparison, not an API.
+
+### P6 — Documentation
+
+* Cross-reference the frame on `axes`, `stickLeft`, `stickRight`: *"Hardware frame: `+x` right, `+y` down. See
+  {@link GamepadAxes}. Game-frame conversion belongs in the controller — see `KeyboardCameraController`."*
+* Drop the misleading `?.` from the `buttons` `@example` once P1 lands.
+* Worked gamepad-locomotion example in the `GamepadDevice` class doc (below), so the next consumer copies the
+  intended composition instead of inventing one.
+
+### Tests
+
+`GamepadDevice.spec.js` currently has 7 tests and does not cover any of this. Add:
+
+* P1: all standard buttons defined on a fresh handle, before any poll; `getButton(20)` still grows.
+* P2: `main` exists and is disconnected on a fresh device; binds to the first pad that connects; mirrors its
+  buttons and axes; on disconnect of the bound pad falls back to the oldest remaining connected pad; goes
+  disconnected with everything released when the last pad is lost; a button held at disconnect is released
+  exactly once; a press on the bound pad fires device-level `on.down` exactly once (double-forwarding guard).
+* §3 regression: `resolvePath(devices, "gamepad/main/buttons/0/down")` resolves to a Signal on a fresh engine
+  with no hardware, is the *same object* after connect→disconnect→reconnect, and dispatches across a pad swap.
+* P3 calibration: a window centered at `(0.03, -0.01)` with small noise yields a center within tolerance and a
+  non-zero, structurally bounded `noiseRadius`; a window containing a held stick is **rejected**; a window with
+  one 0.9 spike is rejected; a swept window is rejected; a window with one mild outlier still yields a
+  median-based center unmoved beyond tolerance; identity + `locked` is a bit-exact passthrough of `raw` to
+  `value`; calibrated `value` is exactly `(0,0)` for samples inside the learned radius; `axes` are byte-identical
+  to source at all deflections (mirror contract); the deprecated `deadZone` setter reaches pads connected later.
+* P3 adversarial (§6.4): connecting while the stick is fully deflected, diagonally deflected, or resting at an
+  axis extreme never calibrates; connecting while it is *slightly* deflected stays bounded below a usable
+  gameplay dead zone and recovers; `main` and a reused slot handle each forget a previous pad's calibration, and
+  can then learn a rest position further out than it; a locked calibration survives reconnection.
+* P4: rest → `(0,0)`; just inside `inner` → `(0,0)`; just outside `inner` → magnitude ≈ 0 (continuity, no jump);
+  at `outer` → magnitude 1; beyond `outer` → magnitude 1; full diagonal on a square-gate pad → magnitude 1, not
+  1.41; isotropy — `(0.14, 0.14)` and `(0.198, 0)` land within epsilon of the same magnitude.
+* P5: each direction; opposing pair cancels to 0; diagonal → `(1, 1)` pre-normalization.
+
+All black-box, against real `GamepadHandle` / `InputDeviceSwitch` / a plain object standing in for the native
+`Gamepad` snapshot (a platform type we cannot construct in node — the only fake here).
+
+### After this proposal, the reviewer's integration reads:
+
+```js
+const pad = engine.devices.gamepad.main;   // always present
+
+if (pad.connected) {
+    const left = pad.stickLeft.value;      // already center-corrected for this specific stick
+
+    gamepad_write_dpad_vector(dpad, pad);
+    apply_radial_dead_zone(stick, left.x, left.y, 0.15, 0.95);
+
+    // fusion + frame: game policy, and this is the whole of it
+    const x = stick.x !== 0 || stick.y !== 0 ? stick.x : dpad.x;
+    const y = stick.x !== 0 || stick.y !== 0 ? stick.y : dpad.y;
+
+    move.set(x, -y);        // this game is y-up; the negation is stated once, here, on purpose
+}
+```
+
+Shorter than what the review reported writing, with zero allocation per frame, no `undefined` guard, every policy
+decision visible at the call site instead of hidden behind an options bag — and a gameplay dead zone the game
+picks for feel rather than to paper over hardware, because the hardware error is already gone by this line.
+
+Hot-swapping pads mid-session requires no code here at all: `main` rebinds and the loop doesn't notice.
+
+---
+
+## 5. Explicitly not doing
+
+* **`pad.isDown(i)`** — a third way to ask a question `buttons[i].is_down` and `getButton(i).is_down` already
+  answer, which silently converts absent hardware into an unpressed button. P1 removes the need.
+* **`pad.getMovement()`** — §1.
+* **Frame negation anywhere in the device layer** — the device reports hardware frame, full stop. One negation,
+  in the controller, where the camera is known.
+* **Growing the ISM string-path layer with gamepad-specific concepts** — make the existing paths resolve (P1/P2);
+  do not build more magic strings.
+* **Per-axis signals on `GamepadHandle`** — noted as a real granularity gap in §3. Partly answered by
+  `GamepadStick.on.changed`; the remaining gap is non-stick axes on exotic mappings. Revisit if a consumer needs
+  it.
+* **A calibration wizard** ("rotate the stick in circles") — the standard consumer-tool flow, and the only way to
+  learn true per-direction range. Out of scope: Phase A needs no UI, and Phase B is deferred. If a settings
+  screen wants one later, `GamepadStickCalibration` is already the serializable thing it would write to.
+* **1€ filter** — right tool for deflected-stick jitter, wrong time. Left room for it inside `GamepadStick`; see
+  P3.
+
+---
+
+## 6. What changed during implementation
+
+Two corrections, both found by tests that failed against the design as written above.
+
+### 6.1 The rest-window guard did not do what §4 claimed
+
+*(§4 now describes the shipped bounds; what it said before this correction is quoted here.)*
+
+Revision 2's P3 asserted that `REST_CANDIDATE_MAX = 0.30` plus a spread check together catch "the player was holding the
+stick", *"because a stick held steady at 0.25 passes the first test alone"*. That reasoning is wrong: a stick
+held **steady** at 0.25 also has near-zero spread, so it passes the second test too. The first implementation
+duly learned a held position as the rest position, producing a phantom −0.23 deflection once the player let go.
+The test asserting it wouldn't is what caught it.
+
+There is no way to tell resting from holding inside a single window — both are steady. So the bounds are now
+biased hard toward rejection, on the reasoning that **failing to calibrate is harmless** (identity is an exact
+passthrough) **while calibrating wrongly is actively harmful**:
+
+* `REST_CANDIDATE_MAX` 0.30 → **0.15**. Drift worse than this is a pad heading for replacement, and past some
+  deflection a steady reading is likelier to be a hand than a stick. *(Tightened again to 0.08 in §6.4, on a
+  better argument than this one.)*
+* `REST_SPREAD_MAX` 0.05 → **0.015**. This is now the primary defence, and it exploits a physical difference the
+  original design ignored: a held stick carries the hand's tremor, a settled one carries only sensor noise, and
+  the two differ by roughly an order of magnitude. The cost is that an unusually noisy stick never calibrates,
+  which is the safe failure.
+
+The residual hole is documented rather than papered over: a player parked at a small steady deflection for a
+full second can still poison the estimate until they release, bounded by `REST_CANDIDATE_MAX`, and the
+minimum-magnitude rule then supersedes it. Both the poisoning and the recovery are tested.
+
+### 6.2 `NOISE_RADIUS_MAX` became unreachable, so the clamp went
+
+With the spread bound at 0.015, a window that passes it cannot produce a radius anywhere near 0.20 — the result
+is structurally bounded at `REST_SPREAD_MAX · √2 · (1 + NOISE_RADIUS_DEVIATIONS)` ≈ 0.106. The clamp was a guard
+for a condition that can no longer occur, so it was removed and the constant kept as a derived, documented
+bound. The test asserts the structural property instead of the removed clamp.
+
+### 6.3 Two smaller notes
+
+* **`main` rebinding was one frame stale.** Binding logic initially lived in `#connect`/`#disconnect`, so a
+  successor picked up mid-poll wasn't fed hardware until the *next* poll — `main.connected` read true while
+  `main.id` still named the unplugged pad. Binding, rebinding and refreshing now all happen in one place at the
+  end of `poll()`, which resolves a swap within a single poll and, incidentally, removed a pre-existing
+  duplicate `pad.update()` per poll.
+* **The deprecated `deadZone` setter is plumbed properly**, not just applied to pads that happen to exist when
+  it is written — new handles pick the override up in `#obtainHandle`. A half-working compatibility shim would
+  have been worse than none.
+
+### 6.4 Adversarial pass: connecting with a deflected stick
+
+Two scenarios were put to the implementation afterwards. One was safe, one was not, and chasing them turned up a
+third defect neither scenario named.
+
+**Connecting with a *fully* deflected stick — safe by construction.** Every sample is far outside
+`REST_CANDIDATE_MAX`, so every window is rejected for as long as the stick is held, and release leaves an exact
+passthrough rather than a phantom pull the other way. Same for a diagonal hold, and for the non-standard
+mappings that report a released trigger as an axis resting at −1: those never calibrate, which is the correct
+outcome, not a silent wrong one.
+
+**Connecting with a *partially* deflected stick — this was the real gap.** A steady hold inside the plausibility
+bound is genuinely indistinguishable from drift in a single window, so it was adopted as the rest position and
+produced a phantom deflection of the same size on release. It self-corrected, but "bounded at 0.15 and recovers
+in about two seconds" is a weaker answer than it needs to be, because the bound was set too generously:
+
+* `REST_CANDIDATE_MAX` 0.15 → **0.08**. The reasoning that fixes it is an asymmetry the earlier revisions
+  missed. Auto-calibration earns its keep on *small* drift — the kind that sits under a gameplay dead zone and
+  still causes slow creep. Drift larger than that is already absorbed by any sane gameplay dead zone (XInput
+  ships 0.24), so declining to calibrate it costs almost nothing. Poisoning, on the other hand, costs a phantom
+  deflection. Tightening trades away the case that needs us least, and in exchange the worst wrong estimate now
+  lands **below any usable gameplay dead zone** — it never reaches the game at all before being superseded.
+  That is asserted directly rather than implied.
+
+**The defect neither scenario named: a handle outliving the hardware it learned.** `main` rebinding to a
+different pad, and a slot handle being reused when a different pad is plugged into that slot, both carried the
+previous pad's calibration onto new hardware. Worse than a stale offset: because the calibrator only ever moves
+its estimate *closer* to the origin, a new pad whose rest position sat further out than the old one's could
+**never** have its own rest position adopted — the wrong calibration would have been permanent. Both paths now
+call `forgetCalibration()`, which is a no-op on a locked calibration, since a supplied profile is not ours to
+discard. Regression tests cover both, including a new pad resting further out and the other way.
+
+**Recovery takes up to two windows, not one.** Windows are fixed and non-overlapping, so the one straddling a
+release or a rebind still contains pre-transition samples and is rejected on spread; only the window after it is
+clean. This affects how fast a correct estimate is found, never whether it is correct. Stated here because the
+first tests written assumed one window and were wrong about the contract, not about the code.
+
+**Tests: 101 passing across 13 suites in `engine/input`.** New: `GamepadHandle.spec.js`,
+`GamepadStick.spec.js`, `GamepadStickCalibration.spec.js`, `gamepad_write_dpad_vector.spec.js`,
+`apply_radial_dead_zone.spec.js`, plus P2/P3 coverage and the `resolvePath` regression in
+`GamepadDevice.spec.js`.
+
+---
+
+## Appendix A — What the state of the art actually does
+
+Surveyed while designing P3. Three things are worth having on the record.
+
+**Nobody good uses a single hard-coded constant, and everybody who ships one ships a different number.**
+
+| Stack | At-rest threshold | Notes |
+|---|---|---|
+| XInput (Microsoft) | 7849/32767 ≈ **0.240** left, 8689/32767 ≈ **0.265** right | Vendor-recommended constants, per-stick — even Microsoft doesn't use one number for both sticks on the same pad |
+| SDL | ±3200/32767 ≈ **0.098** | Documented as "consider at rest"; SDL notes advanced UI should let users set or **autodetect** it |
+| Hall-effect / TMR pads (current gen) | **0.02–0.03** | Manufacturer guidance; stable for the life of the pad rather than degrading |
+| Worn potentiometer pads | **0.2+**, rising | The population XInput's 0.24 is sized for |
+| meep today | 0.1, per-axis | Between the two, correct for neither |
+
+That spread is the argument: a constant is a bet on the worst pad you expect to see, and the modern population is
+bimodal — drift-free magnetic sticks alongside worn potentiometer ones. Measuring costs 60 samples once.
+
+**Native stacks calibrate against hardware data we cannot get.** A Switch pad carries factory calibration in SPI
+flash (per-axis min/center/max, at `0x8010`); desktop stacks apply vendor tables. The Gamepad API gives us
+normalized floats and `id`, and nothing else. So the choice isn't "learn vs. read the real values" — it's "learn
+vs. guess".
+
+**Consumer calibration tools all do the same two things**, which is a decent signal about what actually works:
+sample the resting position over a short window (≈60 frames is the common figure) and subtract it; then optionally
+sweep for range. Firmware-level fixes write the corrected center point to controller NVS. This is Phase A and
+Phase B, and it's why P3 puts center estimation first — offset is the defect people call "drift", and a dead zone
+never fixes an offset, it only hides half of one.
+
+**Dead-zone geometry.** Josh Sutphin's taxonomy (axial / radial / scaled radial / sloped-scaled-axial / hybrid)
+is still the reference, with a good annotated implementation set at
+[Minimuino/thumbstick-deadzones](https://github.com/Minimuino/thumbstick-deadzones). Scaled radial with inner and
+outer bounds is P4, and it's the right default: isotropic boundary, full `[0,1]` output range preserved,
+continuous at the inner edge. Axial has legitimate uses (menus, anything wanting pure horizontal/vertical), which
+is another reason it belongs in a consumer-side function rather than baked into the device.
+
+**Jitter vs. drift are different problems.** Dead zones address error near center. Error while deflected is
+jitter, and the state of the art is the 1€ filter (Casiez, Roussel & Vogel, CHI 2012) — a first-order low-pass
+whose cutoff rises with signal speed, so it stabilizes at rest and doesn't lag under motion. Two parameters,
+trivial to implement, measurably less lag than fixed low-pass at equal jitter reduction. Deferred, not dismissed.
+
+Sources:
+[XInput deadzone constants](https://learn.microsoft.com/en-us/previous-versions/windows/xna/bb197229(v=xnagamestudio.42)) ·
+[SDL3 gamepad axis](https://wiki.libsdl.org/SDL3/SDL_GamepadAxis) ·
+[SDL: stacked deadzones issue](https://github.com/libsdl-org/SDL/issues/3781) ·
+[Doing Thumbstick Dead Zones Right — Josh Sutphin](https://joshsutphin.com/blog/doing-thumbstick-dead-zones-right.html) ·
+[Understanding thumbstick deadzones](https://minimuino.github.io/thumbstick-deadzones/) ·
+[Switch SPI calibration layout](https://github.com/dekuNukem/Nintendo_Switch_Reverse_Engineering/blob/master/spi_flash_notes.md) ·
+[Analog stick calibration data — Hand Held Legend](https://wiki.handheldlegend.com/analog-stick-calibration-data) ·
+[Hall-effect vs traditional thumbsticks](https://www.turtlebeach.com/blog/hall-effect-thumbsticks-vs-traditional-joysticks) ·
+[TMR vs hall-effect](https://www.easysmx.com/blogs/easysmx-controllers/tmr-vs-hall-effect-joysticks) ·
+[Controller calibration & drift — SCUF](https://www.scufgaming.com/us/en/gaming/products/scuf-products/controller-calibration-dead-zones-and-stick-drift-explained/) ·
+[1€ filter (CHI 2012, PDF)](https://direction.bordeaux.inria.fr/~roussel/publications/2012-CHI-one-euro-filter.pdf) ·
+[1€ filter reference implementations](https://github.com/casiez/OneEuroFilter)