package com.onthelevel.core.sensors

/**
 * THE SENSOR-VECTOR CONTRACT: world-up (the gravity REACTION, not the gravity force)
 * expressed in the DEVICE coordinate frame, in m/s².
 * Android convention: x → right edge, y → top edge, z → out of the screen.
 *
 * A phone lying flat screen-up on a level surface reads approximately (0, 0, +9.81).
 * This is what Android's TYPE_ACCELEROMETER and TYPE_GRAVITY natively report at rest —
 * per the SensorEvent docs, a stationary flat device reads +9.81 on Z ("acceleration of
 * the device (0 m/s²) minus the force of gravity (−9.81 m/s²)"). The rotation-vector
 * path is converted to the same convention via [RotationVectorMath]. All three sources
 * therefore agree without sign adjustment; SensorContractTest pins this.
 */
data class GravitySample(
    val x: Double,
    val y: Double,
    val z: Double,
    val timestampNanos: Long,
)

/**
 * The two physical orientations v1 supports (BRIEF.md). Selected manually — never
 * auto-switched.
 *
 * SURFACE: device lying flat, screen up, on the surface being measured. Gravity
 * predominantly along +Z.
 *
 * EDGE: device standing upright on either LONG edge (the edges parallel to the device
 * Y axis) against the surface being measured — like a torpedo level. Screen plane
 * roughly vertical; gravity predominantly along ±X. The level reading is the tilt of
 * the resting edge from horizontal; plumb lean (screen tilted from vertical) is a
 * separate, secondary reading.
 *
 * Placement is validated with [OrientationMath.isPlacementValid]; readings and lock
 * are suppressed when the device is not in the selected mode's geometry.
 */
enum class LevelMode { SURFACE, EDGE }
