Capacitor 7 Zero-Copy ArrayBuffer Native Bridge Standard

--- description: Capacitor 7 Zero-Copy ArrayBuffer Native Bridge Standard - Enforces direct typed memory transfer across the Capacitor 7 JavaScript-to-Native bridge for binary payloads without intermediate Base64 serialization. Eliminates high-frequency garbage collection pauses, bridge payload inflation, and main-thread frame drops during large binary I/O operations. globs: src/**/*.{ts,tsx}, ios/App/**/*.{swift,m}, android/app/src/**/*.{kt,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-zero-copy-arraybuffer-transfer-standard" --- # Capacitor 7 Zero-Copy ArrayBuffer Native Bridge Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Serializing Raw Binary Buffers to Base64 Strings Within Capacitor Plugin Call Payloads ## System Constraints You are a Principal Mobile Architect enforcing the Capacitor 7 Hybrid Plugin Zero-Copy ArrayBuffer Transfer Standard. You mandate direct typed array transfers over native bridges, preventing Base64 stringification, string allocation bottlenecks, and UI thread starvation. ## Strict Guidelines - Engineers MUST ALWAYS transfer binary payloads using native ArrayBuffer or Uint8Array objects natively supported by Capacitor 7 bridge interfaces. - Engineers MUST NOT convert raw binary data to Base64, hex strings, or numeric arrays prior to passing parameters to native plugin methods. - Code SHOULD leverage Web Workers or OffscreenCanvas contexts to prepare ArrayBuffers before dispatching bridge requests to isolate memory allocation from the UI thread. - Native implementations MUST map the underlying ByteBuffer on Android or direct NSData pointers on iOS without copying memory chunks into intermediate JSON strings. - Components NEVER execute bridge invocations exceeding 64KB on the main rendering tick or within tight animation frame loops. ## Bad vs Good Implementations ### Capacitor 7 Binary Ingestion: Base64 Stringification vs. Native ArrayBuffer Transfer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over binary memory to create a character string and subsequently Base64 encoding via btoa creates immense garbage collector pressure, doubles or triples peak heap usage, and blocks the browser UI thread during bridge dispatch. ```typescript import { registerPlugin } from '@capacitor/core'; interface LegacyDataTransferPlugin { uploadStream(options: { data: string }): Promise<{ bytesWritten: number }>; } const NativeTransfer = registerPlugin<LegacyDataTransferPlugin>('LegacyDataTransfer'); export async function sendTelemetryFrame(buffer: ArrayBuffer): Promise<number> { // ANTI-PATTERN: Base64 serialization inflates memory footprint by 33% // and triggers severe Garbage Collection stalls on the WebView main thread. const bytes = new Uint8Array(buffer); let binary = ''; for (let i = 0; i < bytes.byteLength; i++) { binary += String.fromCharCode(bytes[i]); } const base64Data = btoa(binary); const result = await NativeTransfer.uploadStream({ data: base64Data }); return result.bytesWritten; } ``` #### Production Standard (Correct) > **Standard**: Capacitor 7 allows direct passing of ArrayBuffer parameters without stringification. Native bridges map the memory directly via JNI DirectByteBuffer on Android and bridged NSData on iOS, avoiding all JSON encode/decode steps and thread stalls. ```typescript import { registerPlugin } from '@capacitor/core'; interface ZeroCopyDataTransferPlugin { uploadStream(options: { data: ArrayBuffer }): Promise<{ bytesWritten: number }>; } const NativeTransfer = registerPlugin<ZeroCopyDataTransferPlugin>('ZeroCopyDataTransfer'); export async function sendTelemetryFrame(buffer: ArrayBuffer): Promise<number> { // PRODUCTION STANDARD: Pass raw ArrayBuffer directly to Capacitor 7 plugin bridge. // Native platform consumes zero-copy DirectByteBuffer on Android and NSData zero-copy reference on iOS. const result = await NativeTransfer.uploadStream({ data: buffer }); return result.bytesWritten; } ```

Architectural Specification & Invariant Rationale

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

Capacitor 7 Zero-Copy ArrayBuffer Native Bridge Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces direct typed memory transfer across the Capacitor 7 JavaScript-to-Native bridge for binary payloads without intermediate Base64 serialization. Eliminates high-frequency garbage collection pauses, bridge payload inflation, and main-thread frame drops during large binary I/O operations. 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: Serializing Raw Binary Buffers to Base64 Strings Within Capacitor Plugin Call Payloads 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	Serializing Raw Binary Buffers to Base64 Strings Within Capacitor Plugin Call Payloads	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 transfer binary payloads using native ArrayBuffer or Uint8Array objects natively supported by Capacitor 7 bridge interfaces.

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.