Capacitor 7 Structured Binary IPC Serialization Invariant

--- description: Capacitor 7 Structured Binary IPC Serialization Invariant - Enforces zero-overhead binary IPC transfer over the Capacitor 7 native bridge for high-frequency or high-volume data streams. Prohibits base64 stringification and JSON text marshalling of binary payloads to eliminate WebView main-thread garbage collection churn, serialization latency, and 60/120 FPS frame drops. globs: src/**/*.{ts,tsx}, ios/**/*.{swift,m}, android/**/*.{java,kt} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-binary-ipc-serialization-invariant" --- # Capacitor 7 Structured Binary IPC Serialization Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Base64 or JSON Stringification of High-Frequency Native Bridge Payloads ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Structured Binary IPC Serialization invariants. Mandate direct ArrayBuffer, TypedArray, and zero-copy binary transfer mechanisms across the native bridge. Strictly forbid base64 encoding and JSON.stringify serialization for high-frequency sensor streams, camera/image frames, audio buffers, and cryptographic blobs. ## Strict Guidelines - Engineers MUST ALWAYS transfer raw binary data across the Capacitor 7 bridge using native ArrayBuffer or Uint8Array instances without intermediate base64 conversions. - Engineers MUST NOT invoke JSON.stringify, btoa, or custom hex encoding on binary payloads exceeding 1 KB or on any payload transferred at frequencies greater than 10 Hz. - Services MUST implement native plugin methods using direct binary return types (e.g., JSObject containing JSValue with ArrayBuffer support or Capacitor 7 PluginCall binary handlers) on iOS and Android. - Components NEVER trigger synchronous bridge calls for continuous streams; streaming data MUST use asynchronous push notifications delivering typed binary buffers. - Code SHOULD pre-allocate SharedArrayBuffers or reusable TypedArray pools in high-frequency rendering and processing pipelines to eliminate micro-allocations in the WebView. ## Bad vs Good Implementations ### High-Frequency Native Bridge Data Streaming #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Marshalling binary sensor packets via base64 strings requires string allocation, base64 decoding (atob), and manual byte copying in the WebView JavaScript thread at 60-100Hz. This causes massive memory churn, unpredictable Garbage Collection sweeps, and visible UI jank. ```typescript import { registerPlugin } from '@capacitor/core'; interface SensorStreamPlugin { startStreaming(options: { hz: number }): Promise<void>; addListener( eventName: 'sensorData', listenerFunc: (data: { base64Payload: string; timestamp: number }) => void ): Promise<void>; } const SensorStream = registerPlugin<SensorStreamPlugin>('SensorStream'); // ANTI-PATTERN: Decoding base64 in WebView main-thread causes GC pressure and frame drops SensorStream.addListener('sensorData', (event) => { const rawBinary = atob(event.base64Payload); const buffer = new Uint8Array(rawBinary.length); for (let i = 0; i < rawBinary.length; i++) { buffer[i] = rawBinary.charCodeAt(i); } processTelemetry(buffer, event.timestamp); }); ``` #### Production Standard (Correct) > **Standard**: Leverages Capacitor 7 structured binary IPC where the native bridge passes binary blobs directly as typed ArrayBuffer instances. Bypasses text marshalling, base64 transcoding, and string allocation overhead entirely. ```typescript import { registerPlugin, PluginListenerHandle } from '@capacitor/core'; interface SensorStreamPlugin { startStreaming(options: { hz: number }): Promise<void>; addListener( eventName: 'sensorData', listenerFunc: (data: { payload: ArrayBuffer; timestamp: number }) => void ): Promise<PluginListenerHandle>; } const SensorStream = registerPlugin<SensorStreamPlugin>('SensorStream'); // PRODUCTION INVARIANT: Native bridge transmits TypedArray directly into WebView let streamHandle: PluginListenerHandle | null = null; export async function initTelemetry(): Promise<void> { streamHandle = await SensorStream.addListener('sensorData', (event) => { // Direct zero-overhead typed buffer consumption without string decoding const view = new DataView(event.payload); processTelemetryDirect(view, event.timestamp); }); await SensorStream.startStreaming({ hz: 100 }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Structured Binary IPC Serialization Invariant

Capacitor 7 Structured Binary IPC Serialization Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces zero-overhead binary IPC transfer over the Capacitor 7 native bridge for high-frequency or high-volume data streams. Prohibits base64 stringification and JSON text marshalling of binary payloads to eliminate WebView main-thread garbage collection churn, serialization latency, and 60/120 FPS frame drops. 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 Stringification of High-Frequency Native Bridge 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	Base64 or JSON Stringification of High-Frequency Native Bridge 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 raw binary data across the Capacitor 7 bridge using native ArrayBuffer or Uint8Array instances without intermediate base64 conversions.

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.