brewkits · vietnguyentuan2019 · May 5, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/.github/workflows/ci-coverage.yml b/.github/workflows/ci-coverage.yml
@@ -2,9 +2,9 @@ name: "Coverage Report (KMP & iOS)"
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ main ]
+    branches: [ "**" ]
 
 jobs:
   coverage:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ "main", "feature/**" ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "**" ]
   workflow_dispatch:
 
 jobs:

diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml
@@ -2,9 +2,9 @@ name: Code Quality
 
 on:
   push:
-    branches: [ "main", "feature/**" ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "**" ]
   workflow_dispatch:
 
 jobs:

diff --git a/.github/workflows/ios.yml b/.github/workflows/ios.yml
@@ -2,9 +2,9 @@ name: iOS Build
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "**" ]
   workflow_dispatch:
 
 jobs:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [1.3.1] - 2026-05-05
+
+### 🛡️ Critical Bug Fix: iOS Deadlock
+- **iOS Mutex Re-entrancy Fix**: Resolved a critical deadlock in `PlatformGrantDelegate.ios.kt` where calling `request()` would hang indefinitely. This occurred because `requestInternal()` incorrectly called the public `checkStatus()` (which acquires a per-permission Mutex) while the same Mutex was already held by the parent `request()` call.
+- **Regression Safety**: Added `Issue29IosMutexDeadlockTest` to ensure this class of deadlock is automatically detected in the future using `withTimeout` guards.
+
 ## [1.3.0] - 2026-04-29
 
 ### 🚀 Major Architectural Shift: Koin Decoupling

diff --git a/README.md b/README.md
@@ -155,9 +155,9 @@ Most KMP permission libraries are simple wrappers around native APIs. Grant is a
 kotlin {
     sourceSets {
         commonMain.dependencies {
-            implementation("dev.brewkits:grant-core:1.3.0")
-            implementation("dev.brewkits:grant-compose:1.3.0")    // Optional: Compose dialogs
-            implementation("dev.brewkits:grant-core-koin:1.3.0")  // Optional: Koin DI support
+            implementation("dev.brewkits:grant-core:1.3.1")
+            implementation("dev.brewkits:grant-compose:1.3.1")    // Optional: Compose dialogs
+            implementation("dev.brewkits:grant-core-koin:1.3.1")  // Optional: Koin DI support
         }
     }
 }
@@ -167,7 +167,7 @@ kotlin {
 > For projects targeting **Web (JS)** or **Desktop (JVM)**, use an intermediate `mobileMain` source set to avoid linking iOS/Android dependencies on unsupported platforms. [Read the Guide](docs/DEPENDENCY_MANAGEMENT.md).
 
 > [!NOTE]
-> **Koin users**: The Koin integration was moved to `grant-core-koin` in v1.3.0. Add the new artifact alongside `grant-core` and replace `GrantPlatformModule` imports. See the [Migration Guide](docs/MIGRATION_GUIDE.md).
+> **Koin users**: The Koin integration was moved to `grant-core-koin` in v1.3.1. Add the new artifact alongside `grant-core` and replace `GrantPlatformModule` imports. See the [Migration Guide](docs/MIGRATION_GUIDE.md).
 
 ---
 
@@ -177,7 +177,7 @@ kotlin {
 | :--- | :--- |
 | [Architecture](docs/grant-core/ARCHITECTURE.md) | How concurrency, state machines, and the mutex flow work |
 | [iOS Setup](docs/platform-specific/ios/info-plist.md) | Critical `Info.plist` configuration — read before shipping |
-| [Migration Guide](docs/MIGRATION_GUIDE.md) | Upgrading from v1.2.x to v1.3.0 |
+| [Migration Guide](docs/MIGRATION_GUIDE.md) | Upgrading from v1.2.x to v1.3.1 |
 | [Service Checking](docs/grant-core/SERVICES.md) | Combining permission + hardware service checks |
 | [Manual Injection](docs/MANUAL_INJECTION.md) | Using Grant without any DI framework |
 | [Android Reliability](docs/FIX_DEAD_CLICK_ANDROID.md) | How we fix "Dead Clicks" on Android |

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,11 +1,36 @@
 # Grant Library — Roadmap
 
-> Last updated: 2026-04-30 | Current stable: **v1.3.0**
+> Last updated: 2026-05-05 | Current stable: **v1.3.1**
 
 ---
 
+## 🛠️ In Progress / Upcoming
+
+### v1.4.0 (Target: Q3 2026) — Enterprise Hardening & Extensibility
+*Focus: Resilience against Process Death, Performance at Scale, and Architectural Purity.*
+
+**1. Resilience (Android)**
+- [ ] **Process Death Recovery**: Implement `SavedStateHandle` support in `GrantRequestActivity`. Ensure active permission requests survive when the OS kills the app in the background.
+- [ ] **Activity Launch Guard**: Prevent multiple `GrantRequestActivity` instances from overlapping during rapid concurrent calls.
+
+**2. Extensibility (iOS)**
+- [ ] **Handler Registry**: Allow developers to register custom `IosPermissionHandler` implementations for `RawPermission`. No more "Not Implemented" dead-ends on iOS.
+- [ ] **Modern iOS API Support**: Guidelines and helpers for `PHPicker` (no-permission photo selection) and `NSLocationTemporaryFullAccuracyUsageDescriptionKey`.
+
+**3. Performance & UI**
+- [ ] **Parallel Status Checks**: Refactor `GrantGroupHandler` to use `async/awaitAll` for status verification, eliminating "UI Jank" when checking 10+ permissions.
+- [ ] **Emission Throttling**: Use `distinctUntilChanged` on internal flows to prevent redundant UI re-compositions.
+
+**4. Core Architecture**
+- [ ] **Robust Locking**: Replace the brittle `checkStatusInternal` pattern with a cleaner internal/external separation or a re-entrant safe locking strategy.
+- [ ] **Atomic Store Operations**: Ensure `GrantStore` updates are atomic across all platforms to prevent race conditions during rapid state changes.
+
 ## ✅ Released
 
+### v1.3.1 (2026-05-05)
+- HOTFIX: iOS `request()` mutex deadlock resolution (Issue #29)
+- Regression tests for non-reentrant mutex patterns
+
 ### v1.3.0 (2026-04-29)
 - Koin decoupled into `grant-core-koin` module
 - `GrantAndServiceHandler` for unified permission + service flows

diff --git a/demo/iosApp/GrantDemo/GrantDemo.xcodeproj/project.pbxproj b/demo/iosApp/GrantDemo/GrantDemo.xcodeproj/project.pbxproj
@@ -360,7 +360,7 @@
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
 				STRING_CATALOG_GENERATE_SYMBOLS = YES;
-				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
 				SUPPORTS_MACCATALYST = NO;
 				SUPPORTS_MAC_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;
@@ -423,7 +423,7 @@
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
 				STRING_CATALOG_GENERATE_SYMBOLS = YES;
-				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
 				SUPPORTS_MACCATALYST = NO;
 				SUPPORTS_MAC_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;

diff --git a/docs/DEPENDENCY_MANAGEMENT.md b/docs/DEPENDENCY_MANAGEMENT.md
@@ -13,7 +13,7 @@ Grant library has the following dependencies:
 - **AndroidX Activity Compose** `1.12.1` (Android only) - For permission requests
 
 ### Optional Dependencies
-- **Koin** `4.1.1` - For dependency injection (OPTIONAL). Use `dev.brewkits:grant-core-koin:1.3.0`.
+- **Koin** `4.1.1` - For dependency injection (OPTIONAL). Use `dev.brewkits:grant-core-koin:1.3.1`.
 
 ---
 
@@ -26,7 +26,7 @@ Grant library uses **Koin 4.1.1** for optional dependency injection support.
 
 ✅ **Koin is OPTIONAL** - You don't need Koin to use Grant library!
 
-As of version **1.3.0**, Koin support has been moved to a separate module to ensure `grant-core` remains a pure, dependency-free artifact.
+As of version **1.3.1**, Koin support has been moved to a separate module to ensure `grant-core` remains a pure, dependency-free artifact.
 
 1. **Manual Creation (Recommended)** - Use `grant-core`
 2. **Koin DI Modules** - Use `grant-core-koin`

diff --git a/docs/MIGRATION_GUIDE.md b/docs/MIGRATION_GUIDE.md
@@ -1,6 +1,6 @@
 # Migration Guide to Grant
 
-**Version:** 1.3.0
+**Version:** 1.3.1
 **Last Updated:** April 29, 2026
 
 This guide helps you migrate from previous versions of Grant or other permission libraries.
@@ -9,7 +9,7 @@ This guide helps you migrate from previous versions of Grant or other permission
 
 ## 📚 Table of Contents
 
-1. [Upgrading from Grant 1.2.x to 1.3.0](#upgrading-from-grant-12x-to-130)
+1. [Upgrading from Grant 1.2.x to 1.3.1](#upgrading-from-grant-12x-to-130)
 2. [From moko-permissions](#from-moko-permissions)
 3. [From Google Accompanist](#from-google-accompanist)
 4. [From Custom Implementation](#from-custom-implementation)
@@ -19,11 +19,11 @@ This guide helps you migrate from previous versions of Grant or other permission
 
 ---
 
-## 1️⃣ Upgrading from Grant 1.2.x to 1.3.0
+## 1️⃣ Upgrading from Grant 1.2.x to 1.3.1
 
 ### Overview
 
-Version 1.3.0 is a major release focusing on architectural purity and iOS stability. The biggest change is the extraction of Koin into its own module.
+Version 1.3.1 is a major release focusing on architectural purity and iOS stability. The biggest change is the extraction of Koin into its own module.
 
 ### What Changed?
 
@@ -34,16 +34,16 @@ Version 1.3.0 is a major release focusing on architectural purity and iOS stabil
 ### Step-by-Step Upgrade
 
 #### 1. Update Version
-Update your `build.gradle.kts` to version `1.3.0`.
+Update your `build.gradle.kts` to version `1.3.1`.
 
 #### 2. Handle Koin (If you use it)
 If you were using `grantModule` or `grantPlatformModule`, you must now add the `grant-core-koin` dependency:
 
 ```kotlin
 // shared/build.gradle.kts
 commonMain.dependencies {
-    implementation("dev.brewkits:grant-core:1.3.0")
-    implementation("dev.brewkits:grant-core-koin:1.3.0") // New module!
+    implementation("dev.brewkits:grant-core:1.3.1")
+    implementation("dev.brewkits:grant-core-koin:1.3.1") // New module!
 }
 ```
 

diff --git a/docs/grant-core/ARCHITECTURE.md b/docs/grant-core/ARCHITECTURE.md
@@ -53,9 +53,9 @@ This document explains the architectural decisions behind KMP Grant library and
 └──────────────────┘           └──────────────────┘
 ```
 
-## 🍎 iOS Framework Isolation (NEW in v1.3.0)
+## 🍎 iOS Framework Isolation (NEW in v1.3.1)
 
-To avoid Apple App Store rejections due to "unused sensitive permissions" (e.g., your app doesn't use Location but the library contains Location code), Grant v1.3.0 introduced a strict isolation architecture.
+To avoid Apple App Store rejections due to "unused sensitive permissions" (e.g., your app doesn't use Location but the library contains Location code), Grant v1.3.1 introduced a strict isolation architecture.
 
 ### The Problem
 Kotlin/Native's dead code elimination (DCE) sometimes fails to remove framework linkages if they are referenced in a large, monolithic platform delegate. This causes the App Store static scanner to detect frameworks like `CoreLocation` or `CoreBluetooth` even if your app never requests them.

diff --git a/docs/ios/APPLE_FRAMEWORK_LINKING_ISSUE.md b/docs/ios/APPLE_FRAMEWORK_LINKING_ISSUE.md
@@ -2,7 +2,7 @@
 
 > **Related:** Issue #25 — *"Apple wants me to add why I have used them, but I have not used them"*  
 > **Severity:** 🔴 Critical (causes App Store rejection)  
-> **Status:** ✅ RESOLVED in v1.3.0
+> **Status:** ✅ RESOLVED in v1.3.1
 
 ---
 
@@ -87,7 +87,7 @@ Grant currently bundles **all 17 permissions** into a single `grant-core` module
 ```
 User only needs CAMERA + MICROPHONE
        ↓
-Add dependency: implementation("dev.brewkits:grant-core:1.3.0")
+Add dependency: implementation("dev.brewkits:grant-core:1.3.1")
        ↓
 Binary ships with: CoreLocation + EventKit + CoreMotion + CoreBluetooth + ...
        ↓

diff --git a/docs/platform-specific/ios/info-plist.md b/docs/platform-specific/ios/info-plist.md
@@ -4,11 +4,11 @@
 
 iOS requires you to declare **usage descriptions** in `Info.plist` for each permission before requesting it. **If you forget to add these keys, your app will crash immediately** when requesting the permission.
 
-### 🍎 v1.3.0 Architectural Improvement (Framework Isolation)
+### 🍎 v1.3.1 Architectural Improvement (Framework Isolation)
 
-Prior to version 1.3.0, Apple's static analysis would often require **all** usage description keys (Location, Bluetooth, Calendar, etc.) even if your app didn't use them, because the library linked those frameworks statically.
+Prior to version 1.3.1, Apple's static analysis would often require **all** usage description keys (Location, Bluetooth, Calendar, etc.) even if your app didn't use them, because the library linked those frameworks statically.
 
-**Starting with v1.3.0, Grant uses a "Handler Pattern" to isolate framework imports.** This means:
+**Starting with v1.3.1, Grant uses a "Handler Pattern" to isolate framework imports.** This means:
 1.  **Only requested permissions are linked**: If you don't use Location in your code, the `CoreLocation` framework will not be linked to your binary.
 2.  **No more "Dummy" keys**: You no longer need to add usage descriptions for permissions your app doesn't use.
 3.  **App Store Connect safety**: Apple's scanners will only flag frameworks that are actually referenced in your binary.

diff --git a/grant-compose/build.gradle.kts b/grant-compose/build.gradle.kts
@@ -10,7 +10,7 @@ plugins {
 }
 
 group = "dev.brewkits"
-version = "1.3.0"
+version = "1.3.1"
 
 kotlin {
     androidTarget {
@@ -105,7 +105,7 @@ publishing {
     publications.configureEach {
         (this as? MavenPublication)?.let {
             groupId = "dev.brewkits"
-            version = "1.3.0"
+            version = "1.3.1"
 
             pom {
                 name.set("KMP Grant Compose")

diff --git a/grant-core-koin/build.gradle.kts b/grant-core-koin/build.gradle.kts
@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "dev.brewkits"
-version = "1.3.0"
+version = "1.3.1"
 
 kotlin {
     androidTarget {

diff --git a/grant-core/build.gradle.kts b/grant-core/build.gradle.kts
@@ -8,7 +8,7 @@ plugins {
 }
 
 group = "dev.brewkits"
-version = "1.3.0"
+version = "1.3.1"
 
 kotlin {
     androidTarget {
@@ -129,7 +129,7 @@ publishing {
     publications.configureEach {
         (this as? MavenPublication)?.let {
             groupId = "dev.brewkits"
-            version = "1.3.0"
+            version = "1.3.1"
 
             pom {
                 name.set("KMP Grant")