DEV Community: ReClaim

A text-only app drawer in Jetpack Compose: an A–Z scrubber, a recent-installs section, and the index math between them

ReClaim — Sat, 07 Nov 2026 16:41:57 +0000

We're building ReClaim, a minimalist Android launcher that's on Google Play. The Home screen holds a handful of favorites. Everything else lives in one place: a text-only, alphabetical app drawer with a search field, a strip of folders, a "Recently Installed" section, and an A–Z scrubber down the right edge.

No icons is a product decision, not a shortcut. The drawer has to reach every installed app without making the distracting ones look appealing (we wrote about the thinking behind that in designing a minimal Android home screen). But once the icons are gone, the list has to be easy to move through, or people just stop using it. This post is about the small pieces that make a plain list fast: the scrubber, the section math, search, and the places where our code is still wrong.

Stack: Kotlin, Jetpack Compose, Hilt, Room, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts. Our first post on building the launcher covered how we get the app list from LauncherApps and keep it fresh with a callbackFlow. This one starts where that list arrives in the UI.

1. One sorted list feeds everything

The repository combines the raw LauncherApps list with the user's own data (custom names, hidden apps, favorites, folders, active blocks) and emits one sorted list:

val allApps: Flow<List<AppInfo>> = combine(
    baseApps,
    favoritesDao.observeAll(),
    folderDao.observeFolderApps(),
    blockDao.observeAll(),
) { apps, favs, folderApps, blocks ->
    // ... build favKeys, folderMap, blockMap
    apps.map { a ->
        a.copy(
            isFavorite = a.key in favKeys,
            folderId = folderMap[a.key]?.folderId,
            blockedUntil = blockMap[a.packageName],
        )
    }.sortedBy { it.label.lowercase() }
}.flowOn(Dispatchers.Default)

val visibleApps: Flow<List<AppInfo>> = allApps.map { list -> list.filterNot { it.isHidden } }

Two details matter for the drawer. First, label is already the user's custom name if they renamed the app, so sorting, search and the letter index all agree on the same string. Second, hidden apps are filtered out here, before the UI sees anything. The drawer never has to know an app exists if the user hid it.

The sort key is label.lowercase(). Kotlin's String.lowercase() uses "Unicode mapping rules of the invariant locale", so the result doesn't change with the device language. That's predictable, but it isn't how people sort names. More on that in the open items.

2. The letter index is just "first index per bucket"

The scrubber needs to know where each letter starts. Since the list is already sorted, that's one pass:

/** Maps each first letter present in [apps] (A–Z, or '#' for anything else) to its first index. */
private fun buildLetterPositions(apps: List<AppInfo>): Map<Char, Int> {
    val map = LinkedHashMap<Char, Int>()
    apps.forEachIndexed { index, app ->
        val first = app.label.trim().firstOrNull()?.uppercaseChar()
        val bucket = if (first != null && first in 'A'..'Z') first else '#'
        if (bucket !in map) map[bucket] = index
    }
    return map
}

Anything that doesn't start with A–Z goes into #: digits, symbols, accented letters, and non-Latin scripts. The map's keys double as the set of letters that actually have apps, which the scrubber uses to dim the empty ones.

In the screen, it's built from the filtered list, so it stays right while you search:

val filtered = remember(apps, query) {
    if (query.isBlank()) apps else apps.filter { it.label.contains(query.trim(), ignoreCase = true) }
}
val letterPositions = remember(filtered) { buildLetterPositions(filtered) }

3. The scrubber: one gesture loop, drag included

LazyColumn has no built-in fast-scroll index, so AlphabetIndexBar is a 28dp-wide Column of 27 letters with a pointerInput on top. Touch and drag are the same code path: wherever the finger is, map its Y position to a letter.

.onSizeChanged { containerHeightPx = it.height.toFloat() }
.pointerInput(availableLetters) {
    fun handle(y: Float) {
        if (containerHeightPx <= 0f) return
        val raw = (y / containerHeightPx * letters.size).toInt().coerceIn(0, letters.size - 1)
        activeIndex = raw
        nearestAvailableLetter(letters[raw], letters, availableLetters)?.let(onSelect)
    }
    awaitEachGesture {
        val down = awaitFirstDown()
        handle(down.position.y)
        do {
            val event = awaitPointerEvent()
            val change = event.changes.firstOrNull { it.id == down.id }
            if (change != null && change.pressed) {
                handle(change.position.y)
                change.consume()
            }
        } while (event.changes.any { it.pressed })
        activeIndex = null
    }
}

The Compose docs on understanding gestures recommend awaitEachGesture over a raw while (true) loop, because it "restarts the containing block when all pointers have been lifted." That's exactly the lifecycle we want: the bubble shows on down, follows the finger, and activeIndex = null hides it when the gesture ends.

We track the first pointer by id, so a second finger landing on the strip doesn't make the list jump around. And we consume the change, so the list underneath doesn't also try to scroll.

Two small choices make the strip feel solid:

Empty letters still work. If you touch "Q" and you have no Q apps, the strip doesn't go dead. It jumps to the nearest letter that does have apps, checking one step forward, then one step back, then widening:

private fun nearestAvailableLetter(letter: Char, all: List<Char>, available: Set<Char>): Char? {
    if (available.isEmpty()) return null
    if (letter in available) return letter
    val index = all.indexOf(letter)
    var offset = 1
    while (index - offset >= 0 || index + offset < all.size) {
        if (index + offset < all.size && all[index + offset] in available) return all[index + offset]
        if (index - offset >= 0 && all[index - offset] in available) return all[index - offset]
        offset++
    }
    return null
}

The bubble still shows the letter you're touching, not the one you landed on. That keeps the bubble in step with your finger, while the list goes as close as it can.

Landscape doesn't overlap. A short window can't fit 27 lines of 11sp text. Instead of letting the letters run into each other, the font scales down to fit the slot:

val letterSize = if (containerHeightPx <= 0f) {
    11.sp
} else {
    val fitted = with(density) { (containerHeightPx / letters.size * 0.72f).toSp() }
    if (fitted < 11.sp) fitted else 11.sp
}

The jump itself is a plain scrollToItem. The Compose lists guide describes it as a function that "immediately" snaps the scroll position, versus animateScrollToItem for a smooth scroll. While dragging across 27 letters, snapping is what you want. An animation would still be running toward "C" when your finger is already on "M".

4. The section above the list breaks the math

Then we added "Recently Installed": apps installed in the last 14 days, newest first, shown above the alphabetical list. It ages out on its own, so there's nothing to dismiss.

val recentlyInstalled = remember(apps, query) {
    if (query.isNotBlank()) {
        emptyList()
    } else {
        val cutoff = System.currentTimeMillis() - RECENTLY_INSTALLED_WINDOW_MILLIS
        apps.filter { it.firstInstallTime >= cutoff }.sortedByDescending { it.firstInstallTime }
    }
}

It hides while you search, because a name match is what you asked for, not recency.

The catch: the letter positions are indices into filtered, but the LazyColumn now has a header and N recent rows above the first alphabetical row. Tap "M" and you'd land N+1 rows early. The fix is an offset applied at the jump:

val letterIndexOffset = if (recentlyInstalled.isEmpty()) 0 else recentlyInstalled.size + 1

AlphabetIndexBar(
    availableLetters = letterPositions.keys,
    onSelect = { letter ->
        letterPositions[letter]?.let { index ->
            coroutineScope.launch { listState.scrollToItem(index + letterIndexOffset) }
        }
    },
    // ...
)

A recently installed app now appears twice: once in the recent section and once in its alphabetical spot. LazyColumn item keys must be unique, so the recent copy gets a prefix:

items(recentlyInstalled, key = { "recent:${it.key}" }) { app -> AppRow(/* ... */) }
items(filtered, key = { it.key }) { app -> AppRow(/* ... */) }

Without stable keys, the guide notes, "each item's state is keyed against the position of the item in the list," which goes wrong as soon as the list changes. In a launcher it changes all the time: installs, uninstalls, renames, hides.

firstInstallTime comes from LauncherActivityInfo, with a fallback to PackageManager.getPackageInfo() on older devices. More on that fallback below.

5. Search: two entry points, one rule

There are two search boxes. One sits at the top of the drawer and filters the list in place. The other is a full-screen overlay you open by swiping up on Home, with the keyboard already up. Both use the same rule, a case-insensitive contains on the label:

val searchResults: StateFlow<List<AppInfo>> =
    combine(appRepository.visibleApps, _query) { apps, q ->
        if (q.isBlank()) emptyList()
        else apps.filter { it.label.contains(q.trim(), ignoreCase = true) }.take(60)
    } // ...

Both wire the keyboard's Search action to "launch the first result," so typing "map" and hitting enter opens Maps:

keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
keyboardActions = KeyboardActions(onSearch = { filtered.firstOrNull()?.let(onLaunch) }),

And both search visibleApps, so hidden apps don't come back through search. If hiding an app were undone by typing its name, it wouldn't be much of a hide. (Opening a hidden app on purpose goes through its own challenge flow, which we covered in an earlier post on unlock challenges.)

When a query is active, the folder row and the recent section disappear, so the results are just names.

6. Folders that reorder by long-press

Folders sit in a horizontal row above the list. Reordering uses the Reorderable library on a LazyRow. We keep a local copy of the list so the drag feels instant, and only write the new order to Room when the drag stops:

var items by remember { mutableStateOf(folders) }
LaunchedEffect(folders) { items = folders }

val reorderState = rememberReorderableLazyListState(listState) { from, to ->
    items = items.toMutableList().apply { add(to.index, removeAt(from.index)) }
}
// on each chip:
.longPressDraggableHandle(onDragStopped = { onReorderFolders(items) })

The LaunchedEffect(folders) resyncs the local copy when the database emits, for example after a folder is created or deleted somewhere else.

What's still open

Writing this up meant rereading the code against the docs. Four things we found:

Sorting isn't locale-aware. sortedBy { it.label.lowercase() } compares by code point. An accented name like "Élan" sorts after every plain "z". Meanwhile the scrubber puts it in #, which is the last slot on the strip. Java's Collator exists for exactly this: it "performs locale-sensitive String comparison" for "searching and sorting routines for natural language text." Digits have the opposite problem: they sort to the top of the list, so the # at the bottom of the strip jumps you to the top. Switching the sort to Collator.getInstance() is the fix. The bucketing would then need to fold accents too, or "É" would sit among the E apps in the list but still jump from #.
The scrubber can hold a stale callback. pointerInput(availableLetters) only restarts when the set of letters changes. The onSelect lambda it captured knows the old letter positions and the old recent-section offset. Install an app under a letter you already have, and the set is the same, but every position after it moved by one. The usual fix is rememberUpdatedState(onSelect) inside the bar, so the running gesture loop always calls the latest lambda.
The pre-31 fallback isn't needed. Our comment says LauncherActivityInfo.getFirstInstallTime() is API 31+, so older devices fall back to an extra getPackageInfo() binder call per app. The reference page says it was "Added in API level 21," well below our minSdk 26. The branch is harmless but pointless, and it costs one binder call per app on every list refresh on Android 8–11 devices.
"Recently Installed" only ages out on a change. The cutoff is computed inside remember(apps, query), so an app that passes the 14-day mark stays in the section until the app list or the query changes. In practice the list emits often (any install, rename or block), so this is cosmetic.

None of these break the drawer, but the first two are the kind of bug a user notices without being able to describe it ("the letters are a bit off sometimes").

What we'd tell another team

Build every derived thing (sections, letter index, search results) from one sorted, already-filtered list, and use the same label string everywhere.
Treat a fast-scroll strip as one gesture loop: touch and drag share a handler, track a single pointer, consume the event.
Never let a strip letter go dead. Jump to the nearest section instead.
The moment you put anything above an indexed list, apply an offset at the jump, and give duplicated rows their own keys.
Read your own comments against the API reference now and then. Ours said 31; the docs said 21.

If you want to see how the drawer feels, ReClaim is free on Google Play. For the "why" behind a text-only drawer, see how to stop opening apps on autopilot.

This post was drafted with AI assistance and reviewed by the ReClaim team.

Five Android permissions, five different checks: building a setup gate that re-checks on resume

ReClaim — Thu, 05 Nov 2026 16:16:11 +0000

We're building ReClaim, a minimalist Android launcher that's on Google Play. To do its job it needs five things from the user: to be the default Home app, to post notifications, Usage access, an accessibility service for system-wide blocking, and an exemption from battery optimization.

That sounds like one "permissions" problem. It isn't. Each of the five is granted in a different place, and each is checked through a different API. Only one of them is a normal runtime permission. This post walks through the screen that asks for all five: how it checks each one, why it re-checks every time the app comes back to the front, and why it never traps you.

Stack: Kotlin, Jetpack Compose, Hilt, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts. Our first post on building the launcher touched on the Home role and Usage access in passing. This one is about the whole gate.

One snapshot, five booleans

Everything the gate knows fits in one data class:

data class SetupStatus(
    val isDefaultLauncher: Boolean = false,
    val homeRoleStale: Boolean = false,
    val notificationsGranted: Boolean = true,
    val usageAccessGranted: Boolean = false,
    val accessibilityEnabled: Boolean = false,
    val batteryOptimizationExempt: Boolean = false,
) {
    val allGranted: Boolean
        get() = (isDefaultLauncher || homeRoleStale) && notificationsGranted && usageAccessGranted &&
            accessibilityEnabled && batteryOptimizationExempt
}

Two defaults are worth a look. notificationsGranted starts as true because the notification permission doesn't exist before Android 13, so on older phones there's nothing to ask for. And homeRoleStale counts as "good enough" for the launcher check. More on that below.

The snapshot is a plain value. It's rebuilt from scratch on every check, not patched field by field. That keeps the screen honest: what it shows is what Android said a moment ago, not what we remember asking for.

Five checks, five APIs

Here's the function that fills the snapshot:

fun refresh(context: Context) {
    val notificationsGranted = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
    } else {
        true
    }
    val powerManager = context.getSystemService(Context.POWER_SERVICE) as PowerManager
    val isDefaultLauncher = LauncherRoleUtil.isDefaultLauncher(context)
    val homeRoleStale = !isDefaultLauncher && LauncherRoleUtil.holdsHomeRole(context)
    // ...
    _status.value = SetupStatus(
        isDefaultLauncher = isDefaultLauncher,
        homeRoleStale = homeRoleStale,
        notificationsGranted = notificationsGranted,
        usageAccessGranted = usageStatsSource.hasPermission(),
        accessibilityEnabled = AccessibilityUtil.isBlockServiceEnabled(context),
        batteryOptimizationExempt = powerManager.isIgnoringBatteryOptimizations(context.packageName),
    )
    _hasChecked.value = true
}

Five lines, five different subsystems. Let's go through them.

1. Notifications: the only real runtime permission

POST_NOTIFICATIONS is a runtime permission on Android 13 and higher. The check is the standard ContextCompat.checkSelfPermission(), and the request uses the AndroidX RequestPermission contract, which is what the runtime permissions guide recommends:

val requestNotifications = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { viewModel.refresh(context) }

The callback ignores the boolean it's handed and calls refresh() instead. The gate only ever reads its state from the system, so there's one source of truth.

There's a catch the same guide spells out: if the user taps Deny more than once, the system treats that as "don't ask again" and stops showing the dialog. After that, our "Enable" button calls launch(), the callback fires right away, and nothing visible happens. The gate doesn't handle that case yet. It's on the list below.

2. Usage access: an app op, not a permission

PACKAGE_USAGE_STATS is declared in the manifest, but declaring it does nothing on its own. The UsageStatsManager reference says the user "still needs to grant permission through the Settings application", via Settings.ACTION_USAGE_ACCESS_SETTINGS. You can't check it with checkSelfPermission(). You ask AppOpsManager:

fun hasPermission(): Boolean {
    val mode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        appOps.unsafeCheckOpNoThrow(
            AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), context.packageName,
        )
    } else {
        @Suppress("DEPRECATION")
        appOps.checkOpNoThrow(
            AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), context.packageName,
        )
    }
    return mode == AppOpsManager.MODE_ALLOWED
}

Two details from the AppOpsManager reference are worth knowing. First, unsafeCheckOpNoThrow is now marked deprecated in API level 36, and the reference points back to checkOpNoThrow. We target 36, so this branch has a deprecation warning waiting for it. Second, there's a mode besides allowed and ignored: MODE_DEFAULT, which means "use the default security check". The reference says callers "must explicitly check for it and deal with it". We treat anything that isn't MODE_ALLOWED as not granted. That's the cautious reading, but it means a device that reports MODE_DEFAULT with the permission actually granted would keep showing the row.

3. System-wide blocking: a string in secure settings

Accessibility services are switched on in Accessibility settings, never through a dialog in your app. To see whether ours is on, we read the list of enabled services from secure settings and look for our component:

fun isBlockServiceEnabled(context: Context): Boolean {
    val expected = ComponentName(context, BlockAccessibilityService::class.java).flattenToString()
    val enabled = Settings.Secure.getString(
        context.contentResolver,
        Settings.Secure.ENABLED_ACCESSIBILITY_SERVICES,
    ) ?: return false
    val splitter = TextUtils.SimpleStringSplitter(':')
    splitter.setString(enabled)
    for (component in splitter) {
        if (component.equals(expected, ignoreCase = true)) return true
    }
    return false
}

ENABLED_ACCESSIBILITY_SERVICES is documented only as the "List of the enabled accessibility providers". In practice it's a colon-separated list of flattened component names, which is why we split on :. It answers "did the user switch it on?" It doesn't tell you whether the service is bound and running right now. For a setup row, the first question is the right one.

This row also never jumps straight to Settings. The button opens our own disclosure dialog first. Google Play's AccessibilityService policy names launchers among the apps that aren't accessibility tools. Apps like that need a prominent disclosure inside the app that describes the data accessed, explains how it's used, and requires an affirmative user action. So the dialog states plainly that ReClaim isn't an accessibility tool and what the service reads, and only "Continue to Settings" opens ACTION_ACCESSIBILITY_SETTINGS. All three places in the app that can send you to that screen go through the same dialog, so there's no path that skips it.

4. Battery: an allowlist, and a policy question

PowerManager.isIgnoringBatteryOptimizations() tells you whether your package is on the device's power allowlist. Asking to be added is where you need to read the docs carefully:

fun batteryOptimizationIntent(context: Context): Intent =
    Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS, Uri.parse("package:${context.packageName}"))

That action shows a one-tap system "Allow" dialog, and it needs the REQUEST_IGNORE_BATTERY_OPTIMIZATIONS permission in the manifest. The Settings reference is blunt about it: "most applications should not use this". The Doze and App Standby guide says most apps should send users to ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS instead. It also notes that Google Play policies prohibit asking for the direct exemption "unless the core function of the app is adversely affected", and it has a table of acceptable use cases.

Our reasoning is in the code comment: blocking depends on a background process, and Doze or App Standby restricting it can stop blocking without any visible error. If you're copying this pattern, read that table first. The settings-list intent is the safe default.

5. Default launcher: the role and the real answer

The Home row is the one we covered in the earlier post, so briefly: RoleManager can tell you whether you hold ROLE_HOME, but we answer "is ReClaim the launcher?" by resolving the actual Home intent. The two can disagree. Android can drop its saved Home choice while the role still says we hold it, and then the system's "Select a Home app" chooser keeps coming back.

What's new since that post is how the gate reacts. When the role is held but Home doesn't resolve to us, the row's button changes from "Enable" to "Fix" and the description explains what's going on. The role request intent is only built when there's a dialog to show:

onClick = {
    val roleIntent = LauncherRoleUtil.requestRoleIntent(context)
    when {
        roleIntent != null -> requestHomeRole.launch(roleIntent)
        status.homeRoleStale -> showHomeRoleRepair = true
        // No role flow at all (API < 29): the plain picker is the whole story.
        else -> context.startActivity(LauncherRoleUtil.homeSettingsIntent())
    }
},

requestRoleIntent() returns null once we hold the role, because the system would finish the request without drawing anything. In the stale case we show a short dialog instead. It tells you to open Home settings and tap ReClaim even though it already looks selected, which re-applies the choice.

The same mismatch shaped one more helper. When ReClaim sends you home on purpose, for example when you leave a reminder, it scopes the Home intent to its own package while it holds the role:

fun homeIntent(context: Context): Intent {
    val intent = Intent(Intent.ACTION_MAIN)
        .addCategory(Intent.CATEGORY_HOME)
        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    if (!holdsHomeRole(context)) return intent
    // ... logs a warning if Home currently resolves somewhere else
    intent.setPackage(context.packageName)
    return intent
}

With only one possible match, the chooser can't appear. If we don't hold the role, the intent stays unscoped, so you land in whatever Home app you actually picked. That's also why allGranted accepts homeRoleStale: the launcher works, and the "Fix" row is there to explain the leftover prompts, not to block you.

Re-check on resume, not on result

Four of the five rows send you out of the app: to Accessibility settings, Usage access, Home settings, or a system dialog. Some of those return a result and some don't. startActivity() into Settings gives you nothing back. So the gate doesn't rely on results. It re-checks every time the activity resumes:

val setupViewModel: SetupViewModel = hiltViewModel()
val showSetupGate by setupViewModel.showGate.collectAsStateWithLifecycle()
LaunchedEffect(Unit) { setupViewModel.refresh(context) }
DisposableEffect(lifecycleOwner) {
    val observer = LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_RESUME) setupViewModel.refresh(context)
    }
    lifecycleOwner.lifecycle.addObserver(observer)
    onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
}

The activity lifecycle guide is the reason this works. When the user comes back from another activity, the system calls onResume again, and lifecycle-aware components get ON_RESUME. Flip the switch in Settings, press Back, and the row turns into a check mark without you touching anything. All five checks are cheap local lookups, so running them on every resume costs very little.

A gate you can always walk past

Here's what decides whether the gate shows at all:

val showGate: StateFlow<Boolean> = combine(_status, _dismissed, _hasChecked) { status, dismissed, checked ->
    checked && !status.allGranted && !dismissed
}.stateIn(viewModelScope, SharingStarted.Eagerly, false)

Three small choices are packed into that line.

checked first. Before the first refresh(), the snapshot is all defaults, which mostly read "not granted". Without _hasChecked, a fully set-up phone would flash the gate for a frame on every cold start.
Dismissal lasts for the session. The gate's main button is "Continue anyway", and it's always there. Tapping it sets _dismissed, which lives in the ViewModel. It isn't saved anywhere, so the gate comes back on the next cold start if anything is still missing. The runtime permissions guide says not to block the user and to let them cancel any educational flow, and that matches how we want a launcher to behave anyway. It has to work fully even if you skip every row.
An overlay, not a destination. The gate is drawn on top of the nav host rather than being a route in it. You can't land on it with a back press or navigate around it. It shows first, then the first-run tutorial, then the launcher.

What's still open

Writing this up turned up a few gaps, and we'd rather list them than pretend the gate is finished:

After two denials, the notifications row is a dead button. It should send you to the app's notification settings instead of calling launch() again.
The Settings reference warns that some settings actions may have no matching activity on some devices. Our startActivity() calls into Settings from the gate aren't wrapped yet.
Two settings screens show whether system-wide blocking is on, but they don't re-check on resume the way the gate does. One of them can show a stale value after you come back from Settings.
MODE_DEFAULT from AppOps is treated as "not granted", and unsafeCheckOpNoThrow needs replacing now that it's deprecated.

What we'd tell another team

List every special access your app needs and write down which API checks each one. "Permissions" is at least four different systems on Android.
Rebuild the whole status on ON_RESUME. Don't trust activity results for things granted in Settings.
Read state only from the system, even in the callback that just told you the answer.
Gate on "have we checked yet" so a set-up phone never flashes the gate.
Always offer a way past it. Bring it back next launch, not every screen.
For the accessibility service, write the disclosure before the service. For the battery exemption, read the acceptable-use table before you add the direct dialog.

If you'd like the user-side version of the Home step, our guide on how to change the default launcher on Android walks through it screen by screen. ReClaim is on Google Play if you want to see the gate on your own phone.

This post was drafted with AI assistance and reviewed by the ReClaim team.

The edge cases after shipping: re-arming Android alarms after a reboot and counting app usage across midnight

ReClaim — Tue, 03 Nov 2026 16:17:10 +0000

We're building ReClaim, a minimalist Android launcher that's on Google Play. Two earlier posts covered features that measure time: app reminder timers that race AlarmManager against a coroutine, and daily app limits that replay UsageEvents instead of trusting the daily buckets.

Both features worked in the happy path. Both also had a gap that only shows up at a boundary:

A reboot. You set a 15-minute reminder for an app, the phone restarts, and the timer is just gone. No alarm, no countdown notification.
Midnight. You open an app at 11:40 PM and close it at 12:20 AM. Those 20 minutes after midnight never counted toward the new day.

Both fixes went into a single commit. This post walks through it: a small "pending" flag, a boot receiver, and a pure function with seven JVM unit tests. Stack: Kotlin, Hilt, DataStore, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

Edge case 1: a reboot wipes the timer

Here's how a reminder gets scheduled. It's unchanged from the earlier post:

suspend fun schedule(packageName: String, appLabel: String, minutes: Int) {
    if (minutes <= 0) return
    val triggerAt = System.currentTimeMillis() + minutes * 60_000L
    val pendingIntent = alarmPendingIntent(packageName, appLabel, minutes)
    alarmManager.setAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, triggerAt, pendingIntent)
    sessionStore.startSession(packageName, triggerAt, minutes, appLabel)
    ReminderTimerNotification.show(context, packageName, appLabel, triggerAt)
}

There are three pieces of state here. The alarm lives in the system. The end time lives in DataStore, in our app's files. The countdown notification lives in the notification shade. Only one of them survives a restart. The AlarmManager reference says registered alarms "will be cleared if it is turned off and rebooted," and the countdown notification doesn't survive a restart either.

So after a reboot, the DataStore still said "this session ends at 10:42," but nothing was waiting for 10:42. The accessibility service would re-arm its own in-process countdown the next time you switched into that app, because it reads the stored end time on every switch. If you didn't open the app again, nothing happened. Even if you did, the "time remaining" notification was gone until a new session started.

Why a wall-clock end time helps here

One earlier decision made this fix easy. The stored end time is System.currentTimeMillis() plus the duration, and the alarm is RTC_WAKEUP. The SystemClock docs describe elapsedRealtime() as "milliseconds since boot," so it restarts from zero on every boot. An end time stored on that clock would mean nothing after a restart. A wall-clock end time still points at the same moment, so after a reboot we can schedule the alarm again with the stored number as-is.

Step 1: know which sessions still owe an expiry

The obvious way to find "sessions to re-arm" is "every session whose end time is still in the future." That misses one case: a session that ran out while the phone was off. Its end time is in the past, but nobody has handled its "time's up" yet. Re-arming only future sessions would drop it.

So each session gets a pending flag. Starting a session sets it:

private fun pendingKey(packageName: String) = booleanPreferencesKey("$packageName:pending")

suspend fun startSession(packageName: String, untilMillis: Long, minutes: Int, label: String) {
    store.edit {
        it[key(packageName)] = untilMillis
        it[minutesKey(packageName)] = minutes
        it[labelKey(packageName)] = label
        it[pendingKey(packageName)] = true
    }
}

The expiry path clears it. fireExpiry is the one function both the alarm receiver and the in-process countdown call when time is up. It now marks the session handled first:

appScope.launch {
    sessionStore.markExpiryHandled(packageName)
    // ... then decide whether to post the "time's up" notification
}

Clearing the flag has one subtle rule:

suspend fun markExpiryHandled(packageName: String) {
    store.edit {
        // Only clear a session that has actually run out: if time was added (a fresh
        // startSession) before this ran, that newer session must stay pending.
        val until = it[key(packageName)] ?: 0L
        if (until <= System.currentTimeMillis() + EXPIRY_TOLERANCE_MILLIS) it.remove(pendingKey(packageName))
    }
}

The comment explains the race. When time runs out, the user can add more time, and that calls startSession again. If the clear ran blindly after that, it would wipe the pending flag of a session that just started. So the clear only happens when the stored end time has actually passed. The 5-second tolerance (EXPIRY_TOLERANCE_MILLIS = 5_000L) exists because, as the code puts it, "the in-process countdown can fire a hair before the stored end time." Doing the check and the remove inside one edit block keeps them together as one read-modify-write.

Reading the pending set back is a scan over the preference keys:

suspend fun pendingSessions(): List<PendingSession> {
    val prefs = store.data.catch { e -> if (e is IOException) emit(emptyPreferences()) else throw e }.first()
    return prefs.asMap().keys
        .map { it.name }
        .filter { it.endsWith(":pending") }
        .mapNotNull { name ->
            val pkg = name.removeSuffix(":pending")
            if (prefs[pendingKey(pkg)] != true) return@mapNotNull null
            val until = prefs[key(pkg)] ?: return@mapNotNull null
            PendingSession(pkg, until, prefs[minutesKey(pkg)] ?: 0, prefs[labelKey(pkg)] ?: "your app")
        }
}

Website reminders use the same store with site:-prefixed keys, so they come back through this function too.

Step 2: a receiver for boot and app updates

The manifest gets a permission and a receiver:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<receiver
    android:name=".notifications.BootReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
        <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
    </intent-filter>
</receiver>

A few things we checked in the docs before relying on this:

exported="false" still gets the boot broadcast. The <receiver> reference says a non-exported receiver still receives messages "sent by the system, components of the same application, or applications with the same user ID."
Manifest registration is allowed. Since Android 8.0, apps mostly can't declare manifest receivers for implicit broadcasts, but ACTION_BOOT_COMPLETED is on the implicit broadcast exceptions list. ACTION_MY_PACKAGE_REPLACED is sent only to the app that was replaced, so it isn't affected by that limit.
Storage is unlocked by then. The Intent reference says that when ACTION_BOOT_COMPLETED arrives, "the user is unlocked and both device-protected and credential-protected storage can accessed safely." Our DataStore file sits in normal app storage, which the Direct Boot guide calls credential encrypted storage, "the default storage location." We don't need LOCKED_BOOT_COMPLETED or a direct-boot-aware receiver. Re-arming after the first unlock is fine for a screen-time reminder.
It also covers force-stop on newer Android. The same reference notes that from Android 15 (VANILLA_ICE_CREAM), this broadcast is also delivered "when it is removed from the Stopped state," for example on the first launch after a force-stop. One receiver handles that case too.

The scheduling alarms guide adds one more caveat: receiving the boot broadcast "only works if the app has already been launched by the user at least once." For a launcher that already has a running timer, that's always true.

MY_PACKAGE_REPLACED is cheap insurance for updates. Re-arming is idempotent: the alarm's PendingIntent uses the same request code and FLAG_UPDATE_CURRENT, and the set docs say an existing alarm for the same intent "will be removed and replaced by this one." Running it when nothing was lost costs one extra system call per pending session.

The receiver itself is small:

@AndroidEntryPoint
class BootReceiver : BroadcastReceiver() {

    @Inject lateinit var reminderScheduler: ReminderScheduler
    @Inject @ApplicationScope lateinit var appScope: CoroutineScope

    override fun onReceive(context: Context, intent: Intent) {
        when (intent.action) {
            Intent.ACTION_BOOT_COMPLETED, Intent.ACTION_MY_PACKAGE_REPLACED -> Unit
            else -> return
        }
        val pending = goAsync()
        appScope.launch {
            try {
                reminderScheduler.rearmPending()
            } finally {
                pending.finish()
            }
        }
    }
}

The action check follows the BroadcastReceiver.onReceive guidance to "respond only to known actions, ignoring any unexpected Intents." Reading DataStore is a suspend call, so we use goAsync() to move the work off the main thread. The goAsync docs are clear that this doesn't buy unlimited time. The usual limit (around 10 seconds) still applies, counted until finish(). Reading a few preference keys and setting a few alarms fits easily, and the finally makes sure finish() runs even if something throws.

Step 3: re-arm or expire

suspend fun rearmPending() {
    val now = System.currentTimeMillis()
    for (s in sessionStore.pendingSessions()) {
        if (s.untilMillis <= now) {
            fireExpiry(s.packageName, s.label, s.minutes)
        } else {
            alarmManager.setAndAllowWhileIdle(
                AlarmManager.RTC_WAKEUP,
                s.untilMillis,
                alarmPendingIntent(s.packageName, s.label, s.minutes),
            )
            ReminderTimerNotification.show(context, s.packageName, s.label, s.untilMillis)
        }
    }
}

There are two branches and no new logic. A session that's still running gets its alarm and its countdown notification back, pointed at the same end time. A session that ran out while the phone was off goes through fireExpiry, the same function the alarm would have called. That means the per-app "what happens when time's up" setting still applies, and the pending flag gets cleared the usual way. We didn't write a separate "expired during reboot" path, so there's nothing extra to keep in sync.

Edge case 2: a session that crosses midnight

App limits replay MOVE_TO_FOREGROUND and MOVE_TO_BACKGROUND events from UsageStatsManager.queryEvents. Before the fix, the replay queried exactly the window it was measuring:

// before
val events = runCatching { usageStatsManager.queryEvents(start, end) }.getOrNull() ?: return 0L
// ...
UsageEvents.Event.MOVE_TO_FOREGROUND -> {
    if (activeCount == 0) segmentStart = event.timeStamp.coerceIn(start, end)
    activeCount++
}
UsageEvents.Event.MOVE_TO_BACKGROUND -> {
    if (activeCount > 0) {
        // ... close the segment
    }
}

Run that for "today" with the 11:40 PM to 12:20 AM session. The window starts at midnight, so the 11:40 PM foreground event is outside the query. The first event the loop sees for that app is the 12:20 AM MOVE_TO_BACKGROUND, while activeCount is 0. The if (activeCount > 0) guard skips it, and 20 minutes of today's usage disappear. The guard itself is correct, because a stray background event shouldn't count. The query just never showed us the start of the session.

The fix: read earlier, count only inside the window

Two changes. First, query from 12 hours before the window starts:

val queryStart = (start - LOOKBACK_MILLIS).coerceAtLeast(0L)
val events = runCatching { usageStatsManager.queryEvents(queryStart, end) }.getOrNull() ?: return 0L
// ... collect this package's MOVE_TO_FOREGROUND / MOVE_TO_BACKGROUND as ForegroundTransition
return foregroundMillisWithin(transitions, start, end)

companion object {
    /** How far before a window's start to read events, to catch a session already open then. */
    const val LOOKBACK_MILLIS = 12L * 60 * 60 * 1000
}

Second, move the replay into a pure function that clips each session to the window. Clipping is now an overlap calculation instead of coerceIn on each timestamp:

data class ForegroundTransition(val timeStamp: Long, val toForeground: Boolean)

fun foregroundMillisWithin(transitions: Iterable<ForegroundTransition>, start: Long, end: Long): Long {
    if (end <= start) return 0L
    var activeCount = 0
    var segmentStart = -1L
    var total = 0L
    for (t in transitions) {
        if (t.toForeground) {
            if (activeCount == 0) segmentStart = t.timeStamp
            activeCount++
        } else if (activeCount > 0) {
            activeCount--
            if (activeCount == 0 && segmentStart >= 0) {
                total += overlap(segmentStart, t.timeStamp, start, end)
                segmentStart = -1L
            }
        }
    }
    if (activeCount > 0 && segmentStart >= 0) {
        total += overlap(segmentStart, end, start, end)
    }
    return total
}

private fun overlap(segStart: Long, segEnd: Long, start: Long, end: Long): Long =
    (minOf(segEnd, end) - maxOf(segStart, start)).coerceAtLeast(0L)

The per-package activeCount stays. It handles an app moving between its own activities, which produces two foreground events before one background event. What changed is that a session can now start before start and still be counted correctly, and sessions that ended before start add zero.

The same function serves every window: today since midnight, this week since Monday, the 7-day rolling average, and the per-day bars on the reminder screen. Yesterday's bar now gets the 11:40 PM to midnight part of that session, and today's gets the part after midnight. Neither one double counts.

Why pull it out of the Android code

foregroundMillisWithin has no Android types in it, so it runs as a plain JVM unit test. This commit added JUnit to the project for that reason, with seven tests for the boundary cases:

@Test fun sessionSpanningMidnight_countsOnlyTimeAfterMidnight() {
    val events = listOf(fg(midnight - 30 * min), bg(midnight + 20 * min))
    assertEquals(20 * min, foregroundMillisWithin(events, midnight, midnight + 60 * min))
}

@Test fun yesterdayWindow_countsOnlyPartBeforeMidnight() {
    val events = listOf(fg(midnight - 30 * min), bg(midnight + 20 * min))
    assertEquals(30 * min, foregroundMillisWithin(events, midnight - 24 * 60 * min, midnight))
}

@Test fun strayBackgroundWithoutForeground_ignored() {
    val events = listOf(bg(midnight + 5 * min), fg(midnight + 10 * min), bg(midnight + 15 * min))
    assertEquals(5 * min, foregroundMillisWithin(events, midnight, midnight + 60 * min))
}

The other four cover a session still open at "now," a session that ended before midnight (zero), nested activities of the same package (counted once), and an empty window. Testing a midnight bug on a device means waiting for midnight or changing the clock. Here it's a list of timestamps.

The trade-offs of a fixed lookback

12 hours is a bound, not a guarantee. A session that started more than 12 hours before the window still has the old problem. It's a trade-off: long enough to catch an evening session that runs past midnight, short enough to keep the extra events small.
Retention. The queryEvents reference says events "are only kept by the system for a few days." Twelve extra hours shouldn't run into that limit for today's window.
Cost. Every check now replays 12 extra hours of events. Each query returns events for every app, and we filter by package in Kotlin, so the extra work grows with how much you used your phone the evening before.

What's still open

The live check for an app that's open right now adds the in-progress session's length, which is tracked in memory, on top of the replayed history. That in-memory length isn't clipped at midnight yet. So for an app you've had open since before midnight, the live number can include some of last night's minutes until the session ends and the replay takes over. It's a known gap, and we'd rather say so than claim the fix covers everything.

What we'd tell another team

Write down which pieces of your state survive a reboot. For us: DataStore did, the alarm and the notification didn't.
Store end times on the wall clock when they have to survive a restart. elapsedRealtime() restarts at boot.
Track "expiry handled" separately from "end time passed." A session that ran out while the phone was off still needs its expiry handled.
Send the "expired during reboot" case through the same function as a normal expiry.
Query a little before the window and clip with an overlap function. Don't clamp event timestamps one by one.
Pull the counting logic into a pure function, so midnight is just a number in a unit test.

ReClaim is on Google Play if you want to try reminders and app limits on your own phone.

This post was drafted with AI assistance and reviewed by the ReClaim team.

Take the break at the commit: what rest-break studies found, plus a tiny git hook

ReClaim — Sat, 31 Oct 2026 15:17:55 +0000

If you write code for a living, you've heard "take regular breaks" a hundred times. It's easy to agree with and easy to ignore, mostly because the reminder tends to show up at the worst moment: halfway through a stack trace, with six things held in your head.

I wanted answers to two questions. What does the research actually say about short breaks from computer work, and how strong is that evidence? And can a reminder arrive at a moment when stopping costs almost nothing? This post covers both. It ends with a small shell script and git hook that nudges you after a commit once you've gone too long without a break.

What the studies found

NIOSH's data-entry field studies

The most practical work I found comes from NIOSH, the US National Institute for Occupational Safety and Health, which ran NIOSH-IRS field studies with data-entry workers.

In the first study (Galinsky et al., 2000, Ergonomics), workers alternated between two break schedules in 4-week blocks. The conventional schedule had two 15-minute breaks per shift. The supplementary schedule kept those and added a 5-minute break in each hour that didn't already have one, for 20 extra minutes of break time a day. With data from 42 workers, discomfort in several areas of the body, and eyestrain, were significantly lower on the supplementary schedule. On the conventional schedule, discomfort in the right forearm, wrist and hand rose over the work week. On the supplementary schedule, that rise was eliminated. In the authors' words, these benefits came "without reductions in data-entry performance."

A follow-up study (Galinsky et al., 2007, American Journal of Industrial Medicine) used the same two schedules with 51 workers. Discomfort and eyestrain were again significantly lower with supplementary breaks. Data-entry speed was significantly faster with the extra breaks, so work output was maintained even though 20 minutes of work time had been replaced with break time.

That study also tested stretching. Half the workers were randomly assigned to do brief stretches during breaks. They reported stretching during only 25% of conventional breaks and 39% of supplementary breaks, and no significant effect of stretching on discomfort or performance was observed. The authors say low compliance prevented a valid assessment of stretching. So the honest reading is "unknown", not "stretching doesn't work". The break itself was the part with a measurable effect.

Shorter breaks, and whether people take them

Henning et al. (1997, Ergonomics) went shorter. Computer operators at two work sites (73 people and 19 people) were prompted to take three 30-second breaks and one 3-minute break every hour, on top of their normal breaks. Two findings stood out to me:

Operators complied with about half of the added breaks, and they favoured the 3-minute breaks over the 30-second ones.
At the larger site, there was no improvement in productivity or well-being. At the smaller site, productivity and eye, leg and foot comfort all improved when the short breaks included stretching exercises.

The authors conclude that frequent short breaks can benefit productivity and well-being "when the breaks integrate with task demands." That phrase shaped the tool below.

The meta-analysis

Albulescu et al. (2022, PLOS ONE) pooled 22 study samples from 19 records (2,335 participants) on micro-breaks, which they define as breaks of 10 minutes or less. Micro-breaks gave small but significant boosts to vigor (d = .36) and reductions in fatigue (d = .35). The overall effect on performance (d = .16) was not statistically significant.

Breaking performance down by task, the effect was significant for creative tasks and for clerical tasks (the clerical result rests on only two studies). For cognitive tasks it was very small and non-significant, and that category is probably the closest match to most programming work. Longer breaks went with bigger performance gains, and the authors suggest that recovering from highly depleting tasks may need more than 10-minute breaks. They also note that no study found significantly decreased performance when a break was introduced.

Realistically, a short break probably won't make you code faster. It's more likely to leave you less tired, without costing output.

How strong is all this?

Not very, and that's worth saying plainly. A 2018 Cochrane review of ergonomic interventions for office workers (Hoe et al.) rated the evidence that supplementary breaks reduce neck, shoulder and forearm/wrist/hand discomfort as very low quality, based on two studies of data-entry workers. In the Albulescu review, most included studies had an unclear risk of bias. Data entry also isn't programming: OSHA notes that a proficient typist "can easily perform more than 18,000 keystrokes per hour," and most developers don't type nonstop.

Still, the cost is a few minutes an hour, the field studies didn't find a productivity penalty, and OSHA's computer workstation guidance says much the same thing in practical terms: "Every hour, take a five-minute break from computer tasks. Look away, stretch, get up, or walk."

What I took from it

Roughly hourly, a few minutes long. That's what the NIOSH studies tested and what OSHA recommends.
Compliance is the real problem. In both Henning and Galinsky 2007, people skipped much of what they were asked to do. A reminder you ignore does nothing.
Timing matters. Henning's point about integrating with task demands matches my experience. A break that interrupts a hard thought feels expensive. A break right after finishing something feels free.
Make the break a real change. OSHA suggests standing, stretching and moving around. For your eyes, the American Academy of Ophthalmology (AAO) notes that we normally blink about 15 times a minute but only 5 to 7 times a minute at a screen, and suggests looking up and away at a distant object. There's a separate write-up on the 20-20-20 rule if you want the eye side in more detail.

A commit is a natural pause. You've finished a unit of work, and whatever was in your head has just been written down. So that's where the reminder should go.

The tool: a post-commit nudge

Git runs a post-commit hook after a commit is made. The git docs say this hook "is meant primarily for notification, and cannot affect the outcome of git commit," so it can't block or break your commits.

The script keeps a single timestamp: when you last took a break. After each commit it checks how long it's been. If it's been 50 minutes or more, it prints a reminder and, where possible, shows a desktop notification. When you come back, git break resets the timer. It's plain POSIX sh with no dependencies.

Save this as ~/.local/bin/microbreak (or anywhere on your PATH):

#!/bin/sh
# microbreak: nudge me to take a short break at a natural stopping point.
# Usage: microbreak [check|done|status]
state="${XDG_STATE_HOME:-$HOME/.local/state}/microbreak"
limit="${MICROBREAK_MINUTES:-50}"
now=$(date +%s)
mkdir -p "$(dirname "$state")"
[ -s "$state" ] || echo "$now" > "$state"
last=$(cat "$state")
mins=$(( (now - last) / 60 ))

case "${1:-check}" in
  done)
    echo "$now" > "$state"
    echo "microbreak: timer reset" ;;
  status)
    echo "microbreak: ${mins} min since your last break" ;;
  check)
    [ "$mins" -ge "$limit" ] || exit 0
    msg="${mins} min since your last break. Stand up, look at something far away, move for a few minutes. Then run: git break"
    printf '\n  >> %s\n\n' "$msg" >&2
    if command -v notify-send >/dev/null 2>&1; then
      notify-send "Microbreak" "$msg"
    elif command -v osascript >/dev/null 2>&1; then
      osascript -e "display notification \"$msg\" with title \"Microbreak\""
    fi ;;
  *)
    echo "usage: microbreak [check|done|status]" >&2
    exit 2 ;;
esac
exit 0

Make it executable and add a git alias for resetting the timer:

chmod +x ~/.local/bin/microbreak
git config --global alias.break '!microbreak done'

A git alias that starts with ! is run as a shell command, so git break just calls microbreak done.

Hook it into one repo

printf '#!/bin/sh\nmicrobreak check\n' > .git/hooks/post-commit
chmod +x .git/hooks/post-commit

Git ignores hooks that don't have the executable bit set, so don't skip the chmod. If the repo already has a post-commit hook, add the microbreak check line to it instead of overwriting it.

Or hook it into every repo

mkdir -p ~/.config/git/hooks
printf '#!/bin/sh\nmicrobreak check\n' > ~/.config/git/hooks/post-commit
chmod +x ~/.config/git/hooks/post-commit
git config --global core.hooksPath ~/.config/git/hooks

Careful: core.hooksPath tells Git to look for hooks in that directory instead of .git/hooks, so any repo-local hooks (from a hook manager, say) will stop running. If your projects rely on repo hooks, stick with the per-repo setup.

What it looks like

After a commit that crosses the limit:

$ git commit -m "Handle empty config"

  >> 55 min since your last break. Stand up, look at something far away, move for a few minutes. Then run: git break

$ git break
microbreak: timer reset

microbreak status tells you how long it's been. To change the limit, set MICROBREAK_MINUTES in your shell profile, for example export MICROBREAK_MINUTES=45.

Limitations

It only knows what you tell it. It can't tell a lunch break from a long debugging session, so if you step away without running git break, your next commit will nag you.
If you go two hours without committing, you won't hear from it. That's on purpose: it's a commit-time nudge, not a clock. If you want a hard timer, an ordinary timer app is the better tool.
GUI git clients may not show hook output. The desktop notification (via notify-send on Linux or osascript on macOS) is there to cover that case.
50 minutes is a starting point based on the hourly schedules above, not a number with evidence of its own.

What to do with the few minutes

Stand up, get some water, look out a window, roll your shoulders. For well-being, the Albulescu review concludes that the answer to "what should I do on a break?" "seems to be 'any type of decoupling activity'", meaning anything that takes you away from the work. If your forearms are the part that complains, here are some wrist stretches you can do at your desk. Galinsky 2007 couldn't show that stretching adds anything beyond the break itself, so treat stretches as an option, not a requirement.

When to see a clinician

Breaks are a habit, not a treatment. OSHA lists warning signs that include numbness or a burning sensation in the hand, reduced grip strength, swelling or stiffness in the joints, pain in the wrists, forearms, elbows, neck or back, reduced range of motion, aching or tingling, cramping and weakness, and it stresses reporting signs and symptoms as early as possible. The AAO says that if your eyes are consistently red, blurry or watery, or become sensitive to light or painful, you should see an ophthalmologist. If any of that sounds familiar, talk to a doctor or physiotherapist rather than tuning a git hook.

Sources

Galinsky TL, et al. (2000). A field study of supplementary rest breaks for data-entry operators. Ergonomics 43(5):622–638. https://pubmed.ncbi.nlm.nih.gov/10877480/
Galinsky T, et al. (2007). Supplementary breaks and stretching exercises for data entry operators: a follow-up field study. Am J Ind Med 50(7):519–527. https://pubmed.ncbi.nlm.nih.gov/17514726/
Henning RA, et al. (1997). Frequent short rest breaks from computer work: effects on productivity and well-being at two field sites. Ergonomics 40(1):78–91. https://pubmed.ncbi.nlm.nih.gov/8995049/
Albulescu P, et al. (2022). "Give me a break!" A systematic review and meta-analysis on the efficacy of micro-breaks for increasing well-being and performance. PLOS ONE 17(8): e0272460. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0272460
Hoe VC, et al. (2018). Ergonomic interventions for preventing work-related musculoskeletal disorders of the upper limb and neck among office workers. Cochrane Database Syst Rev CD008570. https://pubmed.ncbi.nlm.nih.gov/30350850/
OSHA, Computer Workstations eTool: Work Process and Recognition. https://www.osha.gov/etools/computer-workstations/work-process
American Academy of Ophthalmology, Computers, Digital Devices, and Eye Strain. https://www.aao.org/eye-health/tips-prevention/computer-usage
Git documentation: githooks (https://git-scm.com/docs/githooks) and git-config (https://git-scm.com/docs/git-config).

This post was drafted with AI assistance and reviewed by the MotionLab team.

Unlock challenges that fail when you look away: attention-gated friction in Jetpack Compose

ReClaim — Thu, 29 Oct 2026 15:16:14 +0000

We're building ReClaim, a minimalist Android launcher that's on Google Play. One of its features is hiding apps, and hiding turned out to be a design problem more than a code problem. If a hidden app opens with one tap from search, it isn't really hidden. If it can never be opened, people uninstall the launcher.

So hiding has levels. Here they are, straight from the dialog the user picks from:

HideLevelRow("Simple", "Hidden from the launcher.", 1, onPick)
HideLevelRow("Medium", "Solve a quick challenge to open.", 2, onPick)
HideLevelRow("Maximum", "Solve a harder challenge to open.", 3, onPick)
HideLevelRow("Extreme", "Eyes on the screen the whole time.", 4, onPick)

This post is about how the challenges behind levels 2 to 4 are built in Jetpack Compose, and mostly about level 4, where the rule is "you fail if your attention leaves the screen." There's no camera and no eye tracking involved. Each challenge is designed so that looking away makes you lose. Stack: Kotlin, Jetpack Compose (BOM 2024.12.01), Hilt, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

1. Challenge types are data, and levels pick from them

Every challenge is an enum entry, and each level offers a different subset:

enum class ChallengeType(val label: String) {
    MATH("Math problems"),
    TYPED_PHRASE("Type a phrase"),
    MEMORY_SEQUENCE("Memory sequence"),
    HOLD_TO_CONFIRM("Hold to confirm"),
    SEQUENTIAL_CONFIRMATIONS("Multiple confirmations"),
    REFLECTION("Reason for opening"),
    FOLLOW("Follow the circle"),
    FIND("Find the shape"),
    WATCH("Watch the words"),
}

fun challengeTypesForLevel(level: Int): List<ChallengeType> = when (level) {
    2 -> listOf(MATH, TYPED_PHRASE, MEMORY_SEQUENCE, HOLD_TO_CONFIRM, REFLECTION)
    3 -> listOf(MATH, TYPED_PHRASE, MEMORY_SEQUENCE, HOLD_TO_CONFIRM, REFLECTION,
                SEQUENTIAL_CONFIRMATIONS)
    4 -> listOf(FOLLOW, FIND, WATCH)
    else -> emptyList()
}

Levels 2 and 3 share most types. Level 3 just changes the defaults. Level 4 is a separate set on purpose, and the comment above that function says why: Follow, Find and Watch "are not harder versions of the lower challenges, and a hold is intentionally absent because a finger can stay down while the person looks away."

2. Per-app overrides with `null` meaning "use the default"

People wanted to tune a challenge per app, for example "two minutes of holding for this one app, ten seconds for the rest." Instead of copying level defaults into every row, the config stores only what the user touched:

data class HideChallengeConfig(
    val holdSeconds: Int? = null,
    val mathProblemCount: Int? = null,
    val mathHard: Boolean? = null,
    val sequenceLength: Int? = null,
    val reflectionMinWords: Int? = null,
    val phraseHard: Boolean? = null,
    val followSeconds: Int? = null,
    val findRounds: Int? = null,
    val watchRounds: Int? = null,
)

fun HideChallengeConfig.effectiveHoldSeconds(level: Int): Int =
    holdSeconds ?: if (level >= 3) 120 else 10
fun HideChallengeConfig.effectiveMathProblemCount(level: Int): Int =
    mathProblemCount ?: if (level >= 3) 3 else 1
fun HideChallengeConfig.effectiveFollowSeconds(): Int = followSeconds ?: 20
// ...

The upside: moving an app from Medium to Maximum makes every untouched knob harder at once, while anything the user set by hand stays put. A single router composable then reads the saved type and hands each dialog its effective values:

when (app.challengeType) {
    ChallengeType.MATH, null -> ChallengeDialog(
        problemCount = config.effectiveMathProblemCount(level),
        hard = config.effectiveMathHard(level),
        onSuccess = onSuccess, onDismiss = onDismiss,
    )
    ChallengeType.FOLLOW -> FollowChallengeDialog(
        seconds = config.effectiveFollowSeconds(),
        onSuccess = onSuccess, onDismiss = onDismiss,
    )
    // ... one branch per type
}

Note the null in the first branch: an app hidden before challenge types existed falls back to math, so old data never crashes the router.

3. Levels 2 and 3: friction against autopilot

The lower levels aim at one thing: you can't complete them without thinking for a second. Math draws random operands, with bigger numbers and multiplication only when hard. Typed phrase picks a sentence, and at level 3 the sentences carry punctuation ("This is intentional; I have thought about it.") that has to match exactly. Memory sequence shows colored dots for 2.5 seconds, and any wrong tap clears your input. Reflection asks why you want to open the app and counts words with text.trim().split(Regex("\\s+")), requiring 10 at level 3.

Sequential confirmations, the level 3-only type, is my favorite small trick. It's four steps, and each one is a different action so muscle memory can't carry you through: a button, then a button in a different spot, then a switch that has to be turned on before "Next" is enabled, then a two-second hold.

when (step) {
    0 -> Button(onClick = { step = 1 }) { Text("Continue") }
    1 -> Row(horizontalArrangement = Arrangement.End) {
        Button(onClick = { step = 2 }) { Text("I'm sure") }
    }
    2 -> {
        Switch(checked = toggleChecked, onCheckedChange = { toggleChecked = it })
        Button(onClick = { step = 3 }, enabled = toggleChecked) { Text("Next") }
    }
    else -> HoldButton(targetMillis = 2_000L, label = "Hold to open", onComplete = onSuccess)
}

The weakness of all of these is that they test effort, not attention. You can hold a button for two minutes while watching TV. That's what level 4 is for.

4. Follow the circle: a game loop inside `LaunchedEffect`

Follow asks you to keep a finger on a circle for 20 seconds by default. The circle drifts, so a parked finger loses it, and every couple of seconds it jumps to a new spot. The jump is announced by a small mark that exists only on screen, so you have to be looking to know where to go.

The motion lives in a plain Kotlin class, CircleChase, with three phases:

private enum class ChasePhase { DRIFT, PREVIEW, GRACE }

private const val PREVIEW_MS = 640f
private const val GRACE_MS = 700f
private const val FIRST_JUMP_MS = 2_200f

In DRIFT the circle steers toward a random heading that changes every 550 to 1,250 ms and bounces off the edges. A jump countdown only runs while your finger is actually on the circle (tracking), so the jump is a response to good tracking, not a random punishment. When it hits zero, PREVIEW shows the mark for 640 ms and freezes the circle, so glancing at the mark doesn't by itself knock your finger off. Then the circle teleports to the mark and GRACE gives you 700 ms to land on it. Miss the landing and your earned time resets.

Choosing where to jump is a bounded random search. It tries 24 points and takes the first one that's far enough to require moving, but not so far that it's unfair:

repeat(24) {
    val px = margin + random.nextFloat() * (width - 2 * margin).coerceAtLeast(0f)
    val py = margin + random.nextFloat() * (height - 2 * margin).coerceAtLeast(0f)
    val distance = hypot(px - x, py - y)
    if (distance in minJump..ceiling) {
        previewX = px; previewY = py
        return true
    }
    // ... otherwise remember the farthest legal candidate
}

minJump and maxJump are 108 dp and 170 dp, converted with LocalDensity, and if the field is too small for any legal jump the function returns false and the countdown simply restarts.

The loop itself runs inside a LaunchedEffect driven by withFrameNanos, which suspends until the next frame and gives you its timestamp:

LaunchedEffect(boxSize, speedPxPerMs, contactPx, totalMs) {
    if (boxSize.width < 8 || boxSize.height < 8) return@LaunchedEffect
    val model = CircleChase(/* ... */)
    var lastFrame = 0L
    var done = false
    while (!done) {
        val frame = withFrameNanos { it }
        if (lastFrame == 0L) { lastFrame = frame; continue }
        val dt = ((frame - lastFrame) / 1_000_000f).coerceIn(0f, 32f)
        lastFrame = frame
        val finger = pointer.value
        val wasOn = finger != null && model.contains(finger.x, finger.y, contactPx)
        model.advance(dt, speedPxPerMs, turnPerMs,
            tracking = wasOn && model.phase == ChasePhase.DRIFT)
        // ... add dt to progress while on the circle, reset on a slip
    }
}

Two details matter here. First, dt is clamped to 32 ms. If the app stalls (a GC pause, or the dialog briefly losing focus), the circle doesn't leap across the screen on the next frame. Second, onSuccess and onSlip are read through rememberUpdatedState. The Compose side-effects guide describes exactly this case: a value used inside an effect that shouldn't restart the effect when it changes. Restarting this effect would throw away the player's progress.

Touch tracking is a raw pointer loop with awaitEachGesture, which the gestures guide recommends over a hand-written while (true) because it restarts once all pointers are lifted:

.pointerInput(Unit) {
    awaitEachGesture {
        val down = awaitFirstDown(requireUnconsumed = false)
        pointer.value = down.position
        down.consume()
        try {
            while (true) {
                val event = awaitPointerEvent()
                val change = event.changes.firstOrNull { it.id == down.id } ?: break
                if (!change.pressed) break
                pointer.value = change.position
                change.consume()
            }
        } finally {
            pointer.value = null
        }
    }
}

It follows only the pointer that started the gesture (it.id == down.id), so a second finger can't take over, and the finally clears the position on every exit. The hit test uses a 62 dp contact radius while the circle is drawn at 34 dp. Being slightly generous with fat fingers made the challenge feel fair without making it easy.

5. Find the shape: a conjunction search

Find shows a 5×5 grid of outlines with a small gap in each, and asks you to tap, say, "the triangle with a gap on the left." The board is built so that no single feature gives the answer away:

private fun newFindBoard(random: Random): FindBoard {
    val shape = MarkShape.entries.random(random)
    val gap = GapSide.entries.random(random)
    val target = MarkSpec(shape, gap)
    val otherGaps = GapSide.entries.filter { it != gap }
    val otherShapes = MarkShape.entries.filter { it != shape }
    val cells = ArrayList<FindCell>(FIND_GRID * FIND_GRID)
    cells += FindCell(target, true)
    repeat(6) {
        cells += FindCell(MarkSpec(shape, otherGaps[0]), false)
        cells += FindCell(MarkSpec(shape, otherGaps[1]), false)
        cells += FindCell(MarkSpec(otherShapes[0], gap), false)
        cells += FindCell(MarkSpec(otherShapes[1], gap), false)
    }
    cells.shuffle(random)
    return FindBoard(target, cells)
}

Twelve distractors share the target's shape and twelve share its gap side, so you can't scan for "the only triangle" or "the only left gap." You have to check each cell for both. The glyphs are drawn on a Canvas: circles with drawArc and a 42° missing wedge, and squares and triangles with a Path that skips 18% of one edge. The default is eight boards in a row, and one wrong tap generates a fresh board and sends you back to the first. There's also a 220 ms input lock after each new board, so a tap already on its way from the previous board doesn't count against the next one.

6. Watch the words: recognition isn't enough

Watch flashes eight words, one at a time, for 520 ms each with an 80 ms gap, all from a LaunchedEffect with delay. Then it asks what came right after one of them:

private fun newWatchRound(random: Random): WatchRound {
    val words = WATCH_BANK.shuffled(random).take(8)
    val probe = random.nextInt(0, words.lastIndex)
    val distractors = words
        .filterIndexed { index, _ -> index != probe && index != probe + 1 }
        .shuffled(random)
        .take(3)
    val choices = (distractors + words[probe + 1]).shuffled(random)
    return WatchRound(words, probe, choices)
}

The important line is the distractor filter. Every wrong choice also appeared in the list, so half-noticing the words while looking at something else doesn't help. You have to have seen the order. nextInt(0, words.lastIndex) excludes the last word as the probe, since nothing comes after it. Four rounds by default, and a miss starts over.

7. Don't ask twice: a ten-second grace window

Once the challenges existed, a new annoyance showed up. A hidden app can also have a reminder timer, and opening it could hit two gates back to back: the challenge when you unlock it, then the reminder prompt, which also checks the challenge. So there's a tiny in-memory store keyed by package:

@Singleton
class HiddenChallengeGraceStore @Inject constructor() {
    private val solvedAt = mutableMapOf<String, Long>()

    @Synchronized
    fun markSolved(packageName: String) {
        solvedAt[packageName] = SystemClock.elapsedRealtime()
    }

    @Synchronized
    fun isRecentlySolved(packageName: String): Boolean {
        val at = solvedAt[packageName] ?: return false
        return SystemClock.elapsedRealtime() - at < GRACE_MILLIS
    }

    private companion object { const val GRACE_MILLIS = 10_000L }
}

It uses SystemClock.elapsedRealtime(), time since boot, so changing the phone's clock can't stretch the window. Ten seconds covers "the same open" and nothing more. When a reminder later says time's up, minutes have passed, so continuing asks for the challenge again. It's deliberately not persisted, since every gate runs in the same process.

8. The bug that taught us "a challenge is its own gate"

The launch logic used to tuck the challenge inside the reminder flow. Hiding an app doesn't remove it from Home or from a folder, so a level 2 or 3 app could still be tapped there, and every reason to skip the reminder prompt (a session already running, or no reminder set) skipped the challenge too. The app just opened. The fix was to make the challenge its own branch, checked first:

when {
    blockRepository.isBlocked(app.packageName) ->
        _events.emit(LauncherUiEvent.ShowBlocked(app.packageName))
    app.hideLevel >= 2 && !hiddenChallengeGraceStore.isRecentlySolved(app.packageName) ->
        _events.emit(LauncherUiEvent.ShowHiddenChallenge(app))
    reminderRepository.hasReminder(app.packageName) &&
        !reminderSessionStore.isActive(app.packageName) ->
        _events.emit(LauncherUiEvent.ShowReminderPrompt(app))
    else -> appRepository.launch(app)
}

The lesson generalizes: if a check guards access, give it its own branch at every entry point instead of hoping it rides along with another check.

What we'd tell another team building friction

Separate effort from attention. Holds and long phrases cost time; drifting targets and order questions cost focus.
Store per-item overrides as nullable fields and resolve defaults at read time.
Run animation as a frame loop in LaunchedEffect with a clamped dt, and read callbacks through rememberUpdatedState.
Track one pointer by id, and clear its state in finally.
Build distractors from the same features as the target, so nothing pops out.
Use elapsedRealtime() for short time windows. The hold button still measures with System.currentTimeMillis(), which we plan to move over for the same reason.

If you want to try the levels yourself, ReClaim is on Google Play, and our guide to hiding apps on Android covers the non-code side.

This post was drafted with AI assistance and reviewed by the ReClaim team.

Backup and restore for an Android launcher with Room: debounced snapshots and an empty-database gate

ReClaim — Sat, 24 Oct 2026 15:10:52 +0000

We're building ReClaim, a minimalist Android launcher that's now on Google Play. A launcher stores a lot of small, personal things: your home screen order, folders, hidden apps, blocks, schedules, timers and tasks. Nobody notices that setup until it's gone.

So we built our own backup and restore. It isn't Android's BackupAgent. It's a plain class, also called BackupManager, that does three things:

It keeps a local snapshot of the whole setup, updated automatically.
It can export that snapshot as a single zip the user moves to another phone.
It can restore from either, all or nothing.

Here's how it works, traps included. Stack: Kotlin, Hilt, Room, DataStore, coroutines, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

1. One JSON file, kept outside `databases/`

The snapshot is one JSON document that holds every user-data table, the settings, and a flag for the home background image. It lives in filesDir/backups/, not next to the database. The class comment explains why: the local copy "survives anything that resets the database itself."

private val backupDir: File get() = File(context.filesDir, "backups")
private val backupFile: File get() = File(backupDir, "reclaim_backup.json")
private val writeMutex = Mutex()

private suspend fun writeBackupLocked(): BackupMeta {
    val favorites = favoritesDao.observeAll().first()
    val hidden = hiddenAppsDao.observeAll().first()
    val tasks = taskDao.observeAll().first()
    // ... every other DAO, plus settings
    val root = JSONObject().apply {
        put("formatVersion", 2)
        put("createdAt", System.currentTimeMillis())
        put("favorites", JSONArray(favorites.map {
            it.toJson().put("label", displayLabel(it.packageName, renameMap))
        }))
        put("tasks", JSONArray(tasks.map { it.toJson() }))
        // ...
        put("settings", settings.toBackupJson(tutorialCompleted, hasBackground, renameMap))
    }

    backupDir.mkdirs()
    val tmp = File(backupDir, "${backupFile.name}.tmp")
    tmp.writeText(root.toString())
    tmp.renameTo(backupFile)
    // ... return counts for the UI
}

A few choices are worth calling out:

Write to a temp file, then rename. If the process dies halfway through a write, the half-written file is the .tmp and the previous snapshot is still there.
A Mutex around every write. Auto-backup, manual export and import all go through writeMutex.withLock { ... }, so two snapshots never write the same file at once.
formatVersion from day one. Import checks for it (or for the older favorites key) before trusting a file.
Labels next to package names. A package name like com.example.notes means nothing to a person. We save the display name with it so a later restore can say which apps are missing (section 7).

The entity-to-JSON mappers are written by hand. The comment above them explains the trade-off: "these tables rarely change shape, and a direct field-by-field mapping is far easier to audit for correctness than a reflection-based one."

2. Auto-backup: merge every table, debounce, write

We didn't want a "Back up now" button that people forget to press. Every Room DAO already exposes a Flow, so the auto-backup listens to all of them at once:

private fun startAutoBackup() {
    val changed = merge(
        favoritesDao.observeAll().map {},
        hiddenAppsDao.observeAll().map {},
        blockDao.observeAll().map {},
        // ... one line per table
        settingsRepository.settings.map {},
    )
    appScope.launch {
        changed.debounce(3_000).collect { writeBackup() }
    }
}

.map {} turns every emission into Unit. We don't care what changed, only that something did, because the write always re-reads everything. debounce does the batching. The kotlinx.coroutines docs describe it as filtering out "values that are followed by the newer values within the given timeout," and add that "the latest value is always emitted." Dragging five apps around the home screen produces one write, three seconds after the last drop, instead of five.

3. The trap: an empty database will happily back itself up

This is the part that would have hurt users. Room flows emit their current value as soon as you collect them. If the database ever comes up empty for any reason, the auto-backup loop above would see "a change", wait three seconds, and replace the last good snapshot with an empty one. The one copy that could fix the problem would be gone.

So auto-backup doesn't start right away. On app start, initialize() checks first:

fun initialize() {
    appScope.launch {
        val meta = readMeta()
        val liveEmpty = isLiveDataEmpty()
        if (liveEmpty && meta != null && meta.totalItems > 0) {
            _restoreOffer.value = meta   // UI asks: restore, or start fresh?
        } else {
            startAutoBackup()
        }
    }
}

fun restoreAndResume() {
    appScope.launch {
        val outcome = restoreBackup()
        _restoreOffer.value = null
        if (outcome.missingApps.isNotEmpty()) _missingAppsNotice.value = outcome.missingApps
        startAutoBackup()
    }
}

The UI shows a "Restore your data?" dialog with the snapshot's date and counts, and auto-backup stays off while that question is open. The general lesson: any automatic job that overwrites the "last known good" copy needs a gate for the case where the current state is the thing that's broken.

4. Restore in one Room transaction

A restore means "make the tables look exactly like this file." A half-applied restore is worse than none. So everything runs inside withTransaction:

private suspend fun applyRoot(root: JSONObject, imageFile: File?): BackupApplyResult {
    val missing = root.missingAppLabels()
    db.withTransaction {
        favoritesDao.clearAll()
        hiddenAppsDao.clearAll()
        folderDao.clearAllFolderApps()
        folderDao.clearAllFolders()
        // ... clear every table

        root.jsonArray("favorites").forEachObject { favoritesDao.upsert(it.toFavoriteEntity()) }
        root.jsonArray("folders").forEachObject { folderDao.upsertFolder(it.toFolderEntity()) }
        root.jsonArray("folderApps").forEachObject { folderDao.assign(it.toFolderAppEntity()) }
        // Categories first: a restored task's categoryId has to point at a row that exists.
        root.jsonArray("taskCategories").forEachObject { taskCategoryDao.upsert(it.toTaskCategoryEntity()) }
        root.jsonArray("tasks").forEachObject { taskDao.upsert(it.toTaskEntity()) }
        // ...
    }
    applySettings(root, imageFile)
    return BackupApplyResult(applied = true, missingApps = missing)
}

The Room reference says withTransaction "will be marked as successful unless an exception is thrown in the suspending block or the coroutine is cancelled." A malformed row in the middle of the file rolls back every clear and every insert before it. The same page notes that Room "will only perform at most one transaction at a time", and that's why the clear-then-insert block doesn't interleave with other writes.

Settings live in Preferences DataStore, not Room, so they are applied after the transaction in a single store.edit { ... } call (SettingsRepository.replaceAll). One thing to be clear about: the all-or-nothing guarantee covers the Room tables. Settings and the background image are a separate step.

5. Export: one zip through the Storage Access Framework

To move a setup to another phone, the user needs a file they can see. We use the Storage Access Framework through Compose's activity-result contracts. The screen launches CreateDocument("application/zip") with a suggested name of ReClaim-backup.zip, and the manager writes into the URI it gets back:

private fun zipTo(uri: Uri): Boolean = runCatching {
    val temp = File(context.cacheDir, "reclaim-export.zip")
    ZipOutputStream(temp.outputStream()).use { zip ->
        zip.putNextEntry(ZipEntry("backup.json"))
        backupFile.inputStream().use { it.copyTo(zip) }
        zip.closeEntry()
        if (backgroundFile.isFile && backgroundFile.length() > 0L) {
            zip.putNextEntry(ZipEntry("home_background.jpg"))
            backgroundFile.inputStream().use { it.copyTo(zip) }
            zip.closeEntry()
        }
    }
    val wrote = context.contentResolver.openOutputStream(uri)?.use { out ->
        temp.inputStream().use { it.copyTo(out) }
        true
    } ?: false
    temp.delete()
    wrote
}.getOrDefault(false)

Two points from the SAF guide shaped this. First, because the user picks the location, the mechanism "doesn't require any system permissions." Second, ACTION_CREATE_DOCUMENT "cannot overwrite an existing file"; the system appends a number instead. So exporting twice gives you ReClaim-backup(1).zip rather than silently replacing the first file.

6. Import: treat the file as hostile

An imported file can come from anywhere. The import path assumes nothing about it:

private fun unzipBackup(zipFile: File, dest: File): Boolean {
    var found = false
    ZipInputStream(zipFile.inputStream()).use { zip ->
        var entry = zip.nextEntry
        while (entry != null) {
            val name = File(entry.name).name
            val limit = if (name == "home_background.jpg") IMAGE_LIMIT else JSON_LIMIT
            if (!entry.isDirectory && (name == "backup.json" || name == "home_background.jpg")) {
                val out = File(dest, name)
                val ok = out.outputStream().use { zip.copyLimited(it, limit) }
                if (!ok) { out.delete(); return false }
                if (name == "backup.json") found = true
            }
            zip.closeEntry()
            entry = zip.nextEntry
        }
    }
    return found
}

The layers, in order:

Size caps while copying. copyLimited counts bytes and gives up past a limit: 32 MB for the incoming file, 8 MB for the JSON, 20 MB for the image. We never trust a size the file reports about itself.
Magic bytes, not the extension. isZip() checks for the PK signature. Anything else goes down the legacy path for raw JSON, which still has to parse and contain favorites or formatVersion.
No path traversal. Android's Zip Path Traversal guidance warns that zip entry names can contain ../ and recommends checking the canonical path. We go stricter: File(entry.name).name throws away every directory part, and only two exact names are ever written. An entry called ../../shared_prefs/x.xml turns into x.xml and is skipped.
A throwaway directory. Everything is unpacked into a fresh folder under cacheDir, which is deleted in finally whether the import worked or not.

Only after all that does the file reach applyRoot, and if it applied, the manager immediately writes a new local snapshot so the two copies agree.

7. Apps that aren't installed yet

On a new phone, many of your apps may not be installed yet. We don't drop their rows during restore. Folders, favorites and blocks keep their entries, so the layout comes back intact as you reinstall apps. What we do is tell you which ones are missing:

private fun JSONObject.missingAppLabels(): List<String> {
    // ...
    fun add(packageName: String?, fallback: String?) {
        val pkg = packageName?.takeIf { it.isNotBlank() } ?: return
        if (isPackageInstalled(pkg)) return
        val chosen = renames[pkg]?.takeIf { it.isNotBlank() }
            ?: fallback?.takeIf { it.isNotBlank() }
            ?: pkg
        // ...
    }
    listOf("favorites", "folderApps", "hiddenApps", "blocks", "reminders", "budgets", "scheduleApps")
        .forEach { key ->
            jsonArray(key).forEachObject { add(it.optStringOrNull("packageName"), it.optStringOrNull("label")) }
        }
    // ...
}

This is where saving labels in section 1 pays off. The new phone can't look up a name for a package it doesn't have, but the backup already carries one. Your own rename comes first, then the saved label, and the raw package name only as a last resort.

8. The background image, and what the platform allows

If you picked a custom photo for Home, the snapshot copies it. When Home just shows the system wallpaper, the code tries to capture that too, and avoids re-encoding it on every snapshot by caching WallpaperManager.getWallpaperId(FLAG_SYSTEM). The WallpaperManager reference says a new ID is assigned "every time the wallpaper image is set" so an unchanged ID means the cached JPEG is still current. Reordering apps doesn't re-encode a wallpaper.

We need to be honest about the limits, because the same reference spells them out. Reading the actual wallpaper file has been locked down: on Android 13 apps get the default wallpaper instead, and from Android 14 getWallpaperFile throws unless the app holds permissions a launcher like ours doesn't request. The capture is wrapped in runCatching, so on those versions the snapshot just goes on without it. In practice, the background that reliably travels in a ReClaim backup is a photo you picked inside ReClaim.

9. Why not just rely on Auto Backup?

Android's Auto Backup already exists, and our manifest leaves android:allowBackup="true". It does a different job. Backups run when "at least 24 hours have elapsed since the last backup", the device is idle and on Wi-Fi, and data is restored "whenever the app is installed." That's a good safety net, but the user can't hold that copy or restore it on demand into an app that's already running. Ours is a file they can see and choose when to restore. The two exist side by side.

What we'd tell another app team

Snapshot from your Flows with merge and debounce; don't add a "Back up now" button.
Write to a temp file, then rename, and serialize writers with a Mutex.
Gate the auto-backup when the live data is empty, or it will overwrite your only good copy.
Clear and insert in one transaction, and order inserts by reference.
On import, cap sizes, check magic bytes, strip entry paths, and whitelist file names.
Store human-readable labels next to IDs that won't exist on the next device.

This post was drafted with AI assistance and reviewed by the ReClaim team.

Creator referrals with Next.js and Supabase: first-touch attribution and one commission per payment

ReClaim — Thu, 22 Oct 2026 15:50:16 +0000

A creator referral program sounds like a link and a percentage. Once you build one, it turns into four questions: who gets credit for a signup, which payments earn a commission, how do you avoid counting the same payment twice, and what happens when a payment is refunded after you've recorded it?

We're building MotionLab, an AI-personalized stretching app with a Next.js web app on Vercel, an Android app, and Supabase underneath. Subscriptions come from Stripe on the web and Google Play on Android, and creators who share MotionLab earn a commission on subscriptions they bring in. This post is the code behind that: a landing route that stashes the referral, a Postgres function that records it once, a commissions table keyed so each payment lands once, and the jobs that undo commissions after refunds.

Stack: Next.js App Router, @supabase/supabase-js, PL/pgSQL, the stripe SDK and googleapis. Snippets are trimmed from the real code; // ... (or -- ... in SQL) marks cuts. Commission rates, prices and window lengths are left out on purpose: those are business terms.

1. The link: `/c/{slug}`

Each creator row has a unique slug, and their link is motion-lab.io/c/{slug}: a server component that redirects home if the slug is unknown or inactive:

// src/app/(marketing)/c/[slug]/page.tsx
export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const { slug } = await params;
  const creator = await getCreator(slug);
  const title = creator ? `${creator.displayName} recommends MotionLab` : "MotionLab";
  return {
    title,
    // ...
    robots: { index: false, follow: true }, // referral landing pages aren't indexed
  };
}

export default async function CreatorLandingPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const creator = await getCreator(slug);
  if (!creator) redirect("/");
  return <CreatorLandingClient slug={creator.slug} displayName={creator.displayName} />;
}

Creator pages share most of their copy, so they're noindex via the robots field of generateMetadata. The client half stashes the slug in a cookie and localStorage until the visitor signs up, and builds a Play Store link that carries the slug in the referrer parameter:

// CreatorLandingClient.tsx
// The Android Install Referrer API reads this back as: utm_source=motionlab_creator&utm_content={slug}
function playUrl(slug: string): string {
  const referrer = encodeURIComponent(`utm_source=motionlab_creator&utm_content=${slug}`);
  return `${PLAY_BASE}&referrer=${referrer}`;
}

useEffect(() => {
  // ...
  document.cookie = `ml_ref=${encodeURIComponent(slug)}; path=/; max-age=${maxAge}; SameSite=Lax`;
  try { localStorage.setItem("ml_ref", slug); } catch {}
}, [slug]);

On Android, the Play Install Referrer API returns that string after install; per the migration's comments, the app then calls the same database function as the web, with the user's own JWT.

2. Recording attribution once, inside Postgres

The rules: the first creator to refer a user keeps them, creators can't refer themselves, and two concurrent requests can't both win. Rather than spread those checks across a web route and the Android app, they live in one security definer function with a small string contract:

-- supabase/migrations/0002_referrals.sql
-- Returns: 'set' | 'already' | 'self' | 'invalid' | 'no_profile'
create or replace function public.set_referral_attribution(
    p_user_id uuid, p_creator_slug text, p_source text
) returns text
language plpgsql security definer set search_path = public as $$
declare
    v_creator public.creators%rowtype;
    v_uid     uuid;
    -- ...
begin
    if auth.uid() is not null then
        v_uid := auth.uid();              -- signed-in client: p_user_id is ignored
    elsif coalesce(auth.role(), '') = 'service_role' then
        v_uid := p_user_id;               -- our server route, which verified the user
    else
        return 'invalid';
    end if;

    select * into v_creator from public.creators where slug = p_creator_slug and active;
    if not found then return 'invalid'; end if;

    if v_creator.user_id is not null and v_creator.user_id = v_uid then
        return 'self';
    end if;

    select * into v_profile from public.user_profiles where id = v_uid;
    if not found then return 'no_profile'; end if;             -- caller may retry later
    if v_profile.referred_by_creator_id is not null then return 'already'; end if;

    update public.user_profiles
       set referred_by_creator_id = v_creator.id,
           referred_at            = now(),
           referral_source        = p_source
     where id = v_uid
       and referred_by_creator_id is null;                     -- first-touch lock (race-safe)

    return 'set';
end $$;

The select checks give readable answers. The where ... referred_by_creator_id is null on the update is what enforces first-touch: if two calls race past the select, only one update matches. The set search_path matters too; the Postgres docs on writing SECURITY DEFINER functions safely explain how a definer function without a fixed search path can be tricked into using an object the caller created.

Two more things matter for a definer function in an exposed schema. Postgres grants EXECUTE to PUBLIC on every new function, so a grant ... to authenticated alone doesn't keep anyone out; you have to revoke it. And a function that accepts a user id should only trust that argument from a trusted caller. Our first version fell back to p_user_id whenever auth.uid() was null, which is also true for an anonymous request. A later migration fixed both:

revoke execute on function public.set_referral_attribution(uuid, text, text) from public, anon;
grant  execute on function public.set_referral_attribution(uuid, text, text) to authenticated, service_role;

On the web, a route handler verifies the caller's Supabase access token and passes the verified user id along:

// src/app/api/referral/attribute/route.ts
const supabase = createServerClient();
const { data: { user }, error } = await supabase.auth.getUser(token);
if (error || !user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
// ...
const { data, error: rpcError } = await supabase.rpc("set_referral_attribution", {
  p_user_id: user.id,
  p_creator_slug: slug,
  p_source: "web",
});
// ...
return NextResponse.json({ result: data }); // 'set' | 'already' | 'self' | 'invalid' | 'no_profile'

The browser helper runs from onboarding once a user exists, and is safe to call repeatedly. It clears the stash on any definitive answer and keeps it when the request failed or the profile isn't there yet:

// src/lib/referral/client.ts
const res = await fetch("/api/referral/attribute", { /* ... Bearer token, { slug } */ });
if (!res.ok) return; // keep the stash for a later retry

const { result } = (await res.json()) as { result?: string };
if (result && result !== "no_profile") clearRef();

no_profile means the user's user_profiles row doesn't exist yet. Returning a status instead of failing lets the client retry on a later mount rather than lose the referral.

The tables creators, referral_commissions and referral_payouts have row-level security enabled and no policies. Per Supabase's RLS guide, that leaves nothing readable through the API with the publishable key, while the service role our server code uses bypasses RLS. The same guide warns that policies don't remove grants, so audit both.

3. One commission row per payment

One unique constraint does most of the work:

create table if not exists public.referral_commissions (
    id                  uuid primary key default gen_random_uuid(),
    creator_id          uuid not null references public.creators(id) on delete cascade,
    user_id             uuid not null references auth.users(id) on delete cascade,
    source              text not null,                          -- 'stripe' | 'play'
    external_payment_id text not null,                          -- stripe invoice id / play order id
    commission_cents    int  not null,
    status              text not null default 'pending',        -- pending | paid | reversed
    -- ...
    unique (source, external_payment_id)                        -- idempotency
);

All inserts go through one helper that turns a duplicate into a no-op:

// src/lib/referral/commissions.ts
await supabase
  .from("referral_commissions")
  .upsert({ status: "pending", ...row }, { onConflict: "source,external_payment_id", ignoreDuplicates: true });

With ignoreDuplicates, supabase-js's upsert acts like Postgres's INSERT ... ON CONFLICT DO NOTHING. Every caller here can repeat: Stripe's webhook docs say endpoints "might occasionally receive the same event more than once", and the Play side re-runs on a schedule on purpose. With the payment id as the key, doing the same work twice can't create a second commission.

Stripe is the easy store. The webhook's invoice.payment_succeeded handler, which also sees renewals, calls:

export async function recordStripeCommission(supabase: DB, uid: string, invoice: Stripe.Invoice) {
  const amountPaid = invoice.amount_paid ?? 0;
  if (amountPaid <= 0) return; // skip $0 / fully-discounted / trial invoices
  if (!invoice.id) return;

  const creator = await creatorForUser(supabase, uid);
  if (!creator) return;

  await insertCommission(supabase, {
    // ...
    source: "stripe",
    external_payment_id: invoice.id,
    gross_amount_cents: amountPaid,
    commission_cents: commissionCents(amountPaid, creator.commissionPercent),
  });
}

The amount is what Stripe says was paid, and the key is the invoice id.

4. Google Play: order ids and a daily catch-up

Play is harder. Our server only hears about a renewal when the app syncs or a notification arrives, and the code comment is blunt that the v2 API "does not return the localized paid amount cleanly", so Play commissions use an estimated gross from a configured price map. (Stripe never uses that map.)

The Play key is the order id. Each renewal gets a new one, so one row per order id means one row per payment:

export async function recordPlayCommissionForUser(supabase: DB, uid: string, purchaseToken: string, interval: "month" | "year") {
  const creator = await creatorForUser(supabase, uid);
  if (!creator) return; // avoid hitting the Play API for unattributed users

  const publisher = playPublisher();
  const { data } = await publisher.purchases.subscriptionsv2.get({
    packageName: PLAY_PACKAGE_NAME,
    token: purchaseToken,
  });

  // latestOrderId is deprecated and can name a pending or declined renewal.
  const latestOrderId = data.lineItems?.[0]?.latestSuccessfulOrderId;
  if (!latestOrderId) return;
  // ... insertCommission({ source: "play", external_payment_id: latestOrderId, ... })
}

Our first version read data.latestOrderId. Google has deprecated latestOrderId; for auto-renewing plans it's the last recurring order, "success, pending, or declined". Its replacement in the current resource, lineItems[].latestSuccessfulOrderId, only names successful orders, which is what a commission should hang on, so that's what we key on now.

It's called from our shared Play sync, which runs when the app syncs a purchase, when a Play notification arrives, and in a nightly billing reconcile (only in ACTIVE or CANCELED-not-yet-expired states, so a grace period earns nothing). A separate daily cron sweeps referred Play subscribers as a backstop:

// src/app/api/referral/reconcile-play/route.ts
export async function GET(request: Request) {
  const auth = request.headers.get("authorization");
  if (!process.env.CRON_SECRET || auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
  // ... reconcileAllPlayCommissions(supabase)
}

That's the pattern from Vercel's cron docs, which also say delivery is best effort and a run can occasionally fire twice. The unique key absorbs duplicates, and since each run rechecks the current order id instead of "new since last time", a missed run is caught by the next one.

5. Undoing commissions

In this code path, refunds and chargebacks don't cut access. They reverse the commission, and only while it's still pending. The Stripe webhook resolves the invoice id from charge.refunded or charge.dispute.created, then:

export async function reverseStripeCommissionByInvoiceId(supabase: DB, invoiceId: string) {
  await supabase
    .from("referral_commissions")
    .update({ status: "reversed", reversed_at: new Date().toISOString() })
    .eq("source", "stripe")
    .eq("external_payment_id", invoiceId)
    .eq("status", "pending");
}

Paid commissions are left for manual handling rather than silently clawed back.

For Play, the cron asks the Voided Purchases API for voided orders and reverses matching pending commissions. Two details on that page matter. The default type=0 returns only in-app purchases; subscriptions need type=1. Our first version passed only the package name and never saw a subscription refund; it now passes type: 1 and follows nextPageToken. And the API covers only the past 30 days, so a job that stops for a while can miss voids for good.

6. The holding period and payouts

Refunds can arrive days after a payment, so a commission isn't payable right away. A view sums commissions that are pending, not reversed and older than a holding window (redacted here):

create or replace view public.referral_payable as
select c.creator_id, cr.slug, cr.display_name, c.currency,
       count(*) as commission_count, sum(c.commission_cents) as payable_cents
from public.referral_commissions c
join public.creators cr on cr.id = c.creator_id
where c.status = 'pending'
  and c.reversed_at is null
  and c.created_at < now() - interval '...'
group by -- ...

Views in Postgres run with their owner's rights by default, so they skip the RLS on the tables underneath. Supabase's RLS guide covers this. A view in public that joins creator rows is readable through the API if the client roles have select on it, so ours runs as the caller and only the service role can read it:

alter view public.referral_payable set (security_invoker = true);
revoke all on public.referral_payable from public, anon, authenticated;

Settling a creator is an owner-only route: select the exact rows payable now, stamp them paid with a YYYY-MM batch label, and write a referral_payouts audit row. Updating by the selected ids means a commission that ages into the window mid-request isn't swept into a batch total it wasn't counted in.

What we'd keep, and what we'd change

Put attribution rules in one database function that every client calls. The race-safe part is a WHERE clause. Revoke the default EXECUTE, and only trust a user-id argument from the service role.
Make views over private tables security_invoker, or keep client roles off them.
Key money rows on the store's payment id and make every writer ignore duplicates, so webhooks, syncs and crons can overlap.
Reverse only what hasn't been paid, and hold commissions long enough for refunds to land.
On Play, key on latestSuccessfulOrderId, ask the Voided Purchases API for subscriptions explicitly, and treat the estimated amount as an estimate.

First-touch is a product choice as much as a technical one: easy to reason about and not gameable by re-clicking a link, but it never credits a second creator who actually closed the sale. The creator side of the program is on our partnerships page.

How does your referral code handle attribution and refunds: first-touch or last-touch, and what do you key commissions on? Tell us in the comments.

This post was drafted with AI assistance and reviewed by the MotionLab team.

Daily app limits on Android: replaying UsageEvents instead of trusting the daily buckets

ReClaim — Tue, 20 Oct 2026 15:50:48 +0000

"Thirty minutes of YouTube a day" sounds like one comparison. Enforcing it on Android means answering three questions: how long has the app really been in front today, when exactly does "today" start, and what makes the block land the moment the limit is crossed rather than at the next app switch?

We're building ReClaim, a minimalist Android launcher that's now on Google Play. Its App Limits are a per-app daily budget, with an optional weekly cap, that blocks the app, notifies you, or only tracks. This post is the code behind them: we replay the raw event log instead of trusting aggregate buckets, pin the boundaries to local midnight and Monday, and add the still-running session on top.

Stack: Kotlin, Hilt, Room, coroutines, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

1. Usage access is a special permission

Foreground time comes from UsageStatsManager. The manifest declares PACKAGE_USAGE_STATS, but per the reference, "declaring the permission implies intention to use the API and the user of the device still needs to grant permission through the Settings application." So we check the app op ourselves and send the user to the system screen:

fun hasPermission(): Boolean {
    val mode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        appOps.unsafeCheckOpNoThrow(
            AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), context.packageName,
        )
    } else {
        @Suppress("DEPRECATION")
        appOps.checkOpNoThrow(
            AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), context.packageName,
        )
    }
    return mode == AppOpsManager.MODE_ALLOWED
}

// ...

fun requestPermissionIntent(): Intent =
    Intent(Settings.ACTION_USAGE_ACCESS_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)

Every read below starts with if (!hasPermission()) return@withContext 0L. Without usage access, ReClaim sees zero historical usage.

2. Why we don't use the daily buckets

The obvious call is queryAndAggregateUsageStats(startOfToday, now) and reading totalTimeInForeground. The class docs explain why that's risky for a limit that resets at midnight. Usage data "is aggregated into time intervals: days, weeks, months, and years," and "a request for data in the middle of a time interval will include that interval." queryUsageStats adds that the begin and end times "may be expanded to the nearest whole interval period."

The KDoc on our summing function records what that looked like for us: the aggregate API "can bleed a prior day's total into a query that starts at today's midnight until that bucket rolls over, which silently breaks a 'reset at midnight' budget."

We still use the buckets where precision doesn't matter: the Blocking screen's "block together" suggestions rank last week's most-used apps with queryUsageStats(INTERVAL_DAILY, ...). Enforcement needs something stricter.

3. Replaying the event log

queryEvents(begin, end) returns the raw transitions, each with a timestamp. We walk them for one package and sum the time between "moved to foreground" and "moved to background", clipped to the window:

private fun sumForegroundMillis(packageName: String, start: Long, end: Long): Long {
    if (end <= start) return 0L
    val events = runCatching { usageStatsManager.queryEvents(start, end) }.getOrNull() ?: return 0L
    val event = UsageEvents.Event()
    var activeCount = 0
    var segmentStart = -1L
    var total = 0L
    while (events.hasNextEvent()) {
        events.getNextEvent(event)
        if (event.packageName != packageName) continue
        when (event.eventType) {
            UsageEvents.Event.MOVE_TO_FOREGROUND -> {
                if (activeCount == 0) segmentStart = event.timeStamp.coerceIn(start, end)
                activeCount++
            }
            UsageEvents.Event.MOVE_TO_BACKGROUND -> {
                if (activeCount > 0) {
                    activeCount--
                    if (activeCount == 0 && segmentStart >= 0) {
                        total += (event.timeStamp.coerceIn(start, end) - segmentStart).coerceAtLeast(0L)
                        segmentStart = -1L
                    }
                }
            }
        }
    }
    if (activeCount > 0 && segmentStart >= 0) {
        total += (end - segmentStart).coerceAtLeast(0L)
    }
    return total
}

A few details:

A counter, not pairs. In the UsageEvents.Event reference, MOVE_TO_FOREGROUND and MOVE_TO_BACKGROUND are deprecated in API 29 in favour of ACTIVITY_RESUMED and ACTIVITY_PAUSED, with the same constant values (1 and 2). The newer docs note that "if a package has multiple activities, this event is reported for each activity." So we count active activities and only open or close a segment at zero; the KDoc's example is Chrome hopping between its "tabbed activity <-> first-run activity".
Clipping. Timestamps are coerced into [start, end), and a segment that's still open when the log ends is counted up to end.
Null-safe. The reference says that from Android 11, queryEvents returns null when the user isn't unlocked. The ?: return 0L covers that.

4. Where "today" and "this week" start

The window is a fixed calendar period in the device's zone, not "the last 24 hours":

suspend fun todayForegroundMillis(packageName: String): Long = withContext(Dispatchers.IO) {
    if (!hasPermission()) return@withContext 0L
    val zone = ZoneId.systemDefault()
    val startOfToday = LocalDate.now(zone).atStartOfDay(zone).toInstant().toEpochMilli()
    val now = System.currentTimeMillis()
    sumForegroundMillis(packageName, startOfToday, now)
}

/** Foreground time for [packageName] since this calendar week's Monday, in millis. For the weekly budget cap — a fixed, predictable reset beats a rolling window when something is actually enforcing a limit. */
suspend fun weekForegroundMillis(packageName: String): Long = withContext(Dispatchers.IO) {
    if (!hasPermission()) return@withContext 0L
    val zone = ZoneId.systemDefault()
    val startOfWeek = LocalDate.now(zone)
        .with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY))
        .atStartOfDay(zone).toInstant().toEpochMilli()
    val now = System.currentTimeMillis()
    sumForegroundMillis(packageName, startOfWeek, now)
}

We use atStartOfDay(zone) rather than building midnight by hand. The LocalDate reference says it returns "the earliest valid time according to the rules in the time-zone," which "may not be midnight" in a daylight-saving gap.

Rolling windows still have one job: when you add a limit for one app, the editor suggests a starting value from averageDailyForegroundMillis over the last seven days, rounded down to five minutes.

The budget itself is a Room row (app_budgets, keyed by packageName) with dailyMinutes, a nullable weeklyMinutes, an action and a warn flag. Saving fixes one config mistake:

suspend fun save(budget: AppBudget) = budgetDao.upsert(
    AppBudgetEntity(
        packageName = budget.packageName,
        dailyMinutes = budget.dailyMinutes.coerceAtLeast(1),
        // A weekly cap smaller than the daily one would be self-defeating (the daily limit alone
        // would already block reaching it) — floor it at the daily minutes.
        weeklyMinutes = budget.weeklyMinutes?.coerceAtLeast(budget.dailyMinutes),
        action = budget.action.name,
        warnBeforeLimit = budget.warnBeforeLimit,
    ),
)

5. Counting the session that hasn't ended

Enforcement lives in the accessibility service ReClaim already uses to see which app is in front. The comment on one of its fields describes the problem it works around: "UsageStatsManager only reliably reports a session's foreground time once that session has ended — querying it mid-session can under-report by the session's entire duration so far."

So the service tracks the live part with the monotonic clock:

@Volatile private var currentSessionStartElapsed: Long = SystemClock.elapsedRealtime()

/** How long [pkg] has been continuously in the foreground right now, or 0 if it isn't. */
private fun ongoingSessionMillis(pkg: String): Long =
    if (pkg == lastForegroundPackage) {
        (SystemClock.elapsedRealtime() - currentSessionStartElapsed).coerceAtLeast(0L)
    } else {
        0L
    }

currentSessionStartElapsed resets on every real app switch; System UI window events (shade, quick settings) are ignored first, so pulling down the shade isn't a new session. The check takes the live portion as a parameter:

suspend fun overLimit(budget: AppBudget, extraDailyMillis: Long = 0L, extraWeeklyMillis: Long = 0L): Result? {
    val weeklyLimit = budget.weeklyMillis
    if (weeklyLimit != null && usageStatsSource.weekForegroundMillis(budget.packageName) + extraWeeklyMillis >= weeklyLimit) {
        return Result(Period.WEEKLY)
    }
    if (usageStatsSource.todayForegroundMillis(budget.packageName) + extraDailyMillis >= budget.dailyMillis) {
        return Result(Period.DAILY)
    }
    return null
}

Weekly is checked first because, as the KDoc puts it, "that's the one that actually determines when access returns." That choice decides which message the block screen shows: "Limit reached — more time tomorrow" or "Limit reached — more time next week."

6. Landing the block on time

Accessibility events only arrive when something changes, and as a comment in the service puts it, the next one "might never come if the user just sits on one screen." So when a budgeted app comes to the front under its limit, the service arms a timer for the remaining time:

private suspend fun scheduleBudgetCloseJob(pkg: String, budget: AppBudget) {
    budgetCloseJobs.remove(pkg)?.cancel()
    if (budget.action != BudgetAction.BLOCK) return
    val dailyRemaining = budget.dailyMillis - usageStatsSource.todayForegroundMillis(pkg)
    val weeklyRemaining = budget.weeklyMillis?.let { it - usageStatsSource.weekForegroundMillis(pkg) }
    val remaining = listOfNotNull(dailyRemaining, weeklyRemaining).filter { it > 0 }.minOrNull() ?: return
    budgetCloseJobs[pkg] = scope.launch {
        delay(remaining + 250)
        // ...
        for (attempt in 0 until RECHECK_ATTEMPTS) {
            if (lastForegroundPackage != pkg) return@launch
            val fresh = budgetRepository.budget(pkg) ?: return@launch
            val ongoing = ongoingSessionMillis(pkg)
            val overLimit = budgetLimitChecker.overLimit(fresh, extraDailyMillis = ongoing, extraWeeklyMillis = ongoing)
            if (overLimit != null) {
                handleBudgetLimitReached(pkg, overLimit.period)
                return@launch
            }
            delay(RECHECK_INTERVAL_MS)
        }
    }
}

When it fires, it re-reads the budget from Room (it may have been raised or deleted), confirms the app is still in front, and runs the live check again. If the read comes up just short, it retries five times, two seconds apart.

The job is cancelled when the app leaves the foreground, because a budget only accrues on screen. Our reminder timers do the opposite and keep counting in the background.

Two more paths cover the gaps. Window events inside a budgeted app trigger evaluateBudgetIfDue, at most once every 15 seconds per app. And a limit crossed while the user is elsewhere is deferred:

private suspend fun handleBudgetLimitReached(pkg: String, period: BudgetLimitChecker.Period) {
    if (pkg == lastForegroundPackage) {
        withContext(Dispatchers.Main) { runCatching { showLimitReachedTakeover(pkg, period) } }
    } else {
        markPendingBudgetLimitReached(pkg, period)
    }
}

A pending limit is the first thing checked when that app is next switched into.

There is no stored "blocked until midnight" flag. A comment in the service says "a block must never be a separately-tracked fact that can go stale," and the checker's KDoc spells out the payoff: "a raised limit lifts a block the moment it's saved." The settings list of limit-blocked apps re-runs overLimit every 20 seconds instead of reading a table.

7. Notify, track, and milestone nudges

NOTIFY posts "Daily limit reached" (or weekly) and lets the app keep running. TRACK only counts; every budgeted app also gets a progress ring on its Home tile. With "Notify me at 50% and 80% of the limit" on, the same 15-second check posts milestone nudges, deduped per period:

@Synchronized
private fun notifyOncePeriod(period: String, kind: String, pkg: String, title: String, text: String) {
    val today = LocalDate.now().toString()
    if (today != notifiedDate) {
        notifiedDate = today
        notifiedKeys.removeAll { it.startsWith("daily|") }
    }
    val weekTag = currentWeekStart().toString()
    if (weekTag != notifiedWeekTag) {
        notifiedWeekTag = weekTag
        notifiedKeys.removeAll { it.startsWith("weekly|") }
    }
    val key = "$period|$kind|$pkg"
    if (!notifiedKeys.add(key)) return
    postNotification(title, text, key)
}

8. Trade-offs

No usage access, no history. Without the permission every historical read is 0L, so a limit only sees the current continuous session.
Event retention. The queryEvents reference says "Events are only kept by the system for a few days." A weekly cap replays everything since Monday, so how much of the log a device keeps limits how accurate the weekly total can be late in the week.
Cost. Each check replays the log since midnight or Monday and filters by package in Kotlin. We accept that work for numbers that reset exactly when we say they do.
It needs the service. The close job, deferred takeover and nudges all run in the accessibility service.

Wrapping up

For a limit that resets at a fixed time, replay queryEvents and clip to your window instead of trusting interval buckets.
Count active activities per package rather than pairing events.
Use atStartOfDay(zone) and a fixed Monday for boundaries; keep rolling windows for suggestions.
Add the live session from elapsedRealtime() on top of the historical total.
Arm a timer for the remaining time, re-verify when it fires, and never store "blocked" as a fact.

For the product side of limits versus blocks versus reminders, see app limits vs. blocking vs. reminders.

How do you measure foreground time on Android: events, aggregates, or something else? And how do you handle the day boundary? Tell us in the comments.

This article was drafted with AI assistance and reviewed by the ReClaim team.

One parser, three readers: how our Next.js blog serves browsers, search engines, and Medium's importer

ReClaim — Tue, 20 Oct 2026 15:50:07 +0000

A post on our blog gets read by at least three kinds of client. People read it in a browser. Search crawlers want the text in the HTML, plus some structured data. And Medium's import tool, which we use to syndicate posts, fetches the page remotely and has to find the images by itself.

We're building MotionLab, personalized stretching and mobility sessions. Earlier posts in this series covered our AI session builder, our Postgres push queue, and billing. This one is about the blog. Posts are stored as TypeScript data. A small parser turns plain strings into typed blocks, and that one parse feeds the rendered page, the JSON-LD and the metadata. It also covers the two fixes it took before Medium imports kept our images.

Stack: Next.js 16.2 (App Router), React 19.2, TypeScript. There's no Markdown or MDX library in package.json; the formatting rules live in one file, src/lib/content/blog-format.ts. Snippets are trimmed from the real code; // ... marks cuts.

1. Posts are data, publishing is a commit

Every post is an entry in a Record keyed by slug, in the route file itself:

interface PostData {
  title: string;
  category: string;
  readTime: string;
  metaDescription: string;
  heroImage?: string;
  heroAlt?: string;
  keyTakeaways: string[];
  sections: { heading: string; content: string }[];
}

// ...
const POSTS: Record<string, PostData> = {
  // ...
};

// ...
export const publishedBlogSlugs = Object.keys(POSTS);

export async function generateStaticParams() {
  return publishedBlogSlugs.map((slug) => ({ slug }));
}

generateStaticParams lists every key, so Next.js can prerender each post at build time. sitemap.ts imports publishedBlogSlugs, so a new key lands in the sitemap without a second edit. There's no CMS and no database read at request time.

Each section's content is a plain string with a few Markdown-like conventions. One section of our desk neck-stretch post, for example, is an intro paragraph, a blank line, then numbered steps written like 1. Chin tuck: Look straight ahead and gently slide your chin straight back....

2. First, put the article in the HTML

The root layout wraps every page in a ClientOnly component. This is what it used to look like:

// Renders AuthProvider only on the client — prevents Firebase SDK from running during SSR/build
const AuthProvider = dynamic(() => import("./AuthProvider"), { ssr: false });

export default function ClientOnly({ children }: { children: ReactNode }) {
  return <AuthProvider>{children}</AuthProvider>;
}

The intent was to keep the auth SDK out of server rendering. The side effect was that children, meaning every page, sat inside a component that never renders on the server. Anything that read our raw HTML without running JavaScript got none of the page content.

AuthProvider subscribes to auth state in a useEffect and copies the user, profile and subscription state into Zustand stores. It doesn't provide React context, so it never needed to wrap anything:

// The auth listener stays client-only. Children render on the server so public
// pages, including the blog, are in the HTML.
const AuthProvider = dynamic(() => import("./AuthProvider"), { ssr: false });

export default function ClientOnly({ children }: { children: ReactNode }) {
  return (
    <>
      {children}
      <AuthProvider>{null}</AuthProvider>
    </>
  );
}

The listener still only runs in the browser, and the pages render on the server. If a client-only provider wraps your whole tree, check whether it really needs to be a wrapper.

3. A parser with a small grammar

The parser's output is a small union type:

export type Block =
  | { type: "h3"; text: string }
  | { type: "p"; inlines: Inline[] }
  | { type: "ul"; items: Inline[][] }
  | { type: "ol"; items: Inline[][] }
  | { type: "figure"; src: string; alt: string; credit?: string };

parseBlocks splits the content on blank lines, trims each line, and hands each chunk to parseLines, which tries a fixed list of rules in order:

A chunk whose first line is exactly ![alt](src) becomes a figure, either on its own or followed by an italic credit line like *Photo: Unsplash*.
A chunk where every line is a - or * bullet becomes a ul. Two or more lines that are all numbered become an ol.
A chunk that starts with a bold label can become an h3, with the rest as a paragraph or a list under it.
A single line shaped like 1. Chin tuck: Look straight ahead... becomes an h3 ("1. Chin tuck") plus a paragraph.
Anything else is one paragraph, with its lines joined by spaces.

The bold-label rule is the fussiest, because plenty of sentences start with bold text without being headings:

function headingFromLine(line: string): { heading: string; rest: string } | null {
  const full = line.match(/^\*\*([^*]+)\*\*$/);
  if (full) {
    const heading = cleanHeading(full[1]);
    if (heading.length >= 3 && heading.length <= 120) return { heading, rest: "" };
  }
  const lead = line.match(/^\*\*([^*]+)\*\*([:.]?)\s*(.*)$/);
  if (!lead) return null;
  // ...
  const numbered = /^\d{1,2}\.\s+\S/.test(label);
  const question = label.endsWith("?");
  if (!numbered && !punct && !question) return null;
  if (!numbered && !punct && question && rest.length > 0 && /^[a-z]/.test(rest)) return null;
  return { heading: cleanHeading(label), rest };
}

A bold line on its own is a heading. A bold lead-in only counts when the label ends with a colon or period (inside or just outside the **), is numbered, or is a question. So **When to see a professional.** Stretching is... gets a heading, but **Runners** are the most common... stays a sentence.

Inline parsing is one regex for bold, italic and links. A link only becomes a link if its href passes safeHref:

function safeHref(href: string): boolean {
  if (href.startsWith("/") && !href.startsWith("//")) return true;
  try {
    const url = new URL(href);
    return url.protocol === "https:" || url.protocol === "http:";
  } catch {
    return false;
  }
}

Site-relative paths and http(s) URLs pass. Protocol-relative //host and javascript: don't, and those fall back to plain text. BlogProse renders the blocks as ordinary React elements, so the article body gets React's normal escaping and never goes through dangerouslySetInnerHTML.

4. The same parse, as structured data

Because the content is already typed blocks, structured data doesn't need a second pass over the raw text. faqsFromSections collects question headings (section headings or h3s ending in ?) and pairs each with the first paragraph under it. Answers under 40 characters are skipped, long ones are capped at 500, and fewer than two questions means no FAQ at all. howToFromSections looks for numbered h3 steps followed by a paragraph, and keeps the section with the most steps if it has at least three.

buildBlogGraph always emits a BlogPosting and a BreadcrumbList, and adds FAQPage and HowTo when those helpers find something. The page writes the graph into a script tag:

export function jsonLd(data: unknown): string {
  return JSON.stringify(data).replace(/</g, "\\u003c");
}

// ...
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLd(graph) }} />

JSON.stringify doesn't escape <, so a </script> in a title or answer would close the tag early. \u003c parses back to the same JSON.

One caveat before you invest in FAQ and HowTo markup: Google changed both in 2023. FAQ rich results now only show for "well-known, authoritative government and health websites", and HowTo rich results were deprecated. Google also says unused structured data "does not cause problems". Ours comes out of a parse the page already does, so it's cheap to keep, but don't expect it to change how your results look.

5. Titles and descriptions from the same fields

Our post titles run long, and the root layout has a "%s | MotionLab" title template. seoTitle builds the <title> from the title's first clause:

export function primaryPhrase(title: string): string {
  const cut = title.split(/:\s|\s\|\s|\s[–—]\s/)[0].trim();
  return cut.replace(/\s*\([^)]*\)\s*/g, " ").replace(/\s+/g, " ").trim();
}

// ...
export function seoTitle(title: string): string {
  let phrase = primaryPhrase(title);
  if (phrase.length < 18) {
    phrase = title.replace(/\s*\([^)]*\)\s*/g, " ").replace(/\s+/g, " ").trim();
  }
  if (phrase.length + BRAND.length <= 60) return phrase + BRAND;
  if (phrase.length <= 60) return phrase;
  return trimAtWord(phrase, 60 - BRAND.length) + BRAND;
}

"Power Training and Mobility: Why the Two Go Together (And How to Balance Both)" becomes "Power Training and Mobility | MotionLab". When it has to truncate, trimAtWord cuts at a space and drops trailing words like "to" and "the". generateMetadata passes the result as title: { absolute: title }, which skips the layout template so the brand doesn't appear twice.

metaDescription works the same way for descriptions: keep it if it fits in 160 characters, otherwise cut at the last sentence end after character 100, then at a clause break, and only then at a word.

6. Getting Medium's importer to keep the images

Medium's help center says the import tool hands the URL to a third-party service that returns the page's contents "to the best of their ability". Our images needed two fixes.

Fix one: absolute URLs, plain <img>. next/image renders a relative /_next/image?url=... optimizer URL, and our content uses root-relative paths like /images/blog/.... Both only work if the reader resolves them against our domain, and the optimizer URL also depends on our image endpoint. Now every image source goes through one helper:

export const SITE_URL = "https://motion-lab.io";

// Blog images must render with absolute URLs so off-site importers
// (Medium's medium.com/p/import, RSS readers, scrapers) can fetch them.
// Relative paths resolve the same way a browser would on /blog/<slug>.
export function absoluteUrl(src: string): string {
  try {
    return new URL(src, `${SITE_URL}/blog/`).toString();
  } catch {
    return src;
  }
}

With /blog/ as the base, /images/a.jpg resolves to https://motion-lab.io/images/a.jpg and a bare img.jpg to /blog/img.jpg, as a browser would on /blog/<slug>. The same helper feeds og:image, the Twitter card and the JSON-LD image.

Fix two: no loading="lazy" on body images. The first fix used a plain <img loading="lazy">. Two days later we took the attribute off body images:

<figure key={index} className="my-8">
  <div className="relative w-full aspect-[3/2] rounded-2xl overflow-hidden border border-ml-border">
    {/* Plain <img> with an absolute src (not next/image's /_next/image URL)
        so Medium imports and other off-site readers can fetch it.
        No loading="lazy": Medium's importer drops lazy images. */}
    {/* eslint-disable-next-line @next/next/no-img-element */}
    <img
      src={absoluteUrl(block.src)}
      alt={block.alt}
      decoding="async"
      className="absolute inset-0 h-full w-full object-cover"
    />
  </div>
  {/* ... */}
</figure>

The hero image gets the same treatment, with fetchPriority="high" and no loading attribute. The trade-off is real: blog pages no longer get next/image resizing or the AVIF/WebP formats our next.config.ts enables for the optimizer. Browsers get the original files, which in our posts are almost all JPEGs.

7. Related reading without a database

The links at the bottom of a post come from POSTS too. relatedReading sorts the slugs in the post's category alphabetically and walks outward from the current one, alternating next and previous, until it has five. Then it adds up to two guides whose keywords appear in the slug or title. It's deterministic: the same build always produces the same links.

Wrapping up

Check that your content is in the server HTML before tuning anything else. A client-only wrapper around children can quietly take it out.
When one team writes all the content, a small grammar you own can be enough. Keep the rules next to the parser.
Parse once into typed blocks, then derive the page, the JSON-LD and the metadata from them.
Escape < in inline JSON-LD.
If other services import your pages, give them absolute image URLs and plain <img> tags, and watch out for loading="lazy".

You can see the output on the MotionLab blog: view source on any post for the server-rendered HTML and the JSON-LD.

Do you hand-roll formatting like this, or reach for MDX or remark? And if you syndicate to Medium, what else have you found its importer drops? Tell us in the comments.

This post was drafted with AI assistance and reviewed by the MotionLab team.

Racing AlarmManager with a coroutine: app reminder timers on Android

ReClaim — Thu, 15 Oct 2026 15:20:28 +0000

An app timer on Android sounds simple: pick a number of minutes, wait, then interrupt. In practice three clocks have to agree: the one the user sees, the one that survives your process being killed, and the one that fires on time while they're still in the app.

We're building ReClaim, a minimalist Android launcher with intentional-use reminders. When you open a reminded app, ReClaim asks how long you mean to stay. When that commitment runs out, it either shows a "time's up" screen or sends you Home. This post is the plumbing behind that timer: why it skips exact alarms, how an in-process countdown races AlarmManager, and how the ongoing notification shows a live countdown without us re-posting it every second.

Stack: Kotlin, Hilt, Room, DataStore, coroutines, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

1. One commitment, two timers

Exact alarms (setExact, setExactAndAllowWhileIdle) are the obvious tool, but apps targeting Android 12+ need the SCHEDULE_EXACT_ALARM permission for them (unless they're exempt from battery restrictions), and the docs reserve them for user-facing features with a strong need for exact timing, like an alarm clock. ReClaim schedules an inexact wake-up that's still allowed to run in Doze:

suspend fun schedule(packageName: String, appLabel: String, minutes: Int) {
    if (minutes <= 0) return
    val triggerAt = System.currentTimeMillis() + minutes * 60_000L
    val pendingIntent = alarmPendingIntent(packageName, appLabel, minutes)
    // Inexact-but-idle-friendly: no special exact-alarm permission required. The OS is free to
    // defer this by minutes (observed on-device), so it's a reliability backstop, not the primary
    // enforcement — see BlockAccessibilityService's precise in-process countdown for that.
    alarmManager.setAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, triggerAt, pendingIntent)
    // So the prompt doesn't ask again — from any trigger path — while this commitment is live.
    sessionStore.startSession(packageName, triggerAt, minutes, appLabel)
    // The visible, always-checkable answer to "is my timer still running?" — survives the
    // target app (or ReClaim itself) being backgrounded, closed from Recents, or killed.
    ReminderTimerNotification.show(context, packageName, appLabel, triggerAt)
}

Per the AlarmManager reference, setAndAllowWhileIdle always allows batching. Android won't dispatch these alarms more than about once a minute under normal operation, and in low-power idle that gap "may be significantly longer, such as 15 minutes." That's fine for a backstop that has to survive process death. It's not fine as the moment the user feels.

So the precise path lives in the accessibility service ReClaim already uses to watch which app is in front. While that service is alive, a coroutine waits out the remaining wall-clock time and calls the same expiry function the alarm uses:

private suspend fun scheduleReminderCloseJob(pkg: String, activeUntil: Long) {
    reminderCloseJobs.remove(pkg)?.cancel()
    val remaining = activeUntil - System.currentTimeMillis()
    if (remaining <= 0) return
    reminderCloseJobs[pkg] = scope.launch {
        // No safety buffer here on purpose — the countdown notification's chronometer keeps
        // ticking (into visibly-wrong negative time) for as long as this takes to fire.
        delay(remaining)
        // Re-verify against a fresh read — the session may have been extended, or already handled
        // by the alarm winning the race — before doing anything visible.
        val stillActive = reminderSessionStore.activeUntil(pkg)
        if (stillActive != null && stillActive > System.currentTimeMillis()) return@launch
        val label = reminderSessionStore.label(pkg) ?: labelOf(pkg)
        val minutes = reminderSessionStore.minutes(pkg) ?: 0
        reminderScheduler.fireExpiry(pkg, label, minutes)
    }
}

One detail that's easy to get wrong: ReClaim's App Limit timer is cancelled when the app leaves the foreground, because limit usage only builds up while you're looking at the app. The reminder job is deliberately not cancelled. The field's comment calls a reminder "a wall-clock commitment that keeps counting down in the background, by design." Ten minutes means ten minutes, even if you hop over to Maps halfway through.

2. Persist the session, not just the alarm

The "how long?" prompt mustn't ask again every time Recents brings the app back. The end time, the minutes and the label go into DataStore, keyed by package name:

/**
 * Tracks, per app, when its current "how long" commitment runs out — so the reminder prompt only
 * asks again once that time has actually elapsed, no matter how the app was reopened (ReClaim's own
 * UI, Recent Apps, a notification, another launcher, …). Kept in DataStore rather than memory so it
 * survives the accessibility service's process being killed mid-session.
 */
@Singleton
class ReminderSessionStore @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    // ...
    suspend fun startSession(packageName: String, untilMillis: Long, minutes: Int, label: String) {
        store.edit {
            it[key(packageName)] = untilMillis
            it[minutesKey(packageName)] = minutes
            it[labelKey(packageName)] = label
        }
    }
}

When a reminded app comes to the front, the service either re-arms the countdown for whatever time is left, or shows the prompt:

private fun evaluateReminderIfNeeded(pkg: String) {
    if (pkg !in reminderPackages) return
    scope.launch {
        val activeUntil = reminderSessionStore.activeUntil(pkg)
        if (activeUntil != null && activeUntil > System.currentTimeMillis()) {
            scheduleReminderCloseJob(pkg, activeUntil)
            return@launch
        }
        val intent = ReminderPromptActivity.intent(this@BlockAccessibilityService, pkg)
            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        withContext(Dispatchers.Main) { runCatching { startActivity(intent) } }
    }
}

Re-arming on every switch means the countdown always reflects the current commitment, including one just extended with "add time." Every confirm path calls schedule() again. The broadcast PendingIntent is built with request code packageName.hashCode() and FLAG_UPDATE_CURRENT, so a new schedule for the same app replaces its old alarm instead of adding a second one.

3. Let the OS draw the countdown

Users need a way to check the timer is still running. ReClaim posts an ongoing notification and lets the system render the clock:

val notification = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_notification)
    .setContentTitle(label)
    .setContentText("Reminder running — closes automatically when time's up")
    .setOngoing(true)
    .setOnlyAlertOnce(true)
    .setSilent(true)
    .setPriority(NotificationCompat.PRIORITY_LOW)
    .setCategory(NotificationCompat.CATEGORY_PROGRESS)
    .setUsesChronometer(true)
    .setChronometerCountDown(true)
    .setWhen(expiresAt)
    .setShowWhen(true)
    // Belt-and-suspenders against the chronometer ever visibly counting into negative time:
    // the OS clears this on its own right at expiry even if nothing in-app gets a chance to
    // run (process killed, service off) — see ReminderScheduler.fireExpiry for the normal path.
    .setTimeoutAfter(expiresAt - System.currentTimeMillis())
    .apply { if (contentIntent != null) setContentIntent(contentIntent) }
    .build()

setUsesChronometer(true) shows the when field as an automatically updating timer, and setChronometerCountDown(true) (API 24+) makes it count down toward setWhen(expiresAt). Nothing in our process ticks. setTimeoutAfter (API 26+, which matches our minSdk) cancels the notification at the deadline even if ReClaim never gets to run again.

The notification goes on a low-importance channel created in Application.onCreate(), described as "Ongoing countdown while an App Reminder session is running, and a quiet note when it ends."

4. One expiry function, two callers

The alarm lands in a Hilt-injected receiver, which hands off immediately:

@AndroidEntryPoint
class ReminderReceiver : BroadcastReceiver() {

    @Inject lateinit var reminderScheduler: ReminderScheduler

    override fun onReceive(context: Context, intent: Intent) {
        val packageName = intent.getStringExtra(EXTRA_PACKAGE) ?: return
        val label = intent.getStringExtra(EXTRA_LABEL) ?: "your app"
        val minutes = intent.getIntExtra(EXTRA_MINUTES, 0)
        reminderScheduler.fireExpiry(packageName, label, minutes)
    }
    // ...
}

fireExpiry is where the race gets settled. Its KDoc says it's "safe to run twice in the rare case both fire close together":

fun fireExpiry(packageName: String, label: String, minutes: Int) {
    cancelAlarm(packageName)
    ReminderTimerNotification.cancel(context, packageName)
    reminderRepository.notifyExpired(packageName, label, minutes)

    appScope.launch {
        val host = hostFromSiteKey(packageName)
        val action = if (host != null) {
            websiteReminderRepository.expireAction(host)
        } else {
            reminderRepository.expireAction(packageName)
        }
        if (action == ReminderExpireAction.CLOSE) return@launch
        postExpiredNotification(packageName, label, minutes)
    }
}

The order matters:

Cancel the alarm first. If the coroutine won, the broadcast never arrives.
Cancel the countdown notification.
Emit an ExpiredReminder on a MutableSharedFlow(extraBufferCapacity = 4) so the accessibility service can react. tryEmit never suspends, so the receiver path stays short.
Post a silent "Time's up on …" notification that opens the takeover screen, but only for the default Prompt action. For Close it's skipped on purpose. The comment explains that tapping it "would otherwise reopen the very 'add time?' prompt CLOSE exists to skip, through a back door."

The hostFromSiteKey branch exists because website reminders reuse this path under a site: key (see our website-blocking post).

5. Don't yank the user out of something else

Expiry doesn't always mean "takeover right now." The service collects reminderRepository.expired and checks what's in front:

if (expired.packageName == lastForegroundPackage) {
    // Still on the reminded app right now — this is exactly the moment its
    // configured action (takeover, or straight home) is expected to happen.
    withContext(Dispatchers.Main) { runCatching { handleExpiredReminder(expired) } }
} else {
    // The user already moved on to something else — a full-screen takeover now would
    // interrupt unrelated work. Enforce it instead the moment they switch back into
    // this app (see onAccessibilityEvent), so a minimized/backgrounded reminder app
    // still can't just be silently resumed later with no consequence.
    markPendingExpired(expired)
}

A deferred expiry gets handled the next time that package comes to the front, unless a new session is already active. That check came from a real bug. Reopening through ReClaim's own UI asks "how long?" without looking at the deferred queue, so the old expiry would fire right after the new commitment. In the code's words, that "showed up as 'how long?' and 'your time is up' appearing back to back."

The second trap was System UI. The notification shade, quick settings and volume panel briefly take window focus without the user leaving their app. Counting that as a switch meant a reminder that expired while the shade was open got deferred, and the takeover only showed up at the next real app switch, "well after its own 'time's up' notification." Now window events from com.android.systemui are ignored before lastForegroundPackage is updated.

6. Prompt or close

What happens at expiry is a per-app setting, stored as a nullable string in Room and resolved to a small enum. null means the default:

enum class ReminderExpireAction(val label: String, val description: String) {
    PROMPT(
        "Prompt",
        "The reminder screen pops up instead of Home — leave, or add more time.",
    ),
    CLOSE(
        "Close",
        "Closes the app and takes you straight to the Home screen.",
    ),
}

Only the accessibility service acts on it, because it's the one place that already knows what's in front:

private fun handleExpiredReminder(expired: ExpiredReminder) {
    when (reminderExpireActions[expired.packageName] ?: ReminderExpireAction.PROMPT) {
        ReminderExpireAction.PROMPT -> showExpiredTakeover(expired)
        ReminderExpireAction.CLOSE -> closeToHome(expired.packageName)
    }
}

"Close" doesn't kill anything, since Android gives third-party apps no API to force-stop another app. closeToHome sends a media pause key (KEYCODE_MEDIA_PAUSE, not the play/pause toggle, which could start playback), briefly arms a picture-in-picture dismiss for that one package, and starts the Home intent. The takeover path does the same pause and PiP step before showing its screen.

7. Trade-offs

Late without the service. If the accessibility service isn't running, expiry depends on the inexact alarm alone and can arrive minutes late. That's the cost of not asking for exact-alarm access.
A brief negative countdown. The countdown has no safety buffer, so if it fires a little after expiresAt, the chronometer can briefly show negative time. Cancelling in fireExpiry plus setTimeoutAfter keeps that window short.
Two clocks, one decision. delay() measures elapsed time, while the session's end is wall-clock millis. The close job resolves that by re-reading DataStore and comparing against System.currentTimeMillis() before acting.

Wrapping up

Use an inexact, Doze-friendly alarm as the backstop for process death, not as the clock the user feels.
Race it with a precise in-process delay() while your long-lived service is running, and make expiry idempotent: cancel the alarm first.
Persist the commitment so Recents and notifications don't re-prompt mid-session.
Let NotificationCompat's chronometer draw the countdown.
Defer the takeover when the user is somewhere else, and don't count System UI as an app switch.

For the product side of timers versus blocks versus limits, we wrote up app limits vs. blocking vs. reminders. ReClaim isn't on Google Play yet; it's waitlist-only for now at tryreclaim.io.

Have you shipped a user-facing timer without exact alarms, or found a cleaner way to keep a countdown honest across process death? Tell us in the comments.

This article was drafted with AI assistance and reviewed by the ReClaim team.

Why I Built an Android Launcher That Makes My Phone Harder to Use

ReClaim — Tue, 13 Oct 2026 15:43:56 +0000

Most software I've worked on had the same goal: remove friction. Fewer taps, faster load, smoother onboarding. So it felt strange to start a project whose whole point is to add friction, deliberately, in exactly the right places.

That project is ReClaim, a minimalist Android launcher for people who want to use their phone on purpose. This post is about why I built it as a launcher instead of yet another blocker app, the design decisions that shaped it, and what I learned about building software that wants you to use it less.

The problem: the friction is backwards

Here's the observation that started it. On a typical phone, the most distracting apps are the easiest to reach. They sit on the home screen with bright icons and notification badges, one thumb-tap away. Meanwhile the genuinely useful stuff — your notes, your calendar, your banking app — ends up buried in a folder on page three.

Nobody designed that layout to hurt you. It just accumulates. But the result is that the path of least resistance almost always leads to a feed.

I didn't want to rely on willpower to fix that. Willpower is a finite resource and it's usually lowest exactly when you reach for your phone: tired, bored, waiting in line. What I wanted was to change which actions are easy. Keep productive apps one tap away. Make everything else require a moment of intention first.

Why a launcher, not a blocker

There are plenty of app blockers on Android. I've used several. The recurring problem I ran into is that they sit beside your home screen rather than being it. You still see the icons. You still get the pull. The blocker only steps in after you've already tapped.

A launcher is different. It's the first thing you see every time you unlock your phone. If the home screen itself is calm, a lot of the problem disappears before any blocking kicks in. And because a launcher is your home screen, the rules apply system-wide — set them once, and they're enforced without you having to remember to open another app.

So ReClaim's home screen is intentionally boring: a clock, the favorites you choose, and a plain, icon-free alphabetical app list. No colourful grid, no badges competing for attention. Finding an app means reading its name, which turns out to be a tiny but meaningful speed bump.

Designing the levels of friction

The hardest design question was: how much friction is the right amount? Too little and it's pointless. Too much and people uninstall it in a frustrated moment. I ended up with several tools, each suited to a different relationship with an app.

1. Hard blocks with a timer

Sometimes you just want an app gone. In ReClaim you pick an app and a duration — anywhere from 5 minutes up to a year — and it's unavailable until the timer runs out. There are 18 preset durations, because I found that making people type a custom number was itself a decision point where they'd talk themselves out of it.

One small detail I like: when you block an app, ReClaim suggests other apps you'll probably want to block alongside it. If you block one social app, you're likely to just drift to the next one otherwise.

2. Daily and weekly limits

Not every app deserves a full block. Maybe 20 minutes of a given app per day is fine. With limits, once your time is used up, ReClaim closes the app automatically. No "five more minutes" prompt to negotiate with. And if you genuinely decide you need more, raising the limit lifts the block immediately — the control stays with you, it just requires a conscious choice.

3. Intention reminders

This one is my favourite because it's the gentlest. Before you open an app with a reminder set, ReClaim asks: "How long do you intend to use this?" Then it nudges you when that time is up.

It's a check-in, not a lockout. In my experience, just being asked that question is often enough to change what happens next. Sometimes the honest answer is "I don't actually need to open this."

4. Scheduled blocking

Work hours, bedtime, weekends — recurring windows where specific apps simply aren't available. This removes the daily decision entirely. You decide once, on a calm Sunday afternoon, and future-you doesn't have to fight about it at 11:40 PM.

5. Three levels of hidden apps

Some apps you want to keep installed but out of sight. ReClaim has three levels of hiding friction: hidden behind nothing (just out of the list), hidden behind a puzzle, or hidden behind a real deterrent. The idea is to match the friction to how strong the habit is.

Guardrails I refused to compromise on

Building something that restricts access to a phone comes with responsibility. A few rules I set early:

Emergency apps are never blocked by default. A focus tool should never get between you and a call you actually need to make.
Your other apps work normally. ReClaim changes how you reach apps, not how they behave once open.
No ads, ever. It would be absurd to build a tool against attention-harvesting and then monetise attention.
No account required. You shouldn't need to sign up for anything to have a calmer home screen.

That last two shaped a lot of decisions. If there's nothing to gain from keeping people on-screen, you stop designing for engagement and start designing for the moment someone puts the phone down.

What I learned about "anti-engagement" design

A few lessons that I think apply beyond launchers:

Friction is a design material. We usually treat it as a bug. But a well-placed pause is one of the most respectful things software can offer. The trick is placing it where the user would want it, if they were thinking clearly.

Choices beat walls. The features people (including me) stick with are the ones that preserve agency. A reminder that asks a question respects you more than a lock that assumes you can't be trusted.

Defaults matter more than features. The plain, text-only app list does more quiet work than any individual blocking feature, simply because it's what you see every single time.

Make the escape hatch honest. If raising a limit is possible, make it clear and immediate. Hidden escape hatches feel manipulative; honest ones build trust.

Where it's at

ReClaim is free, and you can follow along or join the waitlist at tryreclaim.io. If you've built anything in the digital wellbeing space, or have strong opinions about how much friction is too much, I'd genuinely love to hear them in the comments — this is the part of the design I'm still learning the most about.

The question I keep coming back to is the one the whole launcher is built around: does this make it easier to use my phone on purpose, or easier to lose an hour to it? It turns out that's a pretty good question for most software.

DEV Community: ReClaim

A text-only app drawer in Jetpack Compose: an A–Z scrubber, a recent-installs section, and the index math between them

1. One sorted list feeds everything

2. The letter index is just "first index per bucket"

3. The scrubber: one gesture loop, drag included

4. The section above the list breaks the math

5. Search: two entry points, one rule

6. Folders that reorder by long-press

What's still open

What we'd tell another team

Five Android permissions, five different checks: building a setup gate that re-checks on resume

One snapshot, five booleans

Five checks, five APIs

1. Notifications: the only real runtime permission

2. Usage access: an app op, not a permission

3. System-wide blocking: a string in secure settings

4. Battery: an allowlist, and a policy question

5. Default launcher: the role and the real answer

Re-check on resume, not on result

A gate you can always walk past

What's still open

What we'd tell another team

The edge cases after shipping: re-arming Android alarms after a reboot and counting app usage across midnight

Edge case 1: a reboot wipes the timer

Why a wall-clock end time helps here

Step 1: know which sessions still owe an expiry

Step 2: a receiver for boot and app updates

Step 3: re-arm or expire

Edge case 2: a session that crosses midnight

The fix: read earlier, count only inside the window

Why pull it out of the Android code

The trade-offs of a fixed lookback

What's still open

What we'd tell another team

Take the break at the commit: what rest-break studies found, plus a tiny git hook

What the studies found

NIOSH's data-entry field studies

Shorter breaks, and whether people take them

The meta-analysis

How strong is all this?

What I took from it

The tool: a post-commit nudge

Hook it into one repo

Or hook it into every repo

What it looks like

Limitations

What to do with the few minutes

When to see a clinician

Sources

Unlock challenges that fail when you look away: attention-gated friction in Jetpack Compose

1. Challenge types are data, and levels pick from them

2. Per-app overrides with null meaning "use the default"

3. Levels 2 and 3: friction against autopilot

4. Follow the circle: a game loop inside LaunchedEffect

5. Find the shape: a conjunction search

6. Watch the words: recognition isn't enough

7. Don't ask twice: a ten-second grace window

8. The bug that taught us "a challenge is its own gate"

What we'd tell another team building friction

Backup and restore for an Android launcher with Room: debounced snapshots and an empty-database gate

1. One JSON file, kept outside databases/

2. Auto-backup: merge every table, debounce, write

3. The trap: an empty database will happily back itself up

4. Restore in one Room transaction

5. Export: one zip through the Storage Access Framework

6. Import: treat the file as hostile

7. Apps that aren't installed yet

8. The background image, and what the platform allows

9. Why not just rely on Auto Backup?

What we'd tell another app team

Creator referrals with Next.js and Supabase: first-touch attribution and one commission per payment

1. The link: /c/{slug}

2. Recording attribution once, inside Postgres

3. One commission row per payment

4. Google Play: order ids and a daily catch-up

5. Undoing commissions

6. The holding period and payouts

What we'd keep, and what we'd change

Daily app limits on Android: replaying UsageEvents instead of trusting the daily buckets

1. Usage access is a special permission

2. Per-app overrides with `null` meaning "use the default"

4. Follow the circle: a game loop inside `LaunchedEffect`

1. One JSON file, kept outside `databases/`

1. The link: `/c/{slug}`