[feat] add a thermal status row to the debug overlay panel (#248)

## Summary by CodeRabbit

* **New Features**
  * Added optional thermal status row to the compact debug overlay (Android 11+ with thermal HAL support). Enable via `OverlayMode.FullMetrics(showThermal = true)`. Displays device thermal throttling states: None, Light, Moderate, Severe, Critical, Emergency, and Shutdown.

* **Documentation**
  * Updated README and CHANGELOG with thermal status row configuration and usage instructions.

* **Tests**
  * Added comprehensive test coverage for thermal status monitoring.

Author: Manabu-GT

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## Version 2.6.0 *(2026-05-18)*
+
+### New Features
+
+* **Thermal status row** – Optional thermal-status indicator for the compact overlay, opt-in via `OverlayMode.FullMetrics(showThermal = true)`. Combines `PowerManager.getCurrentThermalStatus()` with `getThermalHeadroom()` per [Google's ADPF guidance](https://developer.android.com/games/optimize/adpf/thermal#device-limitations-of-the-thermal-api) so devices with an incomplete thermal HAL still surface a useful signal. Requires Android 11 (API 30) or above; row stays hidden on older devices. Resolves [#246](https://github.com/Manabu-GT/DebugOverlay-Android/issues/246).
+
 ## Version 2.5.0 *(2026-05-12)*
 
 ### New Features

README.md

@@ -44,6 +44,7 @@ Draggable overlay with real-time metrics and sparklines:
 - **Heap** – JVM heap usage percentage
 - **PSS** – Proportional Set Size in MB
 - **FPS** – Real-time frame rate
+- **Thermal** – *(optional, Android 11+)* Device thermal status — enable via `OverlayMode.FullMetrics(showThermal = true)`
 
 ### Debug Panel
 Tap the overlay to open a full-screen diagnostic panel:
@@ -178,6 +179,18 @@ DebugOverlay.configure {
 }
 ```
 
+### Thermal status
+
+Opt in to a thermal-status row in the compact overlay:
+
+```kotlin
+DebugOverlay.configure {
+  overlayMode = OverlayMode.FullMetrics(showThermal = true)
+}
+```
+
+The row shows the current thermal-throttling level with a color-coded dot. Labels are abbreviated to fit the compact panel — `None` / `Light` / `Mod` / `Sev` / `Crit` / `Emer` / `Shut` — mapping to `PowerManager.THERMAL_STATUS_NONE` / `_LIGHT` / `_MODERATE` / `_SEVERE` / `_CRITICAL` / `_EMERGENCY` / `_SHUTDOWN` respectively. Requires Android 11 (API 30) or above with a working thermal HAL — the row stays hidden on older devices and on API 30+ devices whose HAL doesn't expose `getThermalHeadroom` data. If the HAL later starts reporting, the row appears on the next poll.
+
 ### Network request tracking
 
 ```kotlin

debugoverlay-core/src/debug/kotlin/com/ms/square/debugoverlay/internal/ui/DebugOverlayPanelPreviews.kt

@@ -25,6 +25,8 @@ import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 import com.ms.square.debugoverlay.internal.data.model.DebugOverlayPanelMetrics
 import com.ms.square.debugoverlay.internal.data.model.Metrics
+import com.ms.square.debugoverlay.internal.data.model.ThermalState
+import com.ms.square.debugoverlay.internal.data.model.ThermalStatus
 import kotlinx.coroutines.delay
 
 // Composable Previews with static data (no performance monitoring)
@@ -35,6 +37,7 @@ private fun DebugOverlayPanelPreview(
   heapPercent: Float = 72f,
   pss: Float = 256f,
   fps: Float = 60f,
+  thermalState: ThermalState? = null,
 ) {
   // Mock data that updates for preview
   var metrics by remember {
@@ -83,7 +86,8 @@ private fun DebugOverlayPanelPreview(
 
   DebugOverlayPanel(
     metrics = metrics,
-    modifier = modifier
+    modifier = modifier,
+    thermalState = thermalState
   )
 }
 
@@ -211,3 +215,25 @@ private fun DebugOverlayPreviewHighLoad() {
     }
   }
 }
+
+@Preview(name = "Panel Only - With Thermal (Severe)", showBackground = true, widthDp = 200, heightDp = 200)
+@Composable
+private fun DebugOverlayPreviewWithThermal() {
+  MaterialTheme {
+    Box(
+      modifier = Modifier
+        .fillMaxSize()
+        .background(MaterialTheme.colorScheme.background)
+        .padding(16.dp),
+      contentAlignment = Alignment.Center
+    ) {
+      DebugOverlayPanelPreview(
+        cpuPercent = 72f,
+        heapPercent = 65f,
+        pss = 380f,
+        fps = 42f,
+        thermalState = ThermalState(ThermalStatus.SEVERE)
+      )
+    }
+  }
+}

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/OverlayMode.kt

@@ -26,8 +26,16 @@ public sealed interface OverlayMode {
    * Best for developers during active development/testing.
    *
    * @param customTabs Custom tabs appended after the built-in tabs in the debug panel.
+   * @param showThermal When `true`, adds a thermal-status row to the real-time metrics panel.
+   *   Requires Android 11 (API 30) or above with a working thermal HAL — the row stays hidden
+   *   on older devices and on API 30+ devices whose HAL does not expose `getThermalHeadroom`
+   *   data. If a HAL later starts reporting real values, the row appears on the next poll.
+   *   Defaults to `false`.
    */
-  public data class FullMetrics(override val customTabs: List<DebugTab> = emptyList()) : WithCustomTabs
+  public data class FullMetrics(
+    override val customTabs: List<DebugTab> = emptyList(),
+    public val showThermal: Boolean = false,
+  ) : WithCustomTabs
 
   /**
    * Shows a minimal bug reporter FAB.

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/OverlayViewManager.kt

@@ -19,6 +19,7 @@ import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.darkColorScheme
 import androidx.compose.material3.lightColorScheme
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.ComposeView
 import androidx.compose.ui.platform.LocalConfiguration
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
@@ -30,6 +31,7 @@ import com.ms.square.debugoverlay.core.R
 import com.ms.square.debugoverlay.internal.bugreport.ActivityProvider
 import com.ms.square.debugoverlay.internal.bugreport.ui.BugReportActivity
 import com.ms.square.debugoverlay.internal.bugreport.ui.DraggableBugReporterFab
+import com.ms.square.debugoverlay.internal.data.model.ThermalState
 import com.ms.square.debugoverlay.internal.data.source.DebugOverlayPanelDataSourceImpl
 import com.ms.square.debugoverlay.internal.data.source.OverlayPreferences
 import com.ms.square.debugoverlay.internal.data.source.SharedPreferencesOverlayPreferences
@@ -42,9 +44,11 @@ import curtains.OnRootViewsChangedListener
 import curtains.phoneWindow
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.drop
+import kotlinx.coroutines.flow.flowOf
 import kotlinx.coroutines.flow.flowOn
 import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach
@@ -233,13 +237,18 @@ internal class OverlayViewManager(
           }
         ) {
           val currentOverlayMode by overlayMode.collectAsStateWithLifecycle()
-          when (currentOverlayMode) {
+          when (val mode = currentOverlayMode) {
             is OverlayMode.FullMetrics -> {
               val metrics by debugPanelDataSource.debugOverlayPanelMetrics.collectAsStateWithLifecycle(
                 initialValue = null
               )
+              val thermalFlow: Flow<ThermalState?> = remember(mode.showThermal) {
+                if (mode.showThermal) debugPanelDataSource.thermalState else flowOf(null)
+              }
+              val thermalState by thermalFlow.collectAsStateWithLifecycle(initialValue = null)
               DraggableOverlayPanel(
                 metrics = metrics,
+                thermalState = thermalState,
                 initialOffsetX = overlayPreferences.getOverlayX().toFloat(),
                 initialOffsetY = overlayPreferences.getOverlayY().toFloat(),
                 onPositionChanged = onPositionChanged,

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/data/model/ThermalState.kt

@@ -0,0 +1,31 @@
+package com.ms.square.debugoverlay.internal.data.model
+
+/**
+ * Current thermal throttling state of the device.
+ *
+ * Derived from a combination of [android.os.PowerManager.getCurrentThermalStatus] and
+ * [android.os.PowerManager.getThermalHeadroom] (API 30+) using the heuristic described in
+ * the Android ADPF documentation:
+ * https://developer.android.com/games/optimize/adpf/thermal#device-limitations-of-the-thermal-api
+ */
+internal data class ThermalState(val status: ThermalStatus)
+
+/**
+ * Thermal throttling level reported by the platform. Levels [NONE] through [SHUTDOWN] mirror
+ * the `PowerManager.THERMAL_STATUS_*` constants. [UNSUPPORTED] is a synthetic value emitted
+ * when the device cannot report thermal data — either because it pre-dates the thermal API
+ * (Android < 11 / API < 30) or because the thermal HAL is incomplete and
+ * `getThermalHeadroom()` returns `NaN` per its Javadoc contract. The UI hides the row in
+ * both cases. If a HAL later begins returning real headroom values, the state self-heals
+ * to a real level on the next poll.
+ */
+internal enum class ThermalStatus {
+  NONE,
+  LIGHT,
+  MODERATE,
+  SEVERE,
+  CRITICAL,
+  EMERGENCY,
+  SHUTDOWN,
+  UNSUPPORTED,
+}

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/data/source/DebugOverlayPanelDataSource.kt

@@ -3,6 +3,7 @@ package com.ms.square.debugoverlay.internal.data.source
 import android.content.Context
 import com.ms.square.debugoverlay.internal.data.model.DebugOverlayPanelMetrics
 import com.ms.square.debugoverlay.internal.data.model.MetricsAccumulator
+import com.ms.square.debugoverlay.internal.data.model.ThermalState
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.SharingStarted
@@ -12,6 +13,14 @@ import kotlinx.coroutines.flow.shareIn
 
 internal sealed interface DebugOverlayPanelDataSource {
   val debugOverlayPanelMetrics: Flow<DebugOverlayPanelMetrics?>
+
+  /**
+   * Thermal status flow, exposed separately from [debugOverlayPanelMetrics] so consumers can
+   * subscribe conditionally (e.g. only when `OverlayMode.FullMetrics.showThermal` is `true`).
+   * Backed by `shareIn(WhileSubscribed)` so the underlying PowerManager listener / headroom
+   * polling only runs while something is collecting.
+   */
+  val thermalState: Flow<ThermalState>
 }
 
 internal class DebugOverlayPanelDataSourceImpl(context: Context, overlayScope: CoroutineScope) :
@@ -20,14 +29,15 @@ internal class DebugOverlayPanelDataSourceImpl(context: Context, overlayScope: C
   private val cpuDataSource = CpuDataSource()
   private val memoryDataSource = MemoryDataSource(context)
   private val fpsDataSource = FpsDataSource(context)
+  private val thermalDataSource = ThermalDataSource(context)
 
   // Accumulators for maintaining history across flow collection restarts
   private val cpuAccumulator = MetricsAccumulator()
   private val heapAccumulator = MetricsAccumulator()
   private val pssAccumulator = MetricsAccumulator()
   private val fpsAccumulator = MetricsAccumulator()
 
-  private val sharedMetrics: Flow<DebugOverlayPanelMetrics?> = combine(
+  override val debugOverlayPanelMetrics: Flow<DebugOverlayPanelMetrics?> = combine(
     cpuDataSource.cpuUsage().map { cpuAccumulator.accumulate(it.value) },
     memoryDataSource.heapUsage().map { heapAccumulator.accumulate(it.value) },
     memoryDataSource.pss().map { pssAccumulator.accumulate(it) },
@@ -42,13 +52,8 @@ internal class DebugOverlayPanelDataSourceImpl(context: Context, overlayScope: C
       targetFps = fpsDataSource.currentTargetFps,
       maxFps = fpsDataSource.maxSupportedFps
     )
-  }
-    .shareIn(
-      scope = overlayScope,
-      started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 1_000),
-      replay = 1
-    )
+  }.shareIn(overlayScope, SharingStarted.WhileSubscribed(stopTimeoutMillis = 1_000), replay = 1)
 
-  override val debugOverlayPanelMetrics: Flow<DebugOverlayPanelMetrics?>
-    get() = sharedMetrics
+  override val thermalState: Flow<ThermalState> = thermalDataSource.thermalState()
+    .shareIn(overlayScope, SharingStarted.WhileSubscribed(stopTimeoutMillis = 1_000), replay = 1)
 }