Settings: Make charge recording a one-time opt-in with a Charging history screen

The battery hub's "Record statistics" card was a toggle card that stayed on
screen forever. Since the switch is flipped once and then never again, it
occupied the top of the hub permanently for no further purpose.

It becomes a one-time opt-in card: same title, subtitle and tone, but with a
"Start recording" button and a sentence pointing at the new settings screen for
turning it back off. Once recording is on the card is gone entirely and the
charge section becomes the hub's first content. The durable on/off control now
lives in Settings > Charging history, which also carries a retention slider.

Retention is new behavior, not just a new knob. Previously charge_sessions rows
were kept forever and only raw samples were purged, on a hardcoded 30-day
window. Now whole entries are purged by endedAtWallMillis past a user-set
window (3-14 days, default 14) with their samples cascading, while
deleteSamplesOlderThan is retained: a sample's wall time being <= its session's
end stamp does not put it inside the window, so a long charge that ended
recently would otherwise keep its entire curve.

The purge also had to be made reachable. It previously sat inside
reconcileDanglingSessions() behind a maxOfOrNull{}?.let{}, so with no dangling
open rows - the normal state after a clean disable - it never ran at all. It now
runs in startupRepair() after reconciliation, on session seal, and immediately
on a retention change via an ordered Command.Purge.

The recorder's "might we have data" guard moves from the lastCaptureWallMillis
timestamp to a stats.db file check. The stamp was written after the first row
was committed, so a crash in that gap hid existing data from the guard forever.
That also retires the preference outright, removing a DataStore write every ~20s
while charging.

SettingsSliderItem is new: local drag state committed only on release and only
when the value actually changed, so dragging cannot write the shared DataStore
per frame or enqueue a purge per frame. Its label formats the live dragged value
so the number tracks the thumb.

The retention flow is collected at MainActivity's composition root rather than
at the settings destination. StatsViewModel is a lazy by viewModels() delegate,
so collecting at the destination would start its eager sharing in the very frame
the screen appears and render the placeholder default before the stored value
landed.

Author: d4rken

app/src/main/java/eu/darken/amply/common/settings/SettingsComponents.kt

@@ -12,9 +12,14 @@ import androidx.compose.material.icons.filled.Palette
 import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Slider
 import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.alpha
@@ -23,6 +28,7 @@ import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import eu.darken.amply.common.compose.AmplyPreview
 import eu.darken.amply.common.compose.PreviewWrapper
+import kotlin.math.roundToInt
 
 @Composable
 fun SettingsBaseItem(
@@ -116,6 +122,79 @@ fun SettingsSwitchItem(
     },
 )
 
+/**
+ * A discrete whole-number slider row. Deliberately not a [SettingsBaseItem]: the row itself is not a
+ * click target — the track is — so it lays out its own title line (icon + title + [valueLabel]) and
+ * puts the slider beneath, inset to line up with the title.
+ *
+ * The dragged value is local state and is committed **only on release**, and only when it actually
+ * changed. Material's [Slider] fires `onValueChangeFinished` for a plain press-and-release on the
+ * thumb too, so without that guard a no-op gesture would write a preference and kick off whatever
+ * work the change triggers. [value] changing from outside re-syncs the local state.
+ *
+ * [valueLabel] formats the **live** dragged value, not [value] — a caller must not pre-format the
+ * persisted number, or the label would sit frozen on the old value for the whole gesture.
+ */
+@Composable
+fun SettingsSliderItem(
+    title: String,
+    valueLabel: @Composable (Int) -> String,
+    value: Int,
+    range: IntRange,
+    onValueChange: (Int) -> Unit,
+    modifier: Modifier = Modifier,
+    subtitle: String? = null,
+    icon: ImageVector? = null,
+) {
+    var dragged by remember(value) { mutableStateOf(value) }
+    Column(
+        modifier = modifier
+            .fillMaxWidth()
+            .padding(horizontal = 16.dp, vertical = 16.dp),
+    ) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            if (icon != null) {
+                Icon(
+                    imageVector = icon,
+                    contentDescription = null,
+                    modifier = Modifier.size(24.dp),
+                    tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+            Column(
+                modifier = Modifier
+                    .weight(1f)
+                    .padding(start = if (icon != null) 16.dp else 0.dp),
+            ) {
+                Text(title, style = MaterialTheme.typography.bodyLarge, color = MaterialTheme.colorScheme.onSurface)
+                subtitle?.let {
+                    Text(
+                        it,
+                        modifier = Modifier.padding(top = 2.dp),
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+            Text(
+                valueLabel(dragged),
+                modifier = Modifier.padding(start = 8.dp),
+                style = MaterialTheme.typography.titleMedium,
+                color = MaterialTheme.colorScheme.primary,
+            )
+        }
+        Slider(
+            value = dragged.toFloat(),
+            onValueChange = { dragged = it.roundToInt() },
+            onValueChangeFinished = { if (dragged != value) onValueChange(dragged) },
+            valueRange = range.first.toFloat()..range.last.toFloat(),
+            // One stop per whole step, ends excluded.
+            steps = (range.count() - 2).coerceAtLeast(0),
+            modifier = Modifier.padding(start = if (icon != null) 40.dp else 0.dp),
+        )
+    }
+}
+
 @Composable
 fun SettingsCategoryHeader(text: String) {
     Text(
@@ -161,5 +240,15 @@ private fun SettingsComponentsPreview() = PreviewWrapper {
             onCheckedChange = {},
             icon = Icons.Default.Palette,
         )
+        SettingsDivider()
+        SettingsSliderItem(
+            title = "Keep history for",
+            valueLabel = { days -> "$days days" },
+            value = 7,
+            range = 3..14,
+            onValueChange = {},
+            subtitle = "Charges older than this are deleted automatically.",
+            icon = Icons.Default.Palette,
+        )
     }
 }

app/src/main/java/eu/darken/amply/main/ui/MainActivity.kt

@@ -55,6 +55,7 @@ import eu.darken.amply.main.ui.dashboard.DashboardViewModel
 import eu.darken.amply.main.ui.dashboard.shouldMonitorAccess
 import eu.darken.amply.main.ui.onboarding.OnboardingScreen
 import eu.darken.amply.main.ui.settings.AcknowledgementsScreen
+import eu.darken.amply.main.ui.settings.ChargingHistorySettingsScreen
 import eu.darken.amply.main.ui.settings.GeneralSettingsScreen
 import eu.darken.amply.main.ui.settings.ReconnectGestureSettingsScreen
 import eu.darken.amply.main.ui.settings.SettingsDestination
@@ -96,6 +97,15 @@ class MainActivity : ComponentActivity() {
         enableEdgeToEdge()
         setContent {
             val themeState by settingsViewModel.themeState.collectAsState()
+            // Collected here at the composition root, NOT down in the CHARGING_HISTORY_SETTINGS branch
+            // that consumes it. `statsViewModel` is a lazy `by viewModels()` delegate, so collecting at
+            // the destination would construct the ViewModel — and thus start its "eager" sharing — in
+            // the very frame the screen appears, rendering the placeholder default before the stored
+            // value lands (a drag started in that window would also be reset, since the slider re-keys
+            // its local state on the incoming value). Collecting at the root makes it an already-resolved
+            // source by the time the user is two levels deep in Settings, the same way `captureEnabled`
+            // uses the resolved dashboard state instead of its own first emission. Don't move it down.
+            val retentionDays by statsViewModel.retentionDays.collectAsState()
             AmplyTheme(themeState) {
                 Surface(
                     modifier = Modifier.fillMaxSize(),
@@ -285,6 +295,10 @@ class MainActivity : ComponentActivity() {
                         SettingsDestination.SETTINGS -> SettingsScreen(
                             onBack = { destination = SettingsDestination.DASHBOARD },
                             onGeneral = { destination = SettingsDestination.GENERAL },
+                            captureEnabled = state.stats.enabled,
+                            onChargingHistory = {
+                                destination = SettingsDestination.CHARGING_HISTORY_SETTINGS
+                            },
                             // Offered whenever this device is one we want contribution data for (unsupported/lab),
                             // regardless of whether Shizuku is installed yet — the wizard nudges the install.
                             showDiagnostics = state.charging.contributionWanted,
@@ -348,33 +362,36 @@ class MainActivity : ComponentActivity() {
                             onBack = { destination = SettingsDestination.DASHBOARD },
                             onAnyLevelChange = viewModel::setQuickFullChargeAnyLevel,
                         )
-                        // The hub reads the battery straight from the dashboard state (already
-                        // collected) and takes only the capture switch from the stats ViewModel —
-                        // deliberately not its history flow, which is what would open stats.db.
-                        SettingsDestination.BATTERY -> {
-                            val capture by statsViewModel.captureState.collectAsState()
-                            BatteryHubScreen(
-                                readout = state.batteryReadout,
-                                // The switch reads from the already-resolved dashboard state, not from
-                                // captureState: that flow is only subscribed when this screen opens, so
-                                // its first emission is the `false` default and the toggle would render
-                                // off for a frame beside a teaser saying a charge is being recorded.
-                                // Same preference, one resolved source, no disagreement on screen.
-                                captureEnabled = state.stats.enabled,
-                                lastCaptureWallMillis = capture.lastCaptureWallMillis,
-                                teaser = ChargeTeaserState.from(state.stats, state.batteryReadout),
-                                onBack = { destination = SettingsDestination.DASHBOARD },
-                                onOpenHistory = { destination = SettingsDestination.CHARGE_HISTORY },
-                                onCaptureEnabledChange = { enabled ->
-                                    if (enabled) {
-                                        runWithNotifications(NotificationAction.ENABLE_STATS)
-                                    } else {
-                                        statsViewModel.setCaptureEnabled(false)
-                                    }
-                                },
-                                onOpenSession = { id -> openSession(id, SettingsDestination.BATTERY) },
-                            )
-                        }
+                        SettingsDestination.CHARGING_HISTORY_SETTINGS -> ChargingHistorySettingsScreen(
+                            // Both values come from already-resolved sources (the dashboard state and
+                            // the root-collected retention flow), so neither the switch nor the slider
+                            // can render a placeholder for a frame while a first emission lands.
+                            captureEnabled = state.stats.enabled,
+                            retentionDays = retentionDays,
+                            onBack = { destination = SettingsDestination.SETTINGS },
+                            onCaptureEnabledChange = { enabled ->
+                                if (enabled) {
+                                    runWithNotifications(NotificationAction.ENABLE_STATS)
+                                } else {
+                                    statsViewModel.setCaptureEnabled(false)
+                                }
+                            },
+                            onRetentionChange = statsViewModel::setRetentionDays,
+                        )
+                        // The hub reads the battery and the capture flag straight from the dashboard
+                        // state (already collected and resolved, so the opt-in card can't flash on for
+                        // a frame beside a teaser saying a charge is being recorded) — deliberately not
+                        // the stats ViewModel's history flow, which is what would open stats.db.
+                        SettingsDestination.BATTERY -> BatteryHubScreen(
+                            readout = state.batteryReadout,
+                            captureEnabled = state.stats.enabled,
+                            teaser = ChargeTeaserState.from(state.stats, state.batteryReadout),
+                            onBack = { destination = SettingsDestination.DASHBOARD },
+                            onOpenHistory = { destination = SettingsDestination.CHARGE_HISTORY },
+                            // Enable-only: turning recording back off lives in Settings › Charging history.
+                            onEnableCapture = { runWithNotifications(NotificationAction.ENABLE_STATS) },
+                            onOpenSession = { id -> openSession(id, SettingsDestination.BATTERY) },
+                        )
                         // The Room-backed session list is collected only here, so the stats DB isn't
                         // opened just by visiting the hub — a user who never enables statistics never
                         // creates stats.db by looking at their battery.

app/src/main/java/eu/darken/amply/main/ui/battery/BatteryHubScreen.kt

@@ -40,9 +40,10 @@ import eu.darken.amply.common.compose.AmplyPreview
 import eu.darken.amply.common.compose.PreviewWrapper
 
 /**
- * The single battery/charging destination: the capture switch, the current or last charge, and the
- * full live readout. Replaces the split between a read-only battery-detail screen and a statistics
- * screen that each rendered level, current, and temperature through different code.
+ * The single battery/charging destination: the current or last charge and the full live readout, led
+ * by the recording opt-in until it has been accepted. Replaces the split between a read-only
+ * battery-detail screen and a statistics screen that each rendered level, current, and temperature
+ * through different code.
  *
  * State-hoisted and previewable — it renders straight from a [BatteryReadout] plus a
  * [ChargeTeaserState], so it needs no ViewModel of its own. Fields the platform doesn't report render
@@ -53,11 +54,10 @@ import eu.darken.amply.common.compose.PreviewWrapper
 fun BatteryHubScreen(
     readout: BatteryReadout?,
     captureEnabled: Boolean,
-    lastCaptureWallMillis: Long?,
     teaser: ChargeTeaserState,
     onBack: () -> Unit,
     onOpenHistory: () -> Unit,
-    onCaptureEnabledChange: (Boolean) -> Unit,
+    onEnableCapture: () -> Unit,
     onOpenSession: (Long) -> Unit,
 ) {
     Scaffold(
@@ -91,16 +91,15 @@ fun BatteryHubScreen(
             contentPadding = PaddingValues(16.dp),
             verticalArrangement = Arrangement.spacedBy(12.dp),
         ) {
-            item {
-                CaptureToggleCard(
-                    enabled = captureEnabled,
-                    lastCaptureWallMillis = lastCaptureWallMillis,
-                    onCaptureEnabledChange = onCaptureEnabledChange,
-                )
+            // Gated on the authoritative preference, not on the teaser: the opt-in is a one-time
+            // prompt, so it disappears for good the moment recording is on.
+            if (!captureEnabled) {
+                item { CaptureOptInCard(onEnable = onEnableCapture) }
             }
             // The charge section sits above the raw readout: "how is this charge going" is the question
-            // that brings most visits here, and the readout below is reference material. With capture
-            // off there is no section at all — the toggle immediately above already explains why.
+            // that brings most visits here, and the readout below is reference material. With recording
+            // on it is the first thing on the screen; with recording off there is no section at all —
+            // the opt-in card immediately above already explains why.
             if (teaser != ChargeTeaserState.CaptureOff) {
                 item { SectionHeader(stringResource(teaser.sectionTitle())) }
                 item {
@@ -257,14 +256,14 @@ private val previewCharging = BatteryReadout(
 @AmplyPreview
 @Composable
 private fun BatteryHubScreenLivePreview() = PreviewWrapper {
+    // Recording on: no opt-in card, so the live charge is the first thing on the screen.
     BatteryHubScreen(
         readout = previewCharging,
         captureEnabled = true,
-        lastCaptureWallMillis = 0L,
         teaser = ChargeTeaserState.Live(previewLiveSession),
         onBack = {},
         onOpenHistory = {},
-        onCaptureEnabledChange = {},
+        onEnableCapture = {},
         onOpenSession = {},
     )
 }
@@ -278,28 +277,26 @@ private fun BatteryHubScreenLastPreview() = PreviewWrapper {
             plugged = 0,
         ),
         captureEnabled = true,
-        lastCaptureWallMillis = 0L,
         teaser = ChargeTeaserState.Last(previewLastSession),
         onBack = {},
         onOpenHistory = {},
-        onCaptureEnabledChange = {},
+        onEnableCapture = {},
         onOpenSession = {},
     )
 }
 
 @AmplyPreview
 @Composable
 private fun BatteryHubScreenCaptureOffPreview() = PreviewWrapper {
-    // Capture off: no charge section at all, but the full readout is still here — it never depended
-    // on the opt-in.
+    // Never opted in: the opt-in card leads, there is no charge section, and the full readout is still
+    // here — it never depended on recording.
     BatteryHubScreen(
         readout = previewCharging,
         captureEnabled = false,
-        lastCaptureWallMillis = null,
         teaser = ChargeTeaserState.CaptureOff,
         onBack = {},
         onOpenHistory = {},
-        onCaptureEnabledChange = {},
+        onEnableCapture = {},
         onOpenSession = {},
     )
 }
@@ -319,11 +316,10 @@ private fun BatteryHubScreenSparsePreview() = PreviewWrapper {
             voltageMillivolts = 3900,
         ),
         captureEnabled = true,
-        lastCaptureWallMillis = null,
         teaser = ChargeTeaserState.None,
         onBack = {},
         onOpenHistory = {},
-        onCaptureEnabledChange = {},
+        onEnableCapture = {},
         onOpenSession = {},
     )
 }
@@ -336,11 +332,10 @@ private fun BatteryHubScreenLargeFontPreview() = PreviewWrapper {
     BatteryHubScreen(
         readout = previewCharging.copy(technology = "Li-ion polymer (high voltage)"),
         captureEnabled = true,
-        lastCaptureWallMillis = 0L,
         teaser = ChargeTeaserState.Last(previewLastSession),
         onBack = {},
         onOpenHistory = {},
-        onCaptureEnabledChange = {},
+        onEnableCapture = {},
         onOpenSession = {},
     )
 }