Capacitor 7 Zero-Copy Native Bridge Buffer Serialization Standard

--- description: Capacitor 7 Zero-Copy Native Bridge Buffer Serialization Standard - Enforces off-main-thread direct memory-mapped buffer transfer between WebView and native code (Android JNI ByteBuffer and iOS ArrayBuffer / CVPixelBuffer) in Capacitor 7 plugins. Eliminates main UI thread serialization overhead and hitching when ingesting high-throughput sensor streams, camera frames, and audio PCM data. globs: src/**/*.{ts,tsx}, android/src/main/java/**/*.java, android/src/main/kotlin/**/*.kt, ios/Plugin/**/*.swift, ios/Plugin/**/*.m alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor7-zero-copy-bridge-buffer-standard" --- # Capacitor 7 Zero-Copy Native Bridge Buffer Serialization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Base64 or JSON-stringified sensor stream payload marshaling over WebView JavaScript-to-Native bridge ## System Constraints You are a Principal Mobile Architect specializing in Capacitor 7 native runtime internals and high-performance hybrid systems. Mandate off-main-thread zero-copy memory transfers between the WebView and native layers. Strictly ban JSON encoding, Base64 strings, or direct MainThread bridging for binary telemetry, sensor streams, or video feed processing. ## Strict Guidelines - Engineers MUST ALWAYS use native direct `ByteBuffer` (Android) or direct pointer-backed `Data` / `ArrayBuffer` bindings to marshal continuous stream feeds across the bridge. - Engineers MUST NOT convert binary buffers or high-frequency telemetry (>30Hz) into Base64 strings or serialized JSON objects prior to sending over Capacitor plugins. - Native plugins MUST dispatch buffer processing and streaming ingress to background queues (`DispatchQueue.global(qos: .userInteractive)` on iOS; `Dispatchers.Default` / thread pool executors on Android). - Native Android plugins MUST pass memory-mapped Direct ByteBuffers (`ByteBuffer.allocateDirect`) directly into the JNI boundary to prevent garbage collection sweeps and memory duplication. - TypeScript consumers MUST process bridge buffers directly inside a WebWorker using `Transferable` `ArrayBuffer` instances without retaining references on the main UI thread. ## Bad vs Good Implementations ### High-Frequency Native Telemetry Streaming to WebView #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Stringifying sensor data into Base64 and parsing it via atob() on the UI thread causes severe CPU spikes, excessive garbage collection thrashing, and dropped frames (>16ms delays). ```typescript import { registerPlugin } from '@capacitor/core'; interface SensorPlugin { addListener(event: 'onSensorFrame', listener: (data: { base64Data: string; timestamp: number }) => void): Promise<void>; } const SensorNative = registerPlugin<SensorPlugin>('SensorNative'); // Anti-pattern: High-frequency frame processing on Main Thread with Base64 decode SensorNative.addListener('onSensorFrame', (payload) => { const rawBinary = atob(payload.base64Data); const bytes = new Uint8Array(rawBinary.length); for (let i = 0; i < rawBinary.length; i++) { bytes[i] = rawBinary.charCodeAt(i); } renderSensorStream(bytes); }); function renderSensorStream(data: Uint8Array): void { console.log('Processed frame bytes:', data.byteLength); } ``` #### Production Standard (Correct) > **Standard**: ArrayBuffers are received directly from the native zero-copy bridge adapter and transferred off-main-thread to a dedicated WebWorker via Transferable objects with O(1) allocation cost. ```typescript import { registerPlugin } from '@capacitor/core'; interface SensorPlugin { startStreaming(options: { bufferLength: number }): Promise<void>; addListener(event: 'onBufferAvailable', listener: (data: { buffer: ArrayBuffer; timestamp: number }) => void): Promise<void>; } const SensorNative = registerPlugin<SensorPlugin>('SensorNative'); // Worker instantiation to eliminate UI hitching const worker = new Worker(new URL('./sensor.worker.ts', import.meta.url), { type: 'module' }); SensorNative.addListener('onBufferAvailable', ({ buffer, timestamp }) => { // Zero-copy transfer: ownership of ArrayBuffer transfers to worker without cloning worker.postMessage({ buffer, timestamp }, [buffer]); }); export async function initSensors(): Promise<void> { await SensorNative.startStreaming({ bufferLength: 4096 }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Zero-Copy Native Bridge Buffer Serialization Standard

Capacitor 7 Zero-Copy Native Bridge Buffer Serialization Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces off-main-thread direct memory-mapped buffer transfer between WebView and native code (Android JNI ByteBuffer and iOS ArrayBuffer / CVPixelBuffer) in Capacitor 7 plugins. Eliminates main UI thread serialization overhead and hitching when ingesting high-throughput sensor streams, camera frames, and audio PCM data. 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: Base64 or JSON-stringified sensor stream payload marshaling over WebView JavaScript-to-Native bridge 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	Base64 or JSON-stringified sensor stream payload marshaling over WebView JavaScript-to-Native bridge	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 use native direct `ByteBuffer` (Android) or direct pointer-backed `Data` / `ArrayBuffer` bindings to marshal continuous stream feeds across the 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.