Capacitor 7 Native Bridge Thread-Pool Scoping & Dispatch Invariant

--- description: Capacitor 7 Native Bridge Thread-Pool Scoping & Dispatch Invariant - Fences native plugin JSON serialization, binary conversions, and I/O execution away from mobile UI threads into dedicated background dispatch queues. Prevents Android ANR watchdog timeouts and iOS Main Thread Watchdog crashes during high-throughput bridge messaging in Capacitor 7 plugins. Enforces concurrent background workers with explicit main-thread synchronization only during direct WebView manipulation. globs: android/app/src/main/java/**/*.java, android/app/src/main/java/**/*.kt, ios/App/App/**/*.swift, ios/App/App/**/*.m, src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-bridge-thread-pool-scoping-standard" --- # Capacitor 7 Native Bridge Thread-Pool Scoping & Dispatch Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Executing JSON Deserialization, Disk I/O, or Heavy Compute Directly Inside CapacitorPlugin Main Thread Dispatchers ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Native Bridge Thread-Pool Scoping. In Capacitor 7, plugin methods annotated with @PluginMethod execute on the native UI/Main thread by default on iOS, and synchronous message passing blocks WebKit rendering queues. You must mandate off-main-thread execution for all deserialization, file/network I/O, and cryptographic operations via dedicated Grand Central Dispatch (GCD) queues on iOS and Coroutine/Executor thread pools on Android. ## Strict Guidelines - Engineers MUST ALWAYS offload CPU-intensive parsing, file reading, and cryptographic routines to background threads before invoking PluginCall.resolve() or PluginCall.reject(). - Engineers MUST NOT invoke blocking disk I/O, network requests, or large SQLite operations directly inside the raw @PluginMethod or @objc func body without dispatching to a concurrent queue. - iOS Swift plugins MUST use DispatchQueue.global(qos: .userInitiated).async or Swift Concurrency Task.detached(priority: .userInitiated) to wrap heavy bridge logic. - Android Kotlin plugins MUST use CoroutineScope(Dispatchers.IO).launch or execute via bridge.executeOnBackgroundThread { ... } rather than running on the main Looper. - Engineers MUST ensure that any UI-layer calls (e.g., modifying WebView directly, showing native alerts) switch explicitly back to DispatchQueue.main.async or activity.runOnUiThread. - TypeScript bridge consumers SHOULD debounce or chunk payloads exceeding 256KB to minimize bridge serialization latency and memory spikes across the JS-to-Native barrier. ## Bad vs Good Implementations ### Android Kotlin: Offloading Heavy Bridge I/O to Dispatchers.IO #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing file read and decryption directly inside the PluginMethod without a background dispatcher risks triggering an Application Not Responding (ANR) error and drops frames on the main thread. ```kotlin @CapacitorPlugin(name = "SecureStorage") class SecureStoragePlugin : Plugin() { @PluginMethod fun readEncryptedPayload(call: PluginCall) { val key = call.getString("key") ?: return call.reject("Missing key") // VIOLATION: Disk I/O and cryptographic decrypt executing directly on Capacitor caller thread val file = File(context.filesDir, "$key.enc") val rawBytes = file.readBytes() val decryptedString = CryptoManager.decrypt(rawBytes) val ret = JSObject() ret.put("data", decryptedString) call.resolve(ret) } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates file reads and crypto calculations within a CoroutineScope bound to Dispatchers.IO, isolating heavy compute from the main application loop. ```kotlin @CapacitorPlugin(name = "SecureStorage") class SecureStoragePlugin : Plugin() { private val pluginScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) @PluginMethod fun readEncryptedPayload(call: PluginCall) { val key = call.getString("key") ?: run { call.reject("Missing key") return } pluginScope.launch { try { val file = File(context.filesDir, "$key.enc") if (!file.exists()) { call.reject("File not found") return@launch } val rawBytes = file.readBytes() val decryptedString = CryptoManager.decrypt(rawBytes) val ret = JSObject().apply { put("data", decryptedString) } call.resolve(ret) } catch (e: Exception) { call.reject("Decryption failure", e) } } } } ``` ### iOS Swift: Scoping Bridge Work to Dedicated QoS Queue #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling Data(contentsOf:) and JSONSerialization synchronously on the bridge invocation queue locks UI updates and can trigger the iOS watchdog kill timer (0x8badf00d). ```swift @objc(FileProcessorPlugin) public class FileProcessorPlugin: CAPPlugin, CAPBridgedPlugin { public let identifier = "FileProcessorPlugin" public let jsName = "FileProcessor" public let pluginMethods: [CAPPluginMethod] = [ CAPPluginMethod(name: "processLargeFile", returnType: CAPPluginReturnPromise) ] @objc func processLargeFile(_ call: CAPPluginCall) { guard let path = call.getString("path") else { call.reject("No path"); return } // VIOLATION: Synchronous file ingestion and JSON transformation blocks WebKit bridge if let data = try? Data(contentsOf: URL(fileURLWithPath: path)), let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] { call.resolve(json) } else { call.reject("Processing error") } } } ``` #### Production Standard (Correct) > **Standard**: Explicitly fences the blocking disk read and JSON serialization into a dedicated background DispatchQueue with userInitiated QoS, preserving smooth 60/120fps UI rendering. ```swift @objc(FileProcessorPlugin) public class FileProcessorPlugin: CAPPlugin, CAPBridgedPlugin { public let identifier = "FileProcessorPlugin" public let jsName = "FileProcessor" public let pluginMethods: [CAPPluginMethod] = [ CAPPluginMethod(name: "processLargeFile", returnType: CAPPluginReturnPromise) ] private let processingQueue = DispatchQueue(label: "com.app.fileprocessor.queue", qos: .userInitiated, attributes: .concurrent) @objc func processLargeFile(_ call: CAPPluginCall) { guard let path = call.getString("path") else { call.reject("No path"); return } processingQueue.async { do { let url = URL(fileURLWithPath: path) let data = try Data(contentsOf: url) guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] else { call.reject("Invalid JSON payload") return } call.resolve(json) } catch { call.reject("Failed reading payload: \(error.localizedDescription)") } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native Bridge Thread-Pool Scoping & Dispatch Invariant

Capacitor 7 Native Bridge Thread-Pool Scoping & Dispatch Invariant defines an industrial-grade behavioral standard for mobile engineering. Fences native plugin JSON serialization, binary conversions, and I/O execution away from mobile UI threads into dedicated background dispatch queues. Prevents Android ANR watchdog timeouts and iOS Main Thread Watchdog crashes during high-throughput bridge messaging in Capacitor 7 plugins. Enforces concurrent background workers with explicit main-thread synchronization only during direct WebView manipulation. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Executing JSON Deserialization, Disk I/O, or Heavy Compute Directly Inside CapacitorPlugin Main Thread Dispatchers Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Executing JSON Deserialization, Disk I/O, or Heavy Compute Directly Inside CapacitorPlugin Main Thread Dispatchers	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS offload CPU-intensive parsing, file reading, and cryptographic routines to background threads before invoking PluginCall.resolve() or PluginCall.reject().

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.