expo-app-blocker 0.1.63 → 0.1.64

package/README.md

@@ -486,7 +486,12 @@ const config = getBlockConfiguration();
 clearAllBlocks();
 ```
 
-### iOS: Temporary Unlock
+### Temporary Unlock (usage-based)
+
+`temporaryUnlock(minutes)` grants a budget of earned minutes that is consumed
+**only while a blocked app is actually in the foreground** — leaving the blocked
+app pauses the budget; returning resumes it. When the budget is spent, the apps
+re-block.
 
 ```typescript
 import {
@@ -496,45 +501,27 @@ import {
   relockApps,
 } from 'expo-app-blocker';
 
-// Unlock for N minutes (removes shields temporarily)
+// Grant N minutes of usage budget for the blocked apps
 const result = await temporaryUnlock(15);
-// { unlocked: boolean, expiresAt: number }
+// { unlocked: true, expiresAt: number }  (expiresAt is a best-effort hint only)
 
-const unlocked = isTemporarilyUnlocked(); // boolean
-const seconds = getRemainingUnlockTime(); // seconds remaining
-await relockApps();                        // re-lock immediately
+const seconds = getRemainingUnlockTime(); // seconds of budget remaining, 0 if none
+await relockApps();                        // drop the budget now, re-block immediately
 ```
 
-### Android: Temporary Unlock
-
-The same temporary-unlock API works on Android. The foreground service pauses
-blocking for the requested duration and auto-resumes when it expires — the timer
-lives in the service, so it survives your app being backgrounded.
+**How each platform enforces it:**
 
-```typescript
-import {
-  temporaryUnlock,
-  getRemainingUnlockTime,
-  relockApps,
-} from 'expo-app-blocker';
-
-// Suppress blocking for N minutes; auto-resumes on expiry
-await temporaryUnlock(15);
-// { unlocked: true, expiresAt: number }
-
-const seconds = getRemainingUnlockTime(); // seconds remaining, 0 if none
-await relockApps();                        // end the unlock now, re-block immediately
-```
-
-| Function | Android behavior |
-|---|---|
-| `temporaryUnlock(minutes)` | Suppresses blocking for `minutes` (min 1, rounded). Replaces any active unlock. |
-| `getRemainingUnlockTime()` | Seconds left on the active unlock, or `0`. Backed by a persisted expiry, so it's accurate without the app holding service state. |
-| `relockApps()` | Ends the unlock immediately and re-blocks the foreground app on the next poll. |
-| `isTemporarilyUnlocked()` | iOS only — returns `false` on Android. Use `getRemainingUnlockTime() > 0` instead. |
-
-> When an unlock expires while the user is still inside a blocked app, the
-> deep link fires with `reason=expired` (see [Deep-link contract](#deep-link-contract-how-your-app-is-launched)).
+| | Android | iOS |
+|---|---|---|
+| Mechanism | Foreground-service poll consumes the budget each tick spent inside a blocked app | DeviceActivity usage-threshold event re-applies the Family Controls shield after N minutes of measured usage |
+| `getRemainingUnlockTime()` | Live — ticks down while inside a blocked app, freezes otherwise | Returns the **granted** budget; iOS can't expose live usage, so it stays flat until the threshold fires (then `0`) |
+| `isTemporarilyUnlocked()` | Returns `false` (use `getRemainingUnlockTime() > 0`) | `true` while budget remains |
+| Caveats | — | Apple thresholds are unreliable below a few minutes; unspent budget is cleared at the daily schedule boundary (midnight) |
+
+> **Android only:** when the budget runs out while the user is still inside a
+> blocked app, the deep link fires with `reason=expired` (see
+> [Deep-link contract](#deep-link-contract-how-your-app-is-launched)) so you can
+> show a "time's up" screen instead of a cold block.
 
 ### iOS: Shield Button Events
 

package/android/src/main/java/expo/modules/appblocker/AppBlockerService.kt

@@ -20,31 +20,63 @@ import androidx.core.app.NotificationCompat
 class AppBlockerService : Service() {
   private val handler = Handler(Looper.getMainLooper())
   private var lastForegroundPackage: String? = null
+  // Last *known* foreground app. UsageStats only reports recent transitions, so a
+  // poll can momentarily read null while the user sits in one app — we retain the
+  // last non-null reading so earned-time consumption and re-blocking stay reliable.
+  private var currentForeground: String? = null
   private lateinit var overlayManager: OverlayManager
-  private val unlockController by lazy { TemporaryUnlockController(this, handler) }
-  private var wasUnlocked = false
+  private val unlockController by lazy { TemporaryUnlockController(this) }
+  // Timestamp of the last tick spent consuming earned time; 0 when not consuming.
+  private var consumingSinceMs = 0L
+  // Whether a block is currently being enforced (overlay shown / app redirected).
+  private var blocking = false
 
   private val pollRunnable = object : Runnable {
     override fun run() {
-      if (unlockController.isUnlocked) {
-        wasUnlocked = true
+      tick()
+      handler.postDelayed(this, POLL_INTERVAL_MS)
+    }
+  }
+
+  private fun tick() {
+    getCurrentForegroundPackage()?.let { currentForeground = it }
+    val foreground = currentForeground
+
+    if (foreground == null || !isBlocked(foreground)) {
+      // Outside any blocked app: pause consumption and drop any active block.
+      consumingSinceMs = 0L
+      clearBlock()
+      lastForegroundPackage = foreground
+      return
+    }
+
+    if (unlockController.hasTimeLeft) {
+      // Inside a blocked app with earned time — spend it and keep the app usable.
+      val now = System.currentTimeMillis()
+      if (consumingSinceMs > 0L) unlockController.consume(now - consumingSinceMs)
+      consumingSinceMs = now
+      if (unlockController.hasTimeLeft) {
+        clearBlock()
       } else {
-        val foregroundPackage = getCurrentForegroundPackage()
-        val unlockJustExpired = wasUnlocked
-        wasUnlocked = false
-
-        if (unlockJustExpired && foregroundPackage != null && isBlocked(foregroundPackage)) {
-          // Earned time ran out while the user was still inside a blocked app.
-          Log.d(TAG, "Unlock expired in foreground app: $foregroundPackage")
-          lastForegroundPackage = foregroundPackage
-          block(foregroundPackage, BlockReason.EXPIRED)
-        } else if (foregroundPackage != null && foregroundPackage != lastForegroundPackage) {
-          Log.d(TAG, "Foreground changed: $foregroundPackage")
-          lastForegroundPackage = foregroundPackage
-          handleForegroundChange(foregroundPackage)
-        }
+        // Earned time ran out while still inside the app.
+        Log.d(TAG, "Earned time exhausted in foreground app: $foreground")
+        enforceBlock(foreground, BlockReason.EXPIRED)
+      }
+    } else {
+      // Inside a blocked app with no earned time — block on entry.
+      consumingSinceMs = 0L
+      if (!blocking || foreground != lastForegroundPackage) {
+        Log.d(TAG, "Blocked app in foreground: $foreground")
+        enforceBlock(foreground, BlockReason.OPENED)
       }
-      handler.postDelayed(this, POLL_INTERVAL_MS)
+    }
+    lastForegroundPackage = foreground
+  }
+
+  private fun clearBlock() {
+    if (blocking) {
+      overlayManager.hide()
+      blocking = false
     }
   }
 
@@ -62,18 +94,11 @@ class AppBlockerService : Service() {
   private fun isBlocked(packageName: String): Boolean =
     packageName in AppBlockerPrefs.getBlockedPackages(this)
 
-  private fun handleForegroundChange(foregroundPackage: String) {
-    if (isBlocked(foregroundPackage)) {
-      Log.d(TAG, "Blocked app in foreground: $foregroundPackage")
-      block(foregroundPackage, BlockReason.OPENED)
-    } else {
-      overlayManager.hide()
-    }
-  }
-
-  private fun block(packageName: String, reason: BlockReason) {
+  private fun enforceBlock(packageName: String, reason: BlockReason) {
     overlayManager.show(packageName, reason)
     showBlockedNotification(packageName, reason)
+    blocking = true
+    consumingSinceMs = 0L
   }
 
   private fun showBlockedNotification(packageName: String, reason: BlockReason) {
@@ -141,16 +166,21 @@ class AppBlockerService : Service() {
     when (intent?.action) {
       ACTION_TEMPORARY_UNLOCK -> {
         val minutes = intent.getIntExtra(EXTRA_DURATION_MINUTES, 0)
-        Log.d(TAG, "Temporary unlock for $minutes minutes")
-        unlockController.unlock(minutes)
-        overlayManager.hide()
+        Log.d(TAG, "Granting $minutes minutes of earned time")
+        unlockController.grant(minutes)
+        consumingSinceMs = 0L
+        clearBlock()
       }
       ACTION_RELOCK -> {
-        Log.d(TAG, "Relock: ending temporary unlock")
-        unlockController.relock()
-        // Forget the last-seen app so a blocked app already in the foreground
-        // is re-detected and re-blocked on the next poll.
+        Log.d(TAG, "Relock: dropping earned time")
+        unlockController.clear()
+        consumingSinceMs = 0L
+        // Forget the last-seen app so a blocked app already in the foreground is
+        // re-blocked on the next poll. Clearing currentForeground too avoids a
+        // stale reading wrongly blocking a non-blocked app if the next poll reads null.
         lastForegroundPackage = null
+        currentForeground = null
+        clearBlock()
       }
     }
     return START_STICKY

package/android/src/main/java/expo/modules/appblocker/TemporaryUnlockController.kt

@@ -1,64 +1,63 @@
 package expo.modules.appblocker
 
 import android.content.Context
-import android.os.Handler
 
 /**
- * Single source of truth for the Android "temporary unlock" state.
+ * Single source of truth for the Android "earned time" budget.
  *
- * While unlocked, the monitor should not block — see [isUnlocked]. An unlock
- * auto-expires after the requested duration; [relock] ends it early. The expiry
- * timestamp is persisted (see [Store]) so the JS module can read the remaining
- * time without holding a reference to the running service, mirroring the iOS
- * shared-defaults approach.
+ * Unlock time is a *budget of seconds* that is consumed only while a blocked app
+ * is actually in the foreground — see [AppBlockerService], which calls [consume]
+ * on each poll tick spent inside a blocked app and leaves the budget untouched
+ * otherwise. This gives pause/resume semantics: leaving the blocked app freezes
+ * the remaining time; returning resumes it.
  *
- * Drive [unlock] / [relock] from the same (main) thread the [Handler] is bound to.
+ * The budget is persisted (see [Store]) so the JS module can read it without
+ * holding a reference to the running service, mirroring the iOS approach.
+ *
+ * [consume] and [grant] do a read-modify-write on the persisted budget and are
+ * NOT atomic; the service drives both from the main thread (the poll Handler and
+ * onStartCommand share that thread), which serializes them. Don't call these from
+ * another thread without adding synchronization.
  */
-class TemporaryUnlockController(
-  private val context: Context,
-  private val handler: Handler,
-) {
-  private val expireRunnable = Runnable { Store.clear(context) }
-
-  /** True while a temporary unlock is in effect (blocking should be suppressed). */
-  val isUnlocked: Boolean
-    get() = Store.remainingSeconds(context) > 0
+class TemporaryUnlockController(private val context: Context) {
+  /** True while earned time remains (blocking should be suppressed inside blocked apps). */
+  val hasTimeLeft: Boolean
+    get() = Store.remainingMs(context) > 0
 
-  /** Suppress blocking for [durationMinutes], replacing any pending expiry. No-op if <= 0. */
-  fun unlock(durationMinutes: Int) {
+  /** Grant a fresh budget of [durationMinutes], replacing any existing balance. No-op if <= 0. */
+  fun grant(durationMinutes: Int) {
     if (durationMinutes <= 0) return
-    val durationMs = durationMinutes * 60_000L
-    handler.removeCallbacks(expireRunnable)
-    Store.setExpiry(context, System.currentTimeMillis() + durationMs)
-    handler.postDelayed(expireRunnable, durationMs)
+    Store.setRemaining(context, durationMinutes * 60_000L)
+  }
+
+  /** Spend [elapsedMs] of the budget (clamped at 0). Called while inside a blocked app. */
+  fun consume(elapsedMs: Long) {
+    if (elapsedMs <= 0) return
+    val remaining = Store.remainingMs(context)
+    if (remaining <= 0) return
+    Store.setRemaining(context, (remaining - elapsedMs).coerceAtLeast(0))
   }
 
-  /** End any active unlock immediately, restoring blocking. */
-  fun relock() {
-    handler.removeCallbacks(expireRunnable)
-    Store.clear(context)
+  /** Drop the entire budget immediately, restoring blocking. */
+  fun clear() {
+    Store.setRemaining(context, 0)
   }
 
   /**
-   * Stateless persistence for the unlock expiry. Readable from anywhere with a
+   * Stateless persistence for the remaining budget. Readable from anywhere with a
    * [Context] — the running service is not required.
    */
   companion object Store {
-    private const val KEY_EXPIRES_AT = "temporary_unlock_expires_at"
+    private const val KEY_REMAINING_MS = "temporary_unlock_remaining_ms"
 
-    private fun setExpiry(context: Context, expiresAtMs: Long) {
-      AppBlockerPrefs.get(context).edit().putLong(KEY_EXPIRES_AT, expiresAtMs).apply()
+    private fun setRemaining(context: Context, remainingMs: Long) {
+      AppBlockerPrefs.get(context).edit().putLong(KEY_REMAINING_MS, remainingMs).apply()
     }
 
-    private fun clear(context: Context) {
-      AppBlockerPrefs.get(context).edit().remove(KEY_EXPIRES_AT).apply()
-    }
+    private fun remainingMs(context: Context): Long =
+      AppBlockerPrefs.get(context).getLong(KEY_REMAINING_MS, 0L).coerceAtLeast(0L)
 
-    /** Seconds remaining on the active unlock, or 0 if none / already expired. */
-    fun remainingSeconds(context: Context): Int {
-      val expiresAtMs = AppBlockerPrefs.get(context).getLong(KEY_EXPIRES_AT, 0L)
-      val remainingMs = expiresAtMs - System.currentTimeMillis()
-      return if (remainingMs > 0) (remainingMs / 1000).toInt() else 0
-    }
+    /** Seconds of earned time remaining, or 0 if none. */
+    fun remainingSeconds(context: Context): Int = (remainingMs(context) / 1000).toInt()
   }
 }

package/ios/ExpoAppBlockerModule.swift

@@ -14,8 +14,13 @@ public class ExpoAppBlockerModule: Module {
   private var sharedDefaults: UserDefaults?
   private let userDefaults = UserDefaults.standard
   private let blockConfigStorageKey = "appBlocker.blockConfiguration.v1"
+  // Stores the granted earned-time budget in **seconds** (Int). Presence with a
+  // value > 0 means a temporary unlock is active. Enforcement is usage-based: the
+  // shield is re-applied by the DeviceActivityMonitor once cumulative foreground
+  // usage of the blocked apps reaches the threshold (see `startUsageBasedRelock`).
   private let temporaryUnlockKey = "appBlocker.temporaryUnlock.v1"
   private let unlockActivityName = "appBlocker.temporaryUnlock"
+  private let usageEventName = "appBlocker.usageThreshold"
   private let pendingUnlockKey = "appBlocker.pendingUnlock.v1"
   private let minimumTemporaryUnlockMinutes = 1
   private var didLoadPersistedConfig = false
@@ -199,8 +204,8 @@ public class ExpoAppBlockerModule: Module {
           return
         }
 
-        let expirationDate = Date().addingTimeInterval(TimeInterval(sanitizedDurationMinutes * 60))
-        self.sharedDefaults?.set(expirationDate, forKey: self.temporaryUnlockKey)
+        let budgetSeconds = sanitizedDurationMinutes * 60
+        self.sharedDefaults?.set(budgetSeconds, forKey: self.temporaryUnlockKey)
 
         DispatchQueue.main.async {
           self.store.shield.applications = nil
@@ -208,51 +213,39 @@ public class ExpoAppBlockerModule: Module {
           self.store.shield.webDomains = nil
         }
 
-        // Try to schedule relock, but don't fail if schedule is too short
-        // (Apple requires minimum ~15 min for DeviceActivitySchedule)
+        // Re-block once cumulative *usage* of the blocked apps hits the budget.
+        // iOS only counts foreground time, so the budget pauses/resumes for free.
         do {
-          try self.scheduleRelockActivity(expirationDate: expirationDate)
+          try self.startUsageBasedRelock(minutes: sanitizedDurationMinutes)
         } catch {
-          // Schedule failed (too short) - that's OK, we still unlock.
-          // The app will re-check and relock via checkAndApplyUnlockState
-          // when the expiration passes and user returns to the app.
-          print("[AppBlocker] Schedule relock failed (duration may be too short): \(error.localizedDescription)")
+          // Monitoring failed to start (e.g. threshold below Apple's granularity).
+          // The unlock still happens; the shield falls back to re-applying on the
+          // next app launch via checkAndApplyUnlockState.
+          print("[AppBlocker] Usage-based relock failed to start: \(error.localizedDescription)")
         }
 
+        // `expiresAt` is a best-effort wall-clock hint only — actual relock is
+        // usage-based, so the real expiry depends on how much the apps are used.
+        let approxExpiresAt = Date().addingTimeInterval(TimeInterval(budgetSeconds)).timeIntervalSince1970
         DispatchQueue.main.async {
           promise.resolve([
             "unlocked": true,
-            "expiresAt": expirationDate.timeIntervalSince1970
+            "expiresAt": approxExpiresAt
           ])
         }
       }
     }
 
     Function("isTemporarilyUnlocked") { () -> Bool in
-      guard let expirationDate = self.sharedDefaults?.object(forKey: self.temporaryUnlockKey) as? Date else {
-        return false
-      }
-
-      if Date() < expirationDate {
-        return true
-      }
-
-      self.relockApps()
-      return false
+      return self.remainingUnlockBudgetSeconds() > 0
     }
 
+    // NOTE: On iOS this returns the *granted* budget, not a live remaining count —
+    // Apple does not expose cumulative usage to the app, so the value does not tick
+    // down as the blocked apps are used. It drops to 0 once the usage threshold
+    // re-applies the shield (or on relock).
     Function("getRemainingUnlockTime") { () -> Int in
-      guard let expirationDate = self.sharedDefaults?.object(forKey: self.temporaryUnlockKey) as? Date else {
-        return 0
-      }
-
-      let remaining = expirationDate.timeIntervalSince(Date())
-      if remaining > 0 {
-        return Int(remaining)
-      }
-
-      self.relockApps()
-      return 0
+      return self.remainingUnlockBudgetSeconds()
     }
 
     AsyncFunction("relockApps") { (promise: Promise) in
@@ -348,23 +341,14 @@ public class ExpoAppBlockerModule: Module {
 
     ensureLoadedPersistedConfig()
 
-    if let expirationDate = sharedDefaults?.object(forKey: temporaryUnlockKey) as? Date {
-      let remaining = expirationDate.timeIntervalSince(Date())
-
-      if remaining > 0 {
-        DispatchQueue.main.async {
-          self.store.shield.applications = nil
-          self.store.shield.applicationCategories = nil
-          self.store.shield.webDomains = nil
-        }
-
-        do {
-          try scheduleRelockActivity(expirationDate: expirationDate)
-        } catch {
-          relockApps()
-        }
-      } else {
-        relockApps()
+    if remainingUnlockBudgetSeconds() > 0 {
+      // Unlock still active — keep the shield off. The usage-threshold monitor
+      // started in `temporaryUnlock` persists across app launches and will
+      // re-apply the shield once the usage budget is spent.
+      DispatchQueue.main.async {
+        self.store.shield.applications = nil
+        self.store.shield.applicationCategories = nil
+        self.store.shield.webDomains = nil
       }
     } else if let config = currentBlockConfig {
       do {
@@ -497,49 +481,56 @@ public class ExpoAppBlockerModule: Module {
 
   // MARK: - Activity Scheduling
 
-  private func scheduleRelockActivity(expirationDate: Date) throws {
+  /// Start usage-based monitoring: re-apply the shield once cumulative foreground
+  /// usage of the blocked apps reaches `minutes`. iOS counts only active usage, so
+  /// the budget naturally pauses when the apps aren't in use and resumes on return.
+  ///
+  /// Uses an all-day repeating schedule purely as a container for the usage event;
+  /// the `eventDidReachThreshold` callback (in the DeviceActivityMonitor extension)
+  /// does the actual relock. `repeats: true` keeps the monitor alive across days so
+  /// apps are never left unlocked without enforcement; the tradeoff is that
+  /// `intervalDidEnd` clears any unspent budget at the day boundary (earned time
+  /// does not carry across midnight).
+  ///
+  /// Note: Apple's usage thresholds are unreliable below a few minutes — very small
+  /// budgets may relock late or only at the daily interval boundary.
+  private func startUsageBasedRelock(minutes: Int) throws {
     scheduleLock.lock()
     defer { scheduleLock.unlock() }
 
     cancelRelockActivityLocked()
 
-    let activityName = DeviceActivityName(unlockActivityName)
-    let calendar = Calendar.current
-    let now = Date()
-    let startComponents = calendar.dateComponents([.hour, .minute, .second], from: now)
-    let endComponents = calendar.dateComponents([.hour, .minute, .second], from: expirationDate)
-    let nowDay = calendar.startOfDay(for: now)
-    let expirationDay = calendar.startOfDay(for: expirationDate)
-
-    let schedule: DeviceActivitySchedule
-
-    if nowDay == expirationDay {
-      schedule = DeviceActivitySchedule(
-        intervalStart: DateComponents(
-          hour: startComponents.hour,
-          minute: startComponents.minute,
-          second: startComponents.second
-        ),
-        intervalEnd: DateComponents(
-          hour: endComponents.hour,
-          minute: endComponents.minute,
-          second: endComponents.second
-        ),
-        repeats: false
-      )
-    } else {
-      schedule = DeviceActivitySchedule(
-        intervalStart: DateComponents(
-          hour: startComponents.hour,
-          minute: startComponents.minute,
-          second: startComponents.second
-        ),
-        intervalEnd: DateComponents(hour: 23, minute: 59, second: 59),
-        repeats: false
-      )
+    guard let config = currentBlockConfig else {
+      print("[AppBlocker] startUsageBasedRelock: no active config, monitoring not started")
+      return
+    }
+    let appTokens = Set(config.items.compactMap { $0.appToken })
+    let categoryTokens = Set(config.items.compactMap { $0.categoryToken })
+    let webDomainTokens = Set(config.items.compactMap { $0.webDomainToken })
+
+    guard !appTokens.isEmpty || !categoryTokens.isEmpty || !webDomainTokens.isEmpty else {
+      print("[AppBlocker] startUsageBasedRelock: no blockable tokens, monitoring not started")
+      return
     }
 
-    try activityCenter.startMonitoring(activityName, during: schedule)
+    let event = DeviceActivityEvent(
+      applications: appTokens,
+      categories: categoryTokens,
+      webDomains: webDomainTokens,
+      threshold: DateComponents(minute: max(1, minutes))
+    )
+
+    let schedule = DeviceActivitySchedule(
+      intervalStart: DateComponents(hour: 0, minute: 0, second: 0),
+      intervalEnd: DateComponents(hour: 23, minute: 59, second: 59),
+      repeats: true
+    )
+
+    try activityCenter.startMonitoring(
+      DeviceActivityName(unlockActivityName),
+      during: schedule,
+      events: [DeviceActivityEvent.Name(usageEventName): event]
+    )
   }
 
   private func cancelRelockActivity() {
@@ -554,16 +545,12 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func isTemporarilyUnlockedInternal() -> Bool {
-    guard let expirationDate = sharedDefaults?.object(forKey: temporaryUnlockKey) as? Date else {
-      return false
-    }
-
-    if Date() < expirationDate {
-      return true
-    }
+    return remainingUnlockBudgetSeconds() > 0
+  }
 
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
-    return false
+  /// Granted earned-time budget in seconds (0 if no active unlock). See `temporaryUnlockKey`.
+  private func remainingUnlockBudgetSeconds() -> Int {
+    return (sharedDefaults?.object(forKey: temporaryUnlockKey) as? Int) ?? 0
   }
 
   // MARK: - Serialization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "Expo module for cross-platform app blocking. Android: UsageStatsManager + Overlay. iOS: Screen Time API (FamilyControls + ManagedSettings + DeviceActivity).",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -189,7 +189,15 @@ export function isTemporarilyUnlocked(): boolean {
   return NativeModule.isTemporarilyUnlocked();
 }
 
-/** Seconds remaining on the active temporary unlock, or 0 if none. */
+/**
+ * Seconds remaining on the active temporary unlock, or 0 if none.
+ *
+ * Platform divergence: on **Android** this ticks down live as the budget is spent
+ * inside blocked apps (and freezes when you leave). On **iOS** Apple does not expose
+ * live cumulative usage, so this returns the *granted* budget and stays flat until
+ * the usage threshold re-applies the shield (then drops to 0). Don't rely on a
+ * smooth iOS countdown.
+ */
 export function getRemainingUnlockTime(): number {
   if (Platform.OS === "android") return NativeModule.getRemainingUnlockTimeAndroid();
   return NativeModule.getRemainingUnlockTime();

package/targets/DeviceActivityMonitor/DeviceActivityMonitor.swift

@@ -20,6 +20,7 @@ class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
 
   override func intervalDidEnd(for activity: DeviceActivityName) {
     super.intervalDidEnd(for: activity)
+    // Daily safety net: clear any active unlock budget at the schedule boundary.
     sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
     reapplyBlockConfiguration()
   }
@@ -28,6 +29,17 @@ class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
     super.intervalDidStart(for: activity)
   }
 
+  override func eventDidReachThreshold(
+    _ event: DeviceActivityEvent.Name,
+    activity: DeviceActivityName
+  ) {
+    super.eventDidReachThreshold(event, activity: activity)
+    // The user has spent their earned usage budget on the blocked apps —
+    // clear the unlock and re-apply the shield.
+    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    reapplyBlockConfiguration()
+  }
+
   private func reapplyBlockConfiguration() {
     let userDefaults = sharedDefaults ?? UserDefaults.standard