feat: Custom Tab API for debug panel (#213)

- Add `DebugTab` class for custom debug panel tabs with composable content
- Custom tabs configured via `OverlayMode.FullMetrics(customTabs = ...)` — type system prevents misconfiguration with `BugReporterOnly`
- Built-in tabs remain unchanged (private enum, same order as v2.1.x)
- Sample app demonstrates custom SharedPrefs tab with M3-styled card UI

Author: Manabu-GT

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## Version 2.2.0 *(Unreleased)*
+
+### New Features
+
+* **Custom Tab API** – Add app-specific tabs to the debug panel via `DebugTab` class. Custom tabs are appended after built-in tabs and configured via `OverlayMode.FullMetrics(customTabs = ...)`.
+
+### Breaking Changes
+
+* `OverlayMode.FullMetrics` changed from `data object` to `data class`. If you reference it explicitly, change `OverlayMode.FullMetrics` to `OverlayMode.FullMetrics()`. Zero-config users are unaffected.
+
 ## Version 2.1.1 *(2026-03-26)*
 
 ### Dependencies

README.md

@@ -125,6 +125,20 @@ class MyApp : Application() {
 
 <img src="art/readme_bug_reporter_only.gif" alt="Bug Reporter Only Mode">
 
+### Custom tabs
+
+Add app-specific tabs to the debug panel. Custom tabs appear after the built-in tabs:
+
+```kotlin
+DebugOverlay.configure {
+  overlayMode = OverlayMode.FullMetrics(
+    customTabs = listOf(
+      DebugTab(title = "Feature Flags") { FeatureFlagsContent() }
+    )
+  )
+}
+```
+
 ### Network request tracking
 
 ```kotlin

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

@@ -226,7 +226,7 @@ public object DebugOverlay {
    * @see configure
    */
   public data class Config(
-    val overlayMode: OverlayMode = OverlayMode.FullMetrics,
+    val overlayMode: OverlayMode = OverlayMode.FullMetrics(),
     val networkRequestSource: NetworkRequestSource = NoOpNetworkRequestSource,
     val customLogSource: LogSource? = null,
     val bugReportExporter: BugReportExporter = IntentShareExporter,

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

@@ -0,0 +1,28 @@
+package com.ms.square.debugoverlay
+
+import androidx.compose.runtime.Composable
+
+/**
+ * A custom tab displayed in the debug panel.
+ *
+ * Custom tabs are appended after the built-in tabs (Logcat, Network, etc.).
+ * Configure via [OverlayMode.FullMetrics]:
+ *
+ * ```kotlin
+ * DebugOverlay.configure {
+ *   overlayMode = OverlayMode.FullMetrics(
+ *     customTabs = listOf(
+ *       DebugTab(title = "Feature Flags") { FeatureFlagsContent() }
+ *     )
+ *   )
+ * }
+ * ```
+ *
+ * ## Bug Reports
+ * Tabs are UI-only. To include custom data in bug reports, use
+ * [DebugOverlay.addBugReportContributor] separately.
+ *
+ * @param title Display title shown in the tab row.
+ * @param content Composable content rendered when this tab is selected.
+ */
+public class DebugTab(internal val title: String, internal val content: @Composable () -> Unit)

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

@@ -6,7 +6,7 @@ package com.ms.square.debugoverlay
  * Configure via [DebugOverlay.configure]:
  * ```kotlin
  * DebugOverlay.configure {
- *   copy(overlayMode = OverlayMode.BugReporterOnly)
+ *   overlayMode = OverlayMode.BugReporterOnly
  * }
  * ```
  */
@@ -15,8 +15,10 @@ public sealed interface OverlayMode {
    * Shows real-time metrics panel (CPU, Memory, FPS).
    * Tapping opens the debug panel.
    * Best for developers during active development/testing.
+   *
+   * @param customTabs Custom tabs appended after the built-in tabs in the debug panel.
    */
-  public data object FullMetrics : OverlayMode
+  public data class FullMetrics(val customTabs: List<DebugTab> = emptyList()) : OverlayMode
 
   /**
    * Shows a minimal bug reporter FAB.

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

@@ -214,7 +214,7 @@ internal class OverlayViewManager(
         ) {
           val currentOverlayMode by overlayMode.collectAsStateWithLifecycle()
           when (currentOverlayMode) {
-            OverlayMode.FullMetrics -> {
+            is OverlayMode.FullMetrics -> {
               val metrics by debugPanelDataSource.debugOverlayPanelMetrics.collectAsStateWithLifecycle(
                 initialValue = null
               )

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

@@ -28,6 +28,8 @@ import androidx.compose.material3.TopAppBarDefaults
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.key
+import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
@@ -46,6 +48,8 @@ import androidx.compose.ui.window.Dialog
 import androidx.compose.ui.window.DialogProperties
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.ms.square.debugoverlay.DebugOverlay
+import com.ms.square.debugoverlay.DebugTab
+import com.ms.square.debugoverlay.OverlayMode
 import com.ms.square.debugoverlay.core.R
 import com.ms.square.debugoverlay.internal.bugreport.BugReportGenerator
 import com.ms.square.debugoverlay.internal.bugreport.ui.BugReportActivity
@@ -55,7 +59,7 @@ import com.ms.square.debugoverlay.internal.data.DebugOverlayDataRepository
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 
-private enum class DebugTab(@param:StringRes val titleResId: Int) {
+private enum class BuiltInTab(@param:StringRes val titleResId: Int) {
   LOGCAT(R.string.debugoverlay_tab_logcat),
   CUSTOM_LOG(R.string.debugoverlay_tab_custom_log), // Fallback; UI uses dynamic title from source
   APP_EXITS(R.string.debugoverlay_tab_app_exits),
@@ -65,6 +69,14 @@ private enum class DebugTab(@param:StringRes val titleResId: Int) {
   DEVICE_INFO(R.string.debugoverlay_tab_device_info),
 }
 
+/**
+ * A visible tab in the panel — either a built-in tab or a custom [DebugTab].
+ */
+private sealed class PanelTab {
+  data class BuiltIn(val tab: BuiltInTab) : PanelTab()
+  data class Custom(val tab: DebugTab) : PanelTab()
+}
+
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 internal fun DebugPanelDialog(onDismiss: () -> Unit) {
@@ -225,61 +237,58 @@ private fun DebugPanelContent(modifier: Modifier = Modifier) {
   val repository = DebugOverlay.overlayDataRepository
   val hasCustomLogSource by repository.hasCustomLogSource.collectAsStateWithLifecycle()
   val customLogSourceName by repository.customLogSourceName.collectAsStateWithLifecycle()
+  val customTabs = (DebugOverlay.config.overlayMode as? OverlayMode.FullMetrics)?.customTabs.orEmpty()
 
-  // Build visible tabs: hide CUSTOM_LOG when no custom log source is registered
-  val visibleTabs = remember(hasCustomLogSource) {
-    DebugTab.entries.filter { tab ->
-      tab != DebugTab.CUSTOM_LOG || hasCustomLogSource
-    }
-  }
-
-  // Use rememberSaveable to persist tab selection across configuration changes
-  var selectedTab by rememberSaveable { mutableStateOf(DebugTab.LOGCAT) }
-
-  // Validate selection when tabs change (e.g., custom log source removed)
-  LaunchedEffect(visibleTabs) {
-    if (selectedTab !in visibleTabs) {
-      selectedTab = DebugTab.LOGCAT
-    }
+  // Build visible tabs: built-in tabs (with CUSTOM_LOG conditionally shown) + custom tabs
+  val visibleTabs = remember(hasCustomLogSource, customTabs) {
+    val builtIn = BuiltInTab.entries
+      .filter { it != BuiltInTab.CUSTOM_LOG || hasCustomLogSource }
+      .map { PanelTab.BuiltIn(it) }
+    builtIn + customTabs.map { PanelTab.Custom(it) }
   }
 
-  val selectedTabIndex = visibleTabs.indexOf(selectedTab).coerceAtLeast(0)
+  var selectedIndex by rememberSaveable { mutableIntStateOf(0) }
+  selectedIndex = selectedIndex.coerceIn(0, visibleTabs.lastIndex)
 
   Column(modifier = modifier.fillMaxSize()) {
     DebugPanelTabRow(
       visibleTabs = visibleTabs,
-      selectedTab = selectedTab,
-      selectedTabIndex = selectedTabIndex,
+      selectedIndex = selectedIndex,
       customLogSourceName = customLogSourceName,
-      onTabSelected = { selectedTab = it }
+      onTabSelected = { selectedIndex = it }
+    )
+    DebugPanelTabContent(
+      selectedTab = visibleTabs[selectedIndex],
+      repository = repository
     )
-    DebugPanelTabContent(selectedTab = selectedTab, repository = repository)
   }
 }
 
 @Composable
 private fun DebugPanelTabRow(
-  visibleTabs: List<DebugTab>,
-  selectedTab: DebugTab,
-  selectedTabIndex: Int,
+  visibleTabs: List<PanelTab>,
+  selectedIndex: Int,
   customLogSourceName: String?,
-  onTabSelected: (DebugTab) -> Unit,
+  onTabSelected: (Int) -> Unit,
 ) {
   PrimaryScrollableTabRow(
-    selectedTabIndex = selectedTabIndex,
+    selectedTabIndex = selectedIndex,
     modifier = Modifier.fillMaxWidth(),
     containerColor = Color.Transparent
   ) {
-    visibleTabs.forEach { tab ->
+    visibleTabs.forEachIndexed { index, panelTab ->
       Tab(
-        selected = selectedTab == tab,
-        onClick = { onTabSelected(tab) },
+        selected = index == selectedIndex,
+        onClick = { onTabSelected(index) },
         text = {
           Text(
-            text = if (tab == DebugTab.CUSTOM_LOG) {
-              customLogSourceName ?: DEFAULT_CUSTOM_LOG_SOURCE_NAME
-            } else {
-              stringResource(tab.titleResId)
+            text = when (panelTab) {
+              is PanelTab.BuiltIn -> if (panelTab.tab == BuiltInTab.CUSTOM_LOG) {
+                customLogSourceName ?: DEFAULT_CUSTOM_LOG_SOURCE_NAME
+              } else {
+                stringResource(panelTab.tab.titleResId)
+              }
+              is PanelTab.Custom -> panelTab.tab.title
             },
             style = MaterialTheme.typography.labelLarge
           )
@@ -290,20 +299,23 @@ private fun DebugPanelTabRow(
 }
 
 @Composable
-private fun DebugPanelTabContent(selectedTab: DebugTab, repository: DebugOverlayDataRepository) {
+private fun DebugPanelTabContent(selectedTab: PanelTab, repository: DebugOverlayDataRepository) {
   when (selectedTab) {
-    DebugTab.LOGCAT -> LogTabContent(logsFlow = repository.logcatLogs)
-    DebugTab.CUSTOM_LOG -> LogTabContent(logsFlow = repository.customLogSourceLogs)
-    DebugTab.APP_EXITS -> AppExitTabContent(
-      exitInfosFlow = repository.appExitInfos,
-      isSupported = repository.isAppExitSupported
-    )
-    DebugTab.NETWORK -> NetworkTabContent(
-      netStatsFlow = repository.netStats,
-      networkRequestsFlow = repository.networkRequests
-    )
-    DebugTab.JANKSTATS -> JankStatsTabContent(jankStatsFlow = repository.jankStats)
-    DebugTab.UI -> UiTabContent()
-    DebugTab.DEVICE_INFO -> DeviceInfoTabContent(deviceInfoFlow = repository.deviceInfo)
+    is PanelTab.BuiltIn -> when (selectedTab.tab) {
+      BuiltInTab.LOGCAT -> LogTabContent(logsFlow = repository.logcatLogs)
+      BuiltInTab.CUSTOM_LOG -> LogTabContent(logsFlow = repository.customLogSourceLogs)
+      BuiltInTab.APP_EXITS -> AppExitTabContent(
+        exitInfosFlow = repository.appExitInfos,
+        isSupported = repository.isAppExitSupported
+      )
+      BuiltInTab.NETWORK -> NetworkTabContent(
+        netStatsFlow = repository.netStats,
+        networkRequestsFlow = repository.networkRequests
+      )
+      BuiltInTab.JANKSTATS -> JankStatsTabContent(jankStatsFlow = repository.jankStats)
+      BuiltInTab.UI -> UiTabContent()
+      BuiltInTab.DEVICE_INFO -> DeviceInfoTabContent(deviceInfoFlow = repository.deviceInfo)
+    }
+    is PanelTab.Custom -> key(selectedTab.tab) { selectedTab.tab.content() }
   }
 }

debugoverlay-core/src/test/kotlin/com/ms/square/debugoverlay/DebugOverlayTest.kt

@@ -21,7 +21,7 @@ class DebugOverlayTest {
   @After
   fun tearDown() {
     DebugOverlay.configure {
-      overlayMode = OverlayMode.FullMetrics
+      overlayMode = OverlayMode.FullMetrics()
       networkRequestSource = NoOpNetworkRequestSource
       customLogSource = null
       bugReportExporter = IntentShareExporter
@@ -33,7 +33,7 @@ class DebugOverlayTest {
   fun `Config has correct defaults`() {
     val config = DebugOverlay.Config()
 
-    assertThat(config.overlayMode).isEqualTo(OverlayMode.FullMetrics)
+    assertThat(config.overlayMode).isEqualTo(OverlayMode.FullMetrics())
     assertThat(config.networkRequestSource).isEqualTo(NoOpNetworkRequestSource)
     assertThat(config.customLogSource).isNull()
     assertThat(config.bugReportExporter).isSameInstanceAs(IntentShareExporter)
@@ -83,6 +83,19 @@ class DebugOverlayTest {
     assertThat(DebugOverlay.config.networkRequestSource).isSameInstanceAs(networkSource)
   }
 
+  @Test
+  fun `configure sets custom tabs on FullMetrics preserving order`() {
+    val tab1 = DebugTab(title = "Tab 1") {}
+    val tab2 = DebugTab(title = "Tab 2") {}
+
+    DebugOverlay.configure {
+      overlayMode = OverlayMode.FullMetrics(customTabs = listOf(tab1, tab2))
+    }
+
+    val mode = DebugOverlay.config.overlayMode as OverlayMode.FullMetrics
+    assertThat(mode.customTabs).containsExactly(tab1, tab2).inOrder()
+  }
+
   @Test
   fun `addBugReportContributor adds contributors to list`() {
     val contributor1 = TestBugReportContributor("test1.txt")

docs/ARCHITECTURE.md

@@ -82,6 +82,10 @@ interface BugReportDataContributor {
 
 **Auto-registration pattern:** Extensions self-register in their `init` block by calling `DebugOverlay.configure {}`. AndroidX Startup provides zero-config initialization for core and Timber extension (via manifest-declared initializers); OkHttp extension requires manual interceptor registration.
 
+### Custom Tabs
+
+The debug panel supports custom tabs via the `DebugTab` class. Custom tabs are appended after built-in tabs and configured via `OverlayMode.FullMetrics(customTabs = ...)`. Custom tab content is a `@Composable` lambda provided at construction time.
+
 ## UI Architecture
 
 ```

docs/TESTING.md

@@ -57,7 +57,7 @@ Before writing a new test, verify it tests a **unique behavior**:
 // GOOD: One test, multiple assertions for the same behavior
 @Test fun `Config has correct defaults`() {
     val config = Config()
-    assertThat(config.overlayMode).isEqualTo(OverlayMode.FullMetrics)
+    assertThat(config.overlayMode).isEqualTo(OverlayMode.FullMetrics())
     assertThat(config.networkRequestSource).isEqualTo(NoOpNetworkRequestSource)
     assertThat(config.customLogSource).isNull()
 }