Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariant

--- description: Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariant - Mandates direct ArrayBuffer binary transport across the Capacitor 7 native-to-web bridge, strictly prohibiting Base64 or numeric array serialization. Prevents high-frequency garbage collector thrashing, IPC latency spikes, and 33% heap inflation during binary data streaming (BLE, camera frames, SQLite exports, and audio). Enforces direct TypedArray views and ownership transfer semantics on incoming bridge buffers. globs: src/**/*.{ts,tsx}, ios/Plugin/**/*.{swift,m}, android/src/main/**/*.{java,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-zero-copy-arraybuffer-transfer-invariant" --- # Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Serializing Binary Payloads as Base64 Strings or Number Arrays Over the Bridge ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariants. Mandate that all binary payloads crossing the bridge use native ArrayBuffer transfer mechanisms introduced in Capacitor 7. Prohibit Base64 marshaling, numeric array wrapping, and unnecessary memory copies on both the native and web layers. Reject any PR that causes garbage collector churn or bridge serialization overhead. ## Strict Guidelines - Engineers MUST ALWAYS transmit binary payloads across the Capacitor 7 bridge as raw ArrayBuffer instances rather than Base64-encoded strings or JSON arrays. - Engineers MUST NOT invoke Base64 transformation helpers (`btoa`, `atob`, `Buffer.from(..., 'base64')`, or native Base64 encoders) for high-frequency or binary data (>1KB) crossing the bridge. - Code SHOULD wrap returned bridge `ArrayBuffer` instances directly into appropriate `TypedArray` views (e.g., `Uint8Array`, `Float32Array`, `DataView`) without allocating intermediate copies via `.slice()`. - Services MUST detach or unreference binary buffers immediately once processed by downstream Web Workers or pipeline consumers to allow prompt native-side memory reclamation. - Components NEVER execute byte-by-byte iteration or string conversions inside the primary UI thread for incoming bridge event streams. ## Bad vs Good Implementations ### High-Frequency Binary Bridge Transfer (Sensor / BLE Stream) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transporting binary data as Base64 strings generates massive string allocations, triggers WebKit/V8 garbage collection pauses, and wastes CPU cycles parsing text back into byte arrays. ```typescript import { registerPlugin } from '@capacitor/core'; interface LegacyBlePlugin { receivePacket(): Promise<{ data: string }>; // Base64 encoded string } const BleBridge = registerPlugin<LegacyBlePlugin>('BlePlugin'); export async function getSensorFrame(): Promise<Uint8Array> { // ANTI-PATTERN: Base64 serialization causes a 33% payload blowup, // string allocation overhead, and synchronous decoding frame drops. const response = await BleBridge.receivePacket(); const binaryString = atob(response.data); const bytes = new Uint8Array(binaryString.length); for (let i = 0; i < binaryString.length; i++) { bytes[i] = binaryString.charCodeAt(i); } return bytes; } ``` #### Production Standard (Correct) > **Standard**: Capacitor 7 native-to-web zero-copy transfer passes raw ArrayBuffer instances directly through native WebView message channels, eliminating GC pressure, Base64 inflation, and decoding latency. ```typescript import { registerPlugin } from '@capacitor/core'; interface ZeroCopyBlePlugin { // Capacitor 7 allows direct ArrayBuffer returns over the native bridge receivePacket(): Promise<{ data: ArrayBuffer }>; } const BleBridge = registerPlugin<ZeroCopyBlePlugin>('BlePlugin'); export async function getSensorFrame(): Promise<Uint8Array> { // PRODUCTION INVARIANT: Native bridge yields ArrayBuffer directly // backed by shared native memory. Zero-copy TypedArray view constructed. const response = await BleBridge.receivePacket(); if (!(response.data instanceof ArrayBuffer)) { throw new TypeError('Bridge invariant violated: expected raw ArrayBuffer'); } return new Uint8Array(response.data); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariant

Capacitor 7 Native-to-WebView Zero-Copy ArrayBuffer Transfer Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates direct ArrayBuffer binary transport across the Capacitor 7 native-to-web bridge, strictly prohibiting Base64 or numeric array serialization. Prevents high-frequency garbage collector thrashing, IPC latency spikes, and 33% heap inflation during binary data streaming (BLE, camera frames, SQLite exports, and audio). Enforces direct TypedArray views and ownership transfer semantics on incoming bridge buffers. 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 Binary Payloads as Base64 Strings or Number Arrays Over the 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	Serializing Binary Payloads as Base64 Strings or Number Arrays Over the 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 transmit binary payloads across the Capacitor 7 bridge as raw ArrayBuffer instances rather than Base64-encoded strings or JSON arrays.

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.