Merge pull request #30 from brewkits/hotfix/ios-request-mutex-deadlock

release: v1.3.1 — iOS Hotfix & Quality Audit

Author: vietnguyentuan2019

.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:

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ "main", "feature/**" ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "**" ]
   workflow_dispatch:
 
 jobs:

.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:

.github/workflows/ios.yml

@@ -2,9 +2,9 @@ name: iOS Build
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "**" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "**" ]
   workflow_dispatch:
 
 jobs:

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

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 |

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

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;

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`

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!
 }
 ```