expo-app-blocker 0.1.63 → 0.1.65

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 events stepped ~every 30s of the budget; the monitor extension records consumed seconds and re-applies the shield on the final step |
+| `getRemainingUnlockTime()` | Live — ticks down by the second while inside a blocked app, freezes otherwise | **~30s-granular** — steps down as measured usage accrues (the monitor writes consumed seconds to the App Group), freezes when the apps aren't used |
+| `isTemporarilyUnlocked()` | Returns `false` (use `getRemainingUnlockTime() > 0`) | `true` while budget remains |
+| Caveats | — | Apple thresholds are coarse/unreliable below ~a minute, so the finest steps may fire late or be skipped (later steps + the final threshold still re-block, bounding overshoot to ~one step); large budgets auto-coarsen the step to stay under the event cap; unspent budget is cleared at the daily 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,29 @@ 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`).
+  // Stores the granted budget in SECONDS (Int). Presence with value > 0 means a
+  // temporary unlock is active; the monitor reads it to know when to fully re-block.
   private let temporaryUnlockKey = "appBlocker.temporaryUnlock.v1"
   private let unlockActivityName = "appBlocker.temporaryUnlock"
+  // Sub-minute usage steps. We register one DeviceActivityEvent per `usageStepSeconds`
+  // of the budget (threshold = k×step seconds of measured usage). Each step's
+  // eventDidReachThreshold lets the monitor extension write consumed SECONDS back to
+  // the App Group — readable by the host app (unlike DeviceActivityReport). The event
+  // name carries its threshold in seconds (`appBlocker.usageStep.<seconds>`).
+  private let usageStepEventPrefix = "appBlocker.usageStep."
+  // Consumed seconds of the active unlock, written by the monitor extension.
+  private let usageConsumedKey = "appBlocker.usageConsumedSeconds.v1"
+  // Target resolution. Apple's thresholds are coarse/unreliable below ~a minute, so
+  // 30s is a best-effort finer grain; the per-step events that don't fire are still
+  // backstopped by later (coarser-elapsed) ones and the final re-block threshold.
+  private let usageStepSeconds = 30
+  // Cap on registered step events. For large budgets the step auto-coarsens so the
+  // event count stays under this (Apple degrades with too many events).
+  private let maxUsageSteps = 60
   private let pendingUnlockKey = "appBlocker.pendingUnlock.v1"
   private let minimumTemporaryUnlockMinutes = 1
   private var didLoadPersistedConfig = false
@@ -165,7 +186,7 @@ public class ExpoAppBlockerModule: Module {
         self.currentBlockConfig = nil
         self.userDefaults.removeObject(forKey: self.blockConfigStorageKey)
         self.sharedDefaults?.removeObject(forKey: self.blockConfigStorageKey)
-        self.sharedDefaults?.removeObject(forKey: self.temporaryUnlockKey)
+        self.clearUnlockState()
       }
     }
 
@@ -199,8 +220,9 @@ 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)
+        self.sharedDefaults?.set(0, forKey: self.usageConsumedKey)
 
         DispatchQueue.main.async {
           self.store.shield.applications = nil
@@ -208,51 +230,40 @@ 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(budgetSeconds: budgetSeconds)
         } 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.remainingUnlockSeconds() > 0
     }
 
+    // Remaining = granted budget minus the consumed minutes the monitor extension
+    // has written to the App Group as usage accrued. Steps down by ~1 minute per
+    // minute of actual blocked-app usage and freezes while the apps aren't used.
+    // It's minute-granular (not smooth seconds) and may lag real usage slightly —
+    // Apple's thresholds are coarse. Drops to 0 once the budget is fully spent.
     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.remainingUnlockSeconds()
     }
 
     AsyncFunction("relockApps") { (promise: Promise) in
@@ -348,23 +359,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 remainingUnlockSeconds() > 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 {
@@ -481,7 +483,7 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func relockApps() {
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    clearUnlockState()
     cancelRelockActivity()
     ensureLoadedPersistedConfig()
 
@@ -497,49 +499,86 @@ 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 `budgetSeconds`. iOS counts only active usage,
+  /// so the budget naturally pauses when the apps aren't in use and resumes on return.
+  ///
+  /// We register a series of threshold events stepping by `usageStepSeconds` (auto-
+  /// coarsened so the count stays under `maxUsageSteps`). The event name carries its
+  /// threshold in seconds (`usageStepEventPrefix + <seconds>`). Each step's
+  /// `eventDidReachThreshold` (in the DeviceActivityMonitor extension) writes the
+  /// consumed-second count to the App Group — giving the host app a sub-minute,
+  /// pause-when-away consumed counter (`getRemainingUnlockTime`). The final step
+  /// (== budget) is where the monitor re-applies the shield.
+  ///
+  /// Uses an all-day repeating schedule purely as a container for the events.
+  /// `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 coarse/unreliable below ~a minute, so the
+  /// finest steps may fire late or be skipped — later steps and the final threshold
+  /// still re-block, bounding overshoot to roughly one step.
+  private func startUsageBasedRelock(budgetSeconds: 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
+    }
+
+    let budget = max(1, budgetSeconds)
+    // Step by usageStepSeconds, but coarsen so we never exceed maxUsageSteps events.
+    let step = max(usageStepSeconds, Int(ceil(Double(budget) / Double(maxUsageSteps))))
+    var thresholds: [Int] = []
+    var t = step
+    while t < budget {
+      thresholds.append(t)
+      t += step
+    }
+    thresholds.append(budget) // always include the exact budget as the final re-block
+
+    var events: [DeviceActivityEvent.Name: DeviceActivityEvent] = [:]
+    for seconds in thresholds {
+      events[DeviceActivityEvent.Name("\(usageStepEventPrefix)\(seconds)")] = DeviceActivityEvent(
+        applications: appTokens,
+        categories: categoryTokens,
+        webDomains: webDomainTokens,
+        threshold: dateComponents(fromSeconds: seconds)
       )
     }
 
-    try activityCenter.startMonitoring(activityName, during: schedule)
+    // CRITICAL: the interval must start ~now, not at midnight. DeviceActivityEvent
+    // thresholds measure usage accumulated *within the interval, from its start*. An
+    // all-day [00:00, 23:59] interval would count usage since midnight — so any prior
+    // blocked-app use today would have already crossed the thresholds before monitoring
+    // began, and the system never fires a (new) crossing → the shield never re-applies.
+    // Starting the interval at the current time makes thresholds count from the unlock
+    // moment. repeats:false because we re-register on every unlock.
+    let now = Date()
+    let startComps = Calendar.current.dateComponents([.hour, .minute, .second], from: now)
+    let schedule = DeviceActivitySchedule(
+      intervalStart: startComps,
+      intervalEnd: DateComponents(hour: 23, minute: 59, second: 59),
+      repeats: false
+    )
+
+    try activityCenter.startMonitoring(
+      DeviceActivityName(unlockActivityName),
+      during: schedule,
+      events: events
+    )
   }
 
   private func cancelRelockActivity() {
@@ -554,16 +593,33 @@ 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 remainingUnlockSeconds() > 0
+  }
 
+  /// Clear all persisted unlock state (budget + consumed counter).
+  private func clearUnlockState() {
     sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
-    return false
+    sharedDefaults?.removeObject(forKey: usageConsumedKey)
+  }
+
+  /// Seconds of earned time still available: the granted budget minus the seconds
+  /// of blocked-app usage the monitor extension has recorded. 0 if no active unlock
+  /// or the budget is fully consumed. Clamped at 0.
+  private func remainingUnlockSeconds() -> Int {
+    let budgetSeconds = (sharedDefaults?.object(forKey: temporaryUnlockKey) as? Int) ?? 0
+    if budgetSeconds <= 0 { return 0 }
+    let consumedSeconds = (sharedDefaults?.object(forKey: usageConsumedKey) as? Int) ?? 0
+    return max(0, budgetSeconds - consumedSeconds)
+  }
+
+  /// Build a DateComponents threshold from a total number of seconds (normalized
+  /// into hour/minute/second so the system reads it cleanly).
+  private func dateComponents(fromSeconds total: Int) -> DateComponents {
+    return DateComponents(
+      hour: total / 3600,
+      minute: (total % 3600) / 60,
+      second: total % 60
+    )
   }
 
   // MARK: - Serialization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-blocker",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "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

@@ -4,11 +4,19 @@ import FamilyControls
 import Foundation
 
 @available(iOS 15.0, *)
-class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
+// NOTE: the class name MUST be `DeviceActivityMonitorExtension` — it has to match
+// the `NSExtensionPrincipalClass` (`$(PRODUCT_MODULE_NAME).DeviceActivityMonitorExtension`)
+// that @bacons/apple-targets writes into the extension's Info.plist. If it doesn't
+// match, iOS cannot instantiate the extension and NONE of the callbacks fire.
+class DeviceActivityMonitorExtension: DeviceActivityMonitor {
   // CONFIGURE: Replace with your App Group identifier
   private let appGroupIdentifier = "APP_GROUP_PLACEHOLDER"
   private let temporaryUnlockKey = "appBlocker.temporaryUnlock.v1"
   private let blockConfigStorageKey = "appBlocker.blockConfiguration.v1"
+  // Keep these in sync with ExpoAppBlockerModule.swift. temporaryUnlockKey holds the
+  // budget in seconds; usageConsumedKey accumulates consumed seconds.
+  private let usageStepEventPrefix = "appBlocker.usageStep."
+  private let usageConsumedKey = "appBlocker.usageConsumedSeconds.v1"
 
   private let store = ManagedSettingsStore()
   private var sharedDefaults: UserDefaults?
@@ -20,14 +28,63 @@ class AppBlockerDeviceActivityMonitor: DeviceActivityMonitor {
 
   override func intervalDidEnd(for activity: DeviceActivityName) {
     super.intervalDidEnd(for: activity)
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
-    reapplyBlockConfiguration()
+    // Intentionally a no-op. Re-block is driven solely by eventDidReachThreshold
+    // (the usage budget). We must NOT clear unlock state or reapply the shield here:
+    // stopMonitoring() during a re-grant also fires intervalDidEnd, which would wipe
+    // the freshly-granted budget and re-shield the apps immediately after the user
+    // earned time. (Tradeoff: an unspent budget is not force-cleared at the daily
+    // schedule boundary — an acceptable edge case.)
   }
 
   override func intervalDidStart(for activity: DeviceActivityName) {
     super.intervalDidStart(for: activity)
   }
 
+  // Fires once per usage step (threshold = N seconds of measured blocked-app use).
+  // We write the consumed-second count back to the App Group so the host app can
+  // show a live, pause-when-away countdown; once consumed reaches the budget we
+  // clear the unlock and re-apply the shield.
+  override func eventDidReachThreshold(
+    _ event: DeviceActivityEvent.Name,
+    activity: DeviceActivityName
+  ) {
+    super.eventDidReachThreshold(event, activity: activity)
+
+    let stepSeconds = parseStepSeconds(from: event.rawValue)
+    guard stepSeconds > 0 else {
+      // Unknown event — treat as a full relock to stay safe.
+      clearUnlockState()
+      reapplyBlockConfiguration()
+      return
+    }
+
+    // Record consumed seconds monotonically (steps can arrive out of order).
+    let prev = sharedDefaults?.integer(forKey: usageConsumedKey) ?? 0
+    if stepSeconds > prev {
+      sharedDefaults?.set(stepSeconds, forKey: usageConsumedKey)
+    }
+
+    let budgetSeconds = sharedDefaults?.integer(forKey: temporaryUnlockKey) ?? 0
+    if budgetSeconds <= 0 || stepSeconds >= budgetSeconds {
+      // Budget fully spent — re-block.
+      clearUnlockState()
+      reapplyBlockConfiguration()
+    }
+  }
+
+  /// Extract the threshold seconds from an event name like `appBlocker.usageStep.90`;
+  /// 0 if not a usage step.
+  private func parseStepSeconds(from rawName: String) -> Int {
+    guard rawName.hasPrefix(usageStepEventPrefix) else { return 0 }
+    let suffix = rawName.dropFirst(usageStepEventPrefix.count)
+    return Int(suffix) ?? 0
+  }
+
+  private func clearUnlockState() {
+    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    sharedDefaults?.removeObject(forKey: usageConsumedKey)
+  }
+
   private func reapplyBlockConfiguration() {
     let userDefaults = sharedDefaults ?? UserDefaults.standard