Define the public motion value and axis contract #45

Workflow

A game developer sends PlayStation or Switch motion through OpenController and needs to know whether acceleration, gyroscope, and orientation values are calibrated physical quantities or application-defined values, and what physical-axis guarantees the SDK can make.

Dated external observation

• SDL #15972, opened 2026-07-11, reports a Steam Controller 2 gyro interpreted as roll when the game expected yaw after controller-type-based orientation handling. The report describes affected remasters and discusses per-controller axis detection or player-space gyro as workarounds. It is an SDL/game integration report, not an OpenController bug.

Repository gap and interpretation

docs/controller-profiles.md introduces controller.motion() but does not currently say whether the three motion quantities use calibrated physical units, specify their sensor calibration source, or promise a common hardware-to-human coordinate frame. The numeric input range/clamping and component-to-report-field behavior are already covered by the motion encoders and their conformance documentation/tests; this issue must not restate those guarantees as new acceptance work.

The remaining opportunity is to explain the boundary between the SDK's tested report serialization and application/device-specific physical interpretation. The SDL report motivates that clarification but does not show an OpenController user was blocked.

Proposed outcome

Narrowly document the units/calibration status and limits of any axis-orientation guarantee for controller.motion(). Link to the existing report/conformance guarantees for normalized input range, clamping, and component-to-field encoding rather than adding duplicate tests.

Acceptance criteria

• State whether acceleration, gyroscope, and orientation fields are calibrated physical units, normalized abstract values, or caller-provided numbers; if the repo cannot substantiate units/calibration, explicitly say they are unspecified/un-calibrated by this API.
• State which device/coordinate-frame guarantees OpenController does and does not make; do not claim a universal human-centric orientation if it is not implemented.
• Link to docs/gamepad-report-conformance.md and the existing PlayStation/Switch motion fixtures for established numeric-range and same-axis serialization guarantees.
• Add no new tests unless review finds a specific missing assertion beyond the existing fixtures; identify that assertion before expanding scope.
• Keep any example limited to where callers apply a consumer-specific transform, without changing profile encoding.

Validation

Review the doc statements against packages/core/src/hid/playstation.ts, packages/core/src/hid/switch.ts, and existing conformance fixtures. If only documentation changes, run the docs/link check used by the repository; do not duplicate the existing core motion tests.

Non-goals

• No automatic sensor calibration, IMU fusion, gyro aiming, player-space transform, or hardware-specific VID/PID table.
• No change to current numeric bounds, clamping, component mapping, or profile report formats.
• No promise that Steam Input, SDL, an OS, or a game uses the same physical-axis convention.

Confidence and limits

Medium-low. One detailed dated SDL report describes a concrete orientation mismatch and workaround. The public documentation gap is narrow and directly inspectable, but there is no OpenController user report and SDL's hardware-specific issue may not map directly to this raw report API.

Ownership and dependencies

Lane: docs/controller-profiles.md, linking to docs/gamepad-report-conformance.md and existing tests under packages/core/src/__tests__/. No runtime/source changes are expected. Separate from #41's keyboard-mouse semantics and from #44's deferred adaptive-trigger protocol design.