Capacitor 7 Zero-Copy ArrayBuffer JSI Bridge Isolation Standard

--- description: Capacitor 7 Zero-Copy ArrayBuffer JSI Bridge Isolation Standard - Enforces strict Zero-Copy ArrayBuffer transfers across the native-to-web bridge using low-level typed buffers and isolated Web Workers. Prevents main-thread micro-stutter by eliminating base64/JSON string serialization overhead during high-frequency (>=60Hz) biometric and IMU sensor telemetry streaming. Guarantees 60/120 FPS rendering pipelines remain decoupled from incoming native hardware events. globs: src/**/*.{ts,tsx}, android/app/src/main/java/**/*.java, ios/App/App/**/*.swift alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-zero-copy-arraybuffer-jsi-bridge-isolation" --- # Capacitor 7 Zero-Copy ArrayBuffer JSI Bridge Isolation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Streaming High-Frequency Sensor Packets as Base64/JSON Strings Across the Capacitor Bridge onto the Main Thread ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Zero-Copy ArrayBuffer JSI Bridge Isolation. You MUST intercept any telemetry, audio, or biometric pipelines streaming data over Capacitor bridge mechanisms. Never allow Base64 encoding, standard Capacitor plugin JSON event emitting, or main-thread data parsing for high-throughput (>=60Hz) continuous data streams. Mandate Direct ByteBuffer mapping to ArrayBuffer/SharedArrayBuffer, offload bridge ingestion directly into Dedicated Web Workers via transferable objects, and enforce rigid memory lifecycle discipline. ## Strict Guidelines - Engineers MUST ALWAYS transfer binary telemetry via ArrayBuffer instances using transferable objects (`[buffer]`) when passing across thread boundaries to prevent structured cloning overhead. - Engineers MUST NOT serialize binary or high-frequency sensor streams into Base64 strings, JSON payloads, or delimited strings over standard `notifyListeners()`. - Code SHOULD utilize direct memory views (`Float32Array`, `Uint8Array`, `DataView`) instantiated on pre-allocated buffers rather than allocating new objects per telemetry frame. - Services MUST process high-frequency (>=60Hz) native biometric or IMU hardware events within a dedicated Web Worker to eliminate UI thread frame-drops and micro-stutter. - Components NEVER consume raw native sensor event listeners directly in React/Vue/Angular rendering lifecycles; they MUST subscribe only to throttled or derived UI state emitted from the telemetry worker. ## Bad vs Good Implementations ### Ingesting High-Frequency Biometric/IMU Telemetry via Zero-Copy Worker Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Parsing Base64-encoded strings and allocating JSON objects on the main thread for high-frequency hardware events triggers massive garbage collection thrashing and bridge latency, causing visible UI micro-stutters and dropped frames. ```typescript import { Plugins } from '@capacitor/core'; const { BiometricSensorPlugin } = Plugins; // Anti-pattern: High-frequency 100Hz telemetry parsed via JSON on the main thread BiometricSensorPlugin.addListener('onTelemetryBatch', (data: { samples: string }) => { // Decoding base64 and JSON parsing on UI thread triggers massive GC and micro-stutter const rawJson = atob(data.samples); const parsedSamples: number[] = JSON.parse(rawJson); updateChartOnMainThread(parsedSamples); }); function updateChartOnMainThread(samples: number[]): void { console.log('Main thread UI blocked during parsing:', samples.length); } ``` #### Production Standard (Correct) > **Standard**: Eliminates serialization overhead by receiving binary telemetry directly as an ArrayBuffer and using transferable objects to offload processing to a Web Worker, ensuring zero allocation on the main thread and keeping rendering locked at 60/120 FPS. ```typescript // Production standard: Zero-copy ArrayBuffer routing into dedicated telemetry worker const worker = new Worker(new URL('./telemetry.worker.ts', import.meta.url), { type: 'module' }); interface NativeBinaryPlugin { registerBinaryReceiver(callback: (buffer: ArrayBuffer) => void): Promise<void>; } declare const BiometricBridge: NativeBinaryPlugin; // Register direct native ArrayBuffer callback without JSON overhead BiometricBridge.registerBinaryReceiver((rawBuffer: ArrayBuffer) => { // Transfer memory buffer zero-copy directly to Web Worker // rawBuffer becomes detached and neutered on main thread instantly worker.postMessage({ type: 'TELEMETRY_FRAME', payload: rawBuffer }, [rawBuffer]); }); // Worker Implementation (telemetry.worker.ts): // self.onmessage = (event: MessageEvent<{ type: string; payload: ArrayBuffer }>) => { // const view = new Float32Array(event.data.payload); // // Process hardware frame off-thread... // }; ```

Architectural Specification & Invariant Rationale

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

Capacitor 7 Zero-Copy ArrayBuffer JSI Bridge Isolation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict Zero-Copy ArrayBuffer transfers across the native-to-web bridge using low-level typed buffers and isolated Web Workers. Prevents main-thread micro-stutter by eliminating base64/JSON string serialization overhead during high-frequency (>=60Hz) biometric and IMU sensor telemetry streaming. Guarantees 60/120 FPS rendering pipelines remain decoupled from incoming native hardware events. 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: Streaming High-Frequency Sensor Packets as Base64/JSON Strings Across the Capacitor Bridge onto the Main Thread 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	Streaming High-Frequency Sensor Packets as Base64/JSON Strings Across the Capacitor Bridge onto the Main Thread	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 telemetry via ArrayBuffer instances using transferable objects (`[buffer]`) when passing across thread boundaries to prevent structured cloning overhead.

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.