Capacitor 7 Native-to-WebView Message Batching & Reactive Backpressure Guardrail

--- description: Capacitor 7 Native-to-WebView Message Batching & Reactive Backpressure Guardrail - High-frequency native notifications in Capacitor 7 overwhelm the single-threaded WebView event loop, causing runaway V8/JavaScriptCore heap allocation, dropped frames, and mobile OS memory terminations (Jetsam/LMK). This guardrail mandates bounded sliding-window batching, cooperative pull-based backpressure, and queue-overflow shedding strategies across the native-to-JS bridge interface. globs: src/**/*.{ts,tsx}, ios/App/App/**/*.swift, android/app/src/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-native-webview-batching-backpressure" --- # Capacitor 7 Native-to-WebView Message Batching & Reactive Backpressure Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded fire-and-forget native telemetry flooding the Capacitor JS bridge without backpressure ## System Constraints You are a Principal Mobile Architect enforcing strict throughput boundaries and cooperative backpressure on Capacitor 7 native-to-WebView communication channels. High-frequency sensors (BLE, IMU, GPS, audio PCM, network telemetry) must never emit individual unthrottled notifyListeners() calls into the WebView. You must enforce discrete batch windows, maximum ring-buffer queue depths, drop-oldest eviction semantics, and pull-based consumer acknowledgments before scheduling additional native bridge transfers. ## Strict Guidelines - Engineers MUST ALWAYS aggregate high-frequency native telemetry into micro-batches using fixed time windows (e.g., 16ms-50ms) or maximum batch sizes before crossing the Capacitor bridge. - Engineers MUST NOT allow native plugins to invoke notifyListeners() on raw hardware sensor callbacks without bounded queue validation and rate limiting. - Code SHOULD implement an explicit backpressure acknowledgment token where the WebView signals ready-state before native queues dispatch subsequent payload batches. - Services MUST enforce a DROP_OLDEST or DROP_LATEST eviction policy when bridge queue capacity exceeds safe operational thresholds (default max depth: 1000 items). - Components NEVER attach direct React/Vue state updates directly to raw Capacitor plugin listeners without debouncing, batching, or running through requestAnimationFrame. ## Bad vs Good Implementations ### Native Plugin Streaming vs. Bounded Batch Flow Control #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw continuous sampling fires hundreds of times per second. Capacitor must serialize each event to JSON and dispatch evaluateJavascript or postMessage across the IPC bridge. This rapidly exhausts the single-threaded JS run loop, balloons memory allocation, causes severe GC pauses, and triggers iOS Jetsam or Android LowMemoryKiller terminations. ```typescript import { PluginListenerHandle } from '@capacitor/core'; import { SensorPlugin, TelemetryReading } from './definitions'; export class TelemetryConsumer { private listener: PluginListenerHandle | null = null; // BAD: Every single high-frequency hardware event fires across the bridge, // immediately allocating in V8 heap and blocking the WebView main thread. async startStreaming(onData: (reading: TelemetryReading) => void): Promise<void> { this.listener = await SensorPlugin.addListener('rawTelemetry', (reading) => { onData(reading); }); await SensorPlugin.startContinuousSampling(); } async stopStreaming(): Promise<void> { await this.listener?.remove(); await SensorPlugin.stopContinuousSampling(); } } ``` #### Production Standard (Correct) > **Standard**: The native layer compresses events into timestamped batches, respecting configured window intervals and max element counts. The WebView acknowledges processed sequence IDs, creating backpressure that forces the native layer to retain or shed data according to an explicit eviction policy rather than thrashing the JavaScript thread. ```typescript import { PluginListenerHandle } from '@capacitor/core'; import { SensorPlugin, TelemetryBatch } from './definitions'; interface StreamOptions { readonly maxBufferSize?: number; readonly flushIntervalMs?: number; } export class TelemetryConsumer { private listener: PluginListenerHandle | null = null; private isProcessing = false; private pendingQueue: TelemetryBatch[] = []; private readonly MAX_QUEUE_DEPTH = 50; // GOOD: Coordinates pull/ack backpressure with native batching async startStreaming( onBatch: (readings: TelemetryBatch) => Promise<void>, options: StreamOptions = {} ): Promise<void> { const flushInterval = options.flushIntervalMs ?? 33; // Align to ~30 FPS this.listener = await SensorPlugin.addListener('telemetryBatch', async (batch: TelemetryBatch) => { if (this.pendingQueue.length >= this.MAX_QUEUE_DEPTH) { // Drop oldest to preserve WebView responsiveness under severe load this.pendingQueue.shift(); } this.pendingQueue.push(batch); this.drainQueue(onBatch); }); await SensorPlugin.configureStream({ batchWindowMs: flushInterval, maxBatchSize: 100, dropPolicy: 'dropOldest' }); await SensorPlugin.startContinuousSampling(); } private async drainQueue(processBatch: (readings: TelemetryBatch) => Promise<void>): Promise<void> { if (this.isProcessing) return; this.isProcessing = true; try { while (this.pendingQueue.length > 0) { const currentBatch = this.pendingQueue.shift(); if (currentBatch) { await processBatch(currentBatch); // Cooperative acknowledgment releases native queue lock await SensorPlugin.acknowledgeBatch({ sequenceId: currentBatch.sequenceId }); } } } finally { this.isProcessing = false; } } async stopStreaming(): Promise<void> { await this.listener?.remove(); this.pendingQueue = []; await SensorPlugin.stopContinuousSampling(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native-to-WebView Message Batching & Reactive Backpressure Guardrail

Capacitor 7 Native-to-WebView Message Batching & Reactive Backpressure Guardrail defines an industrial-grade behavioral standard for mobile engineering. High-frequency native notifications in Capacitor 7 overwhelm the single-threaded WebView event loop, causing runaway V8/JavaScriptCore heap allocation, dropped frames, and mobile OS memory terminations (Jetsam/LMK). This guardrail mandates bounded sliding-window batching, cooperative pull-based backpressure, and queue-overflow shedding strategies across the native-to-JS bridge interface. 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: Unbounded fire-and-forget native telemetry flooding the Capacitor JS bridge without backpressure 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	Unbounded fire-and-forget native telemetry flooding the Capacitor JS bridge without backpressure	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 aggregate high-frequency native telemetry into micro-batches using fixed time windows (e.g., 16ms-50ms) or maximum batch sizes before crossing 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.