Capacitor 7 Concurrent Native Bridge Thread Invariants

--- description: Capacitor 7 Concurrent Native Bridge Thread Invariants - Enforces strict offloading of high-frequency native telemetry and bi-directional hardware streaming away from the WebView main UI thread into dedicated native worker queues and Web Workers. Prevents main-thread micro-stutters and frame drops by establishing batched RingBuffers, asynchronous native dispatching, and zero-copy transfer protocols over Capacitor 7 bridge interfaces. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/main/java/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-bridge-thread-invariants" --- # Capacitor 7 Concurrent Native Bridge Thread Invariants > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Saturating WebView UI thread with synchronous unbatched native bridge event notifications ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Concurrent Native Bridge Thread Invariants. You must mandate that high-frequency hardware streams (IMU, BLE, GPS, audio telemetry) are never dispatched directly to the main thread or directly into unthrottled WebView bridge listeners. All bi-directional bridge calls exceeding 60Hz MUST be isolated in native background queues, buffered via lock-free ring buffers, and transferred across the bridge in coalesced chunks to a dedicated Web Worker via MessageChannel or transferable ArrayBuffers. ## Strict Guidelines - Engineers MUST ALWAYS buffer high-frequency (>60Hz) native hardware events using a native RingBuffer or fixed-interval dispatch window (16ms-33ms) before posting events over the Capacitor bridge. - Engineers MUST NOT invoke `notifyListeners` directly from iOS main dispatch queues (`DispatchQueue.main`) or Android UI threads (`Looper.getMainLooper()`) for streaming telemetry. - Code SHOULD offload JS-side telemetry ingestion to dedicated Web Workers using transferable `ArrayBuffer` payloads via `MessagePort` instead of parsing high-overhead JSON on the UI thread. - Services MUST implement native-side backpressure detection that drops or aggregates hardware frames if the bridge transfer channel is congested or JS processing falls behind. - Components NEVER attach individual React/Vue/Angular state updates directly to raw Capacitor streaming plugin listeners without an intermediate throttling or batching layer. ## Bad vs Good Implementations ### Unthrottled Raw Telemetry Stream vs. Batched Web Worker Bridge Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Attaching a direct listener to an unthrottled 100Hz native telemetry event floods the Capacitor IPC bridge, forcing JSON serialization/deserialization on the main UI thread at every tick, causing immediate jank and severe dropped frames. ```typescript import { PluginListenerHandle } from '@capacitor/core'; import { BleTelemetryPlugin } from './plugins/telemetry'; let listenerHandle: PluginListenerHandle | null = null; // ANTI-PATTERN: Direct binding of 100Hz BLE telemetry to UI state causes bridge congestion and frame drops export function startTelemetryStream(onData: (val: number) => void) { listenerHandle = BleTelemetryPlugin.addListener('telemetryData', (event: { value: number }) => { // Directly executing on WebView main thread for every 10ms frame onData(event.value); }); } export function stopTelemetryStream() { if (listenerHandle) { listenerHandle.remove(); } } ``` #### Production Standard (Correct) > **Standard**: Batches native hardware stream frames native-side within a 33ms window and transfers the continuous ArrayBuffer directly to a background Web Worker using zero-copy semantics, completely isolating the WebView main thread from data ingestion. ```typescript import { BleTelemetryPlugin } from './plugins/telemetry'; interface TelemetryBufferPayload { buffer: ArrayBuffer; sampleCount: number; } // PRODUCTION FIX: Offload ingestion to Web Worker using batched binary packets export class TelemetryBridgeManager { private worker: Worker; private channel: MessageChannel; constructor(workerScriptUrl: string) { this.worker = new Worker(workerScriptUrl, { type: 'module' }); this.channel = new MessageChannel(); this.worker.postMessage({ type: 'INIT_PORT' }, [this.channel.port2]); } public async startStream(): Promise<void> { // Native plugin configured with internal 30ms RingBuffer and binary transfer await BleTelemetryPlugin.setStreamingParameters({ batchIntervalMs: 33, format: 'binary' }); await BleTelemetryPlugin.addListener('telemetryBatch', (payload: TelemetryBufferPayload) => { // Transfer ArrayBuffer directly to Web Worker with zero copy, bypassing UI execution this.channel.port1.postMessage(payload.buffer, [payload.buffer]); }); await BleTelemetryPlugin.startHardwareStream(); } public async stopStream(): Promise<void> { await BleTelemetryPlugin.stopHardwareStream(); await BleTelemetryPlugin.removeAllListeners(); this.worker.terminate(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Concurrent Native Bridge Thread Invariants

Capacitor 7 Concurrent Native Bridge Thread Invariants defines an industrial-grade behavioral standard for mobile engineering. Enforces strict offloading of high-frequency native telemetry and bi-directional hardware streaming away from the WebView main UI thread into dedicated native worker queues and Web Workers. Prevents main-thread micro-stutters and frame drops by establishing batched RingBuffers, asynchronous native dispatching, and zero-copy transfer protocols over Capacitor 7 bridge interfaces. 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: Saturating WebView UI thread with synchronous unbatched native bridge event notifications 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	Saturating WebView UI thread with synchronous unbatched native bridge event notifications	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 buffer high-frequency (>60Hz) native hardware events using a native RingBuffer or fixed-interval dispatch window (16ms-33ms) before posting events over the Capacitor bridge.

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.