expo-app-blocker 0.1.64 → 0.1.66

package/README.md

@@ -513,10 +513,10 @@ await relockApps();                        // drop the budget now, re-block imme
 
 | | 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`) |
+| 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 unreliable below a few minutes; unspent budget is cleared at the daily schedule boundary (midnight) |
+| 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

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

@@ -2,9 +2,15 @@ package expo.modules.appblocker
 
 import android.content.Context
 import android.content.SharedPreferences
+import org.json.JSONArray
+import org.json.JSONObject
 
 object AppBlockerPrefs {
   const val PREFS_NAME = "expo_app_blocker_prefs"
+  private const val KEY_PENDING_INTERCEPTS = "pending_intercepts"
+  private const val KEY_LAST_INTERCEPT_TS = "last_intercept_ts"
+  private const val INTERCEPT_DEBOUNCE_MS = 2_000L
+  private const val MAX_PENDING_INTERCEPTS = 200
   const val KEY_BLOCKED_PACKAGES = "blocked_packages"
   private const val KEY_OVERLAY_TITLE = "overlay_title"
   private const val KEY_OVERLAY_TEXT = "overlay_text"
@@ -149,6 +155,59 @@ object AppBlockerPrefs {
   fun getNotificationText(context: Context): String =
     get(context).getString(KEY_NOTIFICATION_TEXT, null) ?: "{appName} is blocked. Tap to manage."
 
+  /**
+   * Queue one OS-level block event for the app to drain into
+   * `blocker_intercepts`. Debounced globally so the poll loop can't emit
+   * duplicates for a single block, and capped to bound storage.
+   */
+  fun appendIntercept(context: Context, appName: String, interceptedAtMs: Long) {
+    val prefs = get(context)
+    val lastTs = prefs.getLong(KEY_LAST_INTERCEPT_TS, 0L)
+    if (lastTs > 0L && interceptedAtMs - lastTs < INTERCEPT_DEBOUNCE_MS) return
+
+    val arr = try {
+      JSONArray(prefs.getString(KEY_PENDING_INTERCEPTS, "[]"))
+    } catch (e: Exception) {
+      JSONArray()
+    }
+    arr.put(JSONObject().put("appName", appName).put("interceptedAt", interceptedAtMs))
+
+    val trimmed = if (arr.length() > MAX_PENDING_INTERCEPTS) {
+      JSONArray().also { t ->
+        for (i in (arr.length() - MAX_PENDING_INTERCEPTS) until arr.length()) t.put(arr.get(i))
+      }
+    } else {
+      arr
+    }
+
+    prefs.edit()
+      .putString(KEY_PENDING_INTERCEPTS, trimmed.toString())
+      .putLong(KEY_LAST_INTERCEPT_TS, interceptedAtMs)
+      .apply()
+  }
+
+  /** Return and clear the queued block events. */
+  fun drainIntercepts(context: Context): List<Map<String, Any>> {
+    val prefs = get(context)
+    val arr = try {
+      JSONArray(prefs.getString(KEY_PENDING_INTERCEPTS, "[]"))
+    } catch (e: Exception) {
+      JSONArray()
+    }
+    val out = ArrayList<Map<String, Any>>(arr.length())
+    for (i in 0 until arr.length()) {
+      val o = arr.getJSONObject(i)
+      out.add(
+        mapOf(
+          "appName" to o.optString("appName", ""),
+          "interceptedAt" to o.optDouble("interceptedAt"),
+        )
+      )
+    }
+    if (arr.length() > 0) prefs.edit().remove(KEY_PENDING_INTERCEPTS).apply()
+    return out
+  }
+
   private fun putNullableFloat(editor: SharedPreferences.Editor, key: String, value: Float?) {
     if (value != null) editor.putFloat(key, value) else editor.remove(key)
   }

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

@@ -97,10 +97,22 @@ class AppBlockerService : Service() {
   private fun enforceBlock(packageName: String, reason: BlockReason) {
     overlayManager.show(packageName, reason)
     showBlockedNotification(packageName, reason)
+    recordIntercept(packageName)
     blocking = true
     consumingSinceMs = 0L
   }
 
+  /** Queue this block event for the app to drain (debounced in prefs). */
+  private fun recordIntercept(packageName: String) {
+    val appName = try {
+      val pm = this.packageManager
+      pm.getApplicationLabel(pm.getApplicationInfo(packageName, 0)).toString()
+    } catch (e: Exception) {
+      packageName
+    }
+    AppBlockerPrefs.appendIntercept(this, appName, System.currentTimeMillis())
+  }
+
   private fun showBlockedNotification(packageName: String, reason: BlockReason) {
     val appName = try {
       val pm = this.packageManager

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

@@ -103,6 +103,10 @@ class ExpoAppBlockerModule : Module() {
       AppBlockerPrefs.getBlockedPackages(context).toList()
     }
 
+    Function("drainPendingIntercepts") {
+      AppBlockerPrefs.drainIntercepts(context)
+    }
+
     Function("startMonitoring") {
       AppBlockerService.start(context)
       Log.d(TAG, "startMonitoring called")

package/ios/ExpoAppBlockerModule.swift

@@ -18,10 +18,27 @@ public class ExpoAppBlockerModule: Module {
   // 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"
-  private let usageEventName = "appBlocker.usageThreshold"
+  // 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 pendingInterceptsKey = "appBlocker.pendingIntercepts.v1"
   private let minimumTemporaryUnlockMinutes = 1
   private var didLoadPersistedConfig = false
 
@@ -170,7 +187,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()
       }
     }
 
@@ -184,6 +201,16 @@ public class ExpoAppBlockerModule: Module {
       return hasPending
     }
 
+    Function("drainPendingIntercepts") { () -> [[String: Any]] in
+      guard let defaults = self.sharedDefaults else { return [] }
+      let queue = defaults.array(forKey: self.pendingInterceptsKey) as? [[String: Any]] ?? []
+      if !queue.isEmpty {
+        defaults.removeObject(forKey: self.pendingInterceptsKey)
+        defaults.synchronize()
+      }
+      return queue
+    }
+
     Function("isAppBlocked") { (bundleIdentifier: String) -> Bool in
       self.ensureLoadedPersistedConfig()
       guard let config = self.currentBlockConfig else {
@@ -206,6 +233,7 @@ public class ExpoAppBlockerModule: Module {
 
         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
@@ -216,7 +244,7 @@ public class ExpoAppBlockerModule: Module {
         // 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.startUsageBasedRelock(minutes: sanitizedDurationMinutes)
+          try self.startUsageBasedRelock(budgetSeconds: budgetSeconds)
         } catch {
           // Monitoring failed to start (e.g. threshold below Apple's granularity).
           // The unlock still happens; the shield falls back to re-applying on the
@@ -237,15 +265,16 @@ public class ExpoAppBlockerModule: Module {
     }
 
     Function("isTemporarilyUnlocked") { () -> Bool in
-      return self.remainingUnlockBudgetSeconds() > 0
+      return self.remainingUnlockSeconds() > 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).
+    // 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
-      return self.remainingUnlockBudgetSeconds()
+      return self.remainingUnlockSeconds()
     }
 
     AsyncFunction("relockApps") { (promise: Promise) in
@@ -341,7 +370,7 @@ public class ExpoAppBlockerModule: Module {
 
     ensureLoadedPersistedConfig()
 
-    if remainingUnlockBudgetSeconds() > 0 {
+    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.
@@ -465,7 +494,7 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func relockApps() {
-    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    clearUnlockState()
     cancelRelockActivity()
     ensureLoadedPersistedConfig()
 
@@ -482,19 +511,26 @@ public class ExpoAppBlockerModule: Module {
   // MARK: - Activity Scheduling
 
   /// 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.
+  /// 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 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).
+  /// 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 unreliable below a few minutes — very small
-  /// budgets may relock late or only at the daily interval boundary.
-  private func startUsageBasedRelock(minutes: Int) throws {
+  /// 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() }
 
@@ -513,23 +549,46 @@ public class ExpoAppBlockerModule: Module {
       return
     }
 
-    let event = DeviceActivityEvent(
-      applications: appTokens,
-      categories: categoryTokens,
-      webDomains: webDomainTokens,
-      threshold: DateComponents(minute: max(1, minutes))
-    )
+    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)
+      )
+    }
 
+    // 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: DateComponents(hour: 0, minute: 0, second: 0),
+      intervalStart: startComps,
       intervalEnd: DateComponents(hour: 23, minute: 59, second: 59),
-      repeats: true
+      repeats: false
     )
 
     try activityCenter.startMonitoring(
       DeviceActivityName(unlockActivityName),
       during: schedule,
-      events: [DeviceActivityEvent.Name(usageEventName): event]
+      events: events
     )
   }
 
@@ -545,12 +604,33 @@ public class ExpoAppBlockerModule: Module {
   }
 
   private func isTemporarilyUnlockedInternal() -> Bool {
-    return remainingUnlockBudgetSeconds() > 0
+    return remainingUnlockSeconds() > 0
+  }
+
+  /// Clear all persisted unlock state (budget + consumed counter).
+  private func clearUnlockState() {
+    sharedDefaults?.removeObject(forKey: temporaryUnlockKey)
+    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)
   }
 
-  /// 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
+  /// 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.64",
+  "version": "0.1.66",
   "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

@@ -222,6 +222,28 @@ export function checkAndClearPendingUnlock(): boolean {
   return NativeModule.checkAndClearPendingUnlock();
 }
 
+/**
+ * One OS-level block event: the blocker intercepted a blocked app (iOS
+ * shield render / Android foreground block). `interceptedAt` is epoch
+ * milliseconds; `appName` is the localized app name when the platform
+ * can resolve it (null otherwise).
+ */
+export interface PendingIntercept {
+  appName: string | null;
+  interceptedAt: number;
+}
+
+/**
+ * Drain and clear the queue of block events recorded natively since the
+ * last call. Implemented on both platforms (iOS App Group queue / Android
+ * SharedPreferences queue). The app calls this on foreground and persists
+ * the results to power the "blocks" counter.
+ */
+export function drainPendingIntercepts(): PendingIntercept[] {
+  if (Platform.OS !== "ios" && Platform.OS !== "android") return [];
+  return NativeModule.drainPendingIntercepts() ?? [];
+}
+
 export function addPendingUnlockListener(
   handler: () => void
 ): { remove: () => void } | null {

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,24 +28,61 @@ 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()
+    // 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)
-    // The user has spent their earned usage budget on the blocked apps —
-    // clear the unlock and re-apply the shield.
+
+    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)
-    reapplyBlockConfiguration()
+    sharedDefaults?.removeObject(forKey: usageConsumedKey)
   }
 
   private func reapplyBlockConfiguration() {

package/targets/ShieldConfiguration/ShieldConfigurationExtension.swift

@@ -43,6 +43,30 @@ class ShieldConfigurationExtension: ShieldConfigurationDataSource {
     return Date() < expiration
   }
 
+  // Block-event queue, drained by the app into `blocker_intercepts` to power
+  // the "blocks" counter. The system re-renders the shield often (app
+  // switcher previews, re-foreground), so a short global debounce collapses
+  // those bursts into one logical block event.
+  private let pendingInterceptsKey = "appBlocker.pendingIntercepts.v1"
+  private let lastInterceptTsKey = "appBlocker.lastInterceptTs.v1"
+  private let interceptDebounceMs: Double = 2_000
+  private let maxPendingIntercepts = 200
+
+  private func recordIntercept(appName: String) {
+    guard let defaults = UserDefaults(suiteName: appGroupIdentifier) else { return }
+    let nowMs = Date().timeIntervalSince1970 * 1000.0
+    let lastMs = defaults.double(forKey: lastInterceptTsKey)
+    if lastMs > 0, (nowMs - lastMs) < interceptDebounceMs { return }
+
+    var queue = defaults.array(forKey: pendingInterceptsKey) as? [[String: Any]] ?? []
+    queue.append(["appName": appName, "interceptedAt": nowMs])
+    if queue.count > maxPendingIntercepts {
+      queue = Array(queue.suffix(maxPendingIntercepts))
+    }
+    defaults.set(queue, forKey: pendingInterceptsKey)
+    defaults.set(nowMs, forKey: lastInterceptTsKey)
+  }
+
   private func makeConfig(appName: String) -> ShieldConfiguration {
     if isTemporarilyUnlocked() {
       return ShieldConfiguration(
@@ -57,6 +81,10 @@ class ShieldConfigurationExtension: ShieldConfigurationDataSource {
       )
     }
 
+    // A blocked app is being shielded — this is a block event. Record it
+    // (debounced) for the app to drain.
+    recordIntercept(appName: appName)
+
     let count = getBlockedAppCount()
     // The plugin replaces this placeholder with a Swift string literal
     // containing `\(count)` interpolation, or `""` when the user opted out.